MCPGuard-Dynamic

MCP(Model Context Protocol)를 통해 이루어지는 LLM 에이전트 도구 호출을 위한 커널 수준 샌드박싱.

MCPGuard는 MCP 클라이언트(에이전트/러너)와 MCP 서버 하위 프로세스 사이에서 투명한 프록시로 동작하며, 모든 도구 호출에 3계층 방어를 적용합니다. 최하위 계층은 eBPF로 구현되어 시스템 콜 경계에서 capability 정책을 강제하므로, 악의적인 MCP 서버가 자체 구현 내부에 민감한 동작을 하드코딩하여 정책을 우회할 수 없습니다.

이 저장소에는 프록시, eBPF 프로그램, 14개 서버/82개 사례 벤치마크, 그리고 함께 제공되는 논문 Kernel-Level Sandboxing for LLM Agent Tool Calls via eBPF에 사용된 평가 하네스가 포함되어 있습니다.

아키텍처

6가지 전환 가능한 방어 구성(proxy/proxy_base.py)은 논문에서 사용된 절제(ablation) 공간을 포괄합니다: 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

요구 사항

• BPF LSM이 활성화된 Linux 커널 6.x (CONFIG_BPF_LSM=y, 커널 cmdline에 lsm=bpf)
• BPF 타겟을 지원하는 clang 21 이상
• BPF 프로그램과 맵 로딩을 위한 bpftool
• Python 3.12 (표준 라이브러리만 — 타사 의존성 없음)
• Node.js 16+ (servers/js/ 아래 JavaScript MCP 서버에만 필요)

빠른 시작

# 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는 BPF LSM 프로그램과 고정(pinned) 맵을 사용할 수 없을 때 fail-closed로 동작합니다. 이 구성들은 루트 권한으로 eBPF 계층을 설치한 후에만 실행하세요.

주요 결과

논문에서 고정한 codex_20260523_full 14개 서버, 82개 사례 벤치마크에서의 공격 방지율(APR), 유효 공격 방지율(V-APR), 오탐률(FPR):

APR은 C0에서 본질적으로 실패하는 공격을 포함합니다. V-APR은 C0에서 성공하는 공격만을 분모로 사용하므로, 방어 범위에 대한 더 보수적인 지표입니다.

반복 정상 호출 지연 시간 벤치마크는 내부 논문 작업 공간에 results/latency/codex_20260523_latency.md로 저장됩니다. 구성별로 워밍업 20회와 측정 100회로 BN-01(filesystem_server.read_file)을 측정합니다. C-full은 C0 대비 중앙값 지연 시간이 +0.488 ms 증가하며, 이 고정 정상 호출에 대해 p95 1.141 ms를 유지합니다. 공개 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 서버는 신뢰할 수 없는 것으로 간주됩니다. 정상이지만 잘못 구성되었거나, 의도적으로 악의적이거나, 정식 서버를 트로이 목마화한 포크일 수 있습니다. 에이전트/러너와 호스트 OS는 신뢰됩니다. eBPF 계층은 커널이 손상되지 않았다고 가정합니다. 커널 내부 권한 상승(커널 모듈의 CWE-269)은 범위를 벗어납니다.

인용

논문이 게시되면 여기에 BibTeX 항목이 추가될 예정입니다.

기여

CONTRIBUTING.md를 참조하세요. 모든 기여자는 Meta의 CLA에 서명해야 합니다.

보안

보안 문제를 신고하려면 SECURITY.md를 참조하세요. 보안 신고는 공개 GitHub 이슈로 접수하지 마십시오.

라이선스

MIT — LICENSE 참조.