シェル実行

shell ツールは PRX の 3 つのコアツールの 1 つで、default_tools() と all_tools() の両方のレジストリで利用可能です。設定可能なサンドボックス内で OS レベルのコマンド実行を提供し、エージェントが起動するコマンドが厳格な分離、時間制限、出力制約の下で実行されることを保証します。

LLM がシェルコマンドの実行が必要と判断したとき -- パッケージのインストール、コードのコンパイル、システム状態のクエリ、スクリプトの実行 -- コマンド文字列を指定して shell ツールを呼び出します。PRX は設定されたサンドボックスバックエンドで実行をラップし、デフォルト 60 秒のタイムアウトを強制し、出力を 1 MB に制限し、子プロセスを起動する前に機密性の高い環境変数を除去します。

シェルツールは通常、PRX のツール群の中で最も強力かつ最も制限されるツールです。セキュリティポリシーエンジンの主要なターゲットであり、多くのデプロイメントでは実行前に人間の承認を要求する supervised としてマークされています。

設定

シェルツール自体には専用の設定セクションがありません。その動作はセキュリティサンドボックスとリソース制限を通じて制御されます:

[security.sandbox]
enabled = true
backend = "auto"         # "auto" | "landlock" | "firejail" | "bubblewrap" | "docker" | "none"

# カスタム Firejail 引数（backend = "firejail" の場合）
firejail_args = ["--net=none", "--noroot"]

[security.sandbox.docker]
image = "prx-sandbox:latest"
network = "none"
memory_limit = "256m"
cpu_limit = "1.0"

[security.sandbox.bubblewrap]
allow_network = false
writable_paths = ["/tmp"]
readonly_paths = ["/usr", "/lib"]

[security.resources]
max_memory_mb = 512
max_cpu_time_seconds = 60
max_subprocesses = 10
memory_monitoring = true

シェルを supervised としてマークする（呼び出しごとに承認を要求する）場合:

[security.tool_policy.tools]
shell = "supervised"

サンドボックスバックエンド

PRX は 5 つのサンドボックスバックエンドをサポートしています。backend = "auto" の場合、PRX は以下の優先順位で利用可能なバックエンドを探索し、最初に見つかったものを選択します:

バックエンド	プラットフォーム	分離レベル	オーバーヘッド	備考
Landlock	Linux (5.13+)	ファイルシステム LSM	最小	カーネルネイティブ、追加依存なし。カーネルレベルでファイルシステムパスを制限。
Firejail	Linux	フル（ネットワーク、ファイルシステム、PID）	低	ユーザー空間サンドボックス。ネットワーク分離の --net=none、PID ネームスペース、seccomp フィルタリングをサポート。
Bubblewrap	Linux, macOS	ネームスペースベース	低	ユーザーネームスペースを使用。書き込み可能/読み取り専用パスリストを設定可能。
Docker	全て	フルコンテナ	高	使い捨てコンテナ内でコマンドを実行。最大の分離だが最大のレイテンシ。
None	全て	アプリケーション層のみ	なし	OS レベルの分離なし。PRX はタイムアウトと出力制限を引き続き強制するが、プロセスは完全な OS アクセスを持つ。

Landlock

Landlock はカーネル 5.13+ で利用可能な Linux Security Module です。root 権限を必要とせずにカーネルレベルでファイルシステムアクセスを制限します。PRX は Landlock を使用して、シェルコマンドが読み書きできるパスを制限します。

Firejail

Firejail は Linux ネームスペースと seccomp による包括的なサンドボックスを提供します。カスタム引数は firejail_args で渡すことができます:

[security.sandbox]
backend = "firejail"
firejail_args = ["--net=none", "--noroot", "--nosound", "--no3d"]

Bubblewrap

Bubblewrap (bwrap) はユーザーネームスペースを使用して最小限のサンドボックス環境を作成します。Firejail より軽量で、一部の macOS 設定でも動作します:

[security.sandbox.bubblewrap]
allow_network = false
writable_paths = ["/tmp", "/home/user/workspace"]
readonly_paths = ["/usr", "/lib", "/bin"]

Docker

Docker はフルコンテナ分離を提供します。各コマンドは設定されたイメージに基づくフレッシュなコンテナで実行されます:

[security.sandbox.docker]
image = "prx-sandbox:latest"
network = "none"
memory_limit = "256m"
cpu_limit = "1.0"

使用方法

シェルツールはエージェンティックループ中に LLM によって呼び出されます。エージェントの会話で、LLM は以下のようなツール呼び出しを生成します:

{
  "name": "shell",
  "arguments": {
    "command": "ls -la /home/user/project"
  }
}

CLI では、エージェント出力でシェルツールの呼び出しを確認できます。ツール呼び出しには、実行されるコマンドと使用中のサンドボックスバックエンドが表示されます。

実行フロー

1. LLM が command 引数を持つ shell ツール呼び出しを生成
2. セキュリティポリシーエンジンが呼び出しの許可、拒否、または監視要否を確認
3. supervised の場合、PRX は続行前にユーザーの承認を求める
4. サンドボックスバックエンドが適切な分離レイヤーでコマンドをラップ
5. 環境変数がサニタイズされる（下記参照）
6. コマンドが 60 秒のタイムアウトで実行
7. stdout と stderr がキャプチャされ、必要に応じて 1 MB に切り詰め
8. 結果が成功/失敗ステータスを含む ToolResult として LLM に返される

パラメーター

パラメーター	型	必須	デフォルト	説明
command	string	はい	--	実行するシェルコマンド。/bin/sh -c（または同等のもの）に渡される。

ツールは以下を含む ToolResult を返します:

フィールド	型	説明
success	bool	コマンドがコード 0 で終了した場合 true
output	string	stdout と stderr の結合出力、1 MB に切り詰め
error	string?	コマンドが失敗またはタイムアウトした場合のエラーメッセージ

環境変数サニタイズ

シェルツールは子プロセスに厳密なホワイトリストの環境変数のみを渡します。これにより、デーモンの環境に存在する可能性のある API キー、トークン、シークレットの偶発的な漏洩を防ぎます。

許可される環境変数:

変数	目的
PATH	実行可能ファイルの検索パス
HOME	ユーザーホームディレクトリ
TERM	ターミナルタイプ
LANG	ロケール言語
LC_ALL	ロケールオーバーライド
LC_CTYPE	文字タイプロケール
USER	現在のユーザー名
SHELL	デフォルトシェルパス
TMPDIR	一時ディレクトリ

その他のすべての変数 -- API_KEY、AWS_SECRET_ACCESS_KEY、GITHUB_TOKEN、OPENAI_API_KEY、およびカスタム変数を含む -- は子プロセスの環境から除去されます。これは設定で上書きできないハードコードされたセキュリティ境界です。

リソース制限

制限	デフォルト	設定可能	説明
タイムアウト	60 秒	security.resources.max_cpu_time_seconds	コマンドあたりの最大ウォールクロック時間
出力サイズ	1 MB	--	stdout + stderr の最大結合サイズ
メモリ	512 MB	security.resources.max_memory_mb	コマンドあたりの最大メモリ使用量
サブプロセス	10	security.resources.max_subprocesses	生成される子プロセスの最大数

コマンドがタイムアウトを超過した場合、PRX は SIGTERM を送信し、猶予期間後に SIGKILL を送信します。ツール結果はタイムアウトをエラーとして報告します。

出力が 1 MB を超過した場合、出力は切り詰められ、切り詰めを示すメモが付加されます。

セキュリティ

• サンドボックス分離: コマンドは設定されたサンドボックスバックエンド内で実行され、ファイルシステム、ネットワーク、プロセスアクセスを制限
• 環境変数サニタイズ: ホワイトリストに登録された 9 つの環境変数のみが子プロセスに渡される
• ポリシーエンジン: すべてのシェル呼び出しは実行前にセキュリティポリシーエンジンを通過
• 監査ログ: security.audit.enabled = true の場合、すべてのシェルコマンドとその結果が監査ログに記録
• 監視モード: シェルツールはツールポリシーで supervised としてマークでき、各実行前にユーザーの明示的な承認が必要
• リソース制限: タイムアウト、メモリ、出力サイズ、サブプロセス数のハード制限によりリソース枯渇を防止

脅威の軽減

シェルツールはプロンプトインジェクション攻撃の主要なベクトルです。攻撃者が LLM の推論に影響を与えることができた場合（例えば悪意のあるドキュメントコンテンツを通じて）、コマンドを実行するためにシェルツールが使用されます。PRX は以下の方法でこれを軽減します:

1. サンドボックス隔離 -- 悪意のあるコマンドが実行されても、制限されたファイルシステムとネットワークアクセスで実行される
2. 環境変数除去 -- API キーとシークレットは子プロセスで利用不可
3. 監視モード -- ヒューマンインザループが各コマンドを実行前にレビュー可能
4. 監査証跡 -- すべてのコマンドがフォレンジックレビュー用に記録

関連

• セキュリティサンドボックス -- サンドボックスバックエンドの詳細ドキュメント
• ポリシーエンジン -- ツールアクセス制御ルール
• 設定リファレンス -- security.sandbox と security.resources フィールド
• ツール概要 -- 全 46+ ツールとレジストリシステム