カーネルレベルの eBPF サンドボックス - Model Context Protocol (MCP) を介して行われる LLM エージェントのツール呼び出しを保護します。
Model Context Protocol (MCP) を通じて行われる LLM エージェントのツール呼び出しに対するカーネルレベルのサンドボックス化。
MCPGuard は MCP クライアント (エージェント / ランナー) と MCP サーバーサブプロセスの間に透過プロキシとして位置し、すべてのツール呼び出しに対して 3 層の防御を適用します。最下層は eBPF で実装され、システムコール境界でケイパビリティポリシーを強制するため、悪意のある MCP サーバーが自身の実装内に機密性の高い動作をハードコードしてポリシーを回避することはできません。
このリポジトリには、プロキシ、eBPF プログラム、14 サーバー / 82 ケースのベンチマーク、および付随論文 Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF で使用された評価ハーネスが含まれています。
| 層 | コンポーネント | 目的 |
|---|---|---|
| L1 | proxy/policy_engine.py | 各ツールの MCP スキーマから導出されたサーバーごとのケイパビリティポリシー。パス、ネットワーク宛先、プロセス、環境変数の許可リスト。 |
| L2 | proxy/argument_validator.py | ツール呼び出し引数のアプリケーションレベル検査: パスの正規化、URL 検証、プロンプトインジェクション検出、環境変数漏洩 / コマンドインジェクション検出、機密キースキャン、レスポンスのサニタイズ。 |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | OS レベルの強制: 3 つの BPF LSM プログラム (file_guard、net_guard、proc_guard) が open() / connect() / execve() をインターセプトし、1 つのトレースポイントプログラム (fork_guard) が sched_process_fork を介して子プロセスを追跡することで、ポリシーが fork をまたいで引き継がれます。 |
6 つの切り替え可能な防御構成 (proxy/proxy_base.py) が、論文で使用されたアブレーション空間をカバーします: C0 (パススルー)、C-AB (AgentBound ベースライン)、C-app (L1 + L2)、C-ebpf (L3 のみ)、C-full (L1 + L2 + L3)、C-AB+ebpf (AgentBound + L3)。
.
├── proxy/ L1 ポリシーエンジン、L2 引数バリデータ、L3 eBPF コントローラ、AgentBound ベースライン
├── ebpf/ file/net/proc/fork ガード用の BPF C ソース + Makefile + vmlinux.h
├── policies/ サーバーごとの JSON ケイパビリティポリシー (デフォルト + オーバーライド)
├── servers/ 14 の MCP サーバー: 11 の Python (filesystem、notes、weather、shell、sqlite、git、env + 悪意のある / トロイの木馬バリアント) + 3 の JavaScript (servers/js/)
├── test_cases/ 7 カテゴリにわたる 82 のベンチマークシナリオ (file_read、exfiltration、env_leak、sandbox_escape、priv_escalation、cross_language、benign)
├── notes_data/ notes_server で使用される 170 の有効な合成ノート JSON フィクスチャ
├── runner/ evaluate.py、aggregate.py、agentbound_check.py、ebpf_edge_tests.py、latency_benchmark.py、override_workflow.py、smoke_test.py
└── EXECUTION_PLAN.md フェーズごとの再現手順
CONFIG_BPF_LSM=y、カーネルコマンドラインに lsm=bpf)clang 21 以降bpftoolservers/js/ 配下の JavaScript MCP サーバー専用)# Build the eBPF programs
cd ebpf && make && cd ..
# Smoke test (one server, a handful of cases)
python3 runner/smoke_test.py
# Full benchmark for one configuration
python3 runner/evaluate.py --config C-full --run-id trial
# Aggregate a reproduced run
python3 runner/aggregate.py --run-id trial
# Reproduce the steady-state latency table after installing eBPF
sudo python3 runner/latency_benchmark.py --run-id codex_20260523_latency --iterations 100 --warmup 20
# Reproduce the audit/override workflow
python3 runner/override_workflow.py --run-id codex_20260523_override
# Run focused eBPF edge tests after installing eBPF
sudo python3 runner/ebpf_edge_tests.py --run-id codex_20260523_ebpf_edges
# Run AgentBound-style baseline conformance checks
python3 runner/agentbound_check.py --run-id codex_20260523_agentbound
C-ebpf、C-full、C-AB+ebpf は、BPF LSM プログラムとピン留めされたマップが利用できない場合、フェイルクローズするようになりました。これらは root 権限で eBPF 層をインストールした後にのみ実行してください。
単一の固定された実行 codex_20260523_full (14 サーバー、82 ケースのベンチマーク。これは fx_r のカテゴリ別プロファイルです — 論文の表 1 は N=5 の平均を報告しているため、ここでの C-app は 13/48 と表示され、平均の 12/48 とは異なります) における、攻撃防止率 (APR)、実行可能攻撃 APR (V-APR)、および誤検知率 (FPR):
| 構成 | APR | V-APR | ブロックされた実行可能攻撃 | FPR |
|---|---|---|---|---|
| C0 | 21.3% | 0.0% | 0/48 | 0/21 |
| C-AB | 37.7% | 20.8% | 10/48 | 0/21 |
| C-app | 42.6% | 27.1% | 13/48 | 0/21 |
| C-ebpf | 60.7% | 50.0% | 24/48 | 0/21 |
| C-full | 68.9% | 60.4% | 29/48 | 0/21 |
| C-AB+ebpf | 67.2% | 58.3% | 28/48 | 0/21 |
APR には C0 で本質的に失敗する攻撃が含まれます。V-APR は C0 で成功する攻撃のみを分母として使用しており、これは防御カバレッジのより保守的な指標です。
良性呼び出しの反復レイテンシベンチマークは、内部論文ワークスペースに results/latency/codex_20260523_latency.md として保存されています。これは BN-01 (filesystem_server.read_file) を 20 回のウォームアップ呼び出しと構成ごとに 100 回の測定呼び出しで測定します。C-full は C0 に対して中央値レイテンシが +0.488 ms 増加し、この固定された良性呼び出しでは p95 が 1.141 ms のままです。公開 CodeSync ツリーには results/ が含まれていないため、外部ユーザーは上記のコマンドでこの成果物を再生成します。
監査 / オーバーライドワークフローは、内部に results/audit/codex_20260523_override.md として保存されています。これは、良性の拒否が構造化された監査イベントとして記録され、policies/overrides 互換のレイアウトの下でスコープ付きオペレーターオーバーライドを追加することによって解決される方法を示しています。
集中的な eBPF エッジテストは、内部に results/ebpf_edges/codex_20260523_ebpf_edges.md として保存されています。これらは、フェイルクローズのマップ可用性、ワークスペース書き込み許可動作、ディレクトリプレフィックス境界の拒否、/tmp ステージングの拒否、および localhost への持ち出しの拒否をカバーしています。
AgentBound スタイルのベースライン検査は、内部に results/agentbound/codex_20260523_agentbound.md として保存されています。これは、C-AB がサーバーごとのアプリケーションレベルの再現であることを文書化し、期待される引数可視カバレッジと実装隠蔽の盲点を検証します。
MCP サーバーは信頼されていないものとして扱われます。良性だが設定ミス、意図的に悪意がある、または正規サーバーのトロイの木馬化されたフォークである可能性があります。エージェント / ランナーとホスト OS は信頼されています。eBPF 層はカーネルが侵害されていないことを前提としています。カーネル内の権限昇格 (カーネルモジュールにおける CWE-269) は対象外です。
論文が公開され次第、BibTeX エントリがここに追加されます。
CONTRIBUTING.md を参照してください。すべてのコントリビューターは Meta の CLA に署名する必要があります。
セキュリティ問題を報告するには、SECURITY.md を参照してください。セキュリティ報告のために公開 GitHub issue を作成しないでください。
MIT — LICENSE を参照してください。