facebook/mcpguard-dynamicSandbox eBPF em nível de kernel para proteger chamadas de ferramentas do agente LLM feitas através do Model Context Protocol (MCP)
Sandboxing em nível de kernel para chamadas de ferramentas de agentes LLM feitas através do Model Context Protocol (MCP).
O MCPGuard atua como um proxy transparente entre um cliente MCP (o agente / runner) e um subprocesso de servidor MCP, aplicando três camadas de defesa a cada invocação de ferramenta. A camada mais baixa é implementada em eBPF e aplica políticas de capacidade na fronteira de chamadas de sistema, de modo que um servidor MCP malicioso não pode contornar a política codificando comportamento sensível diretamente em sua própria implementação.
Este repositório contém o proxy, os programas eBPF, o benchmark de 14 servidores / 82 casos e o harness de avaliação usados no artigo que o acompanha Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF.
| Camada | Componente | Propósito |
|---|---|---|
| L1 | proxy/policy_engine.py | Política de capacidade por servidor derivada do schema MCP de cada ferramenta; allowlists para caminhos, destinos de rede, processos, variáveis de ambiente. |
| L2 | proxy/argument_validator.py | Inspeção em nível de aplicação dos argumentos de chamadas de ferramentas: canonicalização de caminhos, validação de URL, detecção de prompt-injection, detecção de env-leak / command-injection, varredura de chaves sensíveis, sanitização de respostas. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Aplicação em nível de SO: três programas BPF LSM (file_guard, net_guard, proc_guard) interceptam open() / connect() / execve(), e um programa tracepoint (fork_guard) rastreia processos filhos via sched_process_fork para que a política se propague através de forks. |
Seis configurações de defesa alternáveis (proxy/proxy_base.py) cobrem o espaço de ablação usado no artigo: C0 (passthrough), C-AB (baseline AgentBound), C-app (L1 + L2), C-ebpf (apenas 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 na cmdline do kernel)clang 21 ou mais recente com target BPFbpftool para carregar programas e 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 e C-AB+ebpf agora falham de forma fechada se os programas
BPF LSM e os mapas fixados (pinned) estiverem indisponíveis. Execute-os apenas
após instalar a camada eBPF com privilégios de root.
Taxa de Prevenção de Ataques (APR), APR de ataques viáveis (V-APR) e Taxa de
Falsos Positivos (FPR) para a execução única fixada codex_20260523_full
(benchmark de 14 servidores, 82 casos; este é o perfil por categoria fx_r —
a Tabela 1 do artigo reporta médias de N=5, então C-app aqui lê 13/48 vs a
média de 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 |
A APR inclui ataques que falham intrinsecamente sob C0. A V-APR usa apenas ataques que têm sucesso sob C0 como denominador, o que é a medida mais conservadora de cobertura de defesa.
O benchmark de latência de chamadas benignas repetidas está armazenado no
workspace interno do artigo como results/latency/codex_20260523_latency.md.
Ele mede BN-01 (filesystem_server.read_file) com 20 chamadas de warmup e
100 chamadas medidas por configuração; C-full adiciona +0.488 ms de latência
mediana em relação a C0 e permanece em 1.141 ms p95 para esta chamada benigna
fixa. A árvore pública do CodeSync exclui results/, então usuários externos
regeneram este artefato com o comando acima.
O fluxo de trabalho de auditoria/override está armazenado internamente como
results/audit/codex_20260523_override.md. Ele demonstra como uma negação
benigna é registrada como um evento de auditoria estruturado e resolvida
adicionando um override de operador com escopo sob um layout compatível com
policies/overrides.
Os testes de borda focados em eBPF estão armazenados internamente como
results/ebpf_edges/codex_20260523_ebpf_edges.md. Eles cobrem disponibilidade
de mapas com falha fechada, comportamento de permissão de escrita no workspace,
negação de fronteira de prefixo de diretório, negação de staging em /tmp e
negação de exfiltração para localhost.
A verificação de baseline no estilo AgentBound está armazenada internamente
como results/agentbound/codex_20260523_agentbound.md. Ela documenta que
C-AB é uma reprodução em nível de aplicação, por servidor, e verifica a
cobertura esperada visível por argumentos e o ponto cego oculto na
implementação.
O servidor MCP é tratado como não confiável. Ele pode ser benigno-mas-mal-configurado, intencionalmente malicioso, ou um fork trojanizado de um servidor legítimo. O agente / runner e o SO hospedeiro são confiáveis. A camada eBPF assume que o kernel não está comprometido; escalações de privilégio dentro do kernel (CWE-269 em módulos do kernel) estão fora do escopo.
Uma entrada BibTeX será adicionada aqui assim que o artigo for publicado.
Veja CONTRIBUTING.md. Todos os contribuidores devem assinar o CLA da Meta.
Para reportar um problema de segurança, veja SECURITY.md. Por favor, não abra issues públicas no GitHub para relatórios de segurança.
MIT — veja LICENSE.