MCPGuard-Dynamic

Sandboxing a 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 do 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 das chamadas de sistema, de modo que um servidor MCP malicioso não possa contornar a política embutindo comportamento sensível em sua própria implementação.

Este repositório contém o proxy, os programas eBPF, o benchmark de 14 servidores / 82 casos e a estrutura de avaliação utilizados no artigo que o acompanha Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF.

Arquitetura

Seis configurações de defesa comutáveis (proxy/proxy_base.py) cobrem o espaço de ablação usado no artigo: C0 (passagem), C-AB (linha de base AgentBound), C-app (L1 + L2), C-ebpf (apenas L3), C-full (L1 + L2 + L3), C-AB+ebpf (AgentBound + L3).

Layout do Repositório

.
├── proxy/        Mecanismo de política L1, validador de argumentos L2, controlador eBPF L3, linha de base AgentBound
├── ebpf/         Código-fonte BPF C para guards de arquivo/rede/proc/fork + Makefile + vmlinux.h
├── policies/     Políticas de capacidade JSON por servidor (padrões + sobrescritas)
├── servers/      14 servidores MCP: 11 Python (filesystem, notes, weather, shell, sqlite, git, env + variantes maliciosas/trojan) + 3 JavaScript (servers/js/)
├── test_cases/   82 cenários de benchmark em 7 categorias (file_read, exfiltration, env_leak, sandbox_escape, priv_escalation, cross_language, benign)
├── notes_data/   170 fixtures JSON de notas sintéticas válidas usadas pelo 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   Instruções de reprodução fase por fase

Requisitos

• Kernel Linux 6.x com BPF LSM habilitado (CONFIG_BPF_LSM=y, lsm=bpf na linha de comando do kernel)
• clang 21 ou mais recente com destino BPF
• bpftool para carregar programas e mapas BPF
• Python 3.12 (apenas biblioteca padrão — sem dependências de terceiros)
• Node.js 16+ (apenas para os servidores MCP JavaScript em servers/js/)

Início Rápido

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

# Teste de fumaca (um servidor, alguns casos)
python3 runner/smoke_test.py

# Benchmark completo para uma configuração
python3 runner/evaluate.py --config C-full --run-id trial

# Agregar uma execução reproduzida
python3 runner/aggregate.py --run-id trial

# Reproduzir a tabela de latência em estado estável após instalar o eBPF
sudo python3 runner/latency_benchmark.py --run-id codex_20260523_latency --iterations 100 --warmup 20

# Reproduzir o fluxo de auditoria/sobrescrita
python3 runner/override_workflow.py --run-id codex_20260523_override

# Executar testes de borda eBPF focados após instalar o eBPF
sudo python3 runner/ebpf_edge_tests.py --run-id codex_20260523_ebpf_edges

# Executar verificações de conformidade de linha de base no estilo AgentBound
python3 runner/agentbound_check.py --run-id codex_20260523_agentbound

C-ebpf, C-full e C-AB+ebpf agora falham fechados se os programas BPF LSM e os mapas fixados não estiverem disponíveis. Execute-os somente após instalar a camada eBPF com privilégios de root.

Resultados Principais

Taxa de Prevenção de Ataques (APR), APR de ataques viáveis (V-APR) e Taxa de Falsos Positivos (FPR) no benchmark de 14 servidores e 82 casos do paper codex_20260523_full:

A APR inclui ataques que falham intrinsecamente sob C0. A V-APR usa apenas ataques que têm sucesso sob C0 como denominador, que é a medida mais conservadora de cobertura de defesa.

O benchmark de latência de chamadas benignas repetidas está armazenado no espaço de trabalho interno do paper como results/latency/codex_20260523_latency.md. Ele mede BN-01 (filesystem_server.read_file) com 20 chamadas de aquecimento 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/, portanto, usuários externos regeneram esse artefato com o comando acima.

O fluxo de auditoria/sobrescrita 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 uma sobrescrita de operador com escopo sob o layout compatível com policies/overrides.

Testes de borda eBPF focados estão armazenados internamente como results/ebpf_edges/codex_20260523_ebpf_edges.md. Eles cobrem disponibilidade de mapa fechado-falha, comportamento de permissão de escrita no espaço de trabalho, negação de limite de prefixo de diretório, negação de staging /tmp e negação de exfiltração de localhost.

A verificação de linha de base 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 o ponto cego de cobertura visível de argumentos esperado e a implementação oculta.

Modelo de Ameaça

O servidor MCP é tratado como não confiável. Pode ser benigno, mas mal configurado, intencionalmente malicioso ou uma bifurcação trojanizada de um servidor legítimo. O agente/runner e o sistema operacional host são confiáveis. A camada eBPF assume que o kernel está íntegro; escalonamentos de privilégio no kernel (CWE-269 em módulos do kernel) estão fora do escopo.

Citação

Uma entrada BibTeX será adicionada aqui assim que o artigo for publicado.

Contribuição

Veja CONTRIBUTING.md. Todos os contribuidores devem assinar o CLA da Meta.

Segurança

Para relatar um problema de segurança, veja SECURITY.md. Por favor, não abra issues públicas do GitHub para relatórios de segurança.

Licença

MIT — veja LICENSE.