facebook/mcpguard-dynamicSandbox eBPF a nivel de kernel para asegurar las llamadas a herramientas de agentes LLM realizadas a través del Protocolo de Contexto de Modelo (MCP)
Aislamiento a nivel de kernel para llamadas a herramientas de agentes LLM realizadas a través del Model Context Protocol (MCP).
MCPGuard actúa como un proxy transparente entre un cliente MCP (el agente / runner) y un subproceso de servidor MCP, aplicando tres capas de defensa a cada invocación de herramienta. La capa más baja está implementada en eBPF y aplica políticas de capacidades en el límite de llamadas al sistema, de modo que un servidor MCP malicioso no puede eludir la política codificando comportamientos sensibles directamente en su propia implementación.
Este repositorio contiene el proxy, los programas eBPF, el benchmark de 14 servidores / 82 casos y el arnés de evaluación utilizados en el artículo adjunto Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF.
| Capa | Componente | Propósito |
|---|---|---|
| L1 | proxy/policy_engine.py | Política de capacidades por servidor derivada del esquema MCP de cada herramienta; listas de permitidos para rutas, destinos de red, procesos, variables de entorno. |
| L2 | proxy/argument_validator.py | Inspección a nivel de aplicación de los argumentos de llamadas a herramientas: canonicalización de rutas, validación de URL, detección de inyección de prompts, detección de fuga de entorno / inyección de comandos, escaneo de claves sensibles, sanitización de respuestas. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Aplicación a nivel de SO: tres programas BPF LSM (file_guard, net_guard, proc_guard) interceptan open() / connect() / execve(), y un programa tracepoint (fork_guard) rastrea procesos hijos mediante sched_process_fork para que la política se propague a través de los forks. |
Seis configuraciones de defensa conmutables (proxy/proxy_base.py) cubren el espacio de ablación utilizado en el artículo: C0 (passthrough), C-AB (línea base AgentBound), C-app (L1 + L2), C-ebpf (solo L3), C-full (L1 + L2 + L3), C-AB+ebpf (AgentBound + L3).
.
├── proxy/ Motor de políticas L1, validador de argumentos L2, controlador eBPF L3, línea base AgentBound
├── ebpf/ Fuentes C de BPF para los guardas de file/net/proc/fork + Makefile + vmlinux.h
├── policies/ Políticas de capacidades JSON por servidor (valores por defecto + anulaciones)
├── servers/ 14 servidores MCP: 11 en Python (filesystem, notes, weather, shell, sqlite, git, env + variantes maliciosas/troyanizadas) + 3 en JavaScript (servers/js/)
├── test_cases/ 82 escenarios de benchmark en 7 categorías (file_read, exfiltration, env_leak, sandbox_escape, priv_escalation, cross_language, benign)
├── notes_data/ 170 fixtures JSON de notas sintéticas válidas utilizadas por 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 Instrucciones de reproducción fase por fase
CONFIG_BPF_LSM=y, lsm=bpf en la línea de comandos del kernel)clang 21 o superior con soporte para BPFbpftool para cargar programas y mapas 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 y C-AB+ebpf ahora fallan de forma segura (fail closed) si los programas BPF LSM y los mapas fijados (pinned maps) no están disponibles. Ejecútalos solo después de instalar la capa eBPF con privilegios de root.
Tasa de Prevención de Ataques (APR), APR de ataques viables (V-APR) y Tasa de Falsos Positivos (FPR) para la ejecución única fijada codex_20260523_full (benchmark de 14 servidores, 82 casos; este es el perfil por categoría fx_r — la Tabla 1 del artículo reporta medias de N=5, por lo que C-app aquí se lee 13/48 frente a la media de 12/48):
| Config | APR | V-APR | Viables bloqueados | 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 incluye ataques que fallan intrínsecamente bajo C0. V-APR utiliza solo ataques que tienen éxito bajo C0 como denominador, lo cual es la medida más conservadora de cobertura de defensa.
El benchmark de latencia de llamadas benignas repetidas se almacena en el espacio de trabajo interno del artículo como results/latency/codex_20260523_latency.md. Mide BN-01 (filesystem_server.read_file) con 20 llamadas de calentamiento y 100 llamadas medidas por configuración; C-full añade +0.488 ms de latencia mediana respecto a C0 y se mantiene en 1.141 ms de p95 para esta llamada benigna fija. El árbol público de CodeSync excluye results/, por lo que los usuarios externos regeneran este artefacto con el comando anterior.
El flujo de trabajo de auditoría/anulación se almacena internamente como results/audit/codex_20260523_override.md. Demuestra cómo una denegación benigna se registra como un evento de auditoría estructurado y se resuelve añadiendo una anulación de operador con alcance limitado bajo un diseño compatible con policies/overrides.
Las pruebas de borde focalizadas de eBPF se almacenan internamente como results/ebpf_edges/codex_20260523_ebpf_edges.md. Cubren la disponibilidad de mapas con fallo seguro (fail-closed), el comportamiento de permitir escritura en el espacio de trabajo, la denegación en el límite de prefijo de directorio, la denegación de staging en /tmp y la denegación de exfiltración a localhost.
La verificación de línea base estilo AgentBound se almacena internamente como results/agentbound/codex_20260523_agentbound.md. Documenta que C-AB es una reproducción a nivel de aplicación por servidor y verifica la cobertura esperada visible en argumentos y el punto ciego oculto en la implementación.
El servidor MCP se trata como no confiable. Puede ser benigno pero mal configurado, intencionalmente malicioso o un fork troyanizado de un servidor legítimo. El agente / runner y el SO anfitrión son confiables. La capa eBPF asume que el kernel no está comprometido; las escaladas de privilegios dentro del kernel (CWE-269 en módulos del kernel) quedan fuera del alcance.
Se añadirá aquí una entrada BibTeX una vez que se publique el artículo.
Consulte CONTRIBUTING.md. Todos los contribuyentes deben firmar el CLA de Meta.
Para reportar un problema de seguridad, consulte SECURITY.md. Por favor, no abra issues públicos en GitHub para informes de seguridad.