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

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

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

عرض توضيحي

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

بدء سريع (Docker)

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 فقط:

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:

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 واملأ هذه المتغيرات؛ راجع ذلك الملف للحصول على القائمة الكاملة والافتراضيات.

مزود LLM

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

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

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

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

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

# 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 حتى لا يمكن لنموذج متكرر الهروب). إذا وصلت عملية إلى ميزانيتها، فإنها تبلغ عن نتائج جزئية وتقدم متابعة — والتي تستأنف نفس المحادثة باستخدام الأدلة المسترجعة بالفعل، دون إعادة استدعاءات الأدوات المكتملة. تنمو التكلفة مع عدد استدعاءات الأدوات/النموذج، لذا فإن الميزانيات الأعلى تكلف أكثر.

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

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

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

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

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

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

البنية

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

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

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 على جانب الخادم.

الاختبار

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 غير مرتبط.