dmdhrumilmistry/security-harnessإطار مراجعة أمنية تطبيقية ثابتة متعدد الوكلاء لوكلاء البرمجة بالذكاء الاصطناعي: يرسم خرائط لقواعد الأكواد، ويتقصّى فئات الثغرات، ويسلسل النتائج ويتحقق منها، ويقدّم التقارير بصيغ SARIF وJSON وPDF.
أداة مراجعة أمن التطبيقات متعددة الوكلاء لـ Claude Code (ولاحقًا، وكلاء ذكاء اصطناعي آخرين). مهارة موجّه واحدة توزّع المهام إلى خط أنابيب أمني هجومي كامل يقوم بـ رسم خريطة قاعدة الشيفرة، واصطياد الثغرات باستخدام قاعدة معرفية لكل فئة، وتسلسل النتائج إلى تصعيدات، والتحقق من التأثير الحقيقي، والإبلاغ إلى README / JSON / SARIF / doc / PDF.
النطاق: تنفّذ هذه الأداة تحليلًا ساكنًا (مراجعة الشيفرة المصدرية، تتبّع تدفّق البيانات، بناء PoC/payload) على شيفرة تملكها أو مصرّح لك باختبارها. لا تهاجم أنظمة طرف ثالث حيّة.
security-harness/ # a plugin marketplace └── plugins/security-harness/ ├── skills/ │ ├── sh-router # single entry point - routes any appsec request │ ├── sh-security-review # the pipeline orchestrator (Stages 0-5) │ └── sh-kb-* (15) # per-vuln-class knowledge bases ├── agents/ │ ├── sh-recon # map: Graft graph + stack/SBOM/CVE + attack surface │ ├── sh-hunter # find: source→sink hunting, one per class (parallel) │ ├── sh-chainer # escalate: combine findings into attack chains │ ├── sh-verifier # confirm: offensive + seceng + dev verification + PoC │ └── sh-reporter # deliver: README/JSON/SARIF/HTML/PDF/doc └── references/ # shared contracts (finding schema, SARIF map, state files, rubrics)
### فئات الثغرات المغطاة (مهارات `sh-kb-*`)
التحكم في الوصول (IDOR/BOLA/تصعيد الصلاحيات) · sqli · xss · ssrf · الحقن (cmd/code/SSTI/LDAP) · المصادقة (الجلسة/JWT)
· إلغاء التسلسل · اجتياز المسار (LFI/RFI) · الأسرار · csrf · xxe · إعادة التوجيه المفتوح · التشفير · حالات التسابق
· رفع الملفات. يتم التعامل مع ثغرات التبعيات CVEs/SBOM بواسطة مرحلة الاستطلاع.
## التثبيت
تتوفر أداة التشغيل لعدة وكلاء. تفاصيل التغليف الكاملة وقائمة التحقق
قبل الإصدار موجودة في [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md).
**Claude Code** - أضف هذا المستودع كسوق إضافات (plugin marketplace) وثبّت الإضافة:```
/plugin marketplace add dmdhrumilmistry/security-harness
/plugin install security-harness
/plugin marketplace add يقبل أيًا مما يلي: مسار GitHub owner/repo (كما هو موضح أعلاه)، أو عنوان URL كامل لـ git
(https://github.com/dmdhrumilmistry/security-harness.git)، أو مسار محلي إلى نسخة مستنسخة
(على سبيل المثال /plugin marketplace add ./security-harness من الدليل الذي يحتوي على نسختك المستنسخة).
ثم شغّل /plugin install security-harness وأعد التحميل عند المطالبة.
Gemini CLI - إضافة أصلية، ملف manifest في جذر المستودع:```bash gemini extensions install https://github.com/dmdhrumilmistry/security-harness
**opencode أو Codex أو أي وكيل [agentskills.io](https://agentskills.io)** - انسخ
المهارات إلى دليل الاكتشاف. كما يلتقط Codex ملف `AGENTS.md` من تلقاء نفسه:```bash
git clone https://github.com/dmdhrumilmistry/security-harness
cd security-harness
python3 scripts/sync-agent-skills.py --install agents # ~/.agents/skills
python3 scripts/sync-agent-skills.py --install opencode # ~/.config/opencode/skills
يتم تثبيت Graft وإعداده تلقائيًا بواسطة خط الأنابيب. تشغّل المرحلة 0 الأمر npm install -g @nanonets/graft إذا كان مفقودًا (يتطلب Node/npm)، ثم graft init <target> --no-agents --no-global
لتسجيل خادم Graft MCP وخطافات الحداثة للمستودع الهدف. يُبنى الرسم البياني نفسه (<target>/graft/،
يُتجاهل تلقائيًا بواسطة git) أثناء الاستطلاع. للتثبيت المسبق يدويًا: npm install -g @nanonets/graft. البناء
الهيكلي لـ Graft مجاني ولا يحتاج إلى مفتاح API؛ تمريرة LLM الاختيارية --deep تستخدم GRAFT_API_KEY /
GRAFT_PROVIDER / GRAFT_MODEL عند تعيينها.
تُثبَّت الأدوات الأخرى أيضًا تلقائيًا بواسطة المرحلة 0 عند فقدانها (عبر أي مدير حزم موجود على
الجهاز - winget/choco/scoop، brew، apt، npm/pip/go - انظر references/tooling-setup.md). يُعلَن عن
عمليات التثبيت، وتُفضَّل طرق عدم رفع الصلاحيات، ولا تعيق التشغيل أبدًا: أي شيء يتعذر تثبيته يُوسَم ببساطة
غير متاح ويتحول خط الأنابيب إلى البديل. تثبّت المرحلة 0 فقط ما يملأ مجموعة قدرات مفقودة:
syft · CVEs: أحد grype
(المفضّل)، trivy، أو osv-scannerwkhtmltopdf أو pandoc (لـ PDF/DOCX)؛ وإلا فستحصل على report.html (أو PDF عبر headless-Chrome).جميعها اختيارية - يتحول خط الأنابيب بسلاسة إلى البحث الأصلي + تحليل المانيفست إذا لم يُثبَّت أي منها.
استدعِ الموجّه (router) بطلب باللغة الطبيعية:``` /sh-router full security review of ./api /sh-router find SQLi and IDOR in src/ /sh-router just map this codebase # recon only
أو استدعِ خط الأنابيب مباشرةً:```
/sh-security-review . classes:sqli,access-control,ssrf depth:deep
/sh-security-review . stage:report # regenerate reports for the latest run
تعمل كل مرحلة على نموذج يتناسب مع حملها المعرفي، بحيث تُنفق الرموز (tokens) حيث تعتمد جودة الاكتشاف فعليًا عليها، وتُوفَّر في الأعمال الميكانيكية. هذا هو الإعداد الافتراضي - لا حاجة إلى وسائط.
| المرحلة | النموذج الافتراضي |
|---|---|
| recon | sonnet |
| hunt (لكل فئة) | haiku لفئات الأنماط (secrets, crypto, open-redirect, csrf) · sonnet لتتبع المصدر→المصب (sqli, xss, ssrf, injection, path-traversal, xxe, file-upload, auth) · opus لفئات المنطق العميق (access-control, race-conditions, deserialization) |
| chain | opus |
| verify | opus (بوابة الدقة - تبقى قوية) |
| report | haiku |
يمكن التجاوز باستخدام الوسيطة models: (تُمرَّر عبر الموجّه أيضًا):```
/sh-security-review . # default tiered map above
/sh-security-review . models:max # every stage + hunter on opus (max quality, max cost)
/sh-security-review . models:cheap # aggressive downshift (trades some verify precision)
/sh-security-review . models:verify=opus,hunt=sonnet # per-stage overrides
/sh-security-review . models:report=sonnet,hunt.pattern=sonnet # per-hunter-tier override
المراحل: `setup, recon, hunt, chain, verify, report`. النماذج: `opus, sonnet, haiku, inherit`. بالنسبة لـ `hunt`،
نموذج مجرّد يسطّح جميع الصيادين إليه؛ `hunt.pattern` / `hunt.trace` / `hunt.logic` تستهدف طبقة واحدة.
موفّرات الرموز الأخرى مدمجة: recon يُنشئ صيادين فقط للفئات ذات سطح هجوم حقيقي، والصيادون
يستعلمون من مخطط Graft بدلاً من قراءة الملفات كاملة، ويتم إنشاء `findings.json`/SARIF بواسطة
سكربت حتمي بدلاً من النموذج.
### المخرجات
كل شيء يستقر تحت `<target>/.security-harness/<run-id>/`:
- `recon.md`، `codebase-map.json` - الخريطة (stack، SBOM، CVEs، سطح الهجوم).
- `findings.jsonl` → `chains.md` → `verified.jsonl` - حالة العمل (انظر `references/state-files.md`).
- `reports/` - `README.md`، `findings.json`، `results.sarif`، `report.html`، `report.pdf` (+ `report.docx`).
كل اكتشاف منشور يحمل payload، وPoC، وحكم التحقق، ومعرّفات CWE/OWASP، وCVSS، و
تخفيفاً على مستوى الكود.
## مراجعة طلب السحب
`sh-pr-review` يراجع طلب سحب واحد بدلاً من قاعدة كود كاملة، وينشر
النتيجة كتعليقات مضمّنة **على طلب السحب نفسه**، ويضبط حالة commit باسم `security/pr-review`
يمكن لحماية الفرع فرضها.
**شغّله من جهازك الخاص، على أي PR يمكنك قراءته.** ثبّت الإضافة واسأل:```
review https://github.com/acme/api/pull/128
review PR 42
security review this PR
الصق رابط PR وسيقوم بمراجعة ذلك PR في ذلك المستودع، مع استنساخه إلى دليل مؤقت أولاً، لأن الصيادين يقرؤون الملفات وليس الرقعة فقط. لا شيء يُكتب في المستودع الذي تعمل فيه.
مرّر رقمًا مجردًا وسيتم حله مقابل المستودع الذي أنت فيه حاليًا، الذي
يشير إليه git remote. مرّر لا شيء وسيأخذ الـ PR المفتوح لفرعك الحالي.
المرحلة 7 تطبع النتائج والحكم وتسأل قبل نشر أي شيء - الرفض نتيجة طبيعية، وتبقى الحمولة على القرص لتنشرها لاحقًا.
قبل إنفاق أي تحليل يتحقق مما إذا كان بإمكانك الكتابة فعلاً إلى المستودع الهدف، لذا فإن مراجعة مشروع شخص آخر تخبرك مقدمًا أن النشر سيعيد 403 بدلاً من اكتشاف ذلك بعد عشر دقائق.
ثلاث خصائص تجعله قابلاً للاستخدام كبوابة دمج بدلاً من كونه ضوضاء:
pr_impact
بقيمة introduced أو aggravated أو pre_existing. الأولان يحجبان؛ pre_existing
يُبلَّغ عنه ولا يحجب أبدًا. حجب دمج بسبب كود لم يكتبه المؤلف هو كيف
يُحذف فحص مطلوب، لذا عندما يكون الصياد غير متأكد بين aggravated و
pre_existing، يجب أن يختار pre_existing.sh-kb-*، ثم يختار طبقة. الطبقة 0 (لا تغيير ذا صلة أمنية) لا تطلق شيئًا على
الإطلاق ومع ذلك تضبط الحالة. الطبقة 3 تشغّل خط الأنابيب الكامل.| الحكم | الحالة | متى |
|---|---|---|
| fail | failure | نتيجة introduced أو aggravated عند --fail-on أو أعلى (الافتراضي medium)، ثقة >= 80 |
| warn | success | لا شيء introduced أو aggravated؛ نتائج pre-existing مُبلَّغ عنها |
| pass | success | لا نتائج، أو توقف الفرز عند الطبقة 0 |
| error | error | تعذّر إكمال المراجعة |
warn يبلّغ عن success عن قصد: تحذير يحجب دمجًا هو فشل بخطوات إضافية،
والفرق تستجيب بإزالة الفحص. error يُبقى متميزًا عن
failure حتى لا تبدو جولة معطلة كأنها ثغرة لم يجدها.
حدث المراجعة دائمًا COMMENT، وليس REQUEST_CHANGES أو APPROVE أبدًا. حالة
الالتزام هي آلية الإنفاذ، وهي الفرع الوحيد الذي تقرؤه حماية الفروع.
النطاق: تكتب المهارة إلى الـ pull request وحالة الالتزام، ولا مكان آخر. لا تفتح أي issues ولا تنشئ شيئًا في أي متتبع خارجي.
يُ راجَع الـ PR مرة واحدة لكل دفعة، لذا يجب أن تكون المراجعة الثانية أرخص من الأولى وإلا أصبحت الأداة شيئًا يطفئه الناس.
إزالة التكرار تحدث قبل الإنفاق، وليس قبل النشر. البصمات الموجودة بالفعل على الـ PR تُقرأ في المرحلة 1 وتُسلَّم إلى الصيادين والمدقق. العثور على تكرار في النهاية يعني أن أغلى نموذج في خط الأنابيب قد أكّد بالفعل استنتاجًا كان مكتوبًا على الـ PR طوال الوقت. هذا لا يحتاج إلى ذاكرة تخزين مؤقت: الحالة تعيش في الـ PR، لذا تعمل على جهاز بارد وفي CI.
ذاكرة تخزين مؤقت محلية تجعل الباقي تراكميًا. يخزّن sh-review-cache تجزئات ملفات كل جولة
ونتائجها وأحكامها تحت دليل ذاكرة التخزين المؤقت لنظام التشغيل لديك (أبدًا في المستودع، لأن
مراجعة عبر المستودعات تعمل في نسخة مؤقتة تُحذف). المراجعة التالية تعيد صيد فقط
الملفات التي تغيّر محتواها فعلاً، وتعيد استخدام الأحكام للنتائج غير المتغيرة، و
تعيد استخدام خريطة الاستطلاع إذا لم يتحرك أي شيء تغطيه.
دمج الفرع الأساسي لا يكلف شيئًا. دمج main في فرع PR يغيّر الـ head
SHA ولا شيء مما كتبه المؤلف، لكن حالة الالتزام مثبتة على SHA، لذا يختفي الفحص المطلوب
بصمت من الـ head الجديد. عندما تكون ملفات الـ PR نفسها متطابقة بايت ببايت
و لا تمس دلتا الأساس أي شيء تعتمد عليه النتائج، يُعاد ختم الحكم السابق
على الـ SHA الجديد بدون إطلاق أي وكلاء على الإطلاق. هذا الشرط الأخير هو ما
يجعله آمنًا: دمج أساس يحذف مُطهّرًا يترك كل ملفات الـ PR دون تغيير بينما
يحوّل سطرًا آمنًا إلى سطر قابل للاستغلال.
الإبطال محافظ عن قصد، لأن إدخالًا قديمًا في أداة أمنية لا يجعلها بطيئة، بل يجعلها خاطئة.
مفتاح ذاكرة التخزين المؤقت يجزّئ كل قاعدة معرفة sh-kb-*، لذا فإن تحديث KB يبطل كل نتيجة مخزّنة
--no-cache يعطّلها، و--refresh-cache يعيد ضبط الأساس، وrun.md يسجّل لكل مرحلة
ما تم إطلاقه وإعادة استخدامه وتخطيه، لذا فإن ذاكرة تخزين مؤقت تتوقف بصمت عن الإصابة تكون مرئية
بدلاً من مفترضة.
تُنشر المراجعة وحالة الالتزام افتراضيًا. مراجعة حُسبت ولم
تُسلَّم لم تساعد أحدًا. --confirm يعيد مطالبة قبل النشر، و--dry-run
لا يرسل شيئًا، و--no-status ينشر المراجعة لكنه يترك حالة الالتزام وحدها.
النشر يمر عبر scripts/sh-pr-post.py بدلاً من استدعاءات API المبنية يدويًا، لأنه
عملية متعددة الخطوات بذيل إلزامي: مراجعة، ثم حالة، ثم إيصالات، مع
استرداد 422 بنقل التعليق بدلاً من إزاحة رقم سطر. السكربت
لا يخرج أبدًا تاركًا الحالة عند pending - إذا تعذّر نشر المراجعة فإنه لا يزال
يضبط error، قائلاً إن الأدوات فشلت بدلاً من اتهام الـ PR.
التعليقات المضمّنة محجوزة للنتائج عند medium أو أعلى بثقة >= 80. النتائج منخفضة الخطورة تذهب في قسم النص المطوي، لذا فإن ظهور نتيجة منخفضة الأولوية بدون تعليقات مضمّنة هو السياسة تعمل، وليس فشلاً.
كل جولة تسجّل ما كلفته، لذا يتوقف "ذاكرة التخزين المؤقت تعمل" و"المراجعات أصبحت أبطأ" عن كونهما مسألتي رأي.```bash python3 /scripts/sh-metrics.py path # where records live python3 /scripts/sh-metrics.py report # aggregate, by model python3 /scripts/sh-metrics.py purge --older-than-days 30
ملفان JSONL للإضافة فقط - `runs.jsonl` (المستودع، PR، الطبقة، الحكم، الإجماليات، الأعلام التي
مررتها) و`events.jsonl` (سطر واحد لكل مرحلة أو وكيل: النموذج، الرموز، المدة، النتيجة،
ما إذا كان قد أُعيد استخدامه من ذاكرة التخزين المؤقت). JSONL بحيث تترك التشغيلة المنهارة أسطرًا صالحة فوق
الانهيار.
| المنصة | المقاييس | ذاكرة التخزين المؤقت |
|---|---|---|
| **Linux / BSD** | `$XDG_DATA_HOME/security-harness/metrics`<br>الافتراضي `~/.local/share/security-harness/metrics` | `$XDG_CACHE_HOME/security-harness`<br>الافتراضي `~/.cache/security-harness` |
| macOS | `~/Library/Application Support/security-harness/metrics` | `~/Library/Caches/security-harness` |
| Windows | `%LOCALAPPDATA%\security-harness\metrics` | `%LOCALAPPDATA%\security-harness\cache` |
يتبع Linux مواصفة XDG Base Directory، لذا يحترم كلاهما `XDG_DATA_HOME` و
`XDG_CACHE_HOME` عند تعيينهما ويرجعان إلى `~/.local/share` و`~/.cache` عند
عدم تعيينهما. تجاوز أيًّا منهما مباشرةً باستخدام `SH_METRICS_DIR` و`SH_REVIEW_CACHE_DIR`.
**بخصوص `python` مقابل `python3`:** معظم توزيعات Linux تأتي بـ `python3` ولا تحتوي على `python`
إطلاقًا، لذا تستخدم الأمثلة هنا `python3`. تحمل النصوص البرمجية المرفقة
shebang `#!/usr/bin/env python3` وهي قابلة للتنفيذ، لذا يعمل `./scripts/sh-metrics.py report`
مباشرةً على Linux وmacOS. تحل المهارة
`PY="$(command -v python3 || command -v python)"` مرة واحدة لكل تشغيل، مما يغطي المنصات الثلاث
بما في ذلك Git Bash على Windows.
**محلي بالكامل.** لا يحتوي أي من النصين البرمجيين على أي كود شبكة أو نقطة نهاية للإبلاغ.
يُحجب أي شيء على شكل رمز مميز قبل كتابته، لأن الملفات المحلية تُلصق
في المشكلات.
### تشغيله دون إشراف
اختياري، وقرار منفصل عن استخدام المهارة. شغّله يدويًا على طلبات السحب الخاصة بك
لفترة أولًا، حتى تعرف ما يقوله عن قاعدة الكود الخاصة بك قبل أن يقوله
أمام فريقك.
عندما تكون مستعدًا، يحتوي "فرض الفحص على مستودع" في
[`references/pr-review-mapping.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/plugins/security-harness/references/pr-review-mapping.md)
على سير عمل جاهز للنسخ واللصق لمستودع**ك**، بالإضافة إلى آلية الأمان التي تمنع مهمة ميتة
من ترك فحص مطلوب عالقًا على `pending`.
تبقى العتبة عند الافتراضي `medium`. لا تحجب النتائج الموجودة مسبقًا أي دمج أبدًا،
لذا لا تنتج قاعدة كود غير مفحوصة جدارًا من الأحمر في اليوم الأول - فقط ما
يقدمه طلب السحب فعليًا أو يزيده سوءًا يمكن أن يُفشله.
## كيف يعمل
1. **الإعداد** - فحص الأدوات المتاحة، تحديد النطاق، إنشاء دليل التشغيل.
2. **الاستطلاع** (`sh-recon`) - بناء مخطط Graft؛ اكتشاف الحزمة/الإصدارات؛ SBOM + CVEs؛ تعداد نقاط
الدخول، وحدود الثقة، والمصارف الخطرة.
3. **الصيد** (`sh-hunter` ×N، بالتوازي) - يقوم صياد واحد لكل فئة ذات صلة بتحميل قاعدة معرفته `sh-kb-*`،
ويتتبع مدخلات المهاجم من المصدر إلى المصرف، ويسجل المرشحين. يمنع **سجل المحاولات** المشترك
الوكلاء من تكرار فحوصات بعضهم البعض.
4. **التسلسل** (`sh-chainer`) - تركيب النتائج في مسارات هجوم ذات خطورة أعلى.
5. **التحقق** (`sh-verifier`) - الدحض أولًا، ثم تأكيد قابلية الاستغلال من الأدلة، بناء PoCs، تعيين
CVSS، وقطع الإيجابيات الكاذبة.
6. **التقرير** (`sh-reporter`) - إنتاج المخرجات.
لا يتشارك الوكلاء الفرعيون شيئًا سوى الملفات؛ العقد موجود في `plugins/security-harness/references/state-files.md`.
## التوسيع
أضف فئة ثغرة جديدة بإنشاء `skills/sh-kb-<class>/SKILL.md` متبعًا القالب المشترك
(متى تصطاد · المصادر والمصارف · وصفة الكشف · الحمولات/PoC · مرشحات الإيجابيات الكاذبة · CWE/OWASP ·
تلميحات التسلسل · التخفيف)، ثم أضف الـ slug الخاص بها إلى enum `class` في `references/finding-schema.json`
وجدول التوجيه في `skills/sh-router/SKILL.md`.
## تحديثات قاعدة المعرفة الآلية
يحافظ إجراء GitHub مجدول (`.github/workflows/update-knowledge-base.yml`) على قواعد المعرفة `sh-kb-*`
حديثة. **كل يوم بديل** (وعند `workflow_dispatch` اليدوي)، يشغّل وكيلًا لتقطير أبحاث أمنية عامة جديدة
وموثوقة - OWASP، PortSwigger Research، CWE/CAPEC، NIST، MDN، مستودعات GitHub المنسقة،
وإفصاحات HackerOne العامة - إلى تحسينات صغيرة جيدة المصادر. ثم يقوم **وكيل مراجع خصمي ثانٍ**
بفحص الفرق الناتج بحثًا عن محتوى خبيث/محقون، ويُدمج طلب السحب
**تلقائيًا فقط إذا وافق ذلك المراجع**.
### سيرا عمل، ثلاث مهام
إنشاء طلب السحب منفصل عمدًا عن المراجعة والدمج، لذا فإن الشيء الذي يكتب
الفرق ليس أبدًا هو الشيء الذي يقرر شحنه.
**المرحلة 1 - [`update-knowledge-base.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/update-knowledge-base.yml)**
(مجدولة أو يدوية). مهمة واحدة، `create-pr`:
1. **التوليد** - يعدّل الوكيل قاعدة المعرفة من مصادر مسموح بها. لا commit، لا push.
2. **فتح PR** - خطوة حتمية تفتح (أو تحدّث) طلب سحب على فرع `automated/kb-update`،
موسوم بـ `awaiting-review`.
3. **التسليم** - عند إنشاء طلب سحب ناجح، يرسل المرحلة 2 مع رقم طلب السحب.
**المرحلة 2 - [`kb-review-and-merge.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/kb-review-and-merge.yml)**
(تُرسَل من المرحلة 1، أو تُشغَّل يدويًا مقابل أي طلب سحب آلي). مهمتان:
- **`review`** - تشغيلة وكيل *منفصلة* تفحص الفرق **خصميًا** بحثًا عن
آثار حقن الأوامر، تعديلات خارج النطاق، أسرار/تسريب، PII، استغلالات
مسلحة، مصادر خارج القائمة المسموح بها، أو انتهاكات أسلوب المشروع. ليس لديها **ويب ولا
shell**، و**تفشل مغلقة**: أي شيء مريب، أي عدم يقين، أو ملف حكم مفقود → رفض. يُنشر الحكم
كتعليق على طلب السحب ويقود الوسم.
- **`merge`** - يعمل **فقط** عند `APPROVE`، ويدمج طلب السحب. يتخطاه `REJECT` و
تبلغ مهمة `blocked` عن السبب.
> **لماذا dispatch بدلًا من مشغل `pull_request`:** طلب سحب مفتوح بواسطة `GITHUB_TOKEN`
> لا يشغّل سير عمل `pull_request`. `workflow_dispatch` هو أحد الحدثين
> المعفيين من حارس التكرار هذا، لذا يمكن للمرحلة 1 أن تسلّم بشكل موثوق.
**الدمج التلقائي يعني أن وكيلًا موافقًا يُنزل كودًا في `main`.** الضوابط على ذلك:
- ترفض مهمة الدمج أي طلب سحب مغلق، أو من fork، أو فرعه الرئيسي
خارج `automated/*` (`ALLOWED_HEAD_PREFIX` في سير العمل).
- تفضل الدمج التلقائي الخاص بـ GitHub، لذا **تظل حماية الفرع سارية**. مع قاعدة
على `main` تتطلب مراجعة موافقة، يصطف طلب السحب وينتظر إنسانًا بدلًا من
الدمج. يتراجع إلى دمج فوري فقط على المستودعات التي يكون فيها الدمج التلقائي معطلًا.
- اضبط مدخل `auto_merge` على `false` في تشغيل يدوي للمراجعة دون دمج.
- يخبر prompt المراجع الوكيل أن حكمه ملزم، وليس استشاريًا.
> يتطلب إعداد المستودع **"Allow GitHub Actions to create and approve pull requests"** (Settings →
> Actions → General → Workflow permissions) حتى يتمكن سير العمل من فتح طلب السحب. إذا أردت إنسانًا في
> الحلقة رغم الدمج التلقائي، احمِ `main` بقاعدة حماية فرع تتطلب طلب سحب و
> مراجعة موافقة واحدة على الأقل - يحترم مسار الدمج التلقائي ذلك.
### وكلاء قابلون للتوصيل
تعمل كلتا المرحلتين عبر [`.github/actions/ai-agent`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/actions/ai-agent/action.yml)،
وهو إجراء مركب يرسل إلى أي وكيل تقوم بتكوينه. Claude Code، OpenAI
Codex، Gemini CLI، ومخرج احتياطي لأي شيء آخر:
| `agent` | يشغّل | بيانات الاعتماد |
|---|---|---|
| `claude` (افتراضي) | `anthropics/claude-code-action@v1` | `CLAUDE_CODE_OAUTH_TOKEN` أو `ANTHROPIC_API_KEY` |
| `codex` | `codex exec --full-auto` | `OPENAI_API_KEY` |
| `gemini` | `gemini --yolo --prompt` | `GEMINI_API_KEY` |
| `custom` | `KB_AGENT_INSTALL` / `KB_AGENT_COMMAND` الخاص بك | ما يحتاجه |
اختر لكل تشغيل من مدخلات `workflow_dispatch`، أو اضبط متغيرات المستودع لتغيير
الافتراضي: `KB_AGENT` و`KB_MODEL` للمولّد، `KB_REVIEW_AGENT` و
`KB_REVIEW_MODEL` للمراجع. تشغيل المولّد والمراجع على **وكلاء مختلفين**
خطوة تقوية ذات مغزى: الحقن المضبوط لنموذج واحد أقل احتمالًا
أن ينجح على نموذج ثانٍ مستقل.
بالنسبة لـ `agent: custom`، اضبط `KB_AGENT_COMMAND` على أمر shell. يُكتب الـ prompt إلى
الملف المسمى بواسطة `$AGENT_PROMPT_FILE`، ويحمل `$AGENT_MODEL` مدخل النموذج.
دفاعات حقن الأوامر، بما أن المولّد يقرأ الويب المفتوح:
- **قائمة النطاقات المسموح بها.** `WebFetch` مقيد بالنطاقات الموثوقة في
`.github/kb-update/trusted-sources.md` (منسوخة في `--allowedTools` الخاص بسير العمل). يمكن لـ `WebSearch`
اكتشاف عناوين URL، لكن النطاقات المسموح بها فقط يمكن جلبها فعليًا.
- **المحتوى بيانات، وليس أوامر.** يوجّه prompt المهمة (`.github/kb-update/prompt.md`) Claude إلى
معاملة كل بايت مجلوب كمادة مرجعية غير موثوقة وتجاهل أي تعليمات مدمجة في
صفحة - نصوص تقارير HackerOne (التي ينشئها المستخدمون) موسومة كأعلى مستوى خطورة.
- **لا shell، لا push على المولّد؛ المراجع هو البوابة.** يمكن للمولّد تعديل الملفات فقط.
المراجع المستقل (`.github/kb-update/review-prompt.md`) هو ما يقف بين المحتوى المجلوب
و`main` - لا شيء يُدمج دون موافقته الصريحة.
- **وكلاء مختلفون للمولّد والمراجع.** اختياري، وهو أقوى نسخة من البوابة: اضبط
`KB_AGENT` و`KB_REVIEW_AGENT` على محركين مختلفين.
**الإعداد:**
- أضف بيانات الاعتماد لأي وكيل تستخدمه (Settings → Secrets and variables → Actions):
**`CLAUDE_CODE_OAUTH_TOKEN`** (افتراضي)، `ANTHROPIC_API_KEY`، `OPENAI_API_KEY`، أو `GEMINI_API_KEY`.
يصادق رمز OAuth مقابل **حدود استخدام اشتراك Claude الخاص بك** بدلًا من مفتاح
API مقيس - أنشئه محليًا باستخدام `claude setup-token` (يتطلب اشتراك Claude Pro/Max نشطًا)
والصق النتيجة.
- فعّل **"Allow GitHub Actions to create and approve pull requests"** (Settings → Actions → General →
Workflow permissions) حتى يتمكن سير العمل من فتح طلب السحب الخاص به. موصى به: أضف قاعدة حماية فرع على `main`
تتطلب طلب سحب ومراجعة موافقة، حتى لا يُنزل أي تغيير آلي دون إنسان حتى مع
تفعيل الدمج التلقائي.
- لتغيير المصادر المسموح بها، عدّل القائمة المسموح بها في `trusted-sources.md` **و** إدخالات
`WebFetch(domain:...)` المطابقة في سير العمل - أبقِ الاثنين متزامنين.
يسجل كل تشغيل ما فعله في `.github/kb-update/last-run-summary.md`.
## خارطة الطريق
- ~~توصيل مرآة Codex / Cursor.~~
✅ تم الشحن: `AGENTS.md`، امتداد Gemini CLI، و`scripts/sync-agent-skills.py`
لـ `.agents/skills` وopencode. انظر [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md).
- ~~تحسين اختياري بقاعدة المعرفة عبر الجلب المباشر (PortSwigger/OWASP/CWE) فوق المراجع المنسقة.~~
✅ تم الشحن كمحدّث قاعدة المعرفة المجدول أعلاه.
- جسر DAST اختياري للتأكيد وقت التشغيل لنتائج `needs-runtime`.
## الترخيص
MIT