facebook/mcpguard-dynamicПесочница eBPF на уровне ядра для защиты вызовов инструментов LLM-агентов, совершаемых через Model Context Protocol (MCP)
Песочница на уровне ядра для вызовов инструментов LLM-агентов через Model Context Protocol (MCP).
MCPGuard работает как прозрачный прокси между MCP-клиентом (агентом / раннером) и подпроцессом MCP-сервера, применяя три уровня защиты к каждому вызову инструмента. Нижний уровень реализован на eBPF и обеспечивает соблюдение политик возможностей на границе системных вызовов, поэтому вредоносный MCP-сервер не может обойти политику, жёстко закодировав чувствительное поведение внутри своей реализации.
Этот репозиторий содержит прокси, программы eBPF, бенчмарк из 14 серверов / 82 сценариев и средство оценки, использованное в сопроводительной статье Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF.
| Уровень | Компонент | Назначение |
|---|---|---|
| L1 | proxy/policy_engine.py | Политика возможностей для каждого сервера, выводимая из MCP-схемы каждого инструмента; списки разрешённых путей, сетевых назначений, процессов, переменных окружения. |
| L2 | proxy/argument_validator.py | Проверка аргументов вызова инструмента на уровне приложения: канонизация путей, валидация URL, обнаружение prompt-injection, обнаружение утечки переменных окружения / command-injection, сканирование чувствительных ключей, санитизация ответов. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | Принудительное применение на уровне ОС: три программы BPF LSM (file_guard, net_guard, proc_guard) перехватывают open() / connect() / execve(), а одна программа tracepoint (fork_guard) отслеживает дочерние процессы через sched_process_fork, чтобы политика сохранялась при форках. |
Шесть переключаемых конфигураций защиты (proxy/proxy_base.py) покрывают пространство абляций, использованное в статье: C0 (passthrough), 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
CONFIG_BPF_LSM=y, lsm=bpf в командной строке ядра)clang 21 или новее с поддержкой BPF targetbpftool для загрузки программ и карт 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 и C-AB+ebpf теперь отказывают безопасно (fail closed), если программы BPF LSM
и закреплённые карты недоступны. Запускайте их только после установки слоя eBPF
с правами root.
Attack Prevention Rate (APR), viable-attack APR (V-APR) и False Positive
Rate (FPR) для единственного закреплённого запуска codex_20260523_full (бенчмарк из 14 серверов, 82 сценариев;
это профиль fx_r по категориям — в Таблице 1 статьи приводятся средние по N=5, поэтому C-app здесь показывает 13/48 против среднего 12/48):
| Конфигурация | APR | V-APR | Заблокировано жизнеспособных | 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 включает атаки, которые изначально не проходят при C0. V-APR использует в качестве знаменателя только атаки, которые успешны при C0, что является более консервативной мерой покрытия защиты.
Бенчмарк повторяющейся задержки benign-вызовов хранится во внутреннем рабочем пространстве статьи
как results/latency/codex_20260523_latency.md. Он измеряет BN-01
(filesystem_server.read_file) с 20 прогревочными вызовами и 100 измеряемыми вызовами на
конфигурацию; C-full добавляет +0.488 мс к медианной задержке относительно C0 и остаётся
на уровне 1.141 мс p95 для этого фиксированного benign-вызова. Публичное дерево CodeSync исключает
results/, поэтому внешние пользователи воспроизводят этот артефакт с помощью команды выше.
Рабочий процесс аудита/переопределения хранится внутри как
results/audit/codex_20260523_override.md. Он демонстрирует, как benign-отказ
записывается как структурированное событие аудита и разрешается путём добавления ограниченного
операторского переопределения в layout, совместимый с 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-сервер считается недоверенным. Он может быть benign, но неправильно настроенным, намеренно вредоносным или троянизированным форком легитимного сервера. Агент / раннер и хостовая ОС считаются доверенными. Слой eBPF предполагает, что ядро не скомпрометировано; повышения привилегий внутри ядра (CWE-269 в модулях ядра) вне области рассмотрения.
Запись BibTeX будет добавлена здесь после публикации статьи.
См. CONTRIBUTING.md. Все участники должны подписать CLA Meta.
Чтобы сообщить о проблеме безопасности, см. SECURITY.md. Пожалуйста, не создавайте публичные issues на GitHub для отчётов о безопасности.
MIT — см. LICENSE.