MCPGuard-Dynamic

Sandboxing a nivel de kernel para llamadas a herramientas de agentes LLM realizadas a través del Protocolo de Contexto de Modelo (MCP).

MCPGuard actúa como un proxy transparente entre un cliente MCP (el agente / ejecutor) 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 las llamadas al sistema, de modo que un servidor MCP malicioso no pueda eludir la política codificando comportamiento sensible dentro de 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.

Arquitectura

Seis configuraciones de defensa intercambiables (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).

Estructura del Repositorio

.
├── proxy/        Motor de políticas L1, validador de argumentos L2, controlador eBPF L3, línea base AgentBound
├── ebpf/         Fuentes C de BPF para guardianes de archivo/red/proc/fork + Makefile + vmlinux.h
├── policies/     Políticas de capacidades JSON por servidor (valores predeterminados + anulaciones)
├── servers/      14 servidores MCP: 11 Python (filesystem, notes, weather, shell, sqlite, git, env + variantes maliciosas/troyanas) + 3 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

Requisitos

• Kernel Linux 6.x con BPF LSM habilitado (CONFIG_BPF_LSM=y, lsm=bpf en la línea de comandos del kernel)
• clang 21 o más reciente con destino BPF
• bpftool para cargar programas y mapas BPF
• Python 3.12 (solo biblioteca estándar — sin dependencias de terceros)
• Node.js 16+ (solo para los servidores MCP JavaScript bajo servers/js/)

Inicio Rápido

# Compilar los programas eBPF
cd ebpf && make && cd ..

# Prueba rápida (un servidor, un puñado de casos)
python3 runner/smoke_test.py

# Benchmark completo para una configuración
python3 runner/evaluate.py --config C-full --run-id trial

# Agregar una ejecución reproducida
python3 runner/aggregate.py --run-id trial

# Reproducir la tabla de latencia en estado estable después de instalar eBPF
sudo python3 runner/latency_benchmark.py --run-id codex_20260523_latency --iterations 100 --warmup 20

# Reproducir el flujo de trabajo de auditoría/anulación
python3 runner/override_workflow.py --run-id codex_20260523_override

# Ejecutar pruebas específicas de eBPF después de instalar eBPF
sudo python3 runner/ebpf_edge_tests.py --run-id codex_20260523_ebpf_edges

# Ejecutar comprobaciones de conformidad de línea base estilo AgentBound
python3 runner/agentbound_check.py --run-id codex_20260523_agentbound

C-ebpf, C-full y C-AB+ebpf ahora fallan cerrados si los programas BPF LSM y los mapas anclados no están disponibles. Ejecútelos solo después de instalar la capa eBPF con privilegios de root.

Resultados Destacados

Tasa de Prevención de Ataques (APR), APR de ataques viables (V-APR) y Tasa de Falsos Positivos (FPR) en el benchmark de 14 servidores y 82 casos fijado en el artículo codex_20260523_full:

APR incluye ataques que fallan intrínsecamente bajo C0. V-APR utiliza solo ataques que tienen éxito bajo C0 como denominador, que 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 agrega +0.488 ms de latencia mediana en relación con C0 y se mantiene en 1.141 ms p95 para esta llamada benigna fija. El árbol público 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 ámbito bajo el diseño compatible con policies/overrides.

Las pruebas específicas de eBPF se almacenan internamente como results/ebpf_edges/codex_20260523_ebpf_edges.md. Cubren disponibilidad de mapas con fallo cerrado, comportamiento de escritura permitida en el espacio de trabajo, denegación en límite de prefijo de directorio, denegación de staging en /tmp y denegación de exfiltración a localhost.

La comprobació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.

Modelo de Amenazas

El servidor MCP se considera no confiable. Puede ser benigno pero mal configurado, intencionalmente malicioso o una bifurcación troyanizada de un servidor legítimo. El agente / ejecutor 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) están fuera del alcance.

Citación

Se añadirá una entrada BibTeX aquí una vez que se publique el artículo.

Contribuciones

Véase CONTRIBUTING.md. Todos los contribuyentes deben firmar el CLA de Meta.

Seguridad

Para reportar un problema de seguridad, véase SECURITY.md. No abra issues públicos de GitHub para informes de seguridad.

Licencia

MIT — véase LICENSE.