diaphora-mcp

[النسخة الروسية](https://github.com/xteardx/diaphora-mcp/blob/master/README.ru.md)

# Diaphora MCP

قارن بين ملفين ثنائيين تم تحليلهما بواسطة IDA من مساعد الذكاء الاصطناعي الخاص بك. يقوم Diaphora MCP بتصدير قواعد بيانات IDA المحفوظة، وتشغيل [Diaphora](https://github.com/joxeankoret/diaphora)، ويتيح للذكاء الاصطناعي فحص الدوال المتناظرة ومخططات الاستدعاء الخاصة بها.

تحتوي الواجهة الافتراضية على **10 أدوات** تركز على المقارنة. يوفر Diaphora المطابقات؛ ويقرأ الذكاء الاصطناعي الكود الفعلي ويشرح التغييرات.

[البدء السريع](#quick-start) · [أمثلة](#examples) · [الأدوات](#tools) · [استكشاف الأخطاء وإصلاحها](#troubleshooting)

```text
old.i64 + new.i64 → headless export → SQLite exports + diff results
                                       ↓
                            summary → matched code → call graph
```

## المتطلبات

- Python 3.10+، وIDA Pro مع `idat.exe`/`idat64`، وإضافة Diaphora مثبتة.
- كلا الملفين الثنائيين محللان ومحفوظان كقواعد بيانات `.i64`/`.idb`.
- عميل MCP محلي، مثل Codex أو Claude Code أو Cursor.
- مُفكِّك Hex-Rays متوافق فقط إذا كنت تريد الكود الزائف.

يتم تثبيت IDA وDiaphora بشكل منفصل. يستهدف التحقق من صحة مخطط الفروقات حاليًا Diaphora **3.4.1**؛ قد تحتاج المخططات الأخرى إلى تحديثات توافق. يجب أن يكون مفسر Python المستخدم للفرق مثبتًا عليه تبعيات Diaphora المستقلة.

## البدء السريع

### 1. التثبيت وإنشاء دليل الإخراج

```powershell
git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
New-Item -ItemType Directory -Force C:\diaphora-outputs | Out-Null
```

### 2. توصيل خادم MCP

أضف هذا الإدخال إلى تكوين MCP الخاص بعميلك. استبدل مسارات المستودع وIDA وDiaphora بمسارات التثبيت الخاصة بك. استخدم ملف Python التنفيذي من البيئة التي ثبّت فيها هذا المشروع.

```json
{
  "mcpServers": {
    "diaphora": {
      "command": "C:/src/diaphora-mcp/.venv/Scripts/python.exe",
      "args": ["C:/src/diaphora-mcp/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:/Program Files/IDA Professional 9.3/idat.exe",
        "DIAPHORA_DIR": "C:/Program Files/IDA Professional 9.3/plugins/diaphora",
        "DIAPHORA_OUTPUT_ROOT": "C:/diaphora-outputs"
      }
    }
  }
}
```

يشغّل العميل الخادم عبر stdio؛ لا توجد خدمة ويب منفصلة لبدء تشغيلها. أعد تشغيل خادم MCP بعد تغيير الكود أو البيئة الخاصة به. الاتصال الناجح يعرض الأدوات العشر المذكورة أدناه.

### 3. اطلب من مساعدك مقارنة الملفات

```text
Use Diaphora to compare C:/analysis/old.i64 (old) against
C:/analysis/new.i64 (new). Save output under C:/diaphora-outputs/run-001.
Export headlessly with assembly detail, keep the exports, show a summary,
then inspect partial matches and explain the code changes in the interesting
functions. Use the result mapping when comparing functions and call graphs.
```

اختر **دليل تشغيل جديدًا** في كل مرة. لا يتم استبدال الأهداف المُنشأة الموجودة أبدًا.

## أمثلة

كتل JSON التالية هي **وسائط أدوات MCP**، وليست أوامر shell. يمكن لمساعدك استدعاء الأدوات المذكورة مباشرة. المسارات و`0x401000` أمثلة؛ استخدم المسارات والعناوين التي أرجعها تشغيلك الخاص.

### 1. تصدير ومقارنة قاعدتي بيانات IDA

الأداة: **`batch_export_and_diff`**. القديم دائمًا هو الإدخال الأول، والجديد هو الثاني.

```json
{
  "idb1_path": "C:/analysis/old.i64",
  "idb2_path": "C:/analysis/new.i64",
  "output_dir": "C:/diaphora-outputs/run-001",
  "export_mode": "headless",
  "use_decompiler": false,
  "summaries_only": false,
  "cleanup": false,
  "limit": 100,
  "unmatched_limit": 50
}
```

يحافظ هذا على تفاصيل التجميع دون الحاجة إلى Hex-Rays. اختر ملف تعريف التصدير الذي تحتاجه:

| التفاصيل | `use_decompiler` | `summaries_only` | الاستخدام |
| --- | --- | --- | --- |
| ملخصات المطابقة | `false` | `true` | تمريرة أولى سريعة؛ بدون كود مفصّل |
| التجميع | `false` | `false` | مقارنة التفكيك بدون مُفكِّك |
| التجميع + الكود الزائف | `true` | `false` | مراجعة الكود باستخدام مُفكِّك Hex-Rays متوافق؛ أبطأ |

خذ دائمًا مسارات الإخراج من الاستجابة:

```text
OLD_SQLITE = steps.export1.output
NEW_SQLITE = steps.export2.output
RESULTS    = steps.diff.output
```

في هذا المثال، الملفات المُنشأة هي `old.diaphora.sqlite` و`new.diaphora.sqlite` و`old_vs_new.diaphora` تحت `run-001`. أسماء الإدخال الأساسية المتساوية تنتج أسماء تصدير مميزة `old_`/`new_`. أبقِ `cleanup=false` لفحص الدوال لاحقًا.

### 2. الحصول على ملخص وفحص المطابقات المتغيرة

الأداة: **`get_diff_summary`**.

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

الأداة: **`get_diff_results`**. تبدأ هذه الصفحة بمطابقات جزئية ذات نسبة أقل.

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora",
  "match_type": "partial",
  "min_ratio": 0.0,
  "limit": 50,
  "offset": 0,
  "unmatched_limit": 50,
  "unmatched_offset": 0,
  "sort_by": "ratio",
  "sort_order": "asc"
}
```

يحدد `partial` فئة مطابقة Diaphora، وليس ضمانًا لتغيير سلوكي. استخدم `match_type="all"` لجميع الفئات المدعومة. تتضمن الاستجابة عدد الفئات، والإجمالي المفلتر، والمطابقات، والصفوف غير المتطابقة، و`next_offset` و`next_unmatched_offset`.

للمتابعة، انسخ الإزاحات التالية المُرجعة إلى الاستدعاء التالي، مع الحفاظ على نفس المرشحات والترتيب. على سبيل المثال، إذا كانتا `50` و`50`، استخدم `offset=50` و`unmatched_offset=50`. تعني الإزاحة التالية `null` أن تلك القائمة انتهت؛ توقف عن تقدّمها. تتقدم القائمتان بشكل مستقل. يجب أن تكون أحجام الصفحات موجبة ويتم تحديدها بحد أقصى 5000. استخدم `sort_order="desc"` لفحص أقوى المطابقات أولاً.

### 3. مقارنة دالة مطابقة ومخططها

الأداة: **`compare_functions`**.

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "address": "0x401000",
  "match_results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

تحتوي الاستجابة على `function_old` و`function_new`، والتجميع/الكود الزائف المتاح، والاختلافات المقاسة، وأدلة الهوية. يمكنك استخدام `name` بدلاً من `address`. إذا تم توفير كلا المحددين، فإن العنوان له الأولوية؛ احذفه عند الاختيار بالاسم.

الأداة: **`get_changed_callgraph`** تقبل نفس الوسائط أعلاه. تترجم عناوين المستدعي/المستدعى المتناظرة قبل الإبلاغ عن التغييرات، وتفصل الجيران غير المحلولين عن فروقات الحواف المؤكدة.

فضّل **العناوين المسبوقة بـ `0x`** لجعل الإدخال السداسي عشري صريحًا. وفّر `match_results_path` عند توفره: فهو يتعامل مع إعادة التأسيس والدوال المعاد تسميتها. العناوين المتساوية وحدها لا تثبت الهوية. تبقى المطابقات الغامضة أو المفقودة غير محلولة بدلاً من اعتبارها عمليات حذف. إذا تحققت يدويًا من زوج، يمكنك توفير `address2` أو `name2` بشكل صريح.

### 4. العثور على دالة وقراءة كودها

الأداة: **`search_export_db`**. يستخدم `name_pattern` SQL LIKE: `%` يطابق أي تسلسل.

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "name_pattern": "%parse%",
  "min_instructions": 20,
  "limit": 20
}
```

الأداة: **`get_function_pseudocode`** تُرجع الكود الزائف المتاح **والتجميع**، رغم اسمها.

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "address": "0x401000"
}
```

إذا كان الكود الزائف فارغًا، أعد تشغيل التصدير إلى دليل تشغيل جديد مع `use_decompiler=true` و`summaries_only=false`، باستخدام مُفكِّك متوافق. استخدم `get_export_info` مع `db_path` لفحص بيانات التصدير الوصفية.

### 5. مقارنة الصادرات التي لديك بالفعل

الأداة: **`diff_diaphora_dbs`**. هذا يتخطى تصدير IDA ويقارن صادرات SQLite الرسمية الموجودة.

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "output_path": "C:/diaphora-outputs/another-diff.diaphora"
}
```

لتصدير جديد واحد، استخدم `export_idb_to_diaphora` مع `idb_path`، و`output_path` جديد، و`export_mode="headless"`.

## الأدوات

| الأداة | الغرض |
| --- | --- |
| `export_idb_to_diaphora` | تصدير قاعدة بيانات IDA محفوظة واحدة |
| `batch_export_and_diff` | تصدير كلا قاعدتي البيانات ومقارنتهما |
| `diff_diaphora_dbs` | مقارنة الصادرات الموجودة |
| `get_diff_summary` | إحصائيات المطابقة وأمثلة محدودة |
| `get_diff_results` | نتائج مفلترة ومرتبة ومقسمة إلى صفحات |
| `get_export_info` | بيانات التصدير الوصفية والأعداد |
| `search_export_db` | البحث عن الدوال |
| `get_function_pseudocode` | قراءة التجميع/الكود الزائف |
| `compare_functions` | مقارنة زوج قديم/جديد محلول |
| `get_changed_callgraph` | مقارنة المستدعين/المستدعين المتناظرين |

يمكن اكتشاف التوقيعات الدقيقة عبر MCP `tools/list`. راجع [مرجع الأدوات](https://github.com/xteardx/diaphora-mcp/blob/master/docs/TOOLS.md).

## أوضاع التصدير والتكوين

| الوضع | السلوك |
| --- | --- |
| `headless` | تشغيل IDA بدون واجهة والتحقق من مخطط الفروقات؛ موصى به للمقارنات |
| `auto` | تجربة جسر واجهة المستخدم الرسومية النشط، ثم الرجوع إلى الوضع بدون واجهة |
| `gui` | يتطلب جلسة واجهة مستخدم رسومية مفتوحة صحيحة؛ لا رجوع إلى الوضع بدون واجهة |

يتطلب `batch_export_and_diff` الوضع `headless`.

| متغير البيئة | المعنى |
| --- | --- |
| `IDAT_PATH` | المسار المطلق لملف IDA التنفيذي بدون واجهة |
| `DIAPHORA_DIR` | الدليل الذي يحتوي على نصوص Diaphora البرمجية |
| `DIAPHORA_OUTPUT_ROOT` | الجذر المسموح به الموجود للصادرات الجديدة ونتائج الفروقات |
| `DIAPHORA_PYTHON` | مفسر الفرق الاختياري؛ الافتراضي هو مفسر خادم MCP |
| `DIAPHORA_ENABLE_LEGACY_TOOLS` | القيمة `1` بالضبط تُفعّل واجهة الأدوات الـ 21 السابقة |

تبقى المطابقة القديمة، ودرجات الميزات، وفرز الأمان، والتقارير، والبيانات الوصفية، والتشخيصات اختيارية. لتفعيلها، أضف الإدخال التالي إلى كائن `env` في التكوين وأعد التشغيل:

```json
{
  "DIAPHORA_ENABLE_LEGACY_TOOLS": "1"
}
```

تستخدم هذه الأدوات استدلالات؛ درجاتها لا تثبت التكافؤ الدلالي أو إصلاحات الأمان أو السببية. [التكوين](https://github.com/xteardx/diaphora-mcp/blob/master/docs/CONFIGURATION.md) · [إعداد واجهة المستخدم الرسومية](https://github.com/xteardx/diaphora-mcp/blob/master/GUI_INSTRUCTIONS.md).

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

| العَرَض | الإجراء |
| --- | --- |
| الهدف موجود بالفعل | استخدم دليل تشغيل جديدًا أو اسم ملف إخراج جديدًا |
| الإخراج خارج الجذر المسموح به | اختر وجهة تحت `DIAPHORA_OUTPUT_ROOT`؛ أنشئ الجذر أولاً |
| تمرير قاعدة بيانات IDA إلى أداة نتائج | استخدم صادرات `.diaphora.sqlite` المُرجعة أو نتائج `.diaphora`، حسب الاقتضاء |
| نظير مفقود/غامض | تحقق من ترتيب القديم/الجديد والتعيين؛ افحص المرشح يدويًا |
| تجميع/كود زائف فارغ | تحقق من ملف تعريف التصدير؛ احصل على تصدير مفصّل جديد |
| يستغرق التصدير/الفرق وقتًا طويلاً | زد مهلة عميل MCP؛ افحص `logs/` المحلية؛ فكّر في تمريرة أولى للملخصات فقط |
| IDB مقفل بجلسة IDA | أغلق الجلسة أو استخدم وضع تصدير واجهة المستخدم الرسومية المطابق لتصدير واحد |
| مخطط غير مدعوم | أعد التصدير بإصدار Diaphora المدعوم؛ راجع الجداول/الأعمدة المفقودة المُبلغ عنها |

تبقى المطابقة استدلالية؛ النسبة العالية دليل وليست إثباتًا. الدوال غير المتطابقة ليست إضافات/عمليات حذف مؤكدة. أبقِ الملفات الثنائية وIDBs والصادرات والسجلات خارج Git. راجع [سير العمل](https://github.com/xteardx/diaphora-mcp/blob/master/docs/WORKFLOWS.md)، و[القيود](https://github.com/xteardx/diaphora-mcp/blob/master/docs/LIMITATIONS.md)، و[الأمان](https://github.com/xteardx/diaphora-mcp/blob/master/SECURITY.md).

## التطوير

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q .
git diff --check
```

تستخدم مجموعة الاختبارات الانحدارية قواعد بيانات اصطناعية وعمليات IDA وهمية. يتطلب تصدير IDA الحقيقي التحقق من التكامل المحلي. [المساهمة](https://github.com/xteardx/diaphora-mcp/blob/master/CONTRIBUTING.md) · [تعليمات الوكيل](https://github.com/xteardx/diaphora-mcp/blob/master/AGENTS.md).