Kernel-Ebene eBPF-Sandbox zur Absicherung von LLM-Agent-Tool-Aufrufen, die über das Model Context Protocol (MCP) getätigt werden.
Sandboxing auf Kernel-Ebene für Tool-Aufrufe von LLM-Agenten über das Model Context Protocol (MCP).
MCPGuard fungiert als transparenter Proxy zwischen einem MCP-Client (dem Agenten/Runner) und einem MCP-Server-Subprozess und wendet auf jeden Tool-Aufruf drei abgestufte Verteidigungsschichten an. Die unterste Schicht ist in eBPF implementiert und erzwingt Capability-Richtlinien an der Systemaufruf-Grenze, sodass ein bösartiger MCP-Server die Richtlinie nicht umgehen kann, indem er sensibles Verhalten in seiner eigenen Implementierung fest codiert.
Dieses Repository enthält den Proxy, die eBPF-Programme, den 14-Server-/82-Fall-Benchmark und die Evaluierungsumgebung, die im zugehörigen Paper Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF verwendet werden.
| Schicht | Komponente | Zweck |
|---|
| L1 | proxy/policy_engine.py | Pro-Server-Capability-Richtlinie, abgeleitet aus dem MCP-Schema jedes Tools; Whitelists für Pfade, Netzwerkziele, Prozesse, Umgebungsvariablen. |
| L2 | proxy/argument_validator.py | Inspektion auf Anwendungsebene der Tool-Aufruf-Argumente: Pfad-Kanonisierung, URL-Validierung, Prompt-Injection-Erkennung, Erkennung von Env-Leak / Command-Injection, Scannen sensibler Schlüssel, Antwortbereinigung. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Durchsetzung auf Betriebssystemebene: Drei BPF-LSM-Programme (file_guard, net_guard, proc_guard) fangen open() / connect() / execve() ab, und ein Tracepoint-Programm (fork_guard) verfolgt Kindprozesse über sched_process_fork, sodass die Richtlinie über Forks hinweg übertragen wird. |
Sechs umschaltbare Verteidigungskonfigurationen (proxy/proxy_base.py) decken den in der Arbeit verwendeten Ablationsraum ab: C0 (Passthrough), C-AB (AgentBound-Baseline), C-app (L1 + L2), C-ebpf (nur L3), C-full (L1 + L2 + L3), C-AB+ebpf (AgentBound + L3).
.
├── proxy/ L1-Richtlinienmodul, L2-Argumentvalidator, L3-eBPF-Controller, AgentBound-Baseline
├── ebpf/ BPF-C-Quellen für Datei/Netzwerk/Prozess/Fork-Guards + Makefile + vmlinux.h
├── policies/ Pro-Server-JSON-Capability-Richtlinien (Standard + Überschreibungen)
├── servers/ 14 MCP-Server: 11 Python (Dateisystem, Notizen, Wetter, Shell, SQLite, Git, Env + bösartige/Trojaner-Varianten) + 3 JavaScript (servers/js/)
├── test_cases/ 82 Benchmark-Szenarien in 7 Kategorien (Dateilesen, Exfiltration, Env-Leak, Sandbox-Escape, Privilegieneskalation, sprachübergreifend, harmlos)
├── notes_data/ 170 gültige synthetische Notizen-JSON-Fixtures, die vom notes_server verwendet werden
├── runner/ evaluate.py, aggregate.py, agentbound_check.py, ebpf_edge_tests.py, latency_benchmark.py, override_workflow.py, smoke_test.py
└── EXECUTION_PLAN.md Phasenweise Reproduktionsanleitung
CONFIG_BPF_LSM=y, lsm=bpf in Kernel-Befehlszeile)clang 21 oder neuer mit BPF-Zielbpftool zum Laden von BPF-Programmen und -Mapsservers/js/)# 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 und C-AB+ebpf schlagen jetzt geschlossen fehl, wenn die BPF-LSM-Programme und gepinnten Maps nicht verfügbar sind. Führen Sie sie nur nach der Installation der eBPF-Schicht mit Root-Rechten aus.
Angriffsverhinderungsrate (APR), realisierbare Angriffs-APR (V-APR) und Falsch-Positiv-Rate (FPR) über den im Paper verankerten codex_20260523_full 14-Server-, 82-Fall-Benchmark:
| Konfiguration | APR | V-APR | Blockierte realisierbare Angriffe | 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 |
Die APR umfasst Angriffe, die unter C0 von Natur aus fehlschlagen. V-APR verwendet nur Angriffe, die unter C0 erfolgreich sind, als Nenner, was das konservativere Maß für die Verteidigungsabdeckung darstellt.
Der wiederholte Latenz-Benchmark für harmlose Aufrufe ist im internen Paper-Workspace als results/latency/codex_20260523_latency.md gespeichert. Er misst BN-01 (filesystem_server.read_file) mit 20 Aufwärmaufrufen und 100 gemessenen Aufrufen pro Konfiguration; C-full fügt +0,488 ms mediane Latenz relativ zu C0 hinzu und bleibt bei 1,141 ms p95 für diesen festen harmlosen Aufruf. Der öffentliche CodeSync-Baum schließt results/ aus, sodass externe Benutzer dieses Artefakt mit dem obigen Befehl neu generieren.
Der Audit-/Override-Workflow ist intern als results/audit/codex_20260523_override.md gespeichert. Er demonstriert, wie eine harmlose Ablehnung als strukturiertes Audit-Ereignis aufgezeichnet und durch Hinzufügen einer bereichsbezogenen Operator-Überschreibung unter einem policies/overrides-kompatiblen Layout aufgelöst wird.
Fokussierte eBPF-Edge-Tests sind intern als results/ebpf_edges/codex_20260523_ebpf_edges.md gespeichert. Sie decken das fehlgeschlossene Map-Verhalten, das Write-Allow-Verhalten des Arbeitsbereichs, die Verweigerung von Verzeichnispräfix-Grenzen, die Verweigerung von /tmp-Staging und die Verweigerung von Localhost-Exfiltration ab.
Die AgentBound-artige Baseline-Prüfung ist intern als results/agentbound/codex_20260523_agentbound.md gespeichert. Sie dokumentiert, dass C-AB eine Pro-Server-Reproduktion auf Anwendungsebene ist, und verifiziert die erwartete argument-sichtbare Abdeckung und den implementierungsversteckten blinden Fleck.
Der MCP-Server wird als nicht vertrauenswürdig betrachtet. Er kann gutartig, aber falsch konfiguriert, absichtlich bösartig oder eine trojanisierte Abzweigung eines legitimen Servers sein. Der Agent/Runner und das Host-Betriebssystem werden als vertrauenswürdig betrachtet. Die eBPF-Schicht geht davon aus, dass der Kernel nicht kompromittiert ist; Privilegieneskalationen im Kernel (CWE-269 in Kernelmodulen) sind nicht im Geltungsbereich.
Ein BibTeX-Eintrag wird hier hinzugefügt, sobald das Paper veröffentlicht ist.
Siehe CONTRIBUTING.md. Alle Mitwirkenden müssen Metas CLA unterzeichnen.
Um ein Sicherheitsproblem zu melden, siehe SECURITY.md. Bitte erstellen Sie keine öffentlichen GitHub-Issues für Sicherheitsmeldungen.
MIT – siehe LICENSE.