╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             Autonomous Offensive/Defensive Research Framework             ║
║             Based on Claude Code (v3.1.0)                                 ║
║                                                                           ║
║             Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake)    ║
║             Michael Bargury, John Cartwright                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀

مُشغِّل `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 devcontainer وتضيف أدوات التحليل الساكن والاختبار العشوائي وأتمتة المتصفح.

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

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

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

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

تُدعم أيضًا حاويات التطوير VS Code devcontainers. لتركيب مجلد هدف، أضفه إلى قسم `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. أما طبقة إرسال التحليل فتُجري استدعاءات API منفصلة لنماذج LLM تُحتسب لكل رمز (token). إذا كنت تستخدم Claude Code فقط كنموذج تحليل (الافتراضي)، فلا توجد تكلفة إضافية تتجاوز اشتراكك. أما إذا قمت بتهيئة نماذج خارجية (OpenAI، Gemini، إلخ)، فتُحتسب تلك الاستدعاءات على مزوّديها.

---

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

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

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

---

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

| الأمر | ما يفعله | الحالة |
|---------|-------------|--------|
| `/agentic` | سير عمل مستقل كامل: الفحص، والتحقق، والاستغلال، والترقيع | مستقر |
| `/scan` | تحليل ساكن باستخدام Semgrep وCodeQL | مستقر |
| `/understand` | رسم سطح الهجوم، وتتبّع تدفقات البيانات، واصطياد متغيّرات الثغرات | مستقر |
| `/binary` | تحقيق في الملفات الثنائية بالصندوق الأسود، وأدلة وقت التشغيل، واستعلامات الرسم البياني والتسليم | تجريبي |
| `/ghidra` | جسر Ghidra للهندسة العكسية: إرفاق/استيراد مشاريع `.gpr`، ومقارنة الفروق بين الإصدارات، وتصدير النتائج | تجريبي |
| `/audit` | مراجعة شيفرة منهجية قائمة على الفرضيات ومدعومة بالأدوات | تجريبي |
| `/review` | الاستعلام عن حالة التدقيق: النتائج، والفجوات، والتغطية، وملاحظات المشغّل | مستقر |
| `/annotate` | إرفاق تعليقات نصية حرة لكل دالة (ملاحظات مراجعة المشغّل) | مستقر |
| `/validate` | خط أنابيب متعدد المراحل للتحقق من قابلية الاستغلال (المراحل 0-F) | مستقر |
| `/diagram` | خرائط مرئية بـ Mermaid من مخرجات JSON الخاصة بـ `/understand` و`/validate` | تجريبي |
| `/codeql` | تحليل عميق بـ CodeQL فقط مع فرز مسبق لتدفق البيانات بـ SMT | مستقر |
| `/analyze` | تحليل نتائج SARIF الموجودة باستخدام LLM، دون إعادة الفحص | مستقر |
| `/openant` | فحص شيفرة المصدر بـ OpenAnt LLM: تحليل AST مع استدلال LLM لكل دالة | تجريبي |
| `/sca` | تحليل تركيب البرمجيات: التبعيات، والتنبيهات، ومؤشرات سلسلة التوريد، وقوائم SBOM، والإصلاحات | تجريبي |
| `/cve-diff` | اكتشاف ومقارنة إصلاح commit الخاص بـ 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` يبني خريطة سياقية لنقاط الدخول وحدود الثقة ونقاط الوصول (sinks) قبل حدوث أي سطر من الفحص. ثم يشغّل `/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؛ ويُحفظ الكود الزائف عالي القيمة
بدلاً من أن يتلاشى داخل التشغيل. كما تُعالَج صادرات PE DLL، وموزّعات برامج تشغيل Windows،
ومعالِجات ioctl لوحدات نواة Linux كمرشّحات دخول خاصة بها،
مع قراءة معمارية PE من ترويسة COFF بدلاً من تخمينها. ثم تستعلم طبقة التحقيق
عن ذلك المخطط، وترتّب الدخول الخارجي قبل مسارات الوصول العامة،
وتكتشف الثنائيات المساعدة/الشقيقة المُعلَنة، وتكتب تقريراً مختصراً مقسّماً إلى حقائق،
واستنتاجات بنيوية، وفرضيات غير مُثبَتة. يمكن لملاحظات Frida، وشواهد انهيار Fuzzing،
وفحوص Z3 الصريحة، وفروقات الثنائيات أن تضيف أدلة أقوى لاحقاً. كما يحتفظ RAPTOR
بمخطط الاستدعاء الداخلي اللازم لاستعادة مرشّحات الدخول المحدودة إلى المحلّل،
حتى يمكن تضييق استدعاء تطبيق ما إلى الدالة الداخلية التي تستدعي فعلاً `XML_Parse`،
أو `d2i_X509`، أو `jpeg_read_header` أو أي سطح محلّل حقيقي آخر دون التظاهر بأن ذلك
إثبات تلوّث (taint proof). `/binary trace-parser <run-dir>` هو المتابعة الديناميكية الصريحة:
يشغّل تتبّع المحلّل الضيق عبر Frida، ثم يحدّث خريطة السياق نفسها،
والتسليم، والمخطط، وتقرير التحقيق في مكانه. يرسم `/binary investigate --active` الخريطة أولاً
ولا يطلق حملة fuzzing حقيقية إلا عند وجود حدّ harness ملموس؛ أما أهداف التطبيقات
وDLL وبرامج التشغيل فتحصل على خطوة harness أو لقطة بدلاً من ذلك. يكتب `/binary harness`
مواصفة harness مدعومة بالأدلة للدخول المختار ولا يُصدر كوداً مصدرياً مرشّحاً إلا عندما
يكون عقد ABI أو IOCTL صريحاً. إنه لا يتسلّل من "`memcpy` موجود" إلى "هذا
قابل للاستغلال": تبقى الاستيرادات والمحدِّدات وحواف الاستدعاء مرشّحات حتى
يثبت شيء ميكانيكي أكثر. راجع `docs/binary-analysis.md`.

---

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

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

يُثري الفحص التبعيات بتن advisories من 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 (~150 قاعدة)** — قواعد تتبع التلوث والأنماط لـ Python وGo وJava وJS/TS. تغطي SQLi وXSS وSSRF وSSTI وحقن الأوامر وإلغاء التسلسل وXXE وحقن LDAP/NoSQL واجتياز المسار وإعادة التوجيه المفتوح وحقن السجل/الترويسة وحقن eval وReDoS وتلوث النموذج الأولي وسوء إعداد JWT والتشفير الضعيف وTLS غير الآمن والأسرار المضمّنة.
- **Coccinelle (68 قاعدة)** — مطابقة بنيوية لـ C/C++. سلامة الذاكرة (double free، use-after-free، تحرير مؤشر غير أساسي، تحرير مصفوفة على المكدس، ذاكرة mmap'd، use-after-close)، أخطاء الأعداد الصحيحة (الطفح، امتداد الإشارة، sizeof المزدوج)، تسريبات الموارد (عدم تطابق popen/fclose، إغلاق fdopendir المزدوج)، التعامل مع المخازن المؤقتة (strncpy بدون NUL، عدم تطابق حجم copy_user، خطأ بمقدار واحد في malloc/strlen)، سلامة معالج الإشارات، سوء استخدام API (نطاق علم fcntl، SIGKILL/SIGSTOP، تبديل البايت المزدوج، المخزن الثابت inet_ntoa)، إزالة المخزن الميت من المترجم، الخلط بين IS_ERR/PTR_ERR في النواة، حقن سلسلة التنسيق، سباقات TOCTOU، والمزيد.
- **CodeQL (8 استعلامات)** — تتبع التلوث بين الإجراءات لـ C++ (حقن سلسلة التنسيق، اقتطاع الأعداد الصحيحة، use-after-move، إبطال المكرر) وJava (XXE، إلغاء التسلسل غير الآمن، حقن السجل، Spring SSRF).

تصفّح القواعد مباشرة: `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 Actions مع تضييق نطاق رسم الاستيراد | طلبات السحب، الدفع إلى `main`، قائمة الدمج، جدولة أسبوعية | `.github/workflows/codeql.yml`، `.github/codeql/codeql-config.yml` |
| تقوية سير العمل | إجراءات الطرف الثالث المثبّتة بـ SHA، أذونات الحد الأدنى، تدقيق بيانات الأوامر الوصفية | كل تغيير في سير العمل وكل تشغيل تدقيق | `.github/workflows/`، `.github/scripts/check_command_metadata.py` |
| تدقيق تسميات المجموعة | التحقق من مخطط تسميات مجموعة التدقيق والتحقق من تثبيت المصدر الأعلى | طلبات السحب (التسميات المتغيرة)، مسح كامل أسبوعي | `.github/workflows/corpus-labels.yml` |
| بوابة RAPTOR SCA لطلبات السحب | انحدارات التبعيات وسلسلة التوريد التي يُدخلها طلب سحب | تغييرات المانيفست / ملف القفل / سير العمل | `.github/workflows/sca-pr-gate.yml` |
| الترقية الذاتية لـ RAPTOR SCA | تقوية التبعيات الميكانيكية ومقترحات الترقية الآمنة | جدولة أسبوعية، تشغيل يدوي | `.github/workflows/sca-self-bump.yml` |
| مجموعة اختراق SCA | ما إذا كانت اختراقات التبعيات المعروفة لا تزال تُطلق الإشارة المتوقعة | جدولة أسبوعية، تغييرات طلبات السحب ذات الصلة | `test/data/sca-e2e/compromise-corpus/`، `.github/workflows/sca-compromise-check.yml` |
| كاشفات ثوابت المستودع | كشف الكود الميت / الاستدعاء الخاطئ، انحراف توثيق متغيرات البيئة، حواجز قائمة المفردات، صيغ JSON الأساسية بالبايت، تدقيق استيراد التبعيات الاختيارية | بوابة طلبات السحب (مهمة `repo-invariants` في `lint.yml`)، بالإضافة إلى مسح يومي | `.github/workflows/lint.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` مثبّت في `pyproject.toml` لكنه لا يحجب أي شيء؛ تنسيق Ruff غير مفروض؛ Semgrep جزء من سطح الماسح في RAPTOR، لكن ليس لدينا بعد سير عمل Semgrep مخصص لـ "فحص RAPTOR بـ RAPTOR".

---

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

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

**طبقة التنسيق** هي Claude Code -- لكن فقط للصدفة التفاعلية `raptor` (هذه الطبقة الحوارية بأوامر الشرطة المائلة). يعمل CLAUDE.md والمهارات والأوامر كتعليمات Claude Code هناك. لتغيير نموذج Claude الذي ينسّق تلك الطبقة، استخدم علم `--model` في Claude Code أو أمر `/model` داخل الجلسة. إذا كنت لا تريد هذه الطبقة على الإطلاق، راجع [التشغيل المستقل تمامًا](#running-fully-standalone-no-claude-code) أدناه.

**طبقة إرسال التحليل** هي 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 بشكل جيد للتحليل؛ إذ يتتبع مستوى الموثوقية في توليد أكواد الاستغلال/التصحيح حجم النموذج والتكميم بدلاً من كونه خاصية ثابتة للنماذج المحلية — راجع [مقايضات الجودة](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs) في دليل LLM، وتحقق من `/scorecard` لمعرفة ما يقيسه نموذجك تحديداً.

### التشغيل بشكل مستقل تماماً (بدون Claude Code)

`bin/raptor` -- الصدفة التفاعلية مع اللافتة والأوامر المائلة، أي هذه الطبقة الحوارية -- تنفّذ مباشرة إلى Claude Code CLI وتحتاج دائماً إلى تسجيل دخول خاص بها. أما الآليات الفعلية تحتها فلا تحتاج ذلك: `python3 raptor.py <mode>` هو واجهة سطر أوامر Python عادية بدون أي اعتماد على Claude Code على الإطلاق.```bash
# No `claude` process involved at any point
python3 raptor.py doctor                        # status check -- explicitly "no claude needed"
python3 raptor.py agentic --repo /path/to/code   # scan -> dedup -> analysis
python3 raptor.py scan --repo /path/to/code

وجّه `models.json` / `OLLAMA_HOST` إلى نسخة Ollama محلية (انظر أعلاه) وهذا المسار بأكمله لا يتحدث أبدًا إلى Anthropic -- مفيد للأجهزة المعزولة أو العتاد المحلي فقط. ستفقد طبقة أوامر الشرطة المائلة الحوارية (هذه الدردشة)؛ خط أنابيب الفحص/التحليل/الاستغلال نفسه غير متأثر.

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

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

يحقق `/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
Web Researcher (James Kettle)                  Web endpoint research (smuggling, cache poisoning, SSRF)
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption

الحفاظ على `/web` وZ3 وSAGE ومجموعات تطوير برامج مزوّدي الخدمات السحابية كإضافات اختيارية يتجنّب جعل تثبيت RAPTOR الافتراضي أثقل وأكثر هشاشة مما ينبغي.