メインコンテンツへスキップ

Bash

このドキュメントでは、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はスクリプトを処理し、サンドボックスが有効かどうかに応じて、直接実行するか、サンドボックス環境内で実行します。stdoutstderr、および最終的なexitCodeを含む出力は、呼び出し元にストリーミングで返されます。

mermaid
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

yaml
type: "@aigne/agent-library/bash"
name: Bash

# 入力スキーマは 'script' パラメータを定義します
input_schema:
  type: object
  properties:
    script:
      type: string
      description: 実行するbashスクリプト。
  required:
    - script

その後、AIGNE CLIを使用してスクリプトを実行できます。

bash
aigne run . Bash --script 'echo "Hello from the Bash Agent!"'

サンドボックスの無効化

開発時、信頼できる環境、またはWindowsでは、サンドボックスを無効にすることができます。

bash-agent-no-sandbox.yaml

yaml
type: "@aigne/agent-library/bash"
name: Bash
sandbox: false # サンドボックスを無効にする

input_schema:
  type: object
  properties:
    script:
      type: string
      description: 実行するbashスクリプト。
  required:
    - script

Caution

サンドボックスを無効にすると、すべてのセキュリティ保護が解除されます。これは、実行されるスクリプトを完全に信頼できる環境でのみ行ってください。

設定

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

yaml
sandbox:
  network:
    # 許可されたドメインのリスト。ワイルドカードがサポートされています。
    allowedDomains:
      - "api.github.com"
      - "*.example.com"
    # 拒否されたドメインのリスト。許可リストよりも優先されます。
    deniedDomains:
      - "*.ads.com"

ファイルシステム制御

特定のパスまたはパターンに対する読み取りおよび書き込み権限を定義します。

filesystem-config.yaml

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を使用した例

defaultModeaskに設定されている場合、コマンドを承認または拒否するためにguard Agentを提供する必要があります。Guard Agentは入力としてスクリプトを受け取り、approvedブール値とオプションのreason文字列を含むオブジェクトを返す必要があります。

guard-config.yaml

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

ベストプラクティス

  • サンドボックスを使用する: 本番環境では常にサンドボックスを有効にして、セキュリティリスクを軽減してください。
  • 最小権限の原則: サンドボックスと権限ルールを設定して、タスクに必要な最小限のアクセスのみを許可するようにします。
  • 危険なコマンドを拒否する: rmsudoddなどの破壊的なコマンドを明示的にdenyリストに追加します。
  • 終了コードを処理する: Agentの出力にあるexitCodeをチェックして、スクリプトの失敗を検出し、処理します。0以外の終了コードは通常エラーを示し、詳細はstderrで確認できます。
  • 機密ファイルを保護する: denyReadを使用して、~/.ssh.envファイル、秘密鍵などの機密ファイルやディレクトリへのアクセスを防ぎます。