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 LLM-Agent-Tool-Aufrufe ü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 bei jedem Tool-Aufruf drei geschichtete Verteidigungslinien 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 verdrahtet.
Dieses Repository enthält den Proxy, die eBPF-Programme, den Benchmark mit 14 Servern / 82 Fällen und die Evaluationsumgebung, die im begleitenden Paper Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF verwendet werden.
| Schicht | Komponente | Zweck |
|---|---|---|
| L1 | proxy/policy_engine.py | Capability-Richtlinie pro Server, abgeleitet aus dem MCP-Schema jedes Tools; Allowlists für Pfade, Netzwerkziele, Prozesse, Umgebungsvariablen. |
| L2 | proxy/argument_validator.py | Inspektion der Tool-Aufruf-Argumente auf Anwendungsebene: Pfad-Kanonisierung, URL-Validierung, Erkennung von Prompt-Injection, Erkennung von Env-Leaks / Command-Injection, Scannen sensibler Schlüssel, Bereinigung von Antworten. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Durchsetzung auf OS-Ebene: 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 erhalten bleibt. |
Sechs umschaltbare Verteidigungskonfigurationen (proxy/proxy_base.py) decken den im Paper 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 Policy Engine, L2 Argument Validator, L3 eBPF Controller, AgentBound-Baseline
├── ebpf/ BPF-C-Quellen für file/net/proc/fork Guards + Makefile + vmlinux.h
├── policies/ JSON-Capability-Richtlinien pro Server (Standardwerte + Overrides)
├── servers/ 14 MCP-Server: 11 Python (filesystem, notes, weather, shell, sqlite, git, env + bösartige/Trojaner-Varianten) + 3 JavaScript (servers/js/)
├── test_cases/ 82 Benchmark-Szenarien in 7 Kategorien (file_read, exfiltration, env_leak, sandbox_escape, priv_escalation, cross_language, benign)
├── notes_data/ 170 gültige synthetische Notes-JSON-Fixtures, die von 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 der Kernel-Cmdline)clang 21 oder neuer mit BPF-Targetbpftool 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 fehlgeschlossen 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.
Attack Prevention Rate (APR), viable-attack APR (V-APR) und False Positive
Rate (FPR) für den einzelnen gepinnten Lauf codex_20260523_full (14-Server-, 82-Fall-
Benchmark; dies ist das fx_r-Pro-Kategorie-Profil — Tabelle 1 des Papers
berichtet N=5-Mittelwerte, daher liest sich C-app hier als 13/48 gegenüber dem 12/48-Mittelwert):
| Konfiguration | APR | V-APR | Viable blockiert | 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 umfasst Angriffe, die unter C0 intrinsisch fehlschlagen. V-APR verwendet nur Angriffe, die unter C0 erfolgreich sind, als Nenner, was das konservativere Maß für die Verteidigungsabdeckung ist.
Der wiederholte Latenz-Benchmark für gutartige Aufrufe ist im internen Paper-
Workspace als results/latency/codex_20260523_latency.md gespeichert. Er misst BN-01
(filesystem_server.read_file) mit 20 Warmup-Aufrufen und 100 gemessenen Aufrufen pro
Konfiguration; C-full fügt +0,488 ms Median-Latenz relativ zu C0 hinzu und bleibt
bei 1,141 ms p95 für diesen festen gutartigen 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 gutartige Ablehnung
als strukturiertes Audit-Ereignis aufgezeichnet und durch Hinzufügen eines bereichsbezogenen
Operator-Overrides unter einem mit 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 Fail-Closed-Map-
Verfügbarkeit, Workspace-Schreib-Allow-Verhalten, Verzeichnispräfix-Grenzablehnung,
/tmp-Staging-Ablehnung und Localhost-Exfiltrations-Ablehnung ab.
Die Baseline-Prüfung im AgentBound-Stil 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 implementierungsverborgenen blinden Fleck.
Der MCP-Server wird als nicht vertrauenswürdig behandelt. Er kann gutartig-aber-fehkonfiguriert, absichtlich bösartig oder ein trojanisierter Fork eines legitimen Servers sein. Der Agent / Runner und das Host-Betriebssystem werden als vertrauenswürdig angesehen. Die eBPF-Schicht geht davon aus, dass der Kernel nicht kompromittiert ist; Privilegieneskalationen im Kernel (CWE-269 in Kernelmodulen) liegen außerhalb des Geltungsbereichs.
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 reichen Sie keine öffentlichen GitHub-Issues für Sicherheitsberichte ein.
MIT — siehe LICENSE.