
إطار عمل بحث أمني مستقل يدمج التحليل الثابت، وتحليل الثنائيات، والاختبار العشوائي، والتحقق من الثغرات المدعوم بنماذج اللغة الكبيرة، وتوليد الاستغلال، وكتابة التصحيحات للعمليات الهجومية والدفاعية.
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ █████╗ ██████╗ ████████╗ ██████╗ ██████╗ ║
║ ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗ ║
║ ██████╔╝███████║██████╔╝ ██║ ██║ ██║██████╔╝ ║
║ ██╔══██╗██╔══██║██╔═══╝ ██║ ██║ ██║██╔══██╗ ║
║ ██║ ██║██║ ██║██║ ██║ ╚██████╔╝██║ ██║ ║
║ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ║
║ ║
║ Autonomous Offensive/Defensive Research Framework ║
║ Based on Claude Code (v3.0.0) ║
║ ║
║ Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake) ║
║ Michael Bargury, John Cartwright ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀
المؤلفون: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright (@gadievron, @danielcuthbert, @thomasdullien, @mbrg, @grokjc)
الترخيص: MIT، انظر LICENSE. لاحظ أن CodeQL له ترخيص خاص به ولا يسمح بالاستخدام التجاري.
المستودع: https://github.com/gadievron/raptor
RAPTOR هو إطار عمل مستقل لأبحاث الأمن مبني على Claude Code (لكنه غير مقيد به - يمكنك أيضًا توصيل طبقة التحليل الخاصة بك). فهو يربط بين التحليل الثابت، وتحليل الثنائيات، والتحقق من الثغرات المدعوم بـ LLM، وتوليد الاستغلال، وكتابة التصحيحات في سير عمل واحد يمكنك تشغيله على قاعدة أكواد أو ثنائي.
إنه ليس برنامجًا مصقولًا. تم بناؤه في وقت الفراغ، ومثبت بالحماس والشريط اللاصق، وهو يعمل بشكل جيد بما يكفي لدرجة أننا لا نستطيع التوقف عن استخدامه. إذا كنت ترغب في تحسينه، افتح PR.
RAPTOR هو اختصار لـ Recursive Autonomous Penetration Testing and Observation Robot. لقد أردنا حقًا تسميته RAPTOR.
pip install semgrep) للتحليل الثابت. CodeQL اختياري لكن موصى به.بالنسبة لطبقة توزيع التحليل (LLM الذي يحلل النتائج الفردية)، يتولى Claude Code نفسه كل شيء افتراضيًا - لا حاجة لمفاتيح API إضافية. إذا كنت تريد تحليلًا متعدد النماذج (مثل Claude + GPT + Gemini)، ستحتاج إلى مفاتيح API لكل مزود. انظر استخدام LLM مختلف أدناه.
git clone https://github.com/gadievron/raptor.git cd raptor
pip install -r requirements.txt
npm install -g @anthropic-ai/claude-code
pip install semgrep
claude
إذا قمت بإضافة `bin/` إلى PATH الخاص بك (أو قمت بإنشاء رابط رمزي `bin/raptor` في مكان ما على PATH)، يمكنك تشغيل `raptor` من أي مجلد -- يقوم المُشغِّل بحل تثبيت RAPTOR وإعداد مجلد العمل تلقائيًا.
**هام:** يقوم RAPTOR بتحميل تكوينه من مجلد المستودع. إذا قمت بتشغيل `claude` من مجلد مختلف، فستحصل على Claude Code العادي، وليس RAPTOR. قم إما بالانتقال إلى المستودع باستخدام `cd` أولاً، أو استخدم المُشغِّل `raptor`.
### الخيار 2: حاوية التطوير (موصى به)
كل شيء مثبت مسبقًا. افتح في VS Code باستخدام **Dev Containers: Open Folder in Container**، أو اسحب الصورة الجاهزة:```bash
docker pull danielcuthbert/raptor:latest
docker run --privileged -it -v "$(pwd):/workspaces/raptor" danielcuthbert/raptor:latest
أو قم ببنائه بنفسك بدلاً من السحب:```bash docker build -f .devcontainer/Dockerfile -t raptor:latest . docker run --privileged -it -v "$(pwd):/workspaces/raptor" raptor:latest
علامة `--privileged` مطلوبة لمصحح الأخطاء الحتمي `rr`. الصورة كبيرة (حوالي 6 جيجابايت). تبدأ من حاوية التطوير Microsoft Python 3.12 وتضيف أدوات التحليل الثابت والتشويش وأتمتة المتصفح.
---
## ما يمكن توقعه عند التشغيل الأول
أبسط شيء يمكنك فعله:```
/scan /path/to/code
يقوم هذا بتشغيل Semgrep (و CodeQL إذا تم تثبيته) ضد الهدف، ويزيل التكرارات من النتائج، ويكتب تقرير SARIF. لا يوجد تحليل LLM، ولا مفاتيح API بخلاف Claude Code. يستغرق بضع دقائق على مستودع نموذجي.
لإضافة التحقق المدعوم بالذكاء الاصطناعي:``` /agentic /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 وتحليل مستودعات غير موثوقة. العمليات الفرعية التي تتعامل مع محتوى غير موثوق يتم وضعها في صندوق رمل باستخدام مساحات أسماء لينكس و Landlock و seccomp. يمنع الصندوق الرملي الوصول إلى الشبكة، ويقيد رؤية نظام الملفات، ويحد من استهلاك الموارد. راجع `docs/sandbox.md` لنموذج التهديد الكامل والتكوين.
يتم تجريد متغيرات البيئة التي يمكنها حقن كود في سلسلة الإطلاق عند بدء التشغيل (`core/security/_dangerous_env_strip.sh`). لا يتم أبدًا إدراج مسارات الملفات من المستودعات الممسوحة في سلاسل الأوامر — تستخدم جميع استدعاءات العمليات الفرعية وسائط قائمة.
---
## ما يمكن أن يفعله RAPTOR
| الأمر | الوظيفة | الحالة |
|---------|-------------|--------|
| `/agentic` | سير عمل مستقل بالكامل: مسح ضوئي، تحقق، استغلال، تصحيح | مستقر |
| `/scan` | تحليل ثابت باستخدام Semgrep و CodeQL | مستقر |
| `/understand` | رسم خريطة سطح الهجوم، تتبع تدفقات البيانات، البحث عن متغيرات الثغرات | مستقر |
| `/binary` | فحص ثنائي باستخدام الصندوق الأسود، أدلة وقت التشغيل، استعلامات الرسم البياني والتسليم | تجريبي |
| `/validate` | خط أنابيب تحقق متعدد المراحل لقابلية الاستغلال (المراحل 0-F) | مستقر |
| `/codeql` | تحليل عميق باستخدام CodeQL فقط مع فحص مسبق لتدفق البيانات عبر SMT | مستقر |
| `/sca` | تحليل تكوين البرمجيات: التبعيات، الاستشارات، إشارات سلسلة التوريد، قوائم مكونات البرمجيات (SBOM)، والإصلاحات | تجريبي |
| `/exploit` | إنشاء كود إثبات مفهوم للاستغلال | تجريبي |
| `/patch` | إنشاء تصحيحات آمنة للثغرات المؤكدة | تجريبي |
| `/fuzz` | اختبار التشويش الثنائي باستخدام AFL++ وتحليل الأعطال | مستقر |
| `/crash-analysis` | تحليل السبب الجذري المستقل للأعطال في C/C++ | مستقر |
| `/oss-forensics` | تحقيق جنائي مدعوم بالأدلة للمستودعات على GitHub | مستقر |
| `/project` | مساحات عمل مسماة لتنظيم عمليات التشغيل وتتبع الاكتشافات بمرور الوقت | مستقر |
| `/threat-model` | إنشاء وفحص وصيانة نماذج التهديد لكل مشروع | مستقر |
| `/sage` | طبقة ذاكرة مستمرة (تخزين، استرجاع، ربط، تأكيد) | مستقر |
| `/frida` | أجهزة ديناميكية عبر Frida | ألفا |
| `/web` | فحص تطبيقات الويب | ألفا/هيكل |
---
## كيف يعمل خط الأنابيب
ابدأ بإنشاء مشروع بحيث تهبط جميع عمليات التشغيل الخاصة بك في مكان واحد:```
/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
بالنسبة لقطعة أثرية مُجمَّعة، فإن نقطة البداية المكافئة هي:```text /binary investigate /path/to/binary # build the evidence-backed binary map /binary graph --edges --json # query the persisted graph /binary trace-parser # collect runtime parser evidence /binary harness # draft a harness only when the boundary is explicit
`/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`.
- المرحلة أ: هل النمط هو بالفعل ثغرة، أم أن الأداة تقوم بمطابقة أنماط ضوضاء؟
- المرحلة ب: ما الذي يحتاجه المهاجم للوصول إليها، وما الذي يعترض الطريق؟
- المرحلة ج: هل مسار الكود موجود فعلياً؟ هل يمكن الوصول إليه من الخارج؟
- المرحلة د: القرار النهائي - هل هذا كود اختباري، هل يحتاج إلى شروط مسبقة غير واقعية، هل النموذج يتحوط؟
- المرحلة هـ: جدوى استغلال الثنائي (عند توفر قطعة أثرية مترجمة)
- المرحلة و: المراجعة الذاتية - هل قامت أي مرحلة سابقة بالتحوط أو تناقضت مع نفسها؟
النتائج التي تجتاز التحقق تحصل على إثباتات استغلال (PoCs) وتصحيحات. يتم تشغيل تحليل عبر النتائج في النهاية للعثور على الأسباب الجذرية المشتركة وسلاسل الهجمات.
`/validate` يقوم بتشغيل نفس المسار كخطوة مستقلة إذا كان لديك بالفعل نتائج من مسح سابق.
بالنسبة للقطعة الأثرية المترجمة، يقوم `/binary <path>` الآن بإجراء تحقيق قائم على الأدلة بدلاً من إغراق المشغل بمجموعة من القطع الأثرية الهندسية العكسية الخام. في الخلفية، لا يزال يقوم ببناء البيان المرتبط بـ SHA-256، وسجل الأدلة، وخريطة السياق، وقائمة التحقق، ورسم SQLite البياني من بيانات الملف الوصفية، والإستيرادات، والمراجع المتقاطعة من radare2. تطبيقات Mach-O تحصل أيضاً على جرد الشرائح، وبيانات الحزمة المعدنية، ومحددات الفئات في Objective-C / Swift؛ يتم الاحتفاظ بالكود الزائف عالي القيمة بدلاً من اختفائه داخل التشغيل. يتم التعامل مع تصديرات DLL لـ PE، ومرسلات برامج تشغيل Windows، ومعالجات ioctl لوحدات kernel في Linux كمرشحات دخول خاصة بها أيضاً، مع قراءة بنية PE من رأس COFF بدلاً من التخمين. ثم تقوم طبقة التحقيق بالاستعلام عن ذلك الرسم البياني، وترتيب الدخول الخارجي قبل أدلة المصارف العامة، واكتشاف الثنائيات المساعدة/الشقيقة المُعلنة، وكتابة تقرير مضغوط مقسم إلى حقائق واستدلالات هيكلية وفرضيات غير مثبتة. يمكن لملاحظات Frida، وشهود أعطال fuzz، وفحوصات Z3 الصريحة، والفروقات الثنائية أن تضيف أدلة أقوى لاحقاً. يحتفظ RAPTOR أيضاً بالرسم البياني للاستدعاءات الداخلية اللازمة لاستعادة مرشحات الدخول إلى المحلل المحدودة، بحيث يمكن تضييق رد اتصال التطبيق إلى الوظيفة الداخلية التي تستدعي فعلياً `XML_Parse` أو `d2i_X509` أو `jpeg_read_header` أو سطح محلل حقيقي آخر دون التظاهر بأن هذا دليل على التلوث. `/binary trace-parser <run-dir>` هو المتابعة الديناميكية الصريحة: يقوم بتشغيل تتبع محلل Frida الضيق، ثم يقوم بتحديث نفس خريطة السياق، والتحويل، والرسم البياني، وتقرير التحقيق في مكانه. `/binary investigate --active` يقوم برسم الخريطة أولاً ولا يطلق حملة fuzz حقيقية إلا عندما يوجد حد تسخير ملموس؛ أهداف التطبيق وDLL وبرنامج التشغيل تحصل على خطوة تسخير أو لقطة بدلاً من ذلك. `/binary harness` يكتب مواصفات تسخير مدعومة بالأدلة للدخول المختار ولا يصدر كوداً مصدرياً مرشحاً إلا عندما يكون عقد ABI أو IOCTL صريحاً. إنه لا يختلق طريقاً من “`memcpy` موجود” إلى “هذا قابل للاستغلال”: الاستيرادات والمحددات وحواف الاستدعاء تبقى مرشحة حتى يثبت شيء ميكانيكي المزيد. انظر `docs/binary-analysis.md`.
## تحليل تكوين البرمجيات
`/sca` يقوم بتحليل جانب التبعيات وسلسلة التوريد للمشروع. إنه ليس مجرد بحث عن CVE في ملف المتطلبات: يكتشف 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
الأوامر الفرعية المفيدة تشمل fix، check، upgrade، diff، verify، health، render، suppress، و clean-cache. راجع docs/sca.md للمرجع الكامل.
لدى RAPTOR تكامل ذو طبقتين مع Z3 (pip install z3-solver). وهو اختياري. كل شيء يعمل بدونه، لكن النتائج تكون أفضل معه.
فحص مسبق لتدفق البيانات (CodeQL)
عندما ينتج CodeQL نتيجة مسار، يتم التحقق من قيود المسار من حيث قابلية الإشباع قبل أي استدعاء لـ LLM. يتم التخلص من المسارات التي ثبت أنه لا يمكن الوصول إليها فورًا. بالنسبة للمسارات التي يمكن الوصول إليها، ينتج Z3 مدخلات مرشحة ملموسة تدخل في موجه التحليل، بحيث يكون لدى LLM شيء محدد للتفكير فيه بدلاً من الأنماط المجردة.
تحليل قيود الأداة الواحدة (جدوى الاستغلال الثنائي)
أثناء تقييم جدوى استغلال الثنائيات، يتحقق Z3 مما إذا كانت قيود السجلات والذاكرة لأداة واحدة قابلة للإشباع مقابل حالة الانهيار الملموسة. يتم ترتيب الأدوات حسب الوصول الفعلي بدلاً من الاستدلالات، لذا تقضي وقتًا على الأدوات التي يمكن أن تعمل بالفعل.
Z3 مثبت مسبقًا في حاوية التطوير. للتثبيت اليدوي: pip install z3-solver.
عند تثبيت orjson (pip install orjson)، يستخدم RAPTOR orjson لجميع تحليل JSON وتسلسله. الفرق في السرعة مهم في قوائم الجرد الكبيرة ومجموعات النتائج. بدونه، كل شيء يعمل بشكل متطابق عبر json من المكتبة القياسية — التبديل شفاف.
قواعد RAPTOR المخصصة ضمن engine/semgrep/rules/ محلية بالكامل وتعمل دون اتصال بالشبكة.
بالنسبة لحزم السجل (p/security-audit، p/owasp-top-ten، إلخ)، يتم شحن دليل الذاكرة المؤقتة فارغًا. أداة الذاكرة المؤقتة (engine/semgrep/tools/cache-packs.py) تتعامل مع التعبئة:```bash
python3 engine/semgrep/tools/cache-packs.py update
python3 engine/semgrep/tools/cache-packs.py fetch
python3 engine/semgrep/tools/cache-packs.py import semgrep-cache-2026-07-16.zip
python3 engine/semgrep/tools/cache-packs.py list
بمجرد تعبئتها، يقوم الماسح بحل معرفات الحزم إلى ملفات محلية ولا تحدث أي استدعاءات شبكية. بدون ذاكرة التخزين المؤقت، سيحاول RAPTOR جلب حزم السجل من semgrep.dev وقت الفحص؛ إذا كان غير متصل بالإنترنت، فإنه يسقط الحزم غير المخزنة مؤقتًا بأمان ويعمل فقط بالقواعد المخصصة.
يحتاج CodeQL إلى الوصول إلى الشبكة فقط أثناء الإعداد الأولي لتنزيل واجهة سطر الأوامر وحزم الاستعلامات. بمجرد تثبيته، يعمل دون اتصال.
---
## القواعد المخصصة
يحتوي RAPTOR على 185 قاعدة تحليل ثابتة مخصصة، تم اختبارها ضد الخصومة لإزالة النتائج الإيجابية الخاطئة:
- **Semgrep (123 قاعدة)** — قواعد تتبع التلوث والنمط للبايثون، وغو، وجافا، وJS/TS. تغطي SQLi، XSS، SSRF، SSTI، حقن الأوامر، إلغاء التسلسل، XXE، حقن LDAP/NoSQL، اجتياز المسار، إعادة التوجيه المفتوحة، حقن السجلات/الرؤوس، حقن eval، ReDoS، تلوث النموذج الأولي، سوء تكوين JWT، التشفير الضعيف، TLS غير آمن، والأسرار المشفرة.
- **Coccinelle (54 قاعدة)** — مطابقة هيكلية لـ 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++ (حقن تنسيق السلسلة، اقتطاع الأعداد الصحيحة، الاستخدام بعد النقل، إبطال المكرر) وجافا (XXE، إلغاء التسلسل غير آمن، حقن السجلات، SSRF في Spring).
تصفح القواعد مباشرة: `engine/semgrep/rules/`، `engine/coccinelle/rules/`، `engine/codeql/queries/`. هذه تكمل حزم السجل (`p/security-audit`، `p/owasp-top-ten`، `p/0xdea`، `p/trailofbits`) التي توفر حوالي 950 قاعدة إضافية—التداخل ضئيل.
---
## استخدام LLM مختلف
يحتوي RAPTOR على طبقتين نموذجيتين منفصلتين، ومن الجدير معرفة كيفية عمل كلتيهما قبل تغيير أي شيء.
طبقة **التنسيق (orchestration)** هي دائمًا Claude Code. يتم تشغيل ملف CLAUDE.md والمهارات والأوامر كتعليمات Claude Code. لتغيير نموذج Claude الذي ينظم RAPTOR، استخدم علامة `--model` الخاصة بـ Claude Code أو الأمر `/model` داخل جلسة.
طبقة **إرسال التحليل (analysis dispatch)** هي 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"
}
]
}
أو تخطَ ملف الإعدادات وقم بتعيين متغيرات البيئة. سيقوم RAPTOR باكتشافها تلقائيًا:```bash export ANTHROPIC_API_KEY=sk-ant-... # Anthropic Claude export OPENAI_API_KEY=sk-... # OpenAI export GEMINI_API_KEY=... # Google Gemini export MISTRAL_API_KEY=... # Mistral export OLLAMA_HOST=http://localhost:11434 # Local Ollama
| الدور | ماذا يفعل |
|------|-------------|
| `analysis` | يُحقق ويحلل كل نتيجة (المراحل من A إلى F) |
| `code` | يكتب براهين المفهوم للاستغلال ورمز التصحيح |
| `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
التحكم في الميزانية:```bash
python3 raptor.py agentic --repo /code --max-cost-usd 5.00
Ollama يعمل للتحليل ولكنه ينتج كود استغلال وتصحيح غير موثوق. لمهام توليد الكود، استخدم نموذجًا من الدرجة الأولى.
### الاختصار السريع من الطبقة السريعة + بطاقة أداء النموذج
عندما يكون لنموذج الطبقة التحليلية لديك نموذج شقيق أرخص من نفس المزود (Anthropic Opus → Haiku، OpenAI 5.x → 4o-mini، Gemini Pro → Flash-Lite، Mistral Large → Small)، سيستخدمه RAPTOR كعامل تصفية مسبق على المستهلكين المتصلين بالركيزة (codeql اليوم؛ SCA وغيرها كإضافات لاحقة). النموذج الرخيص لا يختصر أبدًا إلا على **الإيجابيات الكاذبة الواثقة**؛ الحالات الغامضة والإيجابيات الحقيقية الواثقة (confident-TPs) تعمل دائمًا مع التحليل الكامل. تتراكم الثقة لكل خلية `(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
RAPTOR يتكون من طبقتين.
طبقة تنفيذ Python (raptor.py، packages/، core/، engine/) تتولى المهام الثقيلة: تشغيل Semgrep وCodeQL، إدارة العمليات الفرعية، تحليل SARIF، إزالة النتائج المكررة، إرسال استدعاءات واجهة برمجة تطبيقات LLM، تتبع التكاليف، كتابة ملفات المخرجات. لا تتخذ قرارات. إنها تنفذ.
طبقة القرار Claude Code (.claude/، tiers/، CLAUDE.md) تتخذ القرارات: أي النتائج ينبغي تحديد أولوياتها، كيفية تفسير النتائج، ما هو سيناريو الهجوم، ما إذا كانت الثغرة القابلة للاستغلال واقعية. تم تنفيذها كمهارات وأوامر ووكلاء في Claude Code يتم تحميلها تدريجياً.```
CLAUDE.md always loaded -- bootstrap, routing, security rules
.claude/commands/ slash commands (/agentic, /scan, /validate, etc.)
.claude/skills/ methodology detail, loaded on demand
tiers/ adversarial thinking, recovery, expert personas
.claude/agents/ specialist sub-agents (offsec, crash analysis, forensics)
الانقسام يعني أنه يمكنك تشغيل طبقة Python من خط أنابيب CI (`python3 raptor.py scan --repo ...`) والحصول على مخرجات SARIF منظمة بدون Claude Code، أو تشغيلها تفاعليًا مع سير العمل الكامل.
---
## تحقيقات البرمجيات مفتوحة المصدر
يقوم `/oss-forensics` بالتحقيق في مستودعات GitHub العامة باستخدام أدلة من مصادر متعددة: واجهة برمجة تطبيقات GitHub، و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
أخبر Claude أي واحد تريد استخدامه، على سبيل المثال "استخدم متخصص استغلال الثنائيات".
انظر docs/README.md للفهرس الكامل. الأدلة الرئيسية:
RAPTOR مفتوح المصدر. أماكن جيدة للبدء إذا كنت ترغب في المساهمة:
@RequestParam، FastAPI typed params) — لا يمكن لـ semgrep مطابقة هذه المصادر، لذا نرحب بالأساليب البديلةيتم وضع علامات على الإصدارات كـ vX.Y.Z ويتم بناؤها تلقائيًا بواسطة CI. تحدد بادئات الالتزام ما يذهب إلى سجل التغييرات: feat: للميزات الجديدة، fix: لإصلاحات الأخطاء، security: للتغييرات الأمنية، docs: للتوثيق. أي شيء بدون بادئة يندرج ضمن "تغييرات أخرى". لا توجد اتفاقية صارمة مطلوبة، لكنها تساعد.
أرسل طلبات السحب. تحدث معنا على قناة #raptor في Slack الخاص بـ Prompt||GTFO: https://join.slack.com/t/promptgtfo/shared_invite/zt-3v2b4sll3-SfyzFRw2lykx_XQX7F3uNQ
MIT -- حقوق النشر (c) 2025-2026 Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright.
انظر LICENSE للحصول على النص الكامل. راجع تراخيص جميع التبعيات قبل الاستخدام التجاري -- لا يسمح CodeQL بذلك على وجه الخصوص.
| الملف | المحتوى |
|---|
docs/commands.md | مرجع كامل لأوامر الشرطة المائلة مع كل العلامات |
docs/architecture.md | هيكل قاعدة الكود وشجرة الدلائل |
docs/llm.md | تكوين مزود LLM، Bedrock، سير العمل متعدد النماذج |
docs/sandbox.md | عزل العمليات: الملفات الشخصية، Landlock، مساحات الأسماء |
docs/validation.md | خط أنابيب التحقق من قابلية الاستغلال (المراحل 0--1) |
docs/static-analysis.md | قواعد Semgrep وCoccinelle |
docs/codeql.md | تكامل CodeQL والتحليل الذاتي |
docs/binary-analysis.md | أوراكل ثنائي، /binary، جدوى الاستغلال |
docs/fuzzing.md | AFL++ وlibFuzzer |
docs/crash-analysis.md | تحليل السبب الجذري للأعطال بشكل ذاتي |
docs/sca.md | تحليل تكوين البرمجيات |
docs/frida.md | الأجهزة الديناميكية |
docs/security.md | نموذج الأمان الخاص بـ RAPTOR |
docs/threat-model.md | ميزة نموذج التهديد لكل مشروع |
docs/python-cli.md | مرجع CLI بايثون للبرمجة النصية والتكامل المستمر |
docs/concepts.md | المفاهيم الأساسية: نموذج الطبقتين، دورة حياة الاكتشاف، اختيار الأمر |
docs/agentic.md | سير العمل الذاتي: خط أنابيب /agentic، علامات الإثراء، متعدد النماذج |
docs/dependencies.md | الأدوات الخارجية، الإصدارات، والتراخيص |
tiers/personas/README.md | مرجع الشخصية الخبيرة |