ai-reverse-engineering

# ريف·ديك — الهندسة العكسية بمساعدة الذكاء الاصطناعي باستخدام Ghidra

ريف·ديك هي محطة عمل تحليل ثابت محلية لمستخدم واحد. تجمع بين واجهة مستخدم على الويب تعتمد على الأدلة أولاً ومساعد LLM على ثنائي يتم تحليله بواسطة خدمة Ghidra بدون واجهة رسومية: تصفح الأدلة الحتمية (الدوال، السلاسل النصية، الواردات، المراجع المتقاطعة، رسم بياني محدود للاستدعاءات) مباشرة، أو اطرح أسئلة محدودة على المساعد يجب أن تستند ادعاءاتها الواقعية إلى أدلة يمكن فحصها.

لا يتم تنفيذ الثنائيات المحللة أبدًا. يتواصل المتصفح فقط مع تطبيق Flask هذا؛ يقوم التطبيق بتوكيل الطلبات المُتحقق منها والمكتوبة إلى خدمة Ghidra.

## عرض توضيحي

https://github.com/user-attachments/assets/fba14dc5-7ad5-4137-9349-ed824da64fbe

## بدء سريع (Docker)

```bash
cp .env.example .env      # ضبط API_BASE و MODEL_NAME؛ اضبط API_KEY إذا لزم الأمر
docker compose up --build
```

يقرأ Docker Compose ملف `.env` تلقائيًا للاستيفاء. يفشل قبل البدء إذا كان `API_BASE` أو `MODEL_NAME` مفقودًا؛ يظل `API_KEY=not-used` صالحًا للمزودين المحليين/بدون مفتاح. يبدأ الـ stack كلتا الخدمتين. افتح http://127.0.0.1:5000.

لتشغيل خدمة Ghidra فقط:

```bash
docker pull biniamfd/ghidra-headless-rest:latest   # تأكد من أحدث صورة

docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:latest
```

للحصول على pin قابل للتكرار، استخدم digest الإصدار المختبر بدلاً من `latest`:

```bash
docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:1.2.1@sha256:971591a3a8448d8ed969079b452306e806f36079c3ddd298f4a618d6e2f1442d
```

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

- Docker و Docker Compose (لمسار البدء السريع)، أو Python 3.10+ و Node.js 18+ (للتشغيل من المصدر).
- نقطة نهاية LLM متوافقة مع OpenAI (محلية أو مستضافة) واسم النموذج.
- صورة Ghidra العامة: `biniamfd/ghidra-headless-rest:latest`.

## متغيرات البيئة الأساسية

انسخ `.env.example` إلى `.env` واملأ هذه المتغيرات؛ راجع ذلك الملف للحصول على القائمة الكاملة والافتراضيات.

| المتغير | الافتراضي | المعنى |
| --- | --- | --- |
| `API_BASE` | مطلوب | عنوان URL الأساسي المتوافق مع OpenAI (http/https). يتعطل Compose مبكرًا عند غيابه. |
| `API_KEY` | `not-used` | مفتاح المزود. لا يتم تسجيله أو إرساله إلى المتصفح أبدًا؛ `not-used` صالح للمزودين المحليين بدون مفتاح. |
| `MODEL_NAME` | مطلوب | معرف النموذج المتوقع بواسطة نقطة النهاية المكونة. يتعطل Compose مبكرًا عند غيابه. |
| `LLM_STREAM` | `auto` | نقل التدفق: `auto` (تدفق، الرجوع إلى الاستدعاء المحظور مرة واحدة عند حدوث خطأ توافق قبل الإخراج)، `true` (تدفق دائمًا)، `false` (محظور دائمًا). |
| `GHIDRA_API_BASE` | `http://127.0.0.1:9090` | عنوان URL الأساسي لخدمة Ghidra. |
| `GHIDRA_IMAGE` | `biniamfd/ghidra-headless-rest:1.2.1@sha256:971591a3...` | إصدار مُختبر مثبت بواسطة digest ثابت. `:latest` يحل أيضًا إلى هذا digest؛ تجاوز لتثبيت إصدار مختلف. |
| `HOST` / `PORT` | `127.0.0.1` / `5000` | ربط خادم التطوير. |
| `MAX_UPLOAD_BYTES` | `104857600` | حد حجم الرفع. |
| `CHATS_DIR` | `webui/chats` | دليل سجل المحادثات. |

## مزود LLM

يتحدث ريف·ديك مع **أي نقطة نهاية Chat Completions متوافقة مع OpenAI** عبر OpenAI SDK، ويتم تكوينه بالكامل بواسطة `API_BASE` / `API_KEY` / `MODEL_NAME`. لا يوجد رأس أو معلمة أو منطق نموذج خاص بمزود معين: خادم [Ollama](https://ollama.com) محلي (`API_BASE=http://127.0.0.1:11434/v1`)، أو نقطة نهاية vLLM/llama.cpp/LM Studio مستضافة ذاتيًا، أو OpenAI نفسها، أو بوابة مثل OpenRouter تعمل جميعها بنفس الطريقة.

مثال إعدادات `.env` للمزود (استخدم العناصر النائبة، لا تلتزم بالمفاتيح الحقيقية أبدًا):

```dotenv
# Ollama
API_BASE=http://127.0.0.1:11434/v1
API_KEY=not-used
MODEL_NAME=qwen3:8b
```

```dotenv
# OpenRouter
API_BASE=https://openrouter.ai/api/v1
API_KEY=replace-with-your-key
MODEL_NAME=anthropic/claude-opus-4.8
```

```dotenv
# OpenAI
API_BASE=https://api.openai.com/v1
API_KEY=replace-with-your-key
MODEL_NAME=replace-with-a-supported-model-id
```

```dotenv
# LM Studio أو vLLM أو llama.cpp (اضبط المنفذ/النموذج حسب الخادم)
API_BASE=http://127.0.0.1:1234/v1
API_KEY=not-used
MODEL_NAME=replace-with-the-served-model-id
```

بشكل افتراضي (`LLM_STREAM=auto`)، يطلب المساعد استجابة **متدفقة** ويقوم بنقل الرموز إلى المتصفح فور وصولها. يمنح التدفق أيضًا ضمانًا أقوى للإلغاء: عندما توقف استجابة (أو تغلق التبويب)، يغلق ريف·ديك بسرعة دفق المزود الأساسي ولا يقوم بجولات أدوات أو نموذج إضافية، لذلك يتم إنهاء التوليد المنبع بدلاً من تركه يعمل حتى الاكتمال في الخلفية.

ملاحظات:

- **الفواتير.** يؤدي الإلغاء إلى إغلاق الدفق من جانبنا فورًا، لكن بعض المزودين المستضافين لا يزالون يقومون بفوترة الرموز التي تم إنشاؤها بالفعل (أو للإكمال الكامل) بغض النظر عن قطع الاتصال المبكر من العميل. الضمان يتعلق بـ *عدم القيام بعمل إضافي*، وليس بسياسة الفوترة للمزود.
- **التوافق.** لا تقبل كل نقطة نهاية متوافقة مع OpenAI التدفق مع الأدوات. في وضع `auto`، إذا رفض المزود الطلب المتدفق بسبب خطأ توافق (HTTP 400/404/405/422) *قبل أي* محتوى أو إخراج استدعاء أداة، يتراجع ريف·ديك إلى استدعاء محظور واحد ويتذكر ذلك لبقية العملية. لا يتم التعامل مع أخطاء المصادقة (401/403)، أو تحديد المعدل (429)، أو الخادم (5xx) كمشكلات توافق ويتم عرضها كأخطاء بدلاً من إعادة المحاولة بصمت. اضبط `LLM_STREAM=false` لتخطي التدفق تمامًا، أو `LLM_STREAM=true` لفرضه (بدون تراجع).

## كيفية الاستخدام

افتح التطبيق وقم برفع ثنائي لبدء مهمة تحليل. يطلب المحتوى النصي الواضح التأكيد قبل إرساله إلى Ghidra؛ استخدم تجاوز الثنائي الخام الصريح فقط عندما يكون المحتوى عمدًا برنامجًا ثابتًا/بيانات بدلاً من تنسيق قابل للتنفيذ. بمجرد اكتمال التحليل، قم بالتبديل بين علامتي تبويب مساحة العمل:

- **التحليل** — عروض الأدلة الحتمية: الملخص، الدوال (تصفية/ترقيم الصفحات)، الواردات، السلاسل النصية، عرض استعلام، فاحص دالة (رمز زائف، مراجع متقاطعة، رسم بياني محدود للاستدعاءات، تفريغ سداسي عشري)، وعندما تدعم خدمة Ghidra المتصلة ذلك — الأنواع، المتغيرات العامة، التعليقات التوضيحية الجانبية، تصدير الأرشيف، وترتيب هجوم حتمي مع إشارات إيجابية/مخففة قابلة للتفسير وتغطية الأدلة.
- **المحادثة** — المساعد، في أحد وضعين:
  - **المساعد المشارك** (افتراضي): خطوة واحدة محدودة / استدعاء أداة لكل رسالة، للأسئلة المخصصة.
  - **مستقل**: بدء سير عمل مسمى بميزانية محدودة يقوم بعدة خطوات محدودة بمفرده ويعرض جدول زمني للنشاط المباشر أثناء العمل.

يأخذ كلا الوضعين **ميزانية خطوة** لكل مهمة، وخيار **بدون حد للخطوات** يعمل حتى تنتهي المهمة (لا يزال مقيدًا بـ `MAX_STEP_BUDGET` حتى لا يمكن لنموذج متكرر الهروب). إذا وصلت عملية إلى ميزانيتها، فإنها تبلغ عن نتائج جزئية وتقدم **متابعة** — والتي تستأنف نفس المحادثة باستخدام الأدلة المسترجعة بالفعل، دون إعادة استدعاءات الأدوات المكتملة. تنمو التكلفة مع عدد استدعاءات الأدوات/النموذج، لذا فإن الميزانيات الأعلى تكلف أكثر.

سير العمل المتاحة:

| سير العمل | الغرض | يتطلب عنوان دالة هدف |
| --- | --- | --- |
| `program_triage` | تلخيص الغرض المحتمل للبرنامج من البيانات الوصفية والواردات والسلاسل النصية والدوال. | لا |
| `suspicious_behavior` | عرض المؤشرات الحتمية أولاً، ثم فرضيات محدودة ومُصنفة بوضوح. | لا |
| `selected_function` | فك ترجمة دالة وشرحها مع المتصلين/المستدعين بها. | نعم |
| `call_chain` | استكشاف حي واحد محدود من الرسم البياني للاستدعاءات الأصلي/المركب من دالة بداية. | نعم |
| `attack_surface_triage` | قراءة تغطية/أفضل-K للنقاط الحتمية، ثم فحص ثلاثة مرشحين على الأكثر بعمق؛ النقاط هي أولويات وليست أحكامًا. | لا |
| `vulnerability_hypothesis` | اختيار مرشح واحد محدود وعرض الأدلة والأدلة المضادة والأسئلة المفتوحة؛ لا يقوم بالتأكيد التلقائي أبدًا. | لا |

### تحقيقات فرعية مركزة

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

عندما يكون العمل المركز جاهزًا، اختر **إعادة النتيجة إلى الأصل**. يقوم ريف·ديك باستدعاء نموذج محدود واحد على تلك السلسلة الفرعية فقط، ويتحقق من استشهادات الأدلة الخاصة بها، ويضيف بطاقة استنتاج واحدة مميزة بالإسناد إلى الأصل. يبقى الفرع بأكمله قابلاً لإعادة الفتح، بينما يتلقى سياق الأصل فقط الاستنتاج المدمج – وليس نص الفرع. يتم وضع علامة صريحة على البطاقة المرتجعة التي لا تحتوي على استشهادات مُتحقق منها على أنها غير مُتحقق منها.

تشير إجابات المساعد إلى الأدلة داخليًا كـ `[function:0xADDR]`، `[string:0xADDR]`، أو `[import:name]`. يتم التحقق من الاستشهادات مقابل ما تم استرجاعه فعليًا أثناء الجولة؛ يتم وضع علامة "(غير مُتحقق منه)" على الاستشهاد الذي لا يتطابق ويجب التعامل معه كادعاء غير مؤكد، وليس كحقيقة.

يتم عرض رسومات Mermaid في إخراج المساعد (مثل رسومات رسم بياني للاستدعاءات) في إطار معزول بدون وصول إلى الشبكة الخارجية.

## البنية

يتواصل المتصفح فقط مع تطبيق الويب Rev·Deck. يقوم Rev·Deck بتنسيق LLM المكون وخدمة Ghidra بدون واجهة رسومية، ثم يعرض الأدلة الناتجة ونشاط الوكيل في مساحة عمل واحدة.

<img width="916" height="651" alt="بنية ريف·ديك" src="https://assets.kitploit.com/production/public/readmes/9561/40809484745cf03bf42790c8abff0146755ebb953a3774c8fac17fbc3c0552de.png" />

## التشغيل من المصدر

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
npm ci && npm run vendor        # مرة واحدة: شراء تشغيل Mermaid المثبت

cp .env.example .env            # قم بتحرير API_BASE / MODEL_NAME / API_KEY
set -a; source .env; set +a     # Python العادي لا يقوم بتحميل .env تلقائيًا

# ابدأ خدمة Ghidra المنفصلة، ثم:
python webui/app.py
```

افتح http://127.0.0.1:5000. يقرأ Docker Compose ملف `.env` تلقائيًا؛ يتطلب التنفيذ من المصدر تصديره كما هو موضح أعلاه. خادم تطوير Flask مناسب للاستخدام المحلي؛ صورة Docker تشغل Gunicorn.

## الأمان / الحدود المحلية فقط

هذا مصمم لمحلل موثوق واحد على جهازه الخاص – وليس للاستخدام متعدد المستخدمين أو الاستضافة العامة. افتراضيًا، يربط التطبيق وخدمة Ghidra فقط بـ `127.0.0.1`، وضع التصحيح مغلق، لا يتم تنفيذ الثنائيات المرفوعة أبدًا، ويبقى مفتاح مزود LLM على جانب الخادم.

## الاختبار

```bash
pip install -r requirements.txt -r requirements-dev.txt
python -m pytest
node --test "webui/static/js/tests/**/*.test.mjs"
npm ci && npm run vendor:verify   # يتحقق من سلامة حزمة Mermaid المشتراة
```

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

- **"الخدمة غير متصلة" / يُرجع `/readyz` 503** — خدمة Ghidra غير قابلة للوصول على `GHIDRA_API_BASE`، أو `API_BASE`/`MODEL_NAME` غير مضبوطين.
- **الأنواع/المتغيرات العامة/التعليقات التوضيحية تظهر "يتطلب v1"** — خدمة Ghidra المتصلة لا تعلن عن تلك الإمكانية؛ متوقع على الخدمات الأقدم.
- **أخطاء المحادثة فورًا** — تحقق من `API_BASE`/`API_KEY`/`MODEL_NAME` وأن المزود يمكن الوصول إليه خلال `LLM_TIMEOUT`.
- **الرفض الرفع كبير جدًا** — ارفع `MAX_UPLOAD_BYTES`.
- **الرفع يبدو كنص عادي** — يطلب ريف·ديك التأكيد قبل إرساله إلى Ghidra؛ استمر كثنائي خام فقط عندما يكون ذلك مقصودًا.
- **مهلة التحليل الكبير** — قم بزيادة `ANALYSIS_TIMEOUT` لحاوية Ghidra (على سبيل المثال `5400` للثنائيات C++/Android التي تحتوي على أكثر من 10k دالة) وأعد الرفع. `LLM_TIMEOUT` غير مرتبط.
- **يظهر استشهاد كـ "(غير مُتحقق منه)"** — استشهد النموذج بأدلة لم يسترجعها أبدًا؛ عالج هذا الادعاء كفرضية غير مؤكدة.