Enterprise AI Agent Sandbox

エージェント型AIワークフローにサンドボックス実行を組み込むためのセキュリティフレームワーク。Claude Code、Codex、Cursor、その他のAIエージェントが実行される任意のフォルダにコネクタを配置するだけで、特権コマンドはすべて人間の承認者にエスカレーションされ、エージェントのコンテキスト外で実行され、出力はモデルにフィードバックされて続行できます。

アーキテクチャ

フォルダコネクタは、サンドボックスをプロジェクトに橋渡しします:

• Claude Code フックはツール呼び出しをインターセプトし、特権操作を人間の承認者にエスカレーションし、キャプチャした出力を deny 決定内に返すため、ツールがエージェント権限で実行されることはありません

• MCP サーバー (run_privileged, check_request, sandbox_status) は Model Context Protocol 上で同じループを提供します — Claude Code、Codex、Cursor、Windsurf で動作します

• フォルダキュー (.sandbox/escalations/) はバスです: アトミックファイル操作 (os.replace, os.rename) が、4つの無関係なプロセス (フックサブプロセス、MCPサーバー、承認者ターミナル、ダッシュボード) 間で承認を調整します

• ポリシーエンジンはシェルコマンド、ファイル書き込み、ネットワークリクエスト、読み取りを分類します — 4つのエスカレーショントリガーと、最上位層としてのヒューマン・イン・ザ・ループ

Related MCP server: Approval Gate

Quick Start

# Install the connector
python -m pip install -e ".[dev]"

# Initialize a folder
sandbox init . --claude --mcp

# In one terminal: watch for escalations
sandbox watch .

# In another: use Claude Code or the MCP tools as normal
# Privileged commands will appear in the `watch` terminal for approval

仕組み

1. エージェントがコマンドを実行しようとする — Claude Code の PreToolUse フックがそれをインターセプトします

2. フックが分類してエスカレーションする — 許可リストにないシェルコマンドはフォルダキューに送られます

3. 人間が sandbox watch で承認する — 承認者はコマンドをエージェントの外部で実行します

4. 出力がモデルに返される — permissionDecision:"deny" にラップされ、stdout が reason 文字列に含まれます

5. エージェントは続行する — 結果を受け取りましたが、それ自体が権限を持つことはありません

MCP チャネルも同様に動作します: run_privileged はキャプチャされた出力を含むツール結果を返します。

マイルストーン

• ✅ マイルストーン 0 — 基盤 (バグ修正、パス封じ込め、監査の再水和)

• ✅ マイルストーン 1 — ループ (PreToolUse フック、フォルダキュー、CLI 承認)

• ✅ マイルストーン 2 — MCP チャネル (run_privileged, check_request, sandbox_status)

• ✅ マイルストーン 3 — フォルダレコード (復元可能なオリジナル、連鎖監査、PostToolUse)

• ✅ マイルストーン 4 — その他のトリガー (完全な分類器、記憶された決定、SessionStart コンテキスト)

• ✅ マイルストーン 5 — サーフェス (REST ルート、アンインストール、ドキュメント)

すべてのマイルストーンが完了しました。 完全な技術リファレンスは docs/CONNECTOR.md を参照してください。

Testing

# Run all tests (117 passing)
python -m pytest -q

# Test the loop with a real hook subprocess and background approver
python -m pytest tests/integration/test_connector_loop.py -v

# Test the MCP channel
python -m pytest tests/integration/test_mcp_tools.py -v

Project Structure

src/sandbox/
├── connector/           # Folder connector (queue, hooks, policy, MCP)
├── launcher/            # M1 jailed launcher (job objects, jail, shims)
├── audit/               # Chained audit log with tamper detection
├── broker/              # Non-AI privilege executor
├── fs/                  # Path containment and validation
├── agents/              # Multi-agent sandbox orchestrator
├── api/                 # FastAPI routes and WebSocket
└── ...

主要な設計決定

• フォルダがバス: NTFS 上のアトミックファイル操作が4つの独立したプロセスを調整します (インメモリ状態なし、オープンポートなし、再起動後も存続)

• deny が出力を運ぶ: ツールはエージェント内で実行されず、出力は reason 文字列に貼り戻されます

• CLI ファーストの承認: ヘッドレスで SSH 経由で動作し、ブラウザ依存なし

• フェイルクローズ: 内部エラーは黙って許可するのではなくブロックします

• 削除不可能な自己保護: 書き込み拒否の .sandbox/** とシェル拒否の \.sandbox は、ポリシーが読み込まれるたびに再注入されます — エージェントは自身の制約を削除できません

License

[未定]