このドキュメントでは、Bash Agentについて詳しく説明します。Bash Agentは、Agentワークフロー内でシェルスクリプトやコマンドラインツールを安全に実行できるようにするものです。サンドボックス環境の設定方法、コマンド権限の管理方法、そしてシステムレベルの操作のためにアプリケーションに統合する方法を学びます。
概要
Bash Agentは、制御された安全な環境内でbashスクリプトを実行するように設計されています。AnthropicのSandbox Runtimeを活用して分離された実行空間を提供し、ネットワークやファイルシステム操作を含むシステムアクセスに対してきめ細かな制御を実現します。これにより、システムのセキュリティを損なうことなく、ファイル操作、プロセス管理、シェルコマンドの自動化を必要とするタスクに最適なツールとなります。
主な機能は次のとおりです。
- サンドボックス実行: スクリプトは、ネットワークおよびファイルシステムリソースに対する設定可能なアクセス制御を備えた、分離された環境で実行されます。
- コマンド権限: 堅牢な権限システムにより、特定のコマンドをホワイトリスト、ブラックリスト、または承認要求に設定でき、不正な操作を防ぎます。
- リアルタイム出力: 標準出力 (
stdout) と標準エラー (stderr) は、スクリプトの実行中にリアルタイムでストリーミングされます。 - Guard Agent: 承認が必要なコマンドに対して、別のAgent(「AIガード」)を指定して、カスタムロジックに基づいて実行を動的に承認または拒否させることができます。
Warning
サンドボックスモードはWindowsではサポートされていません。Windowsユーザーは、Bash Agentを使用するために設定で明示的にsandbox: falseを設定する必要があります。サンドボックスを無効にすると、すべてのセキュリティ保護が解除されるため、信頼できる環境でのみ実行してください。
アーキテクチャ
Agentはスクリプトを処理し、サンドボックスが有効かどうかに応じて、直接実行するか、サンドボックス環境内で実行します。stdout、stderr、および最終的なexitCodeを含む出力は、呼び出し元にストリーミングで返されます。
flowchart TB
Input([スクリプト入力]) --> BashAgent[Bash Agent]
BashAgent --> SandboxCheck{サンドボックス有効?}
SandboxCheck -->|はい| Sandbox[サンドボックス実行]
SandboxCheck -->|いいえ| Direct[直接実行]
Sandbox --> ShellProcess[シェルプロセス]
Direct --> ShellProcess
ShellProcess --> StreamOutput[ストリーム出力]
StreamOutput --> Output([stdout, stderr, exitCode])
classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px
classDef process fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px
classDef decision fill:#E8F4F8,stroke:#4A9EBF,stroke-width:2px
class Input,Output inputOutput
class BashAgent,ShellProcess,StreamOutput process
class SandboxCheck decision
class Sandbox,Direct process基本的な使い方
Bash Agentを使用する最も簡単な方法は、YAMLファイルで定義することです。これにより、その動作を宣言的に設定できます。
標準サンドボックスモード
デフォルトでは、Bash Agentは安全なサンドボックス環境で実行されます。
bash-agent.yaml
type: "@aigne/agent-library/bash"
name: Bash
# 入力スキーマは 'script' パラメータを定義します
input_schema:
type: object
properties:
script:
type: string
description: 実行するbashスクリプト。
required:
- scriptその後、AIGNE CLIを使用してスクリプトを実行できます。
aigne run . Bash --script 'echo "Hello from the Bash Agent!"'サンドボックスの無効化
開発時、信頼できる環境、またはWindowsでは、サンドボックスを無効にすることができます。
bash-agent-no-sandbox.yaml
type: "@aigne/agent-library/bash"
name: Bash
sandbox: false # サンドボックスを無効にする
input_schema:
type: object
properties:
script:
type: string
description: 実行するbashスクリプト。
required:
- scriptCaution
サンドボックスを無効にすると、すべてのセキュリティ保護が解除されます。これは、実行されるスクリプトを完全に信頼できる環境でのみ行ってください。
設定
Bash Agentは、実行環境とセキュリティ設定を制御するために、いくつかのオプションで設定できます。
- sandbox
object | boolean(default:true) — AnthropicのSandbox Runtimeに基づいたサンドボックス環境の設定。サンドボックスを無効にするにはfalseに設定します。デフォルトはtrueで、デフォルトの制限が適用されます。 - timeout
number(default:60000) — 実行タイムアウト(ミリ秒)。スクリプトがこの制限を超えると終了します。 - permissions
object— コマンド実行権限の設定。allow、deny、defaultMode、およびguard Agentを含みます。
入力と出力
Agentは単純な入力オブジェクトを受け取り、詳細な出力オブジェクトを生成します。
InputSchema
- script
string(required) — 実行されるbashスクリプト。
OutputSchema
- stdout
string— スクリプトによって生成された標準出力。 - stderr
string— スクリプトによって生成された標準エラー出力。 - exitCode
number— スクリプトの終了コード。通常、0の値は成功を示します。
サンドボックスの設定
サンドボックスは、ネットワークおよびファイルシステムリソースへのアクセスを制限することにより、スクリプト実行のための安全なレイヤーを提供します。
ネットワーク制御
スクリプトがアクセスを許可または禁止されているドメインを指定できます。
network-config.yaml
sandbox:
network:
# 許可されたドメインのリスト。ワイルドカードがサポートされています。
allowedDomains:
- "api.github.com"
- "*.example.com"
# 拒否されたドメインのリスト。許可リストよりも優先されます。
deniedDomains:
- "*.ads.com"ファイルシステム制御
特定のパスまたはパターンに対する読み取りおよび書き込み権限を定義します。
filesystem-config.yaml
sandbox:
filesystem:
# 書き込みが許可されているパスのリスト。
allowWrite:
- "./output"
- "/tmp"
# 書き込みが禁止されているパスのリスト。
denyWrite:
- "/etc"
- "/usr"
# 読み取りが禁止されているパスのリスト。
denyRead:
- "~/.ssh"
- "*.key"権限の設定
権限システムは、どのコマンドが実行できるかを制御します。明確な優先順位で動作します:denyルールはallowルールを上書きし、allowルールはdefaultModeを上書きします。
権限プロパティ
- allow
string[]— 承認なしで実行が許可されるコマンドのホワイトリスト。完全一致(git status)およびワイルドカード付きのプレフィックスマッチング(ls:*)をサポートします。 - deny
string[]— 厳密に禁止されるコマンドのブラックリスト。このリストが最も高い優先度を持ちます。 - defaultMode
string(default:allow) — allowまたはdenyリストに一致しないコマンドのデフォルトの動作。指定可能な値はallow、ask、またはdenyです。 - guard
Agent— defaultModeがaskの場合に呼び出されるAgent。スクリプトを受け取り、ブール値のapprovedステータスを返す必要があります。
Guard Agentを使用した例
defaultModeがaskに設定されている場合、コマンドを承認または拒否するためにguard Agentを提供する必要があります。Guard Agentは入力としてスクリプトを受け取り、approvedブール値とオプションのreason文字列を含むオブジェクトを返す必要があります。
guard-config.yaml
type: "@aigne/agent-library/bash"
name: Bash
permissions:
allow:
- "echo:*"
- "ls:*"
deny:
- "rm:*"
- "sudo:*"
defaultMode: "ask"
guard:
type: "ai"
model: "anthropic/claude-3-5-sonnet-20241022"
instructions: |
You are a security guard for bash command execution.
Analyze the requested script and decide whether to approve it.
Script to evaluate:
```bash
{{script}}
```
Approve safe, read-only operations. Deny any command that
could modify or delete files, or alter system state.
output_schema:
type: object
properties:
approved:
type: boolean
description: Whether to approve the script execution.
reason:
type: string
description: An explanation for the decision.
required:
- approvedベストプラクティス
- サンドボックスを使用する: 本番環境では常にサンドボックスを有効にして、セキュリティリスクを軽減してください。
- 最小権限の原則: サンドボックスと権限ルールを設定して、タスクに必要な最小限のアクセスのみを許可するようにします。
- 危険なコマンドを拒否する:
rm、sudo、ddなどの破壊的なコマンドを明示的にdenyリストに追加します。 - 終了コードを処理する: Agentの出力にある
exitCodeをチェックして、スクリプトの失敗を検出し、処理します。0以外の終了コードは通常エラーを示し、詳細はstderrで確認できます。 - 機密ファイルを保護する:
denyReadを使用して、~/.ssh、.envファイル、秘密鍵などの機密ファイルやディレクトリへのアクセスを防ぎます。