MCPGuard-Dynamic

Песочница на уровне ядра для вызовов инструментов LLM-агента, выполняемых через Model Context Protocol (MCP).

MCPGuard работает как прозрачный прокси между MCP-клиентом (агентом / исполнителем) и дочерним процессом MCP-сервера, применяя три уровня защиты к каждому вызову инструмента. Самый нижний уровень реализован на eBPF и обеспечивает соблюдение политик возможностей на границе системных вызовов, поэтому вредоносный MCP-сервер не может обойти политику, зашив чувствительное поведение непосредственно в собственную реализацию.

Этот репозиторий содержит прокси, eBPF-программы, эталонный набор из 14 серверов / 82 сценариев, а также инфраструктуру оценки, используемые в сопутствующей статье Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF.

Архитектура

Шесть переключаемых конфигураций защиты (proxy/proxy_base.py) покрывают пространство абляции, использованное в статье: C0 (сквозной проход), C-AB (базовый уровень AgentBound), C-app (L1 + L2), C-ebpf (только 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

Требования

• Ядро Linux 6.x с включённым BPF LSM (CONFIG_BPF_LSM=y, lsm=bpf в параметрах ядра)
• clang 21 или новее с поддержкой цели BPF
• bpftool для загрузки BPF-программ и карт
• Python 3.12 (только стандартная библиотека — без сторонних зависимостей)
• Node.js 16+ (только для JavaScript MCP-серверов в servers/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 и C-AB+ebpf теперь переходят в режим fail-closed, если BPF LSM-программы и закреплённые карты недоступны. Запускайте их только после установки eBPF-уровня с правами root.

Ключевые результаты

Коэффициент предотвращения атак (APR), APR по жизнеспособным атакам (V-APR) и коэффициент ложных срабатываний (FPR) на зафиксированном в статье наборе codex_20260523_full из 14 серверов и 82 сценариев:

APR включает атаки, которые изначально завершаются неудачей при C0. В V-APR в знаменателе используются только атаки, успешные при C0, — это более консервативная мера покрытия защиты.

Повторный эталонный тест задержек для безвредных вызовов хранится во внутреннем рабочем пространстве статьи как results/latency/codex_20260523_latency.md. Он измеряет BN-01 (filesystem_server.read_file) с 20 прогревочными и 100 измеряемыми вызовами для каждой конфигурации; C-full добавляет +0.488 мс к медианной задержке относительно C0 и остаётся на уровне 1.141 мс p95 для этого фиксированного безвредного вызова. Публичное дерево CodeSync исключает results/, поэтому внешние пользователи воспроизводят этот артефакт с помощью команды выше.

Рабочий процесс аудита/переопределения хранится внутренне как results/audit/codex_20260523_override.md. Он демонстрирует, как безвредный отказ записывается в виде структурированного события аудита и разрешается добавлением ограниченного операторского переопределения в совместимой с policies/overrides структуре.

Сфокусированные eBPF-тесты крайних случаев хранятся внутренне как results/ebpf_edges/codex_20260523_ebpf_edges.md. Они покрывают недоступность карт в режиме fail-closed, разрешение записи в рабочую область, отказ на границе префикса каталога, отказ промежуточного хранения в /tmp и отказ эксфильтрации через localhost.

Проверка соответствия базовому уровню AgentBound хранится внутренне как results/agentbound/codex_20260523_agentbound.md. В ней документируется, что C-AB — это посегментное воспроизведение на уровне приложения, и проверяется ожидаемое покрытие для видимых аргументов и слепое пятно для скрытой реализации.

Модель угроз

MCP-сервер считается недоверенным. Он может быть безвредным, но неправильно сконфигурированным, намеренно вредоносным или троянизированным форком легитимного сервера. Агент / исполнитель и host-ОС считаются доверенными. eBPF-уровень предполагает, что ядро не скомпрометировано; повышение привилегий внутри ядра (CWE-269 в модулях ядра) выходит за рамки.

Цитирование

Запись BibTeX будет добавлена сюда после публикации статьи.

Участие

См. CONTRIBUTING.md. Все участники должны подписать CLA компании Meta.

Безопасность

Чтобы сообщить о проблеме безопасности, см. SECURITY.md. Пожалуйста, не создавайте публичные GitHub-issue для сообщений о безопасности.

Лицензия

MIT — см. LICENSE.