内核级 eBPF 沙盒，用于保护通过模型上下文协议（MCP）进行的 LLM 代理工具调用。
用于通过模型上下文协议（MCP）进行的 LLM 代理工具调用的内核级沙箱。
MCPGuard 作为透明代理位于 MCP 客户端（代理/运行器）与 MCP 服务器子进程之间，对每次工具调用施加三层防御。最底层基于 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 | 操作系统级强制：三个 BPF LSM 程序（file_guard、net_guard、proc_guard）拦截 open() / connect() / execve()，一个跟踪点程序（fork_guard）通过 sched_process_fork 跟踪子进程，以便策略在进程派生后延续。 |
六种可切换的防御配置（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/ 文件/网络/进程/进程分叉守卫的 BPF C 源码 + Makefile + vmlinux.h
├── policies/ 每服务器的 JSON 能力策略（默认 + 覆盖）
├── servers/ 14 个 MCP 服务器：11 个 Python（文件系统、笔记、天气、shell、sqlite、git、环境 + 恶意/木马变体） + 3 个 JavaScript（servers/js/）
├── test_cases/ 82 个基准测试场景，涵盖 7 个类别（文件读取、数据外泄、环境泄露、沙箱逃逸、权限提升、跨语言、良性）
├── notes_data/ 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 服务器）# 构建 eBPF 程序
cd ebpf && make && cd ..
# 冒烟测试（一个服务器，少量用例）
python3 runner/smoke_test.py
# 一种配置下的完整基准测试
python3 runner/evaluate.py --config C-full --run-id trial
# 汇总复现的运行结果
python3 runner/aggregate.py --run-id trial
# 在安装 eBPF 后复现稳态延迟表
sudo python3 runner/latency_benchmark.py --run-id codex_20260523_latency --iterations 100 --warmup 20
# 复现审计/覆盖工作流
python3 runner/override_workflow.py --run-id codex_20260523_override
# 在安装 eBPF 后运行聚焦的 eBPF 边缘测试
sudo python3 runner/ebpf_edge_tests.py --run-id codex_20260523_ebpf_edges
# 运行 AgentBound 风格的基线合规性检查
python3 runner/agentbound_check.py --run-id codex_20260523_agentbound
C-ebpf、C-full 和 C-AB+ebpf 现在在 BPF LSM 程序和固定映射不可用时自动失败关闭。请仅在以 root 权限安装 eBPF 层后运行它们。
攻击阻止率（APR）、可行攻击 APR（V-APR）以及误报率（FPR），基于论文中固定的 codex_20260523_full 14 服务器、82 用例基准测试：
APR 包含在 C0 下本身就会失败的攻击。V-APR 仅使用在 C0 下成功的攻击作为分母，这是防御覆盖范围更保守的度量。
重复的良性调用延迟基准测试存储在内部论文工作区中的 results/latency/codex_20260523_latency.md。它测量了 BN-01（filesystem_server.read_file），每次配置进行 20 次预热调用和 100 次测量调用；相对于 C0，C-full 增加的中位延迟为 +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 分段拒绝以及本地主机数据外泄拒绝。
AgentBound 风格的基线检查内部存储在 results/agentbound/codex_20260523_agentbound.md。它记录了 C-AB 是每个服务器的应用程序级复现，并验证了预期的参数可见覆盖范围和实现隐藏盲点。
MCP 服务器被视为不可信。它可能是良性但配置错误的、故意恶意的，或者是合法服务器的木马分支。代理/运行器和主机操作系统是可信的。eBPF 层假设内核未被攻破；内核模块中的内核级权限提升（CWE-269）不在范围内。
论文发表后，此处将添加 BibTeX 条目。
参见 CONTRIBUTING.md。所有贡献者必须签署 Meta 的 CLA。
如需报告安全问题，请参见 SECURITY.md。请勿针对安全报告在 GitHub 上提交公共问题。
MIT — 参见 LICENSE。
| 配置 | 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 |