facebook/mcpguard-dynamicSandbox eBPF a livello di kernel per proteggere le chiamate agli strumenti degli agenti LLM effettuate tramite il Model Context Protocol (MCP)
Sandboxing a livello kernel per le chiamate agli strumenti degli agenti LLM effettuate tramite il Model Context Protocol (MCP).
MCPGuard si pone come proxy trasparente tra un client MCP (l'agente / il runner) e un sottoprocesso server MCP, applicando tre difese a livelli a ogni invocazione di strumento. Il livello più basso è implementato in eBPF e applica le politiche di capability al confine delle system call, così un server MCP malevolo non può aggirare la policy codificando comportamenti sensibili all'interno della propria implementazione.
Questo repository contiene il proxy, i programmi eBPF, il benchmark con 14 server / 82 casi e l'harness di valutazione utilizzato nel paper di accompagnamento 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 ciascuno strumento; allowlist per percorsi, destinazioni di rete, processi, 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, sanitizzazione delle risposte. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Applicazione a livello OS: tre programmi BPF LSM (file_guard, net_guard, proc_guard) intercettano open() / connect() / execve(), e un programma tracepoint (fork_guard) traccia i processi figli tramite sched_process_fork così la policy si propaga attraverso i fork. |
Sei configurazioni di difesa commutabili (proxy/proxy_base.py) coprono lo spazio di ablazione utilizzato 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 cmdline del kernel)clang 21 o superiore con target BPFbpftool per caricare 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 pinned non sono disponibili. Eseguirli solo dopo aver installato il livello eBPF
con privilegi di root.
Attack Prevention Rate (APR), viable-attack APR (V-APR) e False Positive
Rate (FPR) per la singola esecuzione pinned codex_20260523_full (benchmark con 14 server, 82 casi;
questo è il profilo per categoria fx_r — la Tabella 1 del paper
riporta medie N=5, quindi C-app qui legge 13/48 rispetto alla media 12/48):
| Config | APR | V-APR | Viable blocked | 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 include attacchi che falliscono intrinsecamente sotto C0. V-APR utilizza solo gli attacchi che hanno successo sotto C0 come denominatore, che è la misura più conservativa della copertura difensiva.
Il benchmark ripetuto di latenza su chiamate benigne è memorizzato nel 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 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 è memorizzato internamente come
results/audit/codex_20260523_override.md. Dimostra come un diniego benigno
viene registrato come evento di audit strutturato e risolto aggiungendo un override
operatore con ambito limitato sotto un layout compatibile con policies/overrides.
I test mirati sugli edge case eBPF sono memorizzati internamente come
results/ebpf_edges/codex_20260523_ebpf_edges.md. Coprono la disponibilità delle mappe in modalità fail-closed,
il comportamento di allow per scrittura nel workspace, il diniego al confine del prefisso di directory,
il diniego di staging in /tmp e il diniego di esfiltrazione verso localhost.
Il controllo baseline in stile AgentBound è memorizzato internamente come
results/agentbound/codex_20260523_agentbound.md. Documenta che C-AB è una
riproduzione a livello applicativo per server e verifica la copertura attesa
visibile dagli argomenti e il blind spot nascosto nell'implementazione.
Il server MCP è considerato non attendibile. Può essere benigno ma mal configurato, intenzionalmente malevolo o un fork trojanizzato di un server legittimo. L'agente / il runner e il sistema operativo host sono attendibili. Il livello eBPF assume che il kernel non sia compromesso; le escalation di privilegi in-kernel (CWE-269 nei moduli del kernel) sono fuori ambito.
Una voce BibTeX sarà aggiunta qui una volta pubblicato il paper.
Vedi CONTRIBUTING.md. Tutti i contributori devono firmare il CLA di Meta.
Per segnalare un problema di sicurezza, vedi SECURITY.md. Si prega di non aprire issue pubbliche su GitHub per segnalazioni di sicurezza.
MIT — vedi LICENSE.