خادم Ghidra MCP

إذا وجدت هذا مفيدًا، يُرجى ⭐ وضع نجمة على المستودع — فهذا يساعد الآخرين في اكتشافه!

إذا كان Ghidra MCP يوفر لك الوقت، فكِّر في دعم المشروع. كل من الدعم لمرة واحدة والدعم المتكرر يساعدان في تمويل تحديثات التوافق، وتقوية بيئة الإنتاج، والوثائق، والأدوات الجديدة.

خادم Model Context Protocol (MCP) جاهز للإنتاج يربط قدرات Ghidra القوية في الهندسة العكسية بأدوات الذكاء الاصطناعي الحديثة وأطر الأتمتة. 271 أداة MCP، وسير عمل ذكي مختبر في المعارك، وأشمل تكامل Ghidra-MCP متاح — يشمل الآن محاكاة P-code، وتكامل المٌصحح الحي، وتحليل تدفق البيانات عبر PCode-graph.

لماذا Ghidra MCP؟

معظم تطبيقات Ghidra MCP تمنحك حفنة من الأدوات للقراءة فقط وتعتبر المهمة منتهية. هذا المشروع مختلف — فقد بُني بواسطة مهندس عكسي يستخدمه يوميًا على ملفات ثنائية حقيقية، وليس كعرض تجريبي.

• 271 أداة MCP — أكثر بـ 3 مرات من أي تطبيق منافس. ليست عمليات قراءة فقط — بل وصول كامل للكتابة لإعادة التسمية، والتصنيف، والتعليق، وإنشاء الهياكل، وتنفيذ السكريبتات، ومحاكاة P-code، والتصحيح الحي.
• سير عمل ذكي مختبر في المعارك — سير عمل توثيق مثبت (الإصدار V5) تم تحسينه عبر مئات الدوال. يتضمن تعليمات خطوة بخطوة، ومرجع تسمية هنغارية، وأدلة معالجة دفعية، واكتشاف الكود اليتيم.
• موثوقية من الدرجة الإنتاجية — معاملات ذرية، وعمليات دفعية (تقليل استدعاءات API بنسبة 93%)، ومهل زمنية قابلة للتكوين، ومعالجة أخطاء لطيفة. لا توجد إخفاقات صامتة.
• نقل توثيق عبر الثنائيات — مطابقة هاش SHA-256 للدوال تنشر التوثيق عبر نسخ الثنائيات تلقائيًا. وثِّق مرة واحدة، طبق في كل مكان.
• تكامل كامل مع خادم Ghidra — الاتصال بخوادم Ghidra المشتركة، وإدارة المستودعات، والتحكم بالنسخ، وسير عمل السحب/الدفع، والتعاون متعدد المستخدمين.
• وضعي الرأس وواجهة المستخدم الرسومية — تشغيل مع أو بدون واجهة Ghidra الرسومية. جاهز لـ Docker لخطوط أنابيب CI/CD والتحليل الآلي على نطاق واسع.
• مصمم برأي محدد — الإصدار v5.0 ينقل اصطلاحات التسمية، وسلامة الأنواع، ومعايير التوثيق إلى طبقة الأدوات. وكلاء الذكاء الاصطناعي والمهندسون البشريون ينتجون مخرجات متسقة دون أدلة أسلوب في كل تعليمة.

فرض الاصطلاحات

لقد مررت بهذا: بعد ستة أشهر من المشروع تجد ProcessItem و process_items و handleItem و ItemProc في نفس قاعدة الكود — أربع دوال تفعل نفس الشيء، مسماة بأربع جلسات أو مهندسين مختلفين دون عقد مشترك. إصلاحها يستغرق وقتًا أطول مما ينبغي، وستتكرر المشكلة.

الإصدار v5.0 ينقل الاصطلاحات من "أشياء يجب تذكرها" إلى طبقة الأدوات، حيث يمكن فرضها فعليًا.

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

بالنسبة للفرق، يلغي هذا الفئة الكاملة من تعليقات المراجعة التي تقول "هذا ليس اصطلاح التسمية لدينا". يظل تحكيم الاصطلاحات في الأداة، وليس في مراجعة الكود.

بالنسبة للعمل الفردي على نطاق واسع، يمنحك analyze_function_completeness درجة 0–100% تقيس بصدق: الاستقطاعات الهيكلية (القمامات المترجمة غير القابلة للإصلاح) تُغتفر في درجتك الفعالة، والتدرج اللوغاريتمي يمنع فئة سيئة واحدة من دفن كل شيء آخر، وجودة تعليق الشريحة المتدرجة تعني أنك تعرف بالضبط ما هو مفقود ولماذا.

🌟 الميزات

تكامل MCP الأساسي

• توافق كامل مع MCP — تنفيذ كامل لبروتوكول سياق النموذج
• 271 أداة MCP — سطح API شامل يغطي كل جانب من جوانب تحليل الثنائيات
• موثوقية من الدرجة الإنتاجية — معاملات ذرية، وعمليات دفعية، ومهل زمنية قابلة للتكوين
• تحليل فوري — تكامل حي مع محرك تحليل Ghidra

ملاحظة التوافق: يتم تطبيع أسماء أدوات MCP لـ GitHub Copilot CLI والتحقق من CAPI. تستخدم أسماء الأدوات المعروضة أحرفًا صغيرة وأرقامًا وشرطات سفلية وواصلات فقط؛ يتم الإعلان عن المسارات HTTP المتداخلة مثل /debugger/status بأسماء مثل debugger_status_2 عند الحاجة لتجنب التصادم مع أدوات الجسر الثابتة.

قدرات تحليل الثنائيات

• تحليل الدوال — إعادة التجميع، رسوم بيانية للاستدعاءات، مراجع متقاطعة، تسجيل الاكتمال
• تحليل تدفق البيانات — نشر قيمة PCode-graph (أمامي/خلفي) من أي متغير أو سجل
• اكتشاف هياكل البيانات — إنشاء struct/union/enum مع تحليل الحقول واقتراحات التسمية
• استخراج السلاسل النصية — بحث بالتعبير المنتظم، تصفية الجودة، اكتشاف الدوال المرتكزة على السلاسل
• تحليل الاستيراد/التصدير — جداول الرموز، المواقع الخارجية، حل الاستيراد الترتيبي
• فحص الذاكرة والبيانات — قراءات الذاكرة الخام، بحث نمط البايت، اكتشاف حدود المصفوفات
• توثيق عبر الثنائيات — مطابقة هاش الدوال ونشر التوثيق عبر الإصدارات

التحليل الديناميكي (الإصدار v5.4.0)

• محاكاة P-code — تشغيل أي دالة بمعزل عبر EmulatorHelper الخاص بـ Ghidra؛ حل هاش API بالقوة الغاشمة في ميلي ثانية
• تكامل المٌصحح الحي — 17 نقطة نهاية Java + 22 أداة جسر Python عبر إطار TraceRmi الخاص بـ Ghidra (dbgeng على Windows PE، gdb/lldb بخلاف ذلك): الإرفاق، الخطوة، نقاط التوقف، السجلات، قراءات الذاكرة، تتبع الدوال غير المقطعي، ترجمة العناوين الثابتة↔الديناميكية الواعية بـ ASLR

سير عمل الهندسة العكسية المدعوم بالذكاء الاصطناعي

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

التطوير والأتمتة

• إدارة سكريبتات Ghidra — إنشاء، تشغيل، تحديث، وحذف سكريبتات Ghidra بالكامل عبر MCP
• دعم البرامج المتعددة — التبديل بين برامج مفتوحة متعددة ومقارنتها
• العمليات الدفعية — إعادة تسمية، تعليق، تصنيف، وإدارة تسميات ضخمة (استدعاءات API أقل بنسبة 93%)
• خادم بدون رأس — تحليل كامل بدون واجهة Ghidra الرسومية — جاهز لـ Docker و CI/CD
• المشروع والتحكم بالنسخ — إنشاء مشاريع، إدارة ملفات، تكامل خادم Ghidra
• التحكم في التحليل — سرد، تكوين، وتشغيل محللات Ghidra برمجيًا

🚀 بداية سريعة

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

• Java 21 LTS (يوصى بـ OpenJDK)
• Apache Maven 3.9+
• Ghidra 12.1.2 (أو إصدار متوافق)
• Python 3.10+ مع uv (موصى به) أو pip + venv

مستخدمو خادم Ghidra المشترك: عملاء Ghidra 12.1.2 يحتاجون إلى خادم Ghidra إصدار 12.1 أو 12.0.5 أو إصدار أحدث متوافق. قم بترقية الخادم قبل استخدام هذه الإضافة من عميل 12.1.

Ghidra 12.1.2 يأتي مع Jython كإضافة اختيارية. تعمل سكريبتات Java افتراضيًا، لكن سكريبتات .py في ghidra_scripts/ تتطلب تثبيت إضافة Jython من File > Install Extensions وإعادة تشغيل Ghidra.

التثبيت

موصى به لجميع المنصات: استخدم python -m tools.setup مباشرة.

ensure-prereqs يثبت متطلبات Python وقت التشغيل بالإضافة إلى ملفات JAR الخاصة بـ Ghidra اللازمة في مستودع Maven المحلي. deploy ينسخ مخرجات البناء، ويُثبّت الإضافة في ملف تعريف المستخدم، ويُصحّح تكوين مستخدم Ghidra.

1. استنساخ المستودع: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. موصى به: تشغيل فحص البيئة المسبق أولاً: ```text python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

3. بناء ونشر إلى Ghidra: ```text python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

deploy يحفظ/يغلق مثيل Ghidra المطابق الذي يعمل بالفعل عند الحاجة ، ويقوم بتثبيت الامتداد، ويبدأ Ghidra، وينتظر صحة MCP، ويقوم بفحوصات دخان المخطط.

4. الوضع الإجباري/اليدوي الاختياري (متقدم): ```text

   Skip automatic prerequisite setup

   python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

5. إظهار تعليمات الأمر: ```text python -m tools.setup --help
   root@kitploit:~

6. وضع البناء الاختياري فقط (متقدم/استكشاف الأخطاء وإصلاحها): ```text python -m tools.setup build
   root@kitploit:~

مسار البناء المدعوم: python -m tools.setup build يستخدم Maven داخليًا وهو سير العمل الأساسي المستخدم في مهام المستودع والمستندات. ```bash

Manual Maven build (requires Ghidra deps already installed in local .m2)

mvn clean package assembly:single -DskipTests

المدخلات:   ```bash
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

التثبيت (لينكس — أوبونتو/ديبيان)

1. استنساخ المستودع: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. تثبيت المتطلبات الأساسية للنظام (إذا لم تكن مثبتة بالفعل): ```bash sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   root@kitploit:~

ملاحظة دبيان/كالي/أوبونتو 23.04+ (PEP 668): هذه التوزيعات تميّز بايثون النظام بأنها مدارة خارجيًا، لذا فإن pip install المجردة تفشل مع error: externally-managed-environment. لا تتجاوزها باستخدام --break-system-packages — فقد يفسد الأدوات المدارة بواسطة apt. بدلاً من ذلك استخدم uv (موصى به — يقوم بإنشاء وإدارة .venv محلي للمشروع تلقائيًا، وهو ما تستخدمه أوامر هذا المستودع):

root@kitploit:~

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run bridge-mcp-ghidra    # يحل التبعيات داخل .venv ويبدأ الجسر

أو بيئة افتراضية تقليدية:

root@kitploit:~

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

3. تشغيل فحص البيئة المبدئي: ```bash python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

4. بناء ونشر إلى Ghidra (أمر واحد): ```bash python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC python -m tools.setup build python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

سيقوم هذا بما يلي:

• تثبيت تبعيات JAR الخاصة بـ Ghidra في مستودع ~/.m2/repository المحلي
• بناء GhidraMCP-<version>.zip باستخدام Maven
• استخراج الإضافة إلى ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/
• تحديث preferences بـ LastExtensionImportDirectory
• تثبيت متطلبات Python

5. اختياري: إعداد تبعيات Maven فقط: ```bash python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

6. عرض تعليمات الأمر: ```bash python -m tools.setup --help
   root@kitploit:~

مسارات Linux: تم تثبيت الامتداد في $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/. ملفات تكوين Ghidra موجودة في $HOME/.config/ghidra/ghidra_<version>_PUBLIC/.

تثبيت (macOS — Homebrew)

1. تثبيت المتطلبات الأساسية: ```bash brew install openjdk@21 maven python ghidra
   root@kitploit:~

2. استنساخ المستودع: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

3. تثبيت Ghidra JARs في Maven المحلي: ```bash python -m tools.setup install-ghidra-deps
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

4. البناء والنشر: ```bash python -m tools.setup ensure-prereqs
   --ghidra-path /opt/homebrew/opt/ghidra/libexec python -m tools.setup build python -m tools.setup deploy
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

تم تثبيت الامتداد إلى ~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/.

ملاحظة: --ghidra-version مطلوب عند استخدام مسار Homebrew لأن المسار لا يحتوي على سلسلة إصدار.

5. تشغيل Ghidra وتمكين الإضافة: ```bash /opt/homebrew/opt/ghidra/libexec/ghidraRun
   root@kitploit:~

في نافذة المشروع الرئيسية: Tools > GhidraMCP > Start MCP Server

6. تكوين Cursor/Claude MCP (~/.cursor/mcp.json): ```json { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"] } } }
   root@kitploit:~

التثبيت (Arch Linux — AUR)

@Pandoriaantje يحافظ على حزم AUR المجتمعية:

• ghidra-mcp-git — يتتبع main
• ghidra-mcp — يتتبع الإصدارات الموسومة

قم بالتثبيت باستخدام مساعد AUR الذي تختاره، على سبيل المثال:```bash yay -S ghidra-mcp # or ghidra-mcp-git

### الاستخدام الأساسي

#### الخيار 1: نقل Stdio (موصى به لأدوات الذكاء الاصطناعي)```bash
uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

لإضافة الجسر إلى Autohand Code من نسخة مستنسخة محلية:```bash autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

أضف `--scope project` قبل `ghidra` لحفظ الخادم في تكوين `.autohand` للمشروع الحالي بدلاً من تكوين المستخدم الخاص بك.

#### الخيار 2: نقل HTTP القابل للتدفق (موصى به لعملاء الويب/HTTP)```bash
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

إعدادات عميل MCP لنقل HTTP (أضف إلى ملف إعدادات MCP الخاص بعميلك):```json { "mcpServers": { "ghidra-mcp-http": { "url": "http://127.0.0.1:8081/mcp" } } }

العملاء المستندة إلى المتصفح (مثل [MCP Inspector](https://github.com/modelcontextprotocol/inspector))
تعمل بشكل مباشر: حيث تجيب وسائل النقل HTTP على طلبات CORS الأولية (`OPTIONS`) وتكشف
عن الترويسات `mcp-session-id` / `mcp-protocol-version` للنصوص البرمجية. تعكس الأصول المسموح بها
سياسة ترويسة المضيف — يُسمح دائمًا بالحلقة المحلية على أي منفذ، بالإضافة إلى مضيف الربط وأي
مضيفين مدرجين في `GHIDRA_MCP_ALLOWED_HOSTS`.

#### الخيار 3: نقل SSE (مهمل — استخدم streamable-http بدلاً من ذلك)```bash
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

إشارات الجسر المتقدمة

توجيه البرنامج الصارم (أمان متعدد البرامج)

عيّن GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 لجعل الجسر يرفض أي استدعاء محدد النطاق لبرنامج يحذف محدد برنامج، مع إعادة خطأ واضح بدلاً من السماح للاستدعاء باستخدام "البرنامج الحالي" المشترك للخادم (البرنامج الذي يحركه switch_program وعلامة تبويب واجهة المستخدم النشطة).```bash export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 uv run bridge-mcp-ghidra

بدون هذا، فإن استدعاءً يحذف `program=` يعمل ضد البرنامج الحالي، وهو أمر جيد لسير عمل برنامج واحد ولكنه خطر بمجرد فتح عدة برامج: يمكن للاستدعاء قراءة أو تعديل الثنائي الخاطئ دون أي خطأ. ويزداد الخطر سوءًا عندما يشارك أكثر من عميل خادمًا واحدًا، لأن كل واحد منهم ينقل المتغير العام للبرنامج الحالي من تحت الآخرين.

مع تفعيل الوضع الصارم، يجب على كل استدعاء ضمن نطاق البرنامج تسمية هدفه. يغطي هذا كل محدد يختار برنامجًا مفتوحًا: `program=` العادي وأدوات البرامج المتقاطعة `source_program`/`target_program` أو `program_a`/`program_b` (مُعلنة كإلزامية، لكن الخادم لا يزال يتراجع إلى البرنامج الحالي عندما يصل أحدها فارغًا). يظهر المحدد المنسي كخطأ صاخب عند أول استدعاء خاطئ بدلاً من كتابة صامتة إلى الثنائي الخاطئ. الأدوات التي لا تحتوي على محدد برنامج (`open_program` و `close_program` تأخذان `path`/`name`) لا تتأثر. معطل بشكل افتراضي: مع عدم تعيين المتغير، يرسل الجسر الاستدعاءات دون تغيير.

#### تقليل الحمل الزائد لسياق الأداة

يُظهر الجسر فهرسًا كبيرًا. للحفاظ على سطح أداة النموذج صغيرًا، قم بتشغيله مع `--lazy` (يقوم بتحميل `listing,function,program` فقط عند الاتصال) واترك النموذج **يكتشف** الباقي حسب الطلب بدلاً من تسجيل كل شيء:

- `search_tools("rename function")` — بحث بالكلمات المفتاحية في **الفهرس بأكمله**، بما في ذلك الأدوات التي مجموعتها غير محملة. كل نتيجة تخبر ما إذا كان يمكن استدعاؤها الآن، وإذا لم يكن الأمر كذلك، الاستدعاء الدقيق `load_tool_group(...)` لتمكينها.
- `list_tool_groups()` — سرد جميع الفئات وحالة تحميلها.
- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — تحميل أو إسقاط فئة في وقت التشغيل.
- `check_tools("rename_or_label,batch_set_comments")` — تأكيد أن أدوات محددة قابلة للاستدعاء الآن.

يعمل `search_tools` في كلا الوضعين eager و `--lazy`، لذا فإن الوكلاء الذين يحترمون `tools/list_changed` يحصلون على اكتشاف كامل دون تكلفة السياق المسبقة.

#### اختياري: بدء تشغيل خادم المصحح المستقل```bash
uv sync --group debugger
uv run python -m debugger

يستمع خادم التصحيح على http://127.0.0.1:8099/ افتراضيًا وهو مطلوب لأدوات الوكيل debugger_* التي يعرضها جسر MCP.

علامات خادم التصحيح:

عيّن GHIDRA_DEBUGGER_URL في ملف .env إذا قمت بتغيير المنفذ أو المضيف الافتراضي حتى يتمكن الجسر من العثور عليه.

في Ghidra

1. شغّل Ghidra وافتح نافذة CodeBrowser
2. في CodeBrowser، فعّل الإضافة عبر File > Configure > Configure All Plugins > GhidraMCP
3. اختياري: تكوين منفذ مخصص عبر CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server
4. شغّل الخادم عبر Tools > GhidraMCP > Start MCP Server
5. يعمل الخادم على http://127.0.0.1:8089/ افتراضيًا

تحقق من عمله```bash

Quick health check

curl http://127.0.0.1:8089/check_connection

Expected: "Connected: GhidraMCP plugin running with program ''"

Get version info

curl http://127.0.0.1:8089/get_version

## دعم هذا المشروع

إذا وفرت لك أداة Ghidra MCP وقتًا في الهندسة أو الهندسة العكسية، ففكر في [رعاية المشروع](https://github.com/sponsors/bethington).

- يساعد التبرع لمرة واحدة في تمويل الإصلاحات وتحديثات التوافق وأعمال الإصدار.
- يساعد التبرع المتكرر في استمرار الصيانة والتوثيق وتقوية الإنتاج.
- يساعد دعم الشركات في تحديد أولويات الموثوقية طويلة الأجل للجسر والخادم غير المرئي (headless) وتكامل المصحح وأدوات سير العمل.

## 🔒 الأمان

تم تصميم GhidraMCP للتطوير **على localhost فقط**. التكوين الافتراضي — خادم HTTP مرتبط بـ `127.0.0.1`، بدون مصادقة — آمن على محطة عمل موثوقة لمستخدم واحد ويتوافق مع سلوك ما قبل الإصدار v5.4.1.

**إذا قمت بتعريض الخادم خارج loopback، فقم بتكوين هذه المتغيرات البيئية الثلاثة أولاً.** يرفض الخادم البدء على ربط غير loopback بدون رمز مميز.

| متغير بيئي | التأثير |
|---|---|
| `GHIDRA_MCP_AUTH_TOKEN` | عند التعيين، يجب أن يحمل كل طلب HTTP `Authorization: Bearer <token>`. مقارنة آمنة زمنيًا. `/mcp/health` و `/health` و `/check_connection` معفاة. |
| `GHIDRA_MCP_ALLOW_SCRIPTS` | اضبط على `1` أو `true` أو `yes` لتمكين `/run_script_inline` و `/run_ghidra_script`. **معطل افتراضيًا اعتبارًا من v5.4.1** — تنفذ هذه النقاط الطرفية (endpoints) Java عشوائية ضد عملية Ghidra. في الوضع غير المرئي (headless) يؤدي هذا أيضًا إلى تشغيل تهيئة OSGi `BundleHost` عند بدء تشغيل الخادم (إطار Felix، ~مئات من ms); اتركه معطلاً إذا لم تكن بحاجة إلى تنفيذ البرامج النصية. |
| `GHIDRA_MCP_FILE_ROOT` | عند التعيين على مسار دليل، تقوم نقاط النهاية الخاصة بمسارات نظام الملفات (`/load_program` و `/import_file` و `/open_project` و `/delete_file` وما إلى ذلك) بتوحيد المدخلات (canonicalize) وتتطلب أن تكون ضمن هذا الجذر. يمنع traversal المسار. |

فرض جودة التسمية منفصل عن الأمان. افتراضيًا، ترفض `rename_function_by_address` ونقاط النهاية العالمية للكتابة الأسماء التي تفشل في اختبارات الجودة المدمجة، وتطبق كتابات حقول الهيكل (struct) اتفاقية البادئة المدمجة للحقول. قم بتعطيل طبقة الاتفاقية المدمجة من خلال **Edit > Tool Options > GhidraMCP HTTP Server > Strict Naming Enforcement**. تغطي نفس خانة الاختيار في خيارات الأداة `rename_data` و `rename_global_variable` و `set_global` و بادئة/حماية النوع لـ `apply_data_type`، والإصلاحات التلقائية للبادئة الهنغارية لحقول الهيكل في `create_struct` و `add_struct_field` و `modify_struct_field`. تتم قراءة الإعداد عند بدء تشغيل خادم MCP أو إعادة تشغيله. لا تزال تحذيرات اتفاقية التسمية للدوال/العالمية تُعاد عند تعطيل الفرض.

### مثال: التعريض لشبكة LAN خاصة مع المصادقة```bash
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1     # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

مصادقة خادم Ghidra

عند الاتصال بخادم Ghidra مشترك، يمكن لـ GhidraMCP إخفاء مربع حوار كلمة المرور تلقائيًا. يحل بيانات الاعتماد بهذا الترتيب (أول قيمة غير فارغة تفوز):

ملاحظة التوافق: يتطلب عملاء Ghidra 12.1.2 خادم Ghidra 12.1.2 أو 12.0.5 أو خادمًا أحدث متوافقًا. الخوادم المشتركة القديمة ليست أهدافًا آمنة لترقية عميل 12.1.

1. متغير البيئة GHIDRA_SERVER_PASSWORD (أو ملف .env في دليل تثبيت Ghidra أو ~)
2. ملف ~/.ghidra-cred — ملف كلمة مرور من سطر واحد في دليل المستخدم الرئيسي
3. ملف <ghidra-install-dir>/.ghidra-cred

يتم حل اسم المستخدم بشكل مشابه: متغير البيئة GHIDRA_SERVER_USER ← خاصية النظام user.name.

إذا لم يتم العثور على كلمة مرور، يعرض Ghidra موجه واجهة المستخدم الرسومية العادي. قم بتعيين هذه في ملف .env (انظر .env.template للكتلة الكاملة) لتمكين المصادقة الصامتة.

الترحيل من الإصدار v5.4.0 → v5.4.1

• نقاط نهاية البرنامج النصي معطلة افتراضيًا الآن. إذا كنت تعتمد على /run_script_inline أو /run_ghidra_script، قم بتصدير GHIDRA_MCP_ALLOW_SCRIPTS=1. هذا تغيير متعمد مسبب للكسر؛ الإعداد الافتراضي السابق كان غير آمن.
• عمليات النشر المحلية على المضيف المحلي لا تحتاج إلى تغييرات. المصادقة، رفض الربط، وفحوصات جذر المسار كلها اختيارية.

❓ استكشاف الأخطاء وإصلاحها

قائمة "GhidraMCP" لا تظهر في الأدوات

السبب: لم يتم تمكين الإضافة أو تثبيتها بشكل صحيح.

الحل:

1. تحقق من تثبيت الإضافة: File > Install Extensions — يجب أن تظهر GhidraMCP
2. قم بتمكين الإضافة: File > Configure > Configure All Plugins > GhidraMCP (حدد المربع)
3. أعد تشغيل Ghidra بعد التثبيت/التمكين

الخادم لا يستجيب / رفض الاتصال

السبب: لم يتم بدء الخادم أو المنفذ خاطئ.

الحل:

1. تأكد من بدء الخادم: Tools > GhidraMCP > Start MCP Server
2. تحقق من المنفذ المهيأ: Edit > Tool Options > GhidraMCP HTTP Server
3. تحقق مما إذا كان المنفذ قيد الاستخدام: ```bash

   Linux/macOS

   lsof -i :8089

   Windows

   netstat -ano | findstr :8089
   root@kitploit:~

4. ابحث عن الأخطاء في وحدة تحكم Ghidra: Window > Console

pip install fails with error: externally-managed-environment

السبب: PEP 668. توزيعات عائلة Debian (Debian 12+, Kali, Ubuntu 23.04+) تحدد Python النظام كمدير خارجي، لذلك يتم حظر pip install العام لحماية الحزم المدارة بواسطة apt.

الحل: استخدم بيئة افتراضية — لا تستخدم --break-system-packages أبدًا. المسار الموصى به هو uv، والذي يدير .venv محليًا للمشروع تلقائيًا:```bash curl -LsSf https://astral.sh/uv/install.sh | sh cd ghidra-mcp uv run bridge-mcp-ghidra

أو venv تقليدي:```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

python -m debugger يفشل مع ModuleNotFoundError لـ pybag أو comtypes

السبب: يستخدم خادم التصحيح المستقل تبعيات Python اختيارية تعمل فقط على ويندوز، ولا يتم تثبيتها افتراضيًا.

الحل:```text uv sync --group debugger uv run python -m debugger

إذا كان لديك كل من Python العامة و venv للمشروع، فتأكد من التثبيت والتشغيل من نفس المفسر.

### 500 أخطاء الخادم الداخلي

**السبب:** استثناء من جانب الخادم، غالبًا بسبب فقدان بيانات البرنامج.

**الحل:**
1. تأكد من تحميل ملف ثنائي في CodeBrowser
2. قم بتشغيل التحليل التلقائي أولاً: **Analysis > Auto Analyze**
3. افحص وحدة تحكم Ghidra (**Window > Console**) بحثًا عن استثناءات Java
4. تتطلب بعض العمليات ملفات ثنائية محللة بالكامل

### 404 أخطاء غير موجودة

**السبب:** نقطة النهاية غير موجودة أو عنوان URL خاطئ.

**الحل:**
1. تحقق من وجود نقطة النهاية: `curl http://127.0.0.1:8089/get_version`
2. تحقق من وجود أخطاء إملائية في اسم نقطة النهاية
3. تأكد من استخدام طريقة HTTP الصحيحة (GET مقابل POST)

### فشل نصوص Ghidra Python مع "No script provider found"

**السبب:** في Ghidra 12.1.2، لم يعد دعم Jython ممكّنًا افتراضيًا. تحتاج نصوص `.py` إلى إضافة Jython المضمنة؛ ويجب أن تستخدم نصوص Python 3 PyGhidra بدلاً من Ghidra Script Manager.

**الحل:**
1. في الواجهة الأمامية لـ Ghidra، افتح **File > Install Extensions**.
2. حدد **Jython**، وأعد تشغيل Ghidra، ثم قم بتحديث مدير النصوص.
3. للأتمتة الجديدة، يُفضل نصوص Java Ghidra أو PyGhidra.

### الإضافة لا تظهر في Install Extensions

**السبب:** ملف JAR في موقع خاطئ.

**الحل:**
1. موقع التثبيت اليدوي: `~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`
2. أو استخدم: **File > Install Extensions > Add** واختر ملف ZIP
3. تأكد من أن JAR/ZIP قد تم بناؤه لإصدار Ghidra الخاص بك

### فشل البناء مع "Ghidra dependencies not found"

**السبب:** لم يتم تثبيت ملفات JAR الخاصة بـ Ghidra في مستودع Maven المحلي.

**الحل:**```text
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

📊 أداء الإنتاج

• أدوات MCP: 271 أداة مطبقة بالكامل
• السرعة: استجابة دون الثانية لمعظم العمليات
• الكفاءة: تقليل بنسبة 93% في استدعاءات API عبر العمليات المجمعة
• الموثوقية: معاملات ذرية بدلالة الكل أو لا شيء
• سير عمل AI: مطالبات توثيق مثبتة تم تحسينها عبر مئات الوظائف الحقيقية
• النشر: نص برمجي آلي للنشر مع إدراك الإصدار

🛠️ مرجع API

271 أداة MCP مدعومة بنقاط نهاية HTTP، مجمعة حسب فئة الكتالوج. تم إنشاؤها من tests/endpoints.json بواسطة python -m tools.gen_readme_api_reference --write؛ المخطط الحي في /mcp/schema هو المرجعي في وقت التشغيل. أنماط الاستخدام: docs/prompts/TOOL_USAGE_GUIDE.md.

إدارة البرنامج والجلسة

• analysis_status - الحصول على حالة التحليل التلقائي للبرامج المفتوحة
• close_program - إغلاق برنامج مفتوح بواسطة مسار المشروع أو الاسم
• create_property_map - إنشاء خريطة خصائص مستخدم لتخزين القيم المقيدة بالنوع والمفهرسة حسب العنوان
• delete_property_map - حذف خريطة خصائص مستخدم وجميع القيم التي تحتويها
• exit_ghidra - حفظ وخروج من Ghidra
• get_address_spaces - سرد جميع مساحات العناوين الفعلية والتراكب في البرنامج (تتضمن التراكبات علامة is_overlay واسم overlayed_space)
• get_current_program_info - الحصول على معلومات البرنامج الحالي
• get_language_metadata - تفريغ وصف لغة البرنامج: مساحات العناوين، السجلات، الرموز الافتراضية، ترتيب البايتات، حجم المؤشر (الإصدار #192)
• get_program_options - قراءة جميع الخيارات في مجموعة خيارات برنامج مع الأنواع والقيم الحالية والافتراضية والأوصاف
• get_property - قراءة القيمة المخزنة في عنوان داخل خريطة خصائص
• import_file - استيراد ملف ثنائي من القرص إلى مشروع Ghidra الحالي وفتحه

تنظيم المشروع

• create_folder - إنشاء مجلد في المشروع
• delete_file - حذف ملف من المشروع
• delete_project - حذف مشروع Ghidra
• list_projects - سرد مشاريع Ghidra المتاحة
• move_file - نقل ملف إلى مجلد مشروع آخر
• move_folder - نقل مجلد إلى موقع آخر
• project_info - الحصول على معلومات مفصلة عن المشروع بما في ذلك الأدوات الجارية والبرامج المفتوحة

دورة حياة المشروع والبرنامج في وضع الرأس

متاحة على الخادم المستقل في وضع الرأس (GhidraMCPHeadlessServer).

• archive_project - أرشفة المشروع المفتوح حاليًا إلى ملف .gar أصلي لـ Ghidra
• checkin_program - إعادة برنامج مفتوح إلى خادم Ghidra المشترك كإصدار جديد
• close_project - إغلاق المشروع المفتوح حاليًا
• create_project - إنشاء مشروع Ghidra جديد
• export_program - تصدير برنامج مفتوح أو مقيم في المشروع إلى ملف Ghidra Zip (.gzf)
• get_project_info - الحصول على معلومات حول المشروع المفتوح حاليًا
• import_program - استيراد ملف Ghidra Zip (.gzf) إلى المشروع المفتوح حاليًا كملف DomainFile جديد تحت target_folder (الافتراضي '/')
• load_program - تحميل ملف ثنائي إلى الخادم في وضع الرأس للتحليل
• load_program_from_project - تحميل برنامج من مشروع Ghidra (وضع الرأس)
• open_project - فتح مشروع Ghidra موجود (.gpr file أو دليل)
• restore_project - استعادة أرشيف .gar لـ Ghidra إلى مشروع جديد على القرص في

القائمة والتعداد

• list_bookmarks - سرد الإشارات المرجعية
• list_calling_conventions - سرد اصطلاحات الاستدعاء المتاحة
• list_classes - سرد أسماء المساحات/الفئات
• list_data_items - سرد البيانات المعرفة
• list_data_items_by_xrefs - سرد البيانات مرتبة حسب عدد المراجع المتقاطعة
• list_exports - سرد الرموز المصدرة
• list_external_locations - سرد المواقع الخارجية
• list_functions - سرد الوظائف مع العناوين
• list_functions_enhanced - سرد الوظائف مع البيانات الوصفية
• list_globals - سرد المتغيرات العامة
• list_imports - سرد الرموز المستوردة
• list_methods - سرد جميع أسماء الوظائف مع ترقيم الصفحات

السياق والبحث

• get_current_address - الحصول على عنوان المؤشر (واجهة المستخدم الرسومية فقط)
• get_current_function - الحصول على الوظيفة عند المؤشر (واجهة المستخدم الرسومية فقط)
• get_current_selection - الحصول على نطاقات العناوين المميزة في قائمة CodeBrowser (واجهة المستخدم الرسومية فقط)
• get_entry_points - الحصول على نقاط الدخول للبرنامج
• get_enum_values - الحصول على قيم التعداد
• get_external_location - الحصول على تفاصيل الموقع الخارجي
• get_full_call_graph - الحصول على مخطط الاستدعاء الكامل
• get_function_by_address - الحصول على الوظيفة في عنوان
• get_function_call_graph - الحصول على مخطط الاستدعاء
• get_function_callees - الحصول على الوظائف التي يتم استدعاؤها
• get_function_callers - الحصول على الوظائف التي تستدعي

البحث

• find_similar_functions - العثور على وظائف مشابهة
• search_byte_patterns - البحث عن أنماط بايت
• search_data_types - البحث في أنواع البيانات
• search_functions - البحث عن وظائف بالاسم
• search_functions_enhanced - بحث متقدم عن الوظائف
• search_strings - البحث عن سلاسل معرفة بواسطة نمط تعبير عادي / سلسلة فرعية

فك التجميع والتفكيك

• decompile_function - فك تجميع وظيفة
• disassemble_bytes - تفكيك نطاق بايت
• disassemble_function - تفكيك وظيفة
• force_decompile - فرض فك تجميع جديد

علامات الوظائف والمتغيرات والسمات

• add_function_tag - إرفاق علامة أو أكثر بوظيفة
• batch_add_function_tags - إرفاق علامات بعدة وظائف في معاملة واحدة
• batch_remove_function_tags - فصل العلامات عن عدة وظائف في معاملة واحدة
• clear_flow_and_repair - تشغيل إجراء 'Clear Flow and Repair' لواجهة المستخدم الرسومية لـ Ghidra على نطاق بذري: يمسح تدفق التعليمات الذي يمكن الوصول إليه من البذرة، ثم يصلح أجسام الوظائف ويعيد تفكيك التدفق المحتفظ به (ClearFlowAndRepairCmd مع clear_data=false, clear_labels=false, repair=true)
• create_function_tag - إنشاء تعريف علامة وظيفة على مستوى البرنامج مع تعليق اختياري
• delete_function_tag - حذف تعريف علامة وظيفة على مستوى البرنامج
• get_function_tags - سرد جميع العلامات المخصصة لوظيفة معينة
• list_class_members - سرد وظائف العضو لفئة C++
• list_function_tags - سرد جميع تعريفات علامات الوظائف على مستوى البرنامج مع أعداد استخدامها
• remove_function_tag - فصل علامة أو أكثر عن وظيفة
• search_functions_by_tag - سرد جميع الوظائف التي تحتوي على علامة محددة مرفقة

المراجع المتقاطعة

• add_memory_reference - إنشاء مرجع متقاطع معرف من قبل المستخدم بين عنوانين من الذاكرة لا يمكن للمحلل التلقائي استنتاجه (جداول المؤشرات المعبأة في وقت التشغيل، جداول الوظائف الافتراضية، مؤشرات الوظائف المرتبطة متأخرًا، جداول القفز/التبديل المفقودة)
• get_bulk_xrefs - الحصول على مراجع متقاطعة لعناوين متعددة
• get_function_xrefs - الحصول على مراجع متقاطعة للوظيفة
• get_xrefs_from - الحصول على مراجع من عنوان
• get_xrefs_to - الحصول على مراجع إلى عنوان
• remove_reference - إزالة مرجع(مراجع) متقاطع من الذاكرة من عنوان إلى آخر — عكس add_memory_reference

أنواع البيانات والهياكل

• add_struct_field - إضافة حقل هيكل
• analyze_global_completeness - تسجيل درجة اكتمال توثيق متغير عام على مقياس 0-100 بميزانية — النظير لعنوان البيانات لـ analyze_function_completeness
• apply_data_type - تطبيق نوع بيانات
• audit_global - تدقيق حالة توثيق متغير عام
• audit_globals_in_function - تدقيق كل متغير عام مشار إليه من داخل وظيفة في استدعاء واحد
• batch_set_variable_types - تعيين أنواع متغيرات متعددة
• clone_data_type - استنساخ نوع بيانات
• create_array_type - إنشاء نوع مصفوفة
• create_data_type_category - إنشاء فئة نوع بيانات
• create_enum - إنشاء تعداد
• create_function_signature - إنشاء نوع توقيع وظيفة
• create_pointer_type - إنشاء نوع مؤشر

إعادة التسمية والتسميات

• batch_create_labels - إنشاء عدة تسميات
• batch_delete_labels - حذف عدة تسميات
• batch_rename_function_components - إعادة تسمية مكونات الوظيفة بشكل مجمع
• create_label - إنشاء تسمية
• delete_label - حذف تسمية في عنوان
• rename_data - إعادة تسمية رمز بيانات
• rename_external_location - إعادة تسمية موقع خارجي
• rename_function - إعادة تسمية وظيفة بالاسم
• rename_function_by_address - إعادة تسمية وظيفة بالعنوان
• rename_global_variable - إعادة تسمية متغير عام
• rename_label - إعادة تسمية تسمية
• rename_or_label - إعادة تسمية أو إنشاء تسمية

التعليقات والإشارات المرجعية

• batch_set_comments - تعيين عدة تعليقات
• clear_function_comments - مسح جميع التعليقات لوظيفة
• delete_bookmark - حذف إشارة مرجعية
• get_comment - الحصول على تعليقات القائمة (لوحة/قبل/نهاية السطر/بعد/قابل للتكرار) في أي عنوان، بما في ذلك عناوين البيانات (على عكس get_plate_comment الذي يتطلب وظيفة)
• get_plate_comment - الحصول على تعليق اللوحة
• set_bookmark - تعيين إشارة مرجعية
• set_comment - تعيين تعليق قائمة من نوع معين (لوحة/قبل/نهاية السطر/بعد/قابل للتكرار) في أي عنوان، بما في ذلك عناوين البيانات
• set_decompiler_comment - تعيين PRE_COMMENT
• set_disassembly_comment - تعيين EOL_COMMENT
• set_plate_comment - تعيين تعليق اللوحة

التحليل

• analyze_api_call_chains - تحليل سلاسل استدعاء API
• analyze_call_graph - تحليل أنماط مخطط استدعاء الوظائف
• analyze_control_flow - تحليل تدفق التحكم
• analyze_data_region - تحليل منطقة البيانات
• analyze_dataflow - تتبع انتشار القيمة خلال وظيفة (رسم PCode، أمامي/خلفي)
• analyze_for_documentation - تحليل توثيق RE مركب (فك تجميع + تصنيف + متغيرات + اكتمال)
• analyze_function_complete - تحليل وظيفة شامل باستدعاء واحد
• analyze_function_completeness - تحليل اكتمال التوثيق
• analyze_struct_field_usage - تحليل استخدام حقول الهيكل
• apply_data_classification - تطبيق تصنيف البيانات
• batch_analyze_completeness - تحليل الاكتمال بشكل مجمع لوظائف متعددة
• - تطبيق كل التوثيق على وظيفة في استدعاء واحد

التوثيق والأرشيف عبر الثنائيات

• archive_ingest_function - استيعاب توثيق وظيفة واحدة في أرشيف متعدد الإصدارات (re_kb.functions على bsim Postgres)
• archive_ingest_program - استيعاب كل وظيفة في برنامج بشكل مجمع في أرشيف التوثيق متعدد الإصدارات
• batch_string_anchor_report - تقرير عن سلاسل الملف المصدر ووظائف FUN_* الخاصة بها
• bulk_fuzzy_match - مطابقة وظائف ضبابية عبر الثنائيات بشكل مجمع
• find_similar_functions_fuzzy - مطابقة وظائف ضبابية عبر الثنائيات
• merge_program_documentation - دمج مجمع: نسخ كل توثيق RE (أسماء الوظائف، التوقيعات، تعليقات اللوحة، تعليقات التعليمات في EOL/PRE/POST، التسميات غير الافتراضية والرموز العامة) من برنامج إلى آخر في العناوين المطابقة

الأداة المساعدة ونقل التوثيق

• apply_function_documentation - تطبيق توثيق الوظيفة
• check_connection - نقطة نهاية فحص الصحة
• compare_programs_documentation - مقارنة التوثيق عبر البرامج
• convert_number - تحويل رقم بين الأساسات
• diff_functions - مقارنة وظيفتين
• find_undocumented_by_string - العثور على وظائف غير موثقة تشير إلى سلسلة
• get_bulk_function_hashes - الحصول على تجزئات الوظائف بشكل مجمع
• get_function_documentation - تصدير توثيق الوظيفة
• get_function_hash - الحصول على تجزئة الوظيفة
• get_function_signature - الحصول على توقيع ميزة الوظيفة
• get_metadata - الحصول على بيانات وصفية للبرنامج
• get_version - الحصول على إصدار الإضافة

المحاكاة

• emulate_function - محاكاة وظيفة واحدة مع إدخالات مسجلة/ذاكرة مسيطر عليها
• emulate_hash_batch - القوة الغاشمة لحل تجزئة API

البرمجة النصية

• run_ghidra_script - تشغيل نص مع التقاط المخرجات
• run_script_inline - تشغيل كود نص مضمن

خادم Ghidra والتحكم في الإصدارات

• server_admin_set_permissions - تعيين أذونات المستخدم على مستودع
• server_admin_terminate_all_checkouts - إنهاء جميع عمليات السحب في مجلد بشكل متكرر
• server_admin_terminate_checkout - إنهاء جميع عمليات السحب على ملف واحد
• server_admin_users - سرد جميع المستخدمين على الخادم
• server_authenticate - تسجيل بيانات اعتماد الخادم للمصادقة البرمجية
• server_checkouts - سرد جميع الملفات المسحوبة في مجلد، بما في ذلك عمليات السحب من جانب الخادم
• server_connect - الاتصال بخادم Ghidra
• server_disconnect - قطع الاتصال بخادم Ghidra
• server_repositories - سرد المستودعات على الخادم المتصل
• server_repository_create - إنشاء مستودع جديد على الخادم
• server_repository_file - الحصول على معلومات ملف من مستودع الخادم

المصحح (Ghidra TraceRmi — واجهة المستخدم الرسومية فقط)

على مضيفات Windows حيث يكون وكيل مصحح WinDbg للجسر نشطًا (GHIDRA_DEBUGGER_URL)، تحصل الأسماء المتضاربة على لاحقة _2 (مثل debugger_status_2).

• debugger_dynamic_to_static - ترجمة عنوان ديناميكي وقت التشغيل من التتبع الحالي إلى عنوان برنامج Ghidra ثابت
• debugger_interrupt - مقاطعة (اختراق) الهدف الجاري
• debugger_launch - تشغيل ملف قابل للتنفيذ من خلال مشغل مصحح Trace RMI لـ Ghidra
• debugger_launch_offers - سرد خيارات تشغيل/إرفاق المصحح المتاحة للبرنامج الحالي
• debugger_list_breakpoints - سرد جميع نقاط التوقف في التتبع الحالي
• debugger_modules - سرد الوحدات (DLLs/EXEs) المحملة في العملية المصححة
• debugger_read_memory - قراءة الذاكرة من العملية المصححة
• debugger_registers - قراءة سجلات وحدة المعالجة المركزية من لقطة التتبع الحالية
• debugger_remove_breakpoint - إزالة نقطة توقف في عنوان
• debugger_resume - استئناف تنفيذ العملية المصححة
• debugger_set_breakpoint - تعيين نقطة توقف تنفيذ برمجية في عنوان في التتبع

النظام

• prompt_policy - تمكين أو تعطيل أو الاستعلام عن معالجة المطالبات الآلية الموسعة بشكل مؤقت

أدوات الجسر الثابتةمُعرّفة في جسر Python نفسه (اكتشاف المثيلات، إدارة مجموعات الأدوات)؛ متاحة دائمًا حتى قبل الاتصال بـ Ghidra. كما يقوم الجسر بتوكيل 22 أداة debugger_* من WinDbg عندما يشير GHIDRA_DEBUGGER_URL إلى خادم المُصحح المستقل.

• check_tools - الإبلاغ عن الأدوات المسجلة والقابلة للاستدعاء حاليًا
• connect_instance - توصيل الجسر بمثيل Ghidra معين
• import_file - استيراد ملف ثنائي من القرص إلى المشروع الحالي وفتحه
• list_instances - اكتشاف مثيلات Ghidra MCP قيد التشغيل (مسح منافذ UDS + TCP)
• list_tool_groups - سرد مجموعات الأدوات وحالة تحميلها
• load_tool_group - تسجيل الأدوات الديناميكية لمجموعة أدوات لدى عميل MCP
• search_tools - البحث في كتالوج الأدوات الكامل حسب الكلمة المفتاحية
• unload_tool_group - إلغاء تسجيل الأدوات الديناميكية لمجموعة أدوات

انظر CHANGELOG.md لتاريخ الإصدارات.

🏗️ الهيكل```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │ │ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │ │ (Claude, etc.) │ │ ghidra/) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ MCP Protocol HTTP REST Ghidra API (stdio/streamable-http) (localhost:8089) (Program, Listing)

### المكونات

- **python/bridge_mcp_ghidra/** — حزمة خادم MCP بلغة بايثون (تُصدر كعجلة `ghidra-mcp-bridge`؛ النص البرمجي لوحدة التحكم `bridge-mcp-ghidra`) التي تترجم بروتوكول MCP إلى استدعاءات HTTP (225 إدخالاً في الكتالوج)
- **GhidraMCP.jar** — مكون إضافي لـ Ghidra يعرض إمكانيات التحليل عبر HTTP (175 نقطة نهاية واجهة المستخدم الرسومية)
- **GhidraMCPHeadlessServer** — خادم مستقل بدون واجهة — 183 نقطة نهاية، لا حاجة لواجهة المستخدم الرسومية
- **ghidra_scripts/** — مجموعة من نصوص الأتمتة للمهام الشائعة

## 🔧 التطوير

### البناء من المصدر```bash
# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z

نظام البناء المعتمد اليوم هو Maven. tools.setup ومهام VS Code وسير العمل الموثق للنشر كلها تبني عبر pom.xml وتكتب القطع الأثرية في target/. يبقى build.gradle في المستودع كخيار احتياطي يدوي للمستخدمين المباشرين لـ Ghidra/Gradle، لكنه ليس المسار الأساسي.

مرجع الأوامر

الأعلام الشائعة التي تقبلها معظم الأوامر:

طبقات اختبار النشر اختيارية لأن طبقات المعيار يمكنها استيراد/إعادة تعيين Benchmark.dll و BenchmarkDebug.exe في مشروع Ghidra النشط. استخدم --test release قبل إصدار الإصدارات، أو قم بتعيين GHIDRA_MCP_DEPLOY_TESTS=release في .env المحلي عندما تريد أن يقوم كل نشر على جهازك بتشغيل انحدار المعيار المباشر. انظر اختبار وانحدار الإصدار.```text

Standard first-time setup and deploy

python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Version bump and tag

python -m tools.setup bump-version --new X.Y.Z --tag

Run offline Java tests

python -m tools.setup run-tests

Show full help

python -m tools.setup --help

### هيكل المشروع```
ghidra-mcp/
├── pyproject.toml           # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/           # Ghidra plugin + headless server (Java)
│   └── com/xebyte/
│       ├── GhidraMCPPlugin.java         # GUI plugin (196 endpoints)
│       ├── headless/                    # Headless server (183 endpoints)
│       └── core/                        # Shared service layer (12 services)
├── debugger/                # Optional standalone debugger server (port 8099)
├── ghidra_scripts/          # Automation scripts for batch workflows
├── tests/                   # Python unit tests + endpoint catalog
│   ├── unit/               # Catalog consistency, schema, tool function tests
│   └── endpoints.json      # Endpoint specification (225 entries)
├── docs/                    # Documentation
│   ├── prompts/            # AI workflow prompts (V5 documentation workflows)
│   ├── releases/           # Version release notes
│   └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/             # Build and deployment CLI (python -m tools.setup)
├── fun-doc/                 # Internal RE curation tool — not part of the MCP plugin
│                            #   Priority-queue worker, LLM scoring, web dashboard.
│                            #   See fun-doc/README.md for details.
└── .github/workflows/      # CI/CD pipelines

تبعيات المكتبة

يجب تثبيت ملفات Ghidra JAR في مستودع Maven المحلي (~/.m2/repository) قبل التجميع. هذا إعداد لمرة واحدة لكل جهاز، ويتكرر عند تغيير إصدار Ghidra. الخيار -Deploy يقوم الآن بتثبيتها تلقائيًا بشكل افتراضي.

تفرض الأداة اتساق الإصدار بين:

• pom.xml (ghidra.version)
• مقطع إصدار --ghidra-path (مثل ghidra_12.1.2_PUBLIC)

إذا لم يتطابقا، يفشل النشر بسرعة مع رسالة خطأ واضحة.

استكشاف الأخطاء وإصلاحها: عدم تطابق الإصدار

إذا رأيت خطأ في عدم تطابق الإصدار، قم بمحاذاة القيمتين:

1. pom.xml → ghidra.version
2. مقطع إصدار --ghidra-path (ghidra_X.Y.Z_PUBLIC)

ثم أعد التشغيل:```text python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

### 4. WAF```text
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"

المكتبات المطلوبة (14 ملف JAR، ~37 ميجابايت):

ملاحظة: المكتبات غير مضمنة في المستودع (انظر .gitignore). يجب تثبيتها من تثبيت Ghidra الخاص بك قبل البناء.

نقطة الدخول للأتمتة:

• python -m tools.setup هي الواجهة المدعومة للإعداد/البناء/النشر/إدارة الإصدارات
• استخدم ensure-prereqs وbuild وdeploy وpreflight وclean-all وbump-version مباشرة
• تستخدم هذه الأوامر حاليًا Maven كخلفية بناء Java القياسية

ميزات التطوير

• النشر الآلي: نص نشر واعٍ بالإصدار
• العمليات المجمعة: تقليل استدعاءات API بنسبة 93%
• المعاملات الذرية: دلالات الكل أو لا شيء
• التسجيل الشامل: إمكانيات التصحيح والتتبع

📚 التوثيق

التوثيق الأساسي

• فهرس التوثيق - تصفح كامل للتوثيق
• هيكل المشروع - دليل تنظيم المشروع
• الاختبار ومراجعة الإصدارات - الاختبارات المحلية، CI، مراجعة Ghidra الحية، وبوابات الإصدار
• اتفاقيات التسمية - معايير تسمية الكود
• التدوين المجري - دليل تسمية المتغيرات

موجهات سير عمل الذكاء الاصطناعي

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

تاريخ الإصدارات

• سجل التغييرات الكامل - ملاحظات إصدار جميع الإصدارات
• ملاحظات الإصدار - توثيق إصدار مفصل

🐳 الخادم بدون واجهة (Docker)

يتضمن GhidraMCP وضع خادم بدون واجهة للتحليل الآلي دون واجهة Ghidra الرسومية.

بداية سريعة مع Docker```bash

Build and run

docker-compose up -d ghidra-mcp

Test connection

curl http://localhost:8089/check_connection

Connection OK - GhidraMCP Headless Server v5.17.0

### سير عمل API بدون رأس```bash
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program

# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis

# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"

# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"

# 5. Get metadata
curl http://localhost:8089/get_metadata

نقاط النهاية الرئيسية بدون واجهة رسومية

التكوين

المتغيرات البيئية لـ Docker:

• GHIDRA_MCP_PORT - منفذ الخادم (الافتراضي: 8089)
• GHIDRA_MCP_BIND_ADDRESS - عنوان الربط (الافتراضي: 0.0.0.0 في Docker)
• JAVA_OPTS - خيارات JVM (الافتراضي: -Xmx4g -XX:+UseG1GC)

🤝 المساهمة

راجع CONTRIBUTING.md للحصول على إرشادات المساهمة التفصيلية.

بداية سريعة

1. انسخ (Fork) المستودع
2. أنشئ فرع ميزة (git checkout -b feature/amazing-feature)
3. ابنِ واختبر تغييراتك (mvn clean package assembly:single -DskipTests أو GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)
4. حدّث التوثيق حسب الحاجة
5. ارتكب تغييراتك (git commit -m 'Add amazing feature')
6. ادفع إلى الفرع (git push origin feature/amazing-feature)
7. افتح طلب سحب (Pull Request)

📄 الترخيص

هذا المشروع مرخص بموجب رخصة Apache 2.0 - راجع ملف LICENSE للتفاصيل.

🏆 حالة الإنتاج

راجع CHANGELOG.md لتاريخ الإصدار وملاحظات الإصدار.

🙏 الإقرارات

هذا المشروع اشتق في الأصل من LaurieWired/GhidraMCP في أغسطس 2025 ومنذ ذلك الحين تمت إعادة كتابته وتوسيعه بشكل كبير. نقر بالعمل الأصلي لـ LaurieWired كنقطة انطلاق. راجع NOTICE لإسناد الترخيص.

👥 المساهمون

استفاد هذا المشروع من عمل المساهمين المخلصين:

المساهمون الأساسيون

@heeen — مساهمات كبيرة تشمل:

• مطابقة الدوال التقريبية والفرق المنظم للمقارنة عبر الثنائيات (#13)
• تحسينات تنفيذ النصوص البرمجية وإصلاح الأخطاء (#12)
• نقاط نهاية API جديدة: save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)
• الرؤية المعمارية: التصميم القائم على التعليقات التوضيحية، نقل UDS، مقترحات تحسين جسر Python

@huehuehuehueing — مساهمات كبيرة تشمل:

• دعم بادئة مساحة العنوان — إضافة صيغة <space>:<hex> (مثل mem:1000, code:ff00) لتحليل العناوين عبر سطح نقطة النهاية بالكامل، مما يفتح أهداف متعددة المساحات مثل البرامج الثابتة المضمنة (#84, يغلق #65)

• معلمة program الاختيارية + إصلاحات مخطط المعلمات المطلوبة — جعل program اختيارية على كل نقطة نهاية مع fallback معقول currentProgram، وأصلح العديد من أخطاء المخطط بين المطلوب والاختياري التي ورثها الكتالوج (#92)

• بذر #44 (أدوات نوع البيانات/التعداد) — المشكلة التي حفزت طبقة فرض التعداد + الهيكل في v5.0

• فريق Ghidra - لمنصة الهندسة العكسية المذهلة

• بروتوكول سياق النموذج - لإطار تكامل الذكاء الاصطناعي المعياري

• المساهمون - للاختبار والملاحظات والتحسينات

🔗 المشاريع ذات الصلة

• re-universe — منصة Ghidra BSim PostgreSQL لتحليل تشابه الثنائيات على نطاق واسع. تتزاوج بشكل مثالي مع GhidraMCP لسير عمل الهندسة العكسية المدعومة بالذكاء الاصطناعي.
• cheat-engine-server-python — خادم MCP لتحليل الذاكرة الديناميكي وتصحيح الأخطاء.

جاهز للنشر في الإنتاج بموثوقية على مستوى المؤسسات وقدرات تحليل ثنائي شاملة.