
يفحص فروقات الكود مع السياق لبناء رسم بياني للتأثير ويستخدم نماذج اللغة الكبيرة (LLMs) للعثور على الثغرات الأمنية، مع دعم فحص المستودعات المتعددة والبوابات في التكامل المستمر (CI) مع إخراج بصيغة SARIF.
تتحقق اختبارات الوحدة الخاصة بـ zairo من أنه يبني المطالبات الصحيحة ويتعامل مع الإجابات بشكل صحيح. لكنها لا تستطيع أن تخبرك ما إذا كان النموذج، عند تزويده بهذه المطالبات، يكتشف ثغرة أدخلها تغيير ما، أو يشير إلى ثغرة غير موجودة. هذا هو الغرض من هذا الدليل: مجموعة من التغييرات المُصنَّفة، وأداة تشغيل تفحص كل تغيير منها عدة مرات باستخدام نموذج حقيقي وتقيّم النتائج.
pip install -e . # from the repo root
export GEMINI_API_KEY=... # whichever key your --model needs
python evals/run.py --model gemini/gemini-2.5-flash --repeats 3 --out results.json
كل حالة تكلّف تقريبًا طلبًا واحدًا لكل رمز متغيّر لكل تكرار. تغيّر الحالات الـ 16 هنا من رمز واحد إلى 4 رموز لكل منها، لذا فإن تشغيلًا من 3 تكرارات يُنشئ نحو 100 طلب. كل تشغيل يسأل النموذج من جديد: لا ذاكرة تخزين مؤقت، ولا ملاحظات تسخين مسبق.
كل دليل في cases/ هو تغيير واحد: يحتوي before/ وafter/ على المستودع (الصغير) بأكمله على كل جانب، ويصنّفه case.json:
{
"description": "What the change does, and why it's vulnerable or not.",
"vulnerable": true,
"symbol": "search_users",
"cwe": "CWE-89",
"source": "synthetic"
}
تُسمّي الحالة القابلة للاستغلال symbol المُغيَّر الذي توجد فيه الثغرة وcwe الخاص بها، إضافةً إلى، في also_cwe، أي CWEs أخرى تصفها كذلك: الترويسة القابلة للانتحال هي CWE-290، لكن CWE-287 وCWE-306 ليستا خاطئتين. الحالة النظيفة لا تحتوي على أيٍّ من هذه، وينبغي أن تكون نظيفة بما لا يقبل الجدل. التغيير الآمن عند high لكن فيه نتيجة medium معقولة يقيس الضجيج، لا الإنذارات الكاذبة. يُثبّت المشغّل before، ثم after، في مستودع جديد ويفحص HEAD~1..HEAD، كما يفعل فحص PR.
هناك 9 حالات قابلة للاستغلال (حقن SQL، اجتياز المسار، فحص مستأجر مُسقَط، تحميل YAML غير آمن، حقن الأوامر، إعادة توجيه مفتوحة، SSRF، التحقق من TLS معطّل، وتجاوز مصادقة عبر ترويسة قابلة للانتحال) و7 حالات نظيفة. عُدّة من الحالات النظيفة مصمّمة لتبدو خطرة: حقن SQL يجري إصلاحه، ORDER BY مُنسَّق من قائمة سماح، استدعاء subprocess بقائمة وسائط ثابتة.
هذه الملفات عيّنات شيفرة قابلة للاستغلال عمدًا. لا تُحزَّم ولا تُشغَّل أبدًا، لكن أي ماسح موجَّه إلى هذا المستودع سيجدها.
النتيجة تحجب عندما يمنع --fail-on الـ PR بسببها: مُعلَّمة بـ introduced_by_change: true، عند --fail-on أو أعلى (الافتراضي high). كل تشغيل يحصل على حكم:
symbol الخاص بالحالة)، أو وجده تحت العتبة (نتيجة أدخلها التغيير هناك، بخطورة أدنى)، أو فوّته.يُترك التشغيل دون تقييم فقط عندما لا يقول شيئًا في أيٍّ من الاتجاهين: تعذّر تقييم الرمز المهم، أو لم تُشَر حالة نظيفة لكن فشل بعض الرموز. النتيجة الحاجبة تُحتسب مهما فشل غيرها، لأن العتبة كانت ستحجب الـ PR بسببها على أي حال. يطبع المشغّل أكثر أسباب فشل الرموز شيوعًا، ويحتفظ --out بها لكل تشغيل. النموذج الاستدلالي الذي يستهلك كل --max-tokens في التفكير لا يجيب أبدًا، فارفعها (إلى 16384، مثلًا) إن كان ذلك هو السبب المذكور.
name وsort في الاستعلام نفسه).يكتب --out نتائج كل تشغيل (الرمز، العنوان، الخطورة، CWE، السطر، ما إذا كان التغيير أدخله وما إذا كان يحجب)، والرموز التي فشلت ولماذا، وأعداد الرموز، والتكاليف والأزمنة، حتى يمكن مقارنة تشغيلين، كنموذجين أو قبل تغيير في الـ prompt وبعده، حالة بحالة.
ست عشرة حالة صغيرة اصطناعية هي اختبار دخان لجودة الكشف، لا معيارًا مرجعيًا. كل واحدة تغيير واحد بخطأ مقصود واحد، في شيفرة أبسط بكثير من خدمة حقيقية، والحالات القابلة للاستغلال من النوع الذي يأمل المراجع في التقاطه. أفضل الحالات التي يمكن إضافتها هي الـ commits الحقيقية التي تُدخل ثغرات (عكس إصلاح CVE، مثلًا). ضع الملفات التي مسّها، قبل وبعد، في مجلد جديد، وسمّه. أبقِها صغيرة بما يكفي ليكون التغيير هو المقصود.
يتحقق tests/test_evals.py من كل حالة دون نموذج: من أنها تُبنى،
وأن zairo يحلل كل ملف يغيّره، وأن symbol الخاص بحالة ثغرة ما
يكون ضمن الرموز التي مسّها التغيير. وإلا لما أمكن أبدًا تسجيل أي فحص
بأنه التقطها.