مُشغّل `raptor` هو الطريقة الموصى بها لبدء جلسة، وهو يعمل من أي دليل — فهو يحدد موقع تثبيت RAPTOR، ويتذكر الدليل الذي أطلقت منه (بحيث تعتمد عليه أوامر مثل `/scan` افتراضيًا)، وينفّذ فحوصات الثقة والمشروع قبل التشغيل، ويحمّل إضافة تتبع التغطية، وينظّف البيئة قبل تسليم المهمة إلى Claude Code. كما يقبل مسار هدف اختياريًا وخيارات مثل `--project` و`--continue` و`--model` — راجع `raptor --help`.

تشغيل `claude` مباشرة من داخل دليل المستودع يعمل أيضًا — حيث يلتقط Claude Code إعدادات RAPTOR من النسخة المحلية — لكنك تتخطى كل ما يفعله المشغّل أعلاه: لا فحوصات قبل التشغيل، ولا تتبع للتغطية، والأوامر التي تعتمد افتراضيًا على "الدليل الذي شغّلت منه" لا يمكنها رؤيته.

**مهم:** يقوم RAPTOR بتحميل إعداداته من دليل المستودع. إذا شغّلت `claude` من أي دليل آخر، فستحصل على Claude Code عادي، وليس RAPTOR. يتجنّب مشغّل `raptor` هذا الوضع الفاشل تمامًا.

### الخيار 2: التشغيل داخل حاوية (موصى به)

يُعد استخدام الحاويات ممارسة أمنية شائعة لتقييد وصول الوكلاء إلى مناطق من نظام الملفات لديك لا تريدهم الوصول إليها، بالإضافة إلى الحد من نطاق الانفجار لأي كود ضار قد يُنفَّذ (مثلًا عبر هجوم على سلسلة التوريد). الصورة كبيرة (حوالي 6 جيجابايت). تبدأ من حاوية Microsoft Python 3.12 للتطوير وتضيف أدوات التحليل الثابت والاختبار بالتغذية العشوائية وأتمتة المتصفح.

يمكنك سحب صورة مبنية مسبقًا:```bash
docker pull danielcuthbert/raptor:latest

يتوقع الصورة أن يتم تركيب إطار عمل RAPTOR (هذا المستودع) في `/workspaces/raptor` عند بدء التشغيل. يمكنك اختياريًا تركيب مجلد هدف للتحليل المحلي.

لبدء الحاوية:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

أضف `--privileged` إذا كنت بحاجة إلى مصحح الأخطاء الحتمي `rr`.

كما أن حاويات التطوير الخاصة بـ VS Code مدعومة أيضًا. لتثبيت مجلد هدف، أضفه إلى قسم `mounts` في ملف `.devcontainer/devcontainer.json`:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

إما بهذه الطريقة، بمجرد دخولك إلى الحاوية، شغّل `raptor` للبدء.

---

## ما يمكن توقعه عند أول تشغيل

أبسط شيء يمكنك القيام به:```
/scan /path/to/code

هذا يشغّل خط الأنابيب الكامل: الفحص، إزالة التكرارات، ثم إرسال كل نتيجة عبر مراحل التحقق (A-F). على قاعدة بيانات متوسطة الحجم تحتوي على ~50 نتيجة، توقّع 10-30 دقيقة وتكلفة تتراوح بين 2-8 دولارات لتكاليف LLM في طبقة التحليل (حسب النموذج). الحد الافتراضي للتكلفة هو 10 دولارات لكل تشغيل؛ يمكنك تعديله باستخدام `--max-cost-usd`.

**ملاحظة حول التكلفة:** طبقة التنسيق في Claude Code تستخدم اشتراكك في Claude. طبقة إرسال التحليل تقوم باستدعاءات منفصلة لواجهة برمجة تطبيقات LLM تُفوتر لكل رمز مميز. إذا كنت تستخدم Claude Code فقط كنموذج تحليل (الوضع الافتراضي)، فلا توجد تكلفة إضافية تتجاوز اشتراكك. إذا قمت بتكوين نماذج خارجية (OpenAI، Gemini، إلخ)، فسيتم فوترة تلك الاستدعاءات لمزودي الخدمة هؤلاء.

---

## نموذج الأمان

يقوم RAPTOR بتشغيل كود مولّد بواسطة LLM ويحلل مستودعات غير موثوقة. العمليات الفرعية التي تتعامل مع محتوى غير موثوق يتم عزلها باستخدام مساحات أسماء Linux وLandlock وseccomp. يمنع العزل الوصول إلى الشبكة، ويقيد رؤية نظام الملفات، ويحد من استهلاك الموارد. راجع `docs/sandbox.md` لنموذج التهديد الكامل والتكوين.

متغيرات البيئة التي قد تحقن كودًا في سلسلة التشغيل يتم إزالتها عند بدء التشغيل (`core/security/_dangerous_env_strip.sh`). مسارات الملفات من المستودعات المفحوصة لا يتم أبدًا إدراجها في سلاسل الصدفة — جميع استدعاءات العمليات الفرعية تستخدم وسائط قائمة على القوائم.

---

## ما يمكن أن يفعله RAPTOR

| الأمر | ما يفعله | الحالة |
|---------|-------------|--------|
| `/agentic` | سير عمل مستقل كامل: فحص، تحقق، استغلال، تصحيح | مستقر |
| `/scan` | تحليل ثابت باستخدام Semgrep وCodeQL | مستقر |
| `/understand` | رسم خريطة سطح الهجوم، تتبع تدفقات البيانات، البحث عن متغيرات الثغرات | مستقر |
| `/binary` | تحقيق ثنائي بصندوق أسود، أدلة وقت التشغيل، استعلامات رسومية وتسليم | تجريبي |
| `/ghidra` | جسر هندسة عكسية Ghidra: إرفاق/استيراد مشاريع `.gpr`، مقارنة عبر الإصدارات، تصدير النتائج | تجريبي |
| `/audit` | مراجعة كود منهجية قائمة على الفرضيات ومدعومة بالأدوات | تجريبي |
| `/review` | الاستعلام عن حالة التدقيق: النتائج، الفجوات، التغطية، ملاحظات المشغّل | مستقر |
| `/annotate` | إرفاق تعليقات نثرية حرة لكل دالة (ملاحظات مراجعة المشغّل) | مستقر |
| `/validate` | خط أنابيب تحقق متعدد المراحل من قابلية الاستغلال (المراحل 0-F) | مستقر |
| `/diagram` | خرائط مرئية Mermaid من مخرجات `/understand` و`/validate` بصيغة JSON | تجريبي |
| `/codeql` | تحليل عميق بـ CodeQL فقط مع فحص مسبق لتدفق البيانات SMT | مستقر |
| `/analyze` | تحليل نتائج SARIF الموجودة باستخدام LLM، دون إعادة الفحص | مستقر |
| `/sca` | تحليل تكوين البرمجيات: التبعيات، التنبيهات الأمنية، إشارات سلسلة التوريد، SBOMs، والإصلاحات | تجريبي |
| `/cve-diff` | اكتشاف ومقارنة التزام الإصلاح لثغرة CVE عبر OSV وNVD وGitHub وGitLab | تجريبي |
| `/cve-env` | بناء والتحقق من بيئة Docker تشغّل التطبيق المتأثر بـ CVE عند إصداره قبل التصحيح | تجريبي |
| `/exploit` | توليد كود استغلال لإثبات المفهوم | تجريبي |
| `/patch` | توليد تصحيحات آمنة للثغرات المؤكدة | تجريبي |
| `/fuzz` | اختبار التشويش الثنائي باستخدام AFL++ وتحليل الأعطال | مستقر |
| `/crash-analysis` | تحليل السبب الجذري المستقل لأعطال C/C++ | مستقر |
| `/oss-forensics` | تحقيق جنائي قائم على الأدلة لمستودعات GitHub | مستقر |
| `/project` | مساحات عمل مسماة لتنظيم التشغيلات وتتبع النتائج بمرور الوقت | مستقر |
| `/describe` | وصف هدف: مزيج اللغات، نظام البناء، فجوات الأدوات، تقدير التكلفة (قراءة فقط) | مستقر |
| `/threat-model` | إنشاء وفحص وصيانة نماذج تهديد لكل مشروع | مستقر |
| `/sage` | طبقة ذاكرة دائمة (تخزين، استرجاع، ربط، تأكيد) | مستقر |
| `/ask` | إرسال مطالبة حرة إلى أي نموذج LLM مكوّن | مستقر |
| `/scorecard` | فحص موثوقية كل نموذج عبر فئات القرار | مستقر |
| `/frida` | أدوات ديناميكية عبر Frida | ألفا |
| `/web` | فحص تطبيقات الويب: الزحف، تكامل ffuf/nuclei، حقن مُتحقق منه عبر oracle، استدعاءات SSRF العمياء | تجريبي |

---

## كيف يعمل خط الأنابيب

ابدأ بإنشاء مشروع بحيث تتراكم جميع تشغيلاتك في مكان واحد:```
/project create myapp --target /path/to/code   # create a project first
/project use myapp                             # set it as active
/understand --map                              # map the attack surface
/agentic --threat-model --validate             # map, model, scan, validate
/project findings                              # review everything in one place

`/understand` يبني خريطة سياق لنقاط الدخول، وحدود الثقة، والمصارف قبل أن يبدأ أي سطر من المسح. ثم يقوم `/agentic` بتشغيل Semgrep وCodeQL، ويزيل التكرار من النتائج، ويوزّع كل نتيجة للتحقق باستخدام منهجية exploitation-validator:

مع `--threat-model`، يشغّل RAPTOR الخريطة أولاً، وينشئ `threat-model.json` و`THREAT_MODEL.md` إذا لم يكن المشروع يمتلكهما بالفعل، ثم يغذّي نسخة مختصرة إلى `/understand`، والتحليل المستقل، و`/validate`. يتم الحفاظ على نماذج التهديد الموجودة في المشروع ما لم تمرر `--threat-model-refresh`؛ ويتم رفض الخرائط الاحتياطية القديمة ما لم تمرر صراحةً `--threat-model-use-stale`. كما يحوّل التدفقات غير المُتحقَّق منها والمُعيَّنة في الخريطة إلى SARIF مرشّح بحيث لا تقضي أخطاء الماسح على عملية التشغيل. إنه سياق يملكه المشغّل، وليس دليلاً سحرياً: النتائج ما تزال تحتاج إلى دليل برمجي أو تأكيد مدعوم بـ oracle. انظر `docs/threat-model.md`.

- المرحلة A: هل النمط هو ثغرة فعلية، أم أن الأداة تطابق أنماطاً ضوضائية؟
- المرحلة B: ما الذي يحتاجه المهاجم للوصول إليه، وما الذي يعترض الطريق؟
- المرحلة C: هل مسار الكود موجود فعلاً؟ هل يمكن الوصول إليه من الخارج؟
- المرحلة D: القرار النهائي — هل هذا كود اختبار، هل يتطلب شروطاً مسبقة غير واقعية، هل النموذج يتحوّط؟
- المرحلة E: جدوى الاستغلال الثنائي (عندما يكون هناك أثر مُجمَّع متاح)
- المرحلة F: مراجعة ذاتية — هل تحوّطت أي مرحلة سابقة أو ناقضت نفسها؟

النتائج التي تجتاز التحقق تحصل على PoCs للاستغلال وتصحيحات مولّدة. يتم تشغيل تحليل عبر النتائج في النهاية للعثور على الأسباب الجذرية المشتركة وسلاسل الهجوم.

`/validate` يشغّل نفس هذه المسارات كخطوة مستقلة إذا كان لديك بالفعل نتائج من مسح سابق.

بالنسبة لأثر مُجمَّع، يقوم `/binary <path>` الآن بتشغيل تحقيق يعتمد على الأدلة أولاً بدلاً من إغراق المشغّل بمجموعة من نتائج الهندسة العكسية الخام. في الخلفية، ما يزال يبني البيان المرتبط بـ SHA-256، وسجل الأدلة، وخريطة السياق، وقائمة التحقق، وقاعدة بيانات SQLite من بيانات الملف الوصفية، والاستيرادات، ومراجع radare2 المتقاطعة. تطبيقات Mach-O تحصل أيضاً على جرد الشرائح، وبيانات الحزمة، ومحددات الفئات Objective-C / Swift؛ ويتم الاحتفاظ بالكود الزائف عالي القيمة بدلاً من اختفائه داخل التشغيل. صادرات DLL الخاصة بـ PE، ومعالجات برامج تشغيل Windows، ومعالجات ioctl لوحدات نواة Linux تُعامل كمرشحات دخول خاصة بها أيضاً، مع قراءة بنية PE من ترويسة COFF بدلاً من التخمين. ثم تستعلم طبقة التحقيق عن تلك الرسوم البيانية، وترتّب الدخول الخارجي قبل مؤشرات المصارف العامة، وتكتشف الملفات الثنائية المساعدة/الشقيقة المُعلنة، وتكتب تقريراً موجزاً مقسّماً إلى حقائق، واستدلالات بنيوية، وفرضيات غير مثبتة. يمكن لملاحظات Frida، وشهود أعطال fuzz، وفحوصات Z3 الصريحة، واختلافات الملفات الثنائية أن تضيف لاحقاً أدلة أقوى. يحتفظ RAPTOR أيضاً بالرسم البياني للاستدعاءات الداخلي اللازم لاستعادة مرشحات الدخول المحدود إلى المحلّل، بحيث يمكن تضييق استدعاء تطبيق إلى الدالة الداخلية التي تستدعي فعلاً `XML_Parse` أو `d2i_X509` أو `jpeg_read_header` أو سطح محلّل حقيقي آخر دون التظاهر بأن ذلك دليل تلوّث. `/binary trace-parser <run-dir>` هو المتابعة الديناميكية الصريحة: يشغّل تتبع Frida الضيق للمحلّل، ثم يحدّث نفس خريطة السياق، والتسليم، والرسم البياني، وتقرير التحقيق في مكانه. `/binary investigate --active` يبني الخريطة أولاً ولا يطلق حملة fuzz حقيقية إلا عندما توجد حدود harness ملموسة؛ أهداف التطبيق وDLL وبرنامج التشغيل تحصل على خطوة harness أو snapshot بدلاً من ذلك. `/binary harness` يكتب مواصفة harness مدعومة بالأدلة للدخول المختار ولا يصدر كوداً مرشحاً إلا عندما يكون عقد ABI أو IOCTL صريحاً. إنه لا يختلق طريقاً من "وجود `memcpy`" إلى "هذا قابل للاستغلال": الاستيرادات والمحددات وحواف الاستدعاء تبقى مرشحات حتى يثبت شيء ميكانيكي أكثر. انظر `docs/binary-analysis.md`.

---

## تحليل تكوين البرمجيات

`/sca` يحلل جانب التبعيات وسلسلة التوريد في المشروع. إنه ليس مجرد بحث عن CVEs في ملف المتطلبات: يكتشف RAPTOR ملفات البيان، وملفات القفل، وأوامر التثبيت المضمّنة، وتبعيات سير العمل، ومصادر حزم الصور الأساسية/الحاويات، ثم يطبّعها في عرض تبعيات موحّد.

يُثري المسح التبعيات باستشارات OSV، وCISA KEV، وEPSS، وCISA Vulnrichment/SSVC، والوصولية، وإشارات أدلة الاستغلال، وفحوصات النظافة، وفرضيات سلسلة التوريد، ونتائج سياسة الترخيص، ومراجعة/فرز LLM اختيارية. يصدر نتائج أصلية بصيغة RAPTOR بالإضافة إلى SBOM ومخرجات متوافقة مع CI:

- `findings.json` — نتائج RAPTOR الأساسية
- `report.md` — ملخص قابل للقراءة البشرية
- `sbom.cdx.json` — SBOM بصيغة CycloneDX مع بيانات VEX
- `findings.sarif` — مخرجات فحص الكود لـ GitHub/GitLab

الأوامر الشائعة:```bash
python3 raptor.py sca --repo /path/to/project
python3 raptor.py sca --repo /path/to/project --no-llm
python3 raptor.py sca --repo /path/to/project --fail-on-severity high --fail-on-kev
python3 raptor.py sca --repo /path/to/project fix
python3 raptor.py sca check PyPI django 4.2.10

بمجرد تعبئتها، يحلّ الماسح الضوئي معرّفات الحزم إلى ملفات محلية ولا يحدث أي استدعاء شبكة. بدون ذاكرة التخزين المؤقت، سيحاول RAPTOR جلب حزم السجل من semgrep.dev وقت الفحص؛ إذا كان غير متصل بالإنترنت، فإنه يُسقط الحزم غير المخزّنة مؤقتًا بأمان ويعمل بالقواعد المخصصة فقط.

يحتاج CodeQL إلى وصول للشبكة فقط أثناء الإعداد الأولي لتنزيل CLI وحزم الاستعلامات. بمجرد تثبيته، يعمل دون اتصال.

---

## القواعد المخصصة

يأتي RAPTOR مع أكثر من 200 قاعدة تحليل ثابت مخصصة، تم اختبارها بشكل عدائي لإزالة النتائج الإيجابية الكاذبة:

- **Semgrep (145 قاعدة)** — قواعد تتبّع التلوث والأنماط لـ Python وGo وJava وJS/TS. تغطي SQLi وXSS وSSRF وSSTI وحقن الأوامر وإلغاء التسلسل وXXE وحقن LDAP/NoSQL واجتياز المسار وإعادة التوجيه المفتوحة وحقن السجلات/الترويسات وحقن eval وReDoS وتلوث النموذج الأولي وسوء تكوين JWT والتشفير الضعيف وTLS غير الآمن والأسرار المضمّنة.
- **Coccinelle (63 قاعدة)** — مطابقة بنيوية لـ C/C++. سلامة الذاكرة (التحرير المزدوج، الاستخدام بعد التحرير، تحرير مؤشر غير أساسي، تحرير مصفوفة مكدس، ذاكرة mmap'd، الاستخدام بعد الإغلاق)، أخطاء الأعداد الصحيحة (الفائض، توسيع الإشارة، sizeof المزدوج)، تسريبات الموارد (عدم تطابق popen/fclose، إغلاق مزدوج لـ fdopendir)، معالجة المخازن المؤقتة (strncpy بدون NUL، عدم تطابق حجم copy_user، خطأ واحد في malloc/strlen)، سلامة معالجات الإشارات، سوء استخدام API (مجال علم fcntl، SIGKILL/SIGSTOP، تبديل البايت المزدوج، المخزن المؤقت الثابت inet_ntoa)، إزالة التخزين الميت في المترجم، الخلط بين IS_ERR/PTR_ERR في النواة، حقن تنسيق السلسلة، سباقات TOCTOU، والمزيد.
- **CodeQL (8 استعلامات)** — تتبّع تلوث عبر الإجراءات لـ C++ (حقن تنسيق السلسلة، اقتطاع الأعداد الصحيحة، الاستخدام بعد النقل، إبطال المكرر) وJava (XXE، إلغاء تسلسل غير آمن، حقن السجلات، SSRF في Spring).

تصفّح القواعد مباشرة: `engine/semgrep/rules/`، `engine/coccinelle/rules/`، `engine/codeql/queries/`. هذه تُكمّل حزم سجل Semgrep التي يسحبها RAPTOR (`p/security-audit`، `p/owasp-top-ten`، `p/secrets` دائمًا؛ حزم لكل مجموعة سياسة مثل `p/command-injection`، `p/jwt`، `p/xss` إضافية) — التداخل ضئيل.

---

## كيف يفحص RAPTOR نفسه

يستخدم RAPTOR قدرًا لا بأس به من أدواته الأمنية الخاصة، لكن من الجدير أن نكون صادقين بشأن ما يمنع طلب السحب فعليًا وما يعمل فقط في الخلفية لإبقائنا ملتزمين. بعض هذا بوابة صارمة، وبعضه فحص مجدول، وبعضه مجرد معيار نحتفظ به لنعرف متى جعلنا الأمور أسوأ. التحليل الأكثر تفصيلًا، بما في ذلك المعاملات الفعلية وكيفية إعادة إنتاج الفحوصات، موجود في `docs/ci-controls.md`.

| التحكم | ما يفحصه | المحفّز | الإعداد / الدليل |
|---|---|---|---|
| Ruff | تدقيق صحة لغة Python (`F401`، `F811`، `F821`، `F841`) | بوابة فرق طلب السحب، بالإضافة إلى تدقيق أسبوعي للشجرة الكاملة | `pyproject.toml`، `.github/workflows/lint.yml` |
| Pytest | حدود الوحدة/التكامل السريعة، مستويات فرعية خاصة بالنظام الفرعي (عبر توزيع مخطط الاستيراد)، تدقيق غلاف المطالبة | طلبات السحب، الدفعات إلى `main`، قائمة الدمج، المجموعة الكاملة المجدولة | `pytest.ini`، `.github/workflows/tests.yml`، `.github/workflows/nightly.yml` |
| CodeQL Advanced | فحص كود Python وC/C++ وإجراءات GitHub مع تضييق نطاق مخطط الاستيراد | طلبات السحب، الدفعات إلى `main`، قائمة الدمج، جدول أسبوعي | `.github/workflows/codeql.yml`، `.github/codeql/codeql-config.yml` |
| تقوية سير العمل | إجراءات طرف ثالث مثبّتة بـ SHA، صلاحيات بأقل امتياز، تدقيق بيانات وصف الأوامر | كل تغيير في سير العمل وكل تشغيل تدقيق | `.github/workflows/`، `.github/scripts/check_command_metadata.py` |
| تدقيق تسميات المجموعة | تدقيق صحة مخطط تسميات مجموعة البيانات والتحقق من تثبيت المصدر العلوي | طلبات السحب (التسميات المتغيرة)، مسح أسبوعي كامل | `.github/workflows/corpus-labels.yml` |
| بوابة SCA لطلبات السحب في RAPTOR | انحدارات التبعيات وسلسلة التوريد التي يُدخلها طلب السحب | تغييرات البيان / ملف القفل / سير العمل | `.github/workflows/sca-pr-gate.yml` |
| التحديث الذاتي SCA في RAPTOR | تقوية التبعيات ميكانيكيًا واقتراحات الترقية الآمنة | جدول أسبوعي، تشغيل يدوي | `.github/workflows/sca-self-bump.yml` |
| مجموعة اختراق SCA | ما إذا كانت اختراقات التبعيات المعروفة لا تزال تُطلق الإشارة المتوقعة | جدول أسبوعي، تغييرات طلبات السحب ذات الصلة | `test/data/sca-e2e/compromise-corpus/`، `.github/workflows/sca-compromise-check.yml` |
| فحص سوء التوصيل | كشف الكود الميت / الاستدعاء الخاطئ، انحراف توثيق متغيرات البيئة، حواجز قائمة المفردات، تدقيق استيراد التبعيات الاختيارية | جدول يومي | `.github/workflows/miswiring-scan.yml`، `.github/scripts/*_baseline.json` |
| معايرة SCA + مجموعة الإجهاد | ما إذا كانت تسجيل المخاطر وتغطية المحلّل تنحرف بمرور الوقت | وظائف مجدولة أسبوعية / شهرية | `packages/sca/data/calibration/`، `.github/workflows/refresh-sca-calibration.yml`، `.github/workflows/sca-stress-sweep.yml` |
| مجموعة تدفق البيانات | تتبّع الدقة / الاستدعاء / فئة النتائج الإيجابية الكاذبة لسلوك المدقّق | معيار يطوّره المطوّر واختبارات المجموعة | `core/dataflow/corpus/`، `core/dataflow/scripts/corpus-metrics` |
| حارس توثيق ضوابط CI | المسارات الموثقة موجودة، إعداد ruff مطابق، README يرتبط بالوثيقة | طلبات السحب | `.github/tests/test_ci_controls_docs.py` |

غير مُطبَّق حاليًا: `mypy` مثبّت في `requirements-dev.txt` لكنه لا يمنع أي شيء؛ تنسيق Ruff غير مُطبَّق؛ Semgrep جزء من سطح ماسح RAPTOR، لكن ليس لدينا بعد سير عمل مخصص "لفحص RAPTOR باستخدام RAPTOR" عبر Semgrep.

---

## استخدام LLM مختلف

لدى RAPTOR طبقتان منفصلتان للنماذج، ومن الجدير معرفة كيفية عمل كلتيهما قبل تغيير أي شيء.

طبقة **التنسيق** هي دائمًا Claude Code. ملفات CLAUDE.md والمهارات والأوامر تعمل جميعها كتعليمات Claude Code. لتغيير نموذج Claude الذي ينسّق RAPTOR، استخدم علم `--model` في Claude Code أو أمر `/model` داخل جلسة.

طبقة **توزيع التحليل** هي LLM الذي يحلل نتائج الثغرات الفردية. هذه منفصلة عن طبقة التنسيق ويمكن أن تكون أي مزوّد مدعوم. قم بتكوينها في `~/.config/raptor/models.json`:```json
{
  "models": [
    {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "api_key": "sk-ant-...",
      "role": "analysis"
    },
    {
      "provider": "openai",
      "model": "gpt-5.4",
      "api_key": "sk-...",
      "role": "analysis"
    },
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "api_key": "sk-ant-...",
      "role": "aggregate"
    }
  ]
}

| الدور | ما يفعله |
|------|-------------|
| `analysis` | يتحقق من كل نتيجة ويحللها (المراحل A-F) |
| `code` | يكتب أكواد استغلال PoCs وأكواد التصحيح |
| `consensus` | تصويت برأي ثانٍ حول النتائج الإيجابية الحقيقية |
| `aggregate` | اختياري. توليف سردي مكتوب بواسطة LLM فوق الارتباط متعدد النماذج الحتمي، يُكتب إلى `aggregation.json` والتقرير النهائي `agentic-report.md` |
| `fallback` | يُستخدم إذا فشل النموذج الأساسي أو وصل إلى حدود المعدل |

إذا لم يتم تعيين أي أدوار، يتولى النموذج الأول في القائمة كل شيء. لتحليل
كود المصدر متعدد النماذج، قم بتكوين نموذجَي `analysis` أو أكثر — ستحصل على
الارتباط الحتمي افتراضيًا. دور `aggregate` اختياري ويضيف
ملخصًا مكتوبًا بواسطة LLM في الأعلى:```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

Ollama يعمل للتحليل لكنه ينتج كود استغلال وتصحيح غير موثوق. بالنسبة لمهام توليد الكود، استخدم نموذجًا من الطراز الأول.

### اختصار الطبقة السريعة + بطاقة أداء النموذج

عندما يكون لنموذج طبقة التحليل لديك نموذج شقيق أرخص من نفس المزود (Anthropic Opus → Haiku، OpenAI 5.x → 4o-mini، Gemini Pro → Flash-Lite، Mistral Large → Small)، سيستخدمه RAPTOR كمرشح مسبق على المستهلكين المتصلين بالركيزة (codeql اليوم؛ SCA وغيرها عند إطلاقها لاحقًا). النموذج الرخيص لا يقوم بالاختصار إلا على **النتائج الإيجابية الخاطئة الواثقة**؛ الحالات الغامضة والنتائج الإيجابية الواثقة دائمًا تخضع للتحليل الكامل. تتراكم الثقة لكل خلية `(model, decision_class)` — يسجل RAPTOR التوافق بين الرخيص والكامل ولا يقوم بالاختصار إلا عندما ينخفض الحد الأعلى ويلسون 95% لمعدل الخطأ في الخلية إلى 5% أو أقل.

لفحص ما تتقنه نماذجك، استخدم `/scorecard` (أو مباشرة: `libexec/raptor-llm-scorecard list`). بطاقة الأداء عامة (الدروس تنتقل عبر المشاريع) وتُحفظ في `out/llm_scorecard.json`.

---

## المشاريع

بدون مشروع، يحصل كل تشغيل على دليله الخاص بعلامة زمنية تحت `out/`. مع مشروع، يذهب كل شيء إلى مكان واحد وتحصل على نتائج مدمجة، وتتبع تغطية، وفروقات بين التشغيلات.```bash
/project create myapp --target /path/to/code -d "Short description"
/project use myapp

/scan
/understand --map
/validate

/project status                # all runs, pass/fail, timestamps
/project findings              # merged findings across all runs
/project findings --detailed   # per-finding detail
/project coverage --detailed   # which files were reviewed
/project diff myapp run1 run2  # compare two runs
/project report                # full merged report
/project clean --keep 3        # remove old runs, keep the last 3
/project export myapp /tmp/myapp.zip
/project none                  # clear active project

التقسيم يعني أنه يمكنك تشغيل طبقة Python من خط أنابيب CI (`python3 raptor.py scan --repo ...`) والحصول على مخرجات SARIF منظمة دون الحاجة إلى Claude Code، أو تشغيلها تفاعليًا مع سير العمل الوكيل الكامل.

---

## فحص الأدلة الجنائية للمصادر المفتوحة (OSS forensics)

`/oss-forensics` يحقق في مستودعات GitHub العامة باستخدام أدلة من مصادر متعددة: GitHub API، وGH Archive (سجل الأحداث غير القابل للتغيير عبر BigQuery)، وWayback Machine، وسجل git المحلي. يشغّل خط أنابيب منظمًا بدءًا من جمع الأدلة مرورًا بتكوين الفرضيات وصولًا إلى تقرير جنائي نهائي.

يتطلب `GOOGLE_APPLICATION_CREDENTIALS` للوصول إلى BigQuery. راجع `.claude/commands/oss-forensics.md` للتفاصيل.

---

## شخصيات الخبراء

سبع شخصيات خبراء متاحة عند الطلب. قم بتحميل واحدة عندما تريد منظورًا مختلفًا حول نتيجة أو تقنية محددة:```
Exploit Developer (Mark Dowd)                  Exploit PoC generation
Crash Analyst (Charlie Miller / Halvar Flake)  Crash analysis and exploitability assessment
Security Researcher                            General adversarial code review
Patch Engineer                                 Secure fix generation
Penetration Tester                             Realistic attack scenario assessment
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption