Model Context Protocol (MCP)을 통해 이루어지는 LLM 에이전트 도구 호출을 보호하기 위한 커널 수준 eBPF 샌드박스
Model Context Protocol(MCP)를 통해 이루어지는 LLM 에이전트 도구 호출을 위한 커널 수준 샌드박싱.
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 검증, 프롬프트 인젝션 탐지, 환경 유출 / 명령 인젝션 탐지, 민감 키 스캔, 응답 정제. |
| L3 | ebpf/*.bpf.c + proxy/ebpf_sandbox.py | OS 수준 강제: 세 개의 BPF LSM 프로그램(file_guard, net_guard, proc_guard)이 open() / connect() / execve()를 가로채고, 하나의 트레이스포인트 프로그램(fork_guard)이 sched_process_fork를 통해 자식 프로세스를 추적하여 정책이 fork를 넘어 유지되도록 한다. |
여섯 가지 전환 가능한 방어 구성(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 정책 엔진, L2 인자 검증기, L3 eBPF 컨트롤러, AgentBound 기준선
├── ebpf/ file/net/proc/fork 가드용 BPF C 소스 + Makefile + vmlinux.h
├── policies/ 서버별 JSON 기능 정책 (기본값 + 재정의)
├── servers/ 14개 MCP 서버: 11개 Python (filesystem, notes, weather, shell, sqlite, git, env + 악성/트로이 목마 변형) + 3개 JavaScript (servers/js/)
├── test_cases/ 7개 카테고리(file_read, exfiltration, env_leak, sandbox_escape, priv_escalation, cross_language, benign)에 걸친 82개 벤치마크 시나리오
├── notes_data/ notes_server에서 사용하는 170개의 유효한 합성 노트 JSON 픽스처
├── runner/ evaluate.py, aggregate.py, agentbound_check.py, ebpf_edge_tests.py, latency_benchmark.py, override_workflow.py, smoke_test.py
└── EXECUTION_PLAN.md 단계별 재현 지침
CONFIG_BPF_LSM=y, lsm=bpf)clang 21 이상bpftoolservers/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 프로그램과
핀된 맵을 사용할 수 없으면 fail closed로 동작한다. 루트 권한으로
eBPF 계층을 설치한 후에만 실행하라.
단일 핀된 실행 codex_20260523_full(14개 서버, 82개 케이스
벤치마크; 이는 fx_r 카테고리별 프로파일이며, 논문의 표 1은 N=5 평균을
보고하므로 여기서 C-app은 13/48로 표시되지만 평균은 12/48임)에 대한
공격 방지율(APR), 실행 가능 공격 APR(V-APR), 오탐률(FPR):
| 구성 | 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에서 성공하는 공격만을 분모로 사용하며, 이는 방어 범위에 대한 더 보수적인 측정치이다.
반복된 정상 호출 지연 벤치마크는 내부 논문 워크스페이스에
results/latency/codex_20260523_latency.md로 저장되어 있다. 이는 BN-01
(filesystem_server.read_file)을 구성별로 20회 워밍업 호출과 100회 측정
호출로 측정한다; 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를 참조하라.