Sandbox eBPF a livello di kernel per proteggere le chiamate agli strumenti degli agenti LLM effettuate tramite il Model Context Protocol (MCP)
Sandboxing a livello di kernel per le chiamate di strumenti degli agenti LLM effettuate tramite il Model Context Protocol (MCP).
MCPGuard si pone come proxy trasparente tra un client MCP (l'agente / runner) e un sottoprocesso del server MCP, applicando tre livelli di difesa a ogni invocazione di strumento. Il livello più basso è implementato in eBPF e applica le policy di capability al confine delle system call, così un server MCP malintenzionato non può aggirare la policy codificando comportamenti sensibili all'interno della propria implementazione.
Questo repository contiene il proxy, i programmi eBPF, il benchmark di 14 server / 82 casi e l'harness di valutazione utilizzati nel paper Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF.
| Livello | Componente | Scopo |
|---|
| L1 | proxy/policy_engine.py | Policy di capability per server derivata dallo schema MCP di ogni strumento; allowlist per percorsi, destinazioni di rete, processi e variabili d'ambiente. |
| L2 | proxy/argument_validator.py | Ispezione a livello applicativo degli argomenti delle chiamate agli strumenti: canonicalizzazione dei percorsi, validazione degli URL, rilevamento di prompt injection, rilevamento di env-leak / command injection, scansione di chiavi sensibili e sanificazione delle risposte. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Applicazione a livello di sistema operativo: tre programmi BPF LSM (file_guard, net_guard, proc_guard) intercettano open() / connect() / execve(), e un programma tracepoint (fork_guard) tiene traccia dei processi figli tramite sched_process_fork, così la policy si propaga attraverso le fork. |
Sei configurazioni di difesa commutabili (proxy/proxy_base.py) coprono lo spazio di ablazione usato nel paper: C0 (passthrough), C-AB (baseline AgentBound), C-app (L1 + L2), C-ebpf (solo 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 sources for file/net/proc/fork guards + Makefile + vmlinux.h
├── policies/ Per-server JSON capability policies (defaults + overrides)
├── servers/ 14 MCP servers: 11 Python (filesystem, notes, weather, shell, sqlite, git, env + malicious/trojan variants) + 3 JavaScript (servers/js/)
├── test_cases/ 82 benchmark scenarios across 7 categories (file_read, exfiltration, env_leak, sandbox_escape, priv_escalation, cross_language, benign)
├── notes_data/ 170 valid synthetic notes JSON fixtures used by notes_server
├── runner/ evaluate.py, aggregate.py, agentbound_check.py, ebpf_edge_tests.py, latency_benchmark.py, override_workflow.py, smoke_test.py
└── EXECUTION_PLAN.md Phase-by-phase reproduction instructions
CONFIG_BPF_LSM=y, lsm=bpf nella riga di comando del kernel)clang 21 o successivo con target BPFbpftool per il caricamento di programmi e mappe BPFservers/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 e C-AB+ebpf ora falliscono in modalità fail-closed se i programmi BPF LSM e le mappe pinnate non sono disponibili. Eseguirli solo dopo aver installato il layer eBPF con privilegi di root.
Tasso di prevenzione degli attacchi (APR), APR degli attacchi validi (V-APR) e tasso di falsi positivi (FPR) sul benchmark codex_20260523_full di 14 server e 82 casi adottato dal paper:
| Config | APR | V-APR | Attacchi validi bloccati | 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 |
L'APR include gli attacchi che falliscono intrinsecamente con C0. Il V-APR utilizza come denominatore solo gli attacchi che hanno successo con C0, che è la misura più conservativa della copertura difensiva.
Il benchmark di latenza con chiamate benigne ripetute è archiviato nello workspace interno del paper come results/latency/codex_20260523_latency.md. Misura BN-01 (filesystem_server.read_file) con 20 chiamate di warmup e 100 chiamate misurate per configurazione; C-full aggiunge +0.488 ms di latenza mediana rispetto a C0 e rimane a 1.141 ms come p95 per questa chiamata benigna fissa. L'albero pubblico CodeSync esclude results/, quindi gli utenti esterni rigenerano questo artefatto con il comando sopra.
Il workflow di audit/override è archiviato internamente come results/audit/codex_20260523_override.md. Dimostra come una negazione benigna venga registrata come evento di audit strutturato e risolta aggiungendo un override operatore con scope limitato in un layout compatibile con policies/overrides.
I test eBPF edge mirati sono archiviati internamente come results/ebpf_edges/codex_20260523_ebpf_edges.md. Coprono la disponibilità delle mappe in fail-closed, il comportamento di consenso alla scrittura nel workspace, la negazione al confine del prefisso di directory, la negazione dello staging in /tmp e la negazione dell'exfiltration verso localhost.
Il check della baseline in stile AgentBound è archiviato internamente come results/agentbound/codex_20260523_agentbound.md. Documenta che C-AB è una riproduzione per-server a livello applicativo e verifica la copertura attesa visibile dagli argomenti e il punto cieco nascosto nell'implementazione.
Il server MCP è considerato non fidato. Può essere benigno ma configurato in modo errato, intenzionalmente malintenzionato o una fork troianizzata di un server legittimo. L'agente / runner e il sistema operativo host sono considerati fidati. Il layer eBPF presuppone che il kernel non sia compromesso; le escalation di privilegi nel kernel (CWE-269 nei moduli del kernel) sono fuori scope.
Una voce BibTeX verrà aggiunta qui una volta che il paper sarà pubblicato.
Vedi CONTRIBUTING.md. Tutti i contributori devono firmare la CLA di Meta.
Per segnalare un problema di sicurezza, vedi SECURITY.md. Non aprire issue pubbliche su GitHub per le segnalazioni di sicurezza.
MIT — vedi LICENSE.