Binary Ninja Headless MCP

خادم Binary Ninja بدون واجهة رسومية يتحدث MCP (بروتوكول سياق النموذج)، مما يمنح وكلاء الذكاء الاصطناعي وصولاً كاملاً إلى سير عمل الهندسة العكسية العميقة — التفكيك، اللغة الوسيطة، التصحيح، الأنواع، المراجع المتقاطعة، والمزيد — بدون واجهة مستخدم.

مُصمم للتشغيل داخل نفس حاوية Docker التي يعمل فيها وكيل runtime. لا مكونات جانبية، لا خدمات إضافية.

هذا المشروع بأكمله — الكود، الاختبارات، والتوثيق — تمت برمجته بنسبة 100% باستخدام الـ vibe coding.

لماذا

خوادم Binary Ninja MCP الحالية إما مقيدة بواجهة المستخدم الرسومية أو تقدم سطح أدوات محدود. هذا الخادم مخصص لوضع headless فقط ومصمم لسير العمل المدفوعة بالوكيل في بيئات الحاويات/الأجهزة الافتراضية المعزولة: يحصل الوكيل على السيطرة الكاملة على نظام التحليل، مما يؤتمت أجزاء كبيرة من الهندسة العكسية بينما تتفاعل أنت وتوجه العملية بشكل تفاعلي.

الهدف هو واجهة يمكن للوكلاء من خلالها فحص التحليل وتحسينه وتوسيعه بمرور الوقت — تحديث الأنواع والرموز والبيانات الوصفية، وتحسين قاعدة بيانات التحليل تدريجياً، وتطبيق التصحيحات والتكرار بأمان مع خيارات التراجع والإعادة، وتشغيل البرامج النصية المخصصة عندما يتطلب سير العمل شيئاً خاصاً.

الميزات

• 181 أداة عبر 36 مجموعة ميزات: التحليل، التفكيك، اللغة الوسيطة، التصحيح، التراجع/الإعادة، الأنواع، سير العمل، الذاكرة، البحث، المراجع المتقاطعة، البرمجة النصية، والمزيد.
• للقراءة فقط بشكل افتراضي مع سير عمل آمن للتغيير (تراجع/إعادة، معاملات).
• الوصول إلى البرمجة النصية عبر binja.eval و binja.call لأي شيء لا يشمله كتالوج الأدوات.
• نقل عبر stdio و TCP.
• لا تبعيات تشغيل إلى جانب Binary Ninja نفسه.
• وضع الواجهة الخلفية المزيفة للتكامل المستمر والتطوير بدون ترخيص Binary Ninja.

المتطلبات الأساسية

• Python 3.11+
• تثبيت Binary Ninja مع ترخيص يدعم التشغيل بدون واجهة رسومية ووحدة Python binaryninja القابلة للاستيراد في بيئة التشغيل الخاصة بك (للتحليل الحقيقي)
• للتكامل المستمر/التطوير بدون Binary Ninja، استخدم وضع الواجهة الخلفية المزيفة

التثبيت

git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .

أو قم بالتثبيت مباشرة من جذر المستودع بدون استنساخ:

pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git

البدء السريع

نقل عبر stdio (الافتراضي):

python3 binary_ninja_headless_mcp.py

نقل عبر TCP:

python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765

وضع الواجهة الخلفية المزيفة (لا يتطلب Binary Ninja):

python3 binary_ninja_headless_mcp.py --fake-backend

الاستخدام مع وكلاء الذكاء الاصطناعي

يتحدث هذا الخادم بروتوكول MCP القياسي عبر stdio (الافتراضي) أو tcp، لذا يمكن لأي مضيف وكيل يدعم MCP استخدامه.

Claude Code

claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py

أو أضفه إلى .mcp.json الخاص بمشروعك:

{
  "mcpServers": {
    "binary_ninja_headless_mcp": {
      "command": "python3",
      "args": ["binary_ninja_headless_mcp.py"],
      "cwd": "/path/to/binary-ninja-headless-mcp"
    }
  }
}

Codex

codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py

مضيف MCP عام

• سجل خادمًا باسم binary_ninja_headless_mcp.
• استخدم الأمر python3 مع الوسائط ["binary_ninja_headless_mcp.py"] عندما يكون cwd هو جذر المستودع، أو استخدم مسارًا مطلقًا للبرنامج النصي في args.
• عيّن cwd على مسار المستودع إذا كنت تريد أن تعمل المسارات النسبية مثل samples/ls بشكل صحيح.
• استخدم نقل stdio ما لم يتطلب مضيفك TCP.
• لوضع التزييف (بدون تثبيت Binary Ninja)، أضف --fake-backend.
• تحقق من الاتصال باستدعاء health.ping، ثم session.open.

نمط التعايش مع Docker

نموذج النشر الموصى به: تشغيل عملية الوكيل وخادم MCP هذا في نفس صورة الحاوية.

مثال أساسي:

FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]

إذا كنت بحاجة إلى تحليل Binary Ninja حقيقي داخل الحاوية، أضف بيئة تشغيل Binary Ninja الخاصة بك + إعداد الترخيص في نفس الصورة وابدأ الوكيل مع تكوين خادم MCP هذا.

أساليب MCP

• initialize
• ping
• tools/list
• tools/call
• shutdown

سلوك tools/list:

• بدون معاملات ترقيم صفحات صريحة، يعيد كتالوج الأدوات الكامل.
• إذا تم توفير offset أو limit، يستخدم إخراجًا مقسمًا إلى صفحات (offset=0, limit=50 بشكل افتراضي في وضع الصفحات).
• يدعم التصفية عبر:
  • prefix (مثلاً binary.)
  • query (مطابقة جزئية لاسم الأداة/الوصف)
• يعيد بيانات وصفية للترقيم: offset, limit, total, has_more.
• عندما يتم اقتطاع الصفحة (has_more=true)، يتضمن next_offset وتلميح notice.

سلوك استجابة استدعاء الأداة:

• structuredContent هو الحمولة الكاملة الأساسية.
• content[0].text هو سلسلة ملخص مضغوطة (ليست تكرار JSON كاملاً).
• هذا الانقسام مقصود للحفاظ على استخدام السياق أصغر مع الاستمرار في عرض بيانات كاملة قابلة للقراءة آلياً.

الجودة والاختبار

هذا المستودع مختبر جيداً وله بوابات جودة إلزامية.

• مجموعة الاختبارات: قم بتشغيل pytest --collect-only -q للحصول على عدد الاختبارات المجمعة الحالي.
• سير عمل التكامل المستمر يفرض:
  • ruff format --check .
  • ruff check .
  • pytest
• يستخدم التكامل المستمر BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 حتى تعمل الفحوصات دون الحاجة إلى تثبيت Binary Ninja.
• تتحقق اختبارات هيكلية إضافية من اتساق سجل الأدوات وإمكانية الوصول إلى الواجهة الخلفية.

ضوابط السياق

• وضع القراءة فقط هو الافتراضي للجلسات المفتوحة (read_only=true).
• binary.basic_blocks_at و function.basic_blocks مقسمة إلى صفحات (offset/limit).
• memory.read له حد أقصى للاستجابة: length <= 65536.

القيود

• واجهات برمجة التطبيقات للمؤسسات غير مغطاة حالياً.
• واجهات برمجة تطبيقات المصحح غير مغطاة حالياً.

نموذج الأمان

• اتصالات MCP (stdio/tcp) غير مصادق عليها بشكل افتراضي.
• يعرض الخادم البرمجة النصية التعسفية عبر binja.eval ووصولاً واسعاً لواجهة برمجة التطبيقات عبر binja.call.
• هذا بتصميم لبيئات الوكيل الموثوقة والمحتواة.
• لا تعرض هذا الخادم مباشرة لمستخدمين أو شبكات غير موثوقة.

سير العمل المحلي للتطوير

ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q

مدمج لاختبار الميزات (Feature Fuzzer)

استخدم مدمج اختبار الميزات (MCP feature fuzzer) المدمج لاختبار سطح أدوات واسع مقابل samples/ls.

واجهة خلفية حقيقية لـ Binary Ninja:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337

تشغيل اختبار دخاني بالواجهة الخلفية المزيفة:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20

كتابة تقرير تغطية بتنسيق JSON:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json

علامات مفيدة:

• --min-success-tools N: يخرج برمز غير صفري إذا نجحت أدوات أقل من N.
• --verbose: طباعة كل استدعاء أداة أثناء الاختبار.
• --update-analysis: فتح الجلسة الأولية مع update_analysis=true.

كتالوج الميزات

يعرض الخادم حالياً 181 أداة عبر 36 مجموعة ميزات.

تحليل (analysis)

• analysis.status: الحصول على حالة التحليل.
• analysis.progress: الحصول على لقطة للتقدم في التحليل.
• analysis.update: تشغيل تحديث تحليل غير متزامن.
• analysis.update_and_wait: تشغيل تحديث تحليل وانتظار الاكتمال.
• analysis.abort: إلغاء التحليل.
• analysis.set_hold: تعليق/تحرير قائمة انتظار التحليل.