内核级 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 schema 推导出的按服务器能力策略；路径、网络目标、进程、环境变量的允许列表。 |
| 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()，以及一个 tracepoint 程序（fork_guard）通过 sched_process_fork 跟踪子进程，使策略能够跨 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/ 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 或更新版本，支持 BPF 目标bpftool，用于加载 BPF 程序和映射servers/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 程序和固定映射不可用时
会以失败关闭（fail closed）方式处理。请仅在以 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 次测量
调用；相对于 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 暂存拒绝以及
localhost 数据外泄拒绝。
AgentBound 风格基线检查存储在内部，路径为
results/agentbound/codex_20260523_agentbound.md。它记录了 C-AB 是按
服务器、应用层的复现，并验证了预期的参数可见覆盖范围和实现隐藏盲点。
MCP 服务器被视为不可信。它可能是良性但配置错误、故意恶意，或者是合法 服务器的木马化分支。智能体 / 运行器和宿主操作系统被视为可信。eBPF 层 假设内核未被攻陷；内核内权限提升（内核模块中的 CWE-269）不在范围内。
论文发表后，将在此处添加 BibTeX 条目。
参见 CONTRIBUTING.md。所有贡献者必须签署 Meta 的 CLA。
要报告安全问题，请参见 SECURITY.md。请勿为安全报告提交 公开的 GitHub issue。
MIT——参见 LICENSE。