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: تعليق/تحرير قائمة انتظار التحليل.

تعليق توضيحي (annotation)

• annotation.rename_function: إعادة تسمية دالة.
• annotation.rename_symbol: إعادة تسمية رمز في عنوان.
• annotation.undefine_symbol: إلغاء تعريف رمز مستخدم في عنوان.
• annotation.define_symbol: تعريف رمز في عنوان.
• annotation.rename_data_var: إعادة تسمية متغير بيانات.
• annotation.define_data_var: تعريف متغير بيانات.
• annotation.undefine_data_var: إلغاء تعريف متغير بيانات.
• annotation.set_comment: تعيين تعليق في عنوان.
• annotation.get_comment: الحصول على تعليق في عنوان.
• annotation.add_tag: إضافة علامة بيانات مستخدم في عنوان.
• annotation.get_tags: الحصول على العلامات في عنوان.

معمارية (arch)

• arch.info: الحصول على بيانات تعريف المعمارية والمنصة.
• arch.disasm_bytes: تفكيك بايتات باستخدام معمارية محددة.
• arch.assemble: تجميع نص تعليمة باستخدام معمارية محددة.

العنوان الأساسي (baseaddr)

• baseaddr.detect: تشغيل كشف العنوان الأساسي.
• baseaddr.reasons: الحصول على أسباب كشف العنوان الأساسي.
• baseaddr.abort: إلغاء كشف العنوان الأساسي.

ثنائي (binary)

• binary.summary: الحصول على ملخص ثنائي/جلسة.
• binary.save: حفظ العرض الثنائي الحالي إلى مسار ملف.
• binary.functions: سرد الدوال مع ترقيم الصفحات.
• binary.strings: سرد السلاسل المكتشفة مع ترقيم الصفحات.
• binary.search_text: البحث عن نص/بايتات خام في جلسة.
• binary.sections: سرد الأقسام مع ترقيم الصفحات.
• binary.segments: سرد القطاعات مع ترقيم الصفحات.
• binary.symbols: سرد الرموز مع ترقيم الصفحات.
• binary.data_vars: سرد متغيرات البيانات مع ترقيم الصفحات.
• binary.get_function_at: العثور على دالة حسب العنوان.
• binary.get_function_disassembly_at: الحصول على التفكيك الكامل للدالة التي تحتوي على عنوان.
• binary.get_function_il_at: الحصول على اللغة الوسيطة الكاملة للدالة التي تحتوي على عنوان.

بنجا (binja)

• binja.info: إرجاع معلومات إصدار/تثبيت Binary Ninja.
• binja.call: جسر عام لواجهة برمجة التطبيقات: استدعاء مسار bn.* أو bv.*.
• binja.eval: تقييم كود Python مع bn, sessions, و bv اختياري.

بيانات (data)

• data.typed_at: الحصول على متغير بيانات بنوع في عنوان.

قاعدة بيانات (database)

• database.create_bndb: إنشاء ملف .bndb من الجلسة.
• database.save_auto_snapshot: حفظ لقطة تلقائية.
• database.info: الحصول على حالة قاعدة بيانات الجلسة.
• database.snapshots: سرد لقطات قاعدة البيانات.
• database.read_global: قراءة مفتاح سلسلة عام من قاعدة البيانات.
• database.write_global: كتابة مفتاح سلسلة عام لقاعدة البيانات.

تصحيح (debug)

• debug.parsers: سرد محللات معلومات التصحيح الصالحة لهذا العرض.
• debug.parse_and_apply: تحليل معلومات التصحيح وتطبيقها على العرض.

تفكيك (disasm)

• disasm.linear: الحصول على سطور تفكيك خطي.
• disasm.function: الحصول على التفكيك الكامل للدالة التي تحتوي على عنوان.
• disasm.range: سطور تفكيك نطاق العنوان.

خارجي (external)

• external.library_add: إضافة مكتبة خارجية.
• external.library_list: سرد المكتبات الخارجية.
• external.library_remove: إزالة مكتبة خارجية.
• external.location_add: إضافة تعيين موقع خارجي.
• external.location_get: الحصول على تعيين موقع خارجي.
• external.location_remove: إزالة تعيين موقع خارجي.

دالة (function)

• function.basic_blocks: سرد الكتل الأساسية في دالة مع ترقيم الصفحات.
• function.callers: مستدعو الدالة.
• function.callees: الدوال المستدعاة من الدالة.
• function.variables: سرد متغيرات الدالة.
• function.var_refs: سرد مراجع المتغيرات في MLIL/HLIL.
• function.var_refs_from: سرد مراجع المتغيرات الناشئة من عنوان.
• function.ssa_var_def_use: الحصول على تعريف واستخدامات متغير SSA.
• function.ssa_memory_def_use: الحصول على تعريف واستخدامات ذاكرة SSA حسب إصدار الذاكرة.
• function.metadata_store: تخزين بيانات وصفية للدالة بواسطة مفتاح.
• function.metadata_query: استعلام بيانات وصفية للدالة بواسطة مفتاح.
• function.metadata_remove: إزالة بيانات وصفية للدالة بواسطة مفتاح.

صحة (health)

• health.ping: فحص الصحة.

لغة وسيطة (il)

• il.function: سرد دالة IL.
• il.instruction_by_addr: الحصول على تعليمة IL حسب عنوان المصدر.
• il.address_to_index: تعيين عنوان إلى فهرس/فهارس IL.
• il.index_to_address: تعيين فهرس IL إلى عنوان المصدر.
• il.rewrite.capabilities: سرد دعم إعادة كتابة IL لدالة واحدة ومستوى IL.
• il.rewrite.noop_replace: إجراء استبدال تعبير IL بدون عملية.
• il.rewrite.translate_identity: ترجمة IL باستخدام استدعاء تعيين الهوية.

محمل (loader)

• loader.rebase: إعادة قاعدة BinaryView.
• loader.load_settings_types: سرد أسماء أنواع إعدادات المحمل.
• loader.load_settings_get: الحصول على قيم إعدادات المحمل.
• loader.load_settings_set: تعيين قيمة إعداد محمل واحدة.

ذاكرة (memory)

• memory.read: قراءة بايتات من العرض (length <= 65536).
• memory.write: كتابة بايتات (سداسي عشري) إلى العرض.
• memory.insert: إدراج بايتات (سداسي عشري) إلى العرض.
• memory.remove: إزالة بايتات من العرض.
• memory.reader_read: قراءة قيم صحيحة عبر BinaryReader.
• memory.writer_write: كتابة قيم صحيحة عبر BinaryWriter.

MCP

• mcp.response_format: شرح حقول نتيجة الأداة (structuredContent الحمولة الكاملة، content[0].text الملخص).

بيانات وصفية (metadata)

• metadata.store: تخزين بيانات وصفية بواسطة مفتاح.
• metadata.query: استعلام بيانات وصفية بواسطة مفتاح.
• metadata.remove: إزالة بيانات وصفية بواسطة مفتاح.

تصحيح (patch)

• patch.assemble: تجميع وكتابة بايتات تعليمة في عنوان.
• patch.status: فحص توفر التصحيح في عنوان.
• patch.convert_to_nop: تحويل التعليمة إلى NOP عندما يكون مدعوماً.
• patch.always_branch: تحويل الفرع الشرطي إلى فرع دائم عندما يكون مدعوماً.
• patch.never_branch: تحويل الفرع الشرطي إلى عدم فرع أبداً عندما يكون مدعوماً.
• patch.invert_branch: تحويل الفرع الشرطي بالعكس عندما يكون مدعوماً.
• patch.skip_and_return_value: تحويل التعليمة إلى تخطي وإرجاع قيمة عندما يكون مدعوماً.

إضافة (plugin)

• plugin.valid_commands: سرد أوامر الإضافة الصالحة في السياق.
• plugin.execute: تنفيذ أمر إضافة صالح في السياق.

مستودع إضافات (plugin_repo)

• plugin_repo.status: سرد مستودعات الإضافات وحالات الإضافات.
• plugin_repo.check_updates: التحقق من تحديثات مستودع الإضافات.
• plugin_repo.plugin_action: تشغيل إجراء تثبيت/إلغاء تثبيت/تمكين/تعطيل على إضافة مستودع.

مشروع (project)

• project.create: إنشاء مشروع.
• project.open: فتح مشروع.
• project.close: إغلاق مشروع متتبع.
• project.list: سرد مجلدات/ملفات المشروع.
• project.create_folder: إنشاء مجلد مشروع.
• project.create_file: إنشاء ملف مشروع من بيانات base64.
• project.metadata_store: تخزين بيانات وصفية للمشروع.
• project.metadata_query: استعلام بيانات وصفية للمشروع.
• project.metadata_remove: إزالة بيانات وصفية للمشروع.

بحث (search)

• search.data: البحث عن أنماط بايتات خام (سلسلة سداسية عشرية).
• search.next_text: العثور على تطابق نصي تالي.
• search.all_text: العثور على جميع التطابقات النصية في نطاق (تعبير عادي اختياري).
• search.next_data: العثور على تطابق بيانات/نمط بايت تالي.
• search.all_data: العثور على جميع تطابقات بيانات/نمط بايت في نطاق.
• search.next_constant: العثور على حدوث ثابت تالي.
• search.all_constant: العثور على جميع حدوثات الثابت في نطاق.

قسم (section)

• section.add_user: إضافة قسم مستخدم.
• section.remove_user: إزالة قسم مستخدم.

قطاع (segment)

• segment.add_user: إضافة قطاع مستخدم.
• segment.remove_user: إزالة قطاع مستخدم.

جلسة (session)

• session.open: فتح ثنائي وإنشاء جلسة.
• session.open_bytes: فتح جلسة ثنائية من بايتات مشفرة بـ base64.
• session.open_existing: فتح جلسة أخرى من ملف جلسة موجودة.
• session.close: إغلاق جلسة مفتوحة واحدة.
• session.list: سرد الجلسات المفتوحة.
• session.mode: الحصول على وضع الأمان/الحتمية للجلسة.
• session.set_mode: تحديث وضع الأمان/الحتمية للجلسة.

مهمة (task)

• task.analysis_update: بدء مهمة تحديث تحليل غير متزامن.
• task.search_text: بدء مهمة بحث غير متزامنة.
• task.status: الحصول على حالة المهمة.
• task.result: الحصول على نتيجة المهمة.
• task.cancel: إلغاء المهمة (أفضل جهد).

تحويل (transform)

• transform.inspect: فحص/معالجة خط أنابيب استخراج التحويل.

نوع (type)

• type.parse_string: تحليل سلسلة نوع واحدة.
• type.parse_declarations: تحليل تصريحات C للأنواع/المتغيرات/الدوال.
• type.define_user: تعريف نوع مستخدم من مصدر النوع.
• type.rename: إعادة تسمية نوع.
• type.undefine_user: إلغاء تعريف نوع مستخدم.
• type.import_library_type: استيراد نوع من مكتبة أنواع.
• type.import_library_object: استيراد نوع كائن من مكتبة أنواع.
• type.export_to_library: تصدير نوع إلى مكتبة أنواع.

أرشيف الأنواع (type_archive)

• type_archive.create: إنشاء وإرفاق أرشيف أنواع اختيارياً.
• type_archive.open: فتح وإرفاق أرشيف أنواع اختيارياً.
• type_archive.list: سرد أرشيفات الأنواع المرفقة.
• type_archive.get: الحصول على أرشيف أنواع متتبع واحد.
• type_archive.pull: سحب الأنواع من أرشيف أنواع.
• type_archive.push: دفع الأنواع إلى أرشيف أنواع.
• type_archive.references: استعلام المراجع الواردة/الصادرة من الأرشيف لنوع واحد.

مكتبة الأنواع (type_library)

• type_library.create: إنشاء وإرفاق مكتبة أنواع اختيارياً.
• type_library.load: تحميل وإرفاق مكتبة أنواع اختيارياً.
• type_library.list: سرد مكتبات الأنواع المرفقة بالعرض.
• type_library.get: الحصول على مكتبة أنواع متتبعة واحدة.

UIDF

• uidf.parse_possible_value: تحليل سلسلة مجموعة القيم المحتملة المقدمة من المستخدم.
• uidf.set_user_var_value: تعيين قيمة متغير مستخدم للدالة.
• uidf.clear_user_var_value: مسح قيمة متغير مستخدم للدالة.
• uidf.list_user_var_values: سرد جميع قيم متغيرات المستخدم لدالة.

تراجع (undo)

• undo.begin: بدء معاملة تراجع.
• undo.commit: تأكيد معاملة تراجع.
• undo.revert: إلغاء معاملة تراجع.
• undo.undo: تنفيذ تراجع.
• undo.redo: تنفيذ إعادة.

قيمة (value)

• value.reg: الحصول على قيمة تسجيل عند/بعد عنوان.
• value.stack: الحصول على محتويات المكدس عند/بعد عنوان.
• value.possible: الحصول على مجموعة القيم المحتملة IL عند عنوان.
• value.flags_at: الحصول على حالة قراءة/كتابة علم IL المرفوع عند عنوان.

سير عمل (workflow)

• workflow.list: سرد سير العمل المسجلة.
• workflow.describe: وصف طوبولوجيا سير العمل والإعدادات.
• workflow.clone: استنساخ سير العمل.
• workflow.insert: إدراج أنشطة قبل نشاط.
• workflow.insert_after: إدراج أنشطة بعد نشاط.
• workflow.remove: إزالة نشاط سير العمل.
• workflow.graph: تلخيص رسم بياني لسير العمل.
• workflow.machine.status: الحصول على حالة آلة سير العمل.
• workflow.machine.control: التحكم في وقت تشغيل آلة سير العمل.

مراجع متقاطعة (xref)

• xref.code_refs_to: مراجع كود إلى عنوان.
• xref.code_refs_from: مراجع كود من عنوان.
• xref.data_refs_to: مراجع بيانات إلى عنوان.
• xref.data_refs_from: مراجع بيانات من عنوان.

اتصال

لمزيد من المعلومات، اتصل بـ Tim Blazytko (@mr_phrazer).