أداة تسخين مرجعية للدفاع عن الشيفرات

تطبيق مرجعي للاكتشاف الذاتي للثغرات ومعالجتها باستخدام Claude، استنادًا إلى ما تعلمناه من الشراكة مع فرق الأمان في عدة مؤسسات منذ إطلاق Claude Mythos Preview. لمزيد من التفاصيل حول هذه الدروس وأفضل الممارسات، راجع منشور المدونة المصاحب (متوفر أيضًا في blog-post.md). للحصول على دليل خفيف باستخدام SDK فقط حول نفس الحلقة (الاستطلاع → البحث → الفرز → التقرير → التصحيح)، راجع الكتاب المصاحب.

هذا المستودع غير مُدار ولا يقبل المساهمات.

🔒 هل تريد خيارًا مُدارًا؟ تقدم Anthropic Claude Security، وهو منتج مُستضاف يجد ويصلح الثغرات في شيفرتك المصدرية عبر مشاريع متعددة. يقوم Claude Security بمسح مستودعك بحثًا عن الثغرات، ويطبق أنبوب تحقق متعدد المراحل لتقليل النتائج الإيجابية الخاطئة، ويتيح لك إدارة النتائج طوال دورة حياتها: الفرز، والتحقق من الإصلاح، وإنشاء الإصلاحات السريعة.

هذا المستودع هو تطبيق مرجعي مفتوح المصدر يعتمد على أفضل الممارسات العامة لإيجاد الثغرات باستخدام Claude. يمكنك استخدامه لبناء أنبوب البحث عن الثغرات الخاص بك، وتخصيص المنطق، ويمكن استخدامه مع أي وصول لديك إلى واجهات Claude API (بما في ذلك Bedrock، أو Vertex، أو Azure).

المحتويات

• مهارات Claude Code: /quickstart، /threat-model، /vuln-scan، /triage، /patch، /customize: تحديد النطاق التفاعلي، والمسح، والفرز، والتصحيح. افتح هذا المستودع في Claude Code وشغّل /quickstart للتعرف على البيئة.
• harness/: أنبوب المرجع الذاتي (الاستطلاع → البحث → التحقق → التقرير → التصحيح)، مُهيّأ لإيجاد ثغرات الذاكرة في C/C++ باستخدام Docker وASAN. هذا التسخين هو مرجع، وليس منتجًا. الشكل العام، والموجهات، والعزل الصندوقي قابلة لإعادة الاستخدام، لكن التسخين لن يعمل على كل قاعدة شيفرات مباشرة. شغّل /customize لنقله إلى لغتك، أو أداة الكشف، أو فئة الثغرات الخاصة بك.

⚠️ الأمان: /quickstart، /threat-model، /vuln-scan، و /triage يقرؤون ويكتبون الملفات فقط. تشغيل /patch على النتائج الثابتة (TRIAGE.json أو VULN-FINDINGS.json) هو أيضًا للقراءة والكتابة فقط. /customize يعدّل شيفرة التسخين ويشغل أوامر التحقق. أي من هذه المهارات آمنة للتشغيل دون عزل صندوقي، طالما أنك تراجع وتوافق على كل استخدام للأداة في Claude Code. أنبوب المرجع الذاتي (بما في ذلك /patch على نتائج الأنبوب) ينفذ الشيفرة الهدف، لذلك يرفض التشغيل خارج صندوق عزل gVisor ما لم يتم تجاوزه صراحةً. للإعداد، شغّل scripts/setup_sandbox.sh مرة واحدة، ثم استدعِ الأنبوب عبر bin/vp-sandboxed. راجع docs/security.md و docs/agent-sandbox.md لمزيد من التفاصيل.

البدء

git clone https://github.com/anthropics/defending-code-reference-harness
cd defending-code-reference-harness
claude

# مقدمة 30 ثانية + تشغيل أول موجه على الهدف الكناري
> /quickstart

> /quickstart كيف أنقل الأنبوب إلى Java؟
> /quickstart كيف أفرز كل هذه الأخطاء؟

قراءة إضافية

• منشور المدونة · منشور المدونة المصاحب مع الدروس وأفضل الممارسات
• الأنبوب · كيفية عمله: رسم بياني، مراحل، إشارات سطر الأوامر
• الأمان · العزل الصندوقي، ما لا يجب تركيبه
• صندوق عزل الوكيل · عزل gVisor + قائمة السماح بالخروج لكل وكيل
• التخصيص · النقل إلى رصيدي؛ أي الملفات تتغير ولماذا
• التصحيح · إنشاء والتحقق من الإصلاحات للأعطال المؤكدة
• استكشاف الأخطاء · التكرارات، حدود المعدل، تثبيت نموذج الوكيل الفرعي
• الضمانات · حظر الأعمال السيبرانية الخطيرة

تسريع العمل

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

الخطوة 1 (اليوم 1): بناء نموذج تهديد وتشغيل أول مسح ثابت + فرز

اليوم 1 يركز على رؤية الحلقة الكاملة من البداية إلى النهاية. باستخدام المهارات التفاعلية فقط، ستبني نموذج تهديد، وتشغل مسحًا ثابتًا محددًا به، وتفرز ما يعود، وتصوغ إصلاحات مقترحة. ستنهي اليوم بنموذج تهديد، وقائمة مرتبة من النتائج الثابتة، وتصحيحات مقترحة.

المهارات ذات الصلة تقرأ وتكتب الملفات فقط في مستودعك. طالما أنك تشغّل Claude Code تفاعليًا وتوافق على كل استخدام للأداة، لا حاجة لعزل صندوقي.

# ثبت كل وكيل فرعي على النموذج الذي تريده
export CLAUDE_CODE_SUBAGENT_MODEL=<model-id>
claude

# 0. مقدمة + تشغيل أول موجه
> /quickstart

# 1. بناء نموذج تهديد (صوّب قبل أن تطلق)
> /threat-model bootstrap targets/canary

# 2. تشغيل مسح ثابت، محددًا بواسطة نموذج التهديد
> /vuln-scan targets/canary

# 3. تحقق، أزل التكرارات، ورتب ما عاد
> /triage targets/canary/VULN-FINDINGS.json

# 4. إنشاء إصلاحات مقترحة للنتائج المؤكدة
> /patch ./TRIAGE.json --repo targets/canary

ينتج هذا التدفق THREAT_MODEL.md، VULN-FINDINGS.{json,md}، TRIAGE.{json,md}، و PATCHES/.

نتائج الثغرات المحتملة المنتجة في الخطوة 1 تأتي من المراجعة الثابتة لـ Claude للشيفرة المصدر (لا شيء يُبنى أو يُشغّل)، لذا توقع نتائج إيجابية خاطئة أكثر على أي أهداف غير الكناري. في الخطوة 2، ستنتج نتائج مؤكدة بالتنفيذ.

ملاحظة: على الهدف الكناري، قد يتجاهل /triage نتائج المسح كإيجابيات خاطئة. entry.c يعلن عن نفسه كشيفرة تجريبية معرضة عمدًا، و /triage يستبعد الأخطاء في شيفرة الاختبار / التجريب بشكل صحيح. لرؤية التدفق الكامل للتأكيد / إزالة التكرار / الإيجابيات الخاطئة، شغّله على التجربة المنظمة بدلاً من ذلك (/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary) أو وجّه مهارات الخطوة 1 إلى شيفرتك الخاصة.

الخطوة 2 (اليوم 2): تشغيل أنبوب المرجع على مكتبة C/C++

في اليوم 2، ستنتقل من المهارات التفاعلية إلى أول تشغيل ذاتي باستخدام أنبوب المرجع. ستشغل حلقة الاستطلاع → البحث → التحقق → التقرير الكاملة في بيئتك على مكتبة مفتوحة المصدر معروفة الثغرات، ثم تنشئ تصحيحًا مقترحًا لما تجده. ستنهي اليوم بمجموعة من الأعطال القابلة للتكرار، وتقارير قابلية الاستغلال، وتصحيحات مقترحة، مع شعور بكيفية عمل الأنبوب.

تشغيل الأنبوب بسيط:

# إعداد لمرة واحدة
python3 -m venv .venv && .venv/bin/pip install -e .
./scripts/setup_sandbox.sh   # يثبّت gVisor، يبني صور الوكيل، ويتحقق من العزل؛ ملاحظة: يتطلب Docker
export ANTHROPIC_API_KEY=sk-ant-...   # أو CLAUDE_CODE_OAUTH_TOKEN، أو Bedrock — راجع docs/agent-sandbox.md

# تشغيل حلقة الاستطلاع → البحث → التحقق → التقرير
bin/vp-sandboxed run drlibs --model <model-id> --runs 3 --parallel --stream --auto-focus
# إنشاء تصحيح مقترح لكل نتيجة
bin/vp-sandboxed patch results/drlibs/<timestamp>/ --model <model-id>

# أو، اطلب من Claude Code تشغيل الأنبوب ومشاهدة التشغيل لك
claude
> run the pipeline on drlibs and explain findings as they come

نتائج الحلقة تهبط في دليل results/drlibs/<timestamp>/. مع العلامة --stream، سيظهر التقرير الأول في دقائق تحت reports/bug_NN/.

⚠️ run يطلق وكلاء ذاتيين. يشغّل الأنبوب كل وكيل داخل حاوية gVisor مع تقييد الخروج إلى Claude API فقط. الأوامر الفرعية التي تطلق الوكيل ترفض البدء خارجه ما لم يتم تجاوزها صراحةً. لمزيد من المعلومات، راجع docs/security.md و docs/agent-sandbox.md.

تحت الغطاء، يمشي الأنبوب عبر سبع مراحل:

1. بناء: يجمّع الهدف في صورة Docker مع ASAN (كاشف أخطاء الذاكرة لـ C و C++). يبني الأنبوب هذه الصورة تلقائيًا في التشغيل الأول باستخدام Dockerfile الخاص بالهدف.
2. استطلاع: وكيل خفيف يقرأ الشيفرة المصدر داخل حاوية معزولة شبكيًا ويقترح تقسيمًا، أي "إليك N نظامًا فرعيًا مختلفًا لتحليل المدخلات يستحق الهجوم بشكل منفصل"، بحيث يستكشف وكلاء البحث المتوازيون مناطق مختلفة بدلاً من التركيز على نفس الخطأ. بدون العلامة --auto-focus، يستخدم الأنبوب قائمة focus_areas من config.yaml الخاص بالهدف.
3. بحث: N من الوكلاء يعملون بالتوازي، كل في حاوية معزولة خاصة به. كل وكيل يقرأ الشيفرة المصدر، ويصوغ مدخلات مشوهة، ويشغّل ملف ASAN الثنائي حتى ينتج مدخل معين عطلاً 3 مرات من أصل 3.
4. تحقق: وكيل تقييم منفصل يعيد إنتاج كل عطل في حاوية جديدة لم يلمسها وكيل البحث. الشيء الوحيد الذي يعبر من وكيل البحث إلى المقيّم هو إثبات المفهوم الذي أنتجه.
5. إزالة التكرار: وكيل حكم يقارن الأعطال المؤكدة ضد الأخطاء المبلغ عنها بالفعل ويقرر ما إذا كان كل منها خطأ جديدًا، أو مثالًا أفضل لخطأ معروف، أو مكررًا للتخطي.
6. تقرير: وكيل تقرير يكتب تحليل قابلية استغلال منظم لكل خطأ فريد، بما في ذلك تفاصيل فئة الأولية، قابلية الوصول، مسار التصعيد، والخطورة.
7. تصحيح (أمر التصحيح المنفصل أعلاه): وكيل تصحيح يكتب إصلاحًا مقترحًا، ووكيل تقييم يؤكد أن الشيفرة الجديدة تُبنى، وأن مدخل إثبات المفهوم الأصلي لم يعد يسبب عطلاً، وأن مجموعة اختبار الهدف لا تزال تمر، وأن وكيل بحث جديد لا يمكنه إيجاد طريقة لتجاوز الإصلاح.

لمزيد من التفاصيل، راجع docs/pipeline.md.

الخطوة 3 (الأيام 3-5): تخصيص الأنبوب لهدفك

في الأيام 3-5، ستخصص التسخين لهدفك الخاص. أولاً، ستوجّه مهارات الخطوة 1 إلى شيفرتك، ثم ستستخدم /customize لنقل الأنبوب إلى رصيدك. بحلول نهاية الأسبوع، سيكون لديك دليل targets/<your-service>/ يمكن للأنبوب تشغيله ضده، تم التحقق منه بتشغيل دخان واحد للأنبوب، وجاهز للتوسع في الخطوة 4.

بينما تم تصميم أنبوب المرجع لإيجاد ثغرات الذاكرة في شيفرات C و C++ ، فإن شكله عام. نقله إلى فئة ثغرات أو لغة جديدة يعني فقط الإجابة على الأسئلة التالية لرصيدك المستهدف:

قبل التخصيص، وجّه مهارات الخطوة 1 إلى شيفرتك الخاصة. كتذكير، هي للقراءة والكتابة فقط، لذا يمكن تشغيلها دون عزل صندوقي.

claude

> /quickstart كيف أخصص هذا لـ ~/code/my-service؟

> /threat-model bootstrap-then-interview ~/code/my-service
> /vuln-scan ~/code/my-service
> /triage ~/code/my-service/VULN-FINDINGS.json --repo ~/code/my-service

ثم، استخدم المخرجات المنتجة من تلك المهارات في مهارة /customize، التي تعدّل التسخين لقاعدة شيفرتك.

> /customize use ~/code/my-service/{THREAT_MODEL.md,VULN-FINDINGS.json} and ./TRIAGE.md

عند الانتهاء من /customize، سيكون لديك دليل targets/my-service/ مُعد. تحقق منه بتشغيل دخان للأنبوب قبل التوسع.

bin/vp-sandboxed run my-service --model <model-id> --runs 1

لمزيد من التفاصيل، راجع docs/customizing.md.

الخطوة 4 (الأسبوع 2): بدء المسح الذاتي، والفرز، والتصحيح

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

# مسح - تشغيل موجة من التشغيلات المتوازية ضد هدفك
bin/vp-sandboxed run my-service --model <model-id> --runs 5 --parallel --stream --auto-focus

# فرز - إزالة التكرار وترتيب كل نتيجة عبر جميع الموجات باستخدام نموذج التهديد
> /triage results/my-service/ --repo ~/code/my-service --auto --votes 5

# تصحيح - إنشاء والتحقق من الإصلاحات، بدءًا من أعلى ما رتبه الفرز
> /patch results/my-service/<timestamp>/ --model <model-id>

⚠️ اتبع نفس إرشادات العزل الصندوقي كما في الخطوة 2

تشغيل أنبوب معين يتحقق بالفعل ويزيل تكرار نتائجه الخاصة. /triage يعمل عبر العديد من تشغيلات الأنبوب. عندما يُوجّه إلى دليل results/، يدمج التكرارات عبر جميع التشغيلات (وأي نتائج ثابتة من /vuln-scan إذا كانت موجودة)، ويعيد معايرة تصنيفات الخطورة ضد نموذج التهديد الخاص بك، ويحاول توجيه كل نتيجة إلى مالك المكون.

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

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

لمزيد من التفاصيل، راجع docs/triage.md و docs/patching.md.

نظرة إلى الأمام

بعد التسريع الأولي، تميل الفرق التي عملنا معها إلى الاستثمار في عدد قليل من الاتجاهات:

1. مراجعة جميع مستودعاتهم الداخلية والتبعيات مفتوحة المصدر الرئيسية، وترتيب أيها الأكثر أهمية للمسح (مثلًا، بناءً على تعرضها، تاريخ CVEs، الأهمية التجارية)، ثم العمل على مسح القائمة حسب ترتيب الأولوية.
2. إعداد بنية تحتية مخصصة للمسح لنقل المسوحات من أجهزة الكمبيوتر المحمولة أو الأجهزة الافتراضية لمرة واحدة. تقاوم الفرق الأكثر نجاحًا الرغبة في بناء منصة المسح المثالية قبل التوسع.
3. دمج المسوحات في دورة حياة تطوير البرمجيات الخاصة بهم. بعض الفرق قامت بإعداد مسوحات متكررة (مثلًا، يوميًا، أسبوعيًا) أو أضافت المسح إلى خطوط أنابيب CI الخاصة بهم.
4. اختبار وتجربة النماذج لإيجاد ما يعمل بشكل أفضل لهم.