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+ (فقط لخوادم 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 بوضع الإغلاق عند الفشل إذا كانت برامج BPF LSM والخرائط المثبّتة غير متاحة. شغّلها فقط بعد تثبيت طبقة eBPF بصلاحيات الجذر.

النتائج الرئيسية

معدل منع الهجمات (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 مللي ثانية عند المئين 95 لهذا الاستدعاء الحميد الثابت. يستثني شجرة CodeSync العامة results/، لذا يعيد المستخدمون الخارجيون توليد هذا الأثر بالأمر أعلاه.

تُخزَّن سير عمل المراجعة/التجاوز داخليًا كـ results/audit/codex_20260523_override.md. توضّح كيف يُسجَّل رفض حميد كحدث مراجعة منظم ويُحَل بإضافة تجاوز عامل مقيَّد ضمن تخطيط متوافق مع policies/overrides.

تُخزَّن اختبارات الحواف المركزة لـ eBPF داخليًا كـ results/ebpf_edges/codex_20260523_ebpf_edges.md. تغطي توفر الخرائط بوضع الإغلاق عند الفشل، وسلوك السماح بالكتابة في مساحة العمل، ورفض حد بادئة الدليل، ورفض التدريج في /tmp، ورفض تسريب البيانات عبر localhost.

تُخزَّن فحوصات خط الأساس بنمط AgentBound داخليًا كـ results/agentbound/codex_20260523_agentbound.md. توثّق أن C-AB هو إعادة إنتاج على مستوى التطبيق لكل خادم، وتتحقق من التغطية المتوقعة المرئية للوسائط ومن النقطة العمياء المخفية عن التنفيذ.

نموذج التهديد

يُتعامل مع خادم MCP ككيان غير موثوق. قد يكون حميدًا لكن سيئ الإعداد، أو خبيثًا عمدًا، أو نسخة مفروسة (trojanized) من خادم شرعي. الوكيل / المُشغِّل ونظام تشغيل المضيف موثوقان. تفترض طبقة eBPF أن النواة غير مخترقة؛ تصعيد الصلاحيات داخل النواة (CWE-269 في وحدات النواة) خارج النطاق.

الاقتباس

سيُضاف إدخال BibTeX هنا بعد نشر الورقة.

المساهمة

انظر CONTRIBUTING.md. يجب على جميع المساهمين توقيع اتفاقية ترخيص المساهمة (CLA) الخاصة بـ Meta.

الأمان

للإبلاغ عن مشكلة أمنية، انظر SECURITY.md. يُرجى عدم فتح قضايا GitHub عامة للتقارير الأمنية.

الترخيص

MIT — انظر LICENSE.