nanda-rani/safeنظام تدقيق أمني سياقي للقطع الأثرية البحثية
تنفّذ SAFE تقييمًا أمنيًا مُتحكَّمًا ومراعيًا لمستودعات الأكواد لنتائج Semgrep وTrivy في القطع البحثية.
تدعم مهمتَي تصنيف مستقلتين: التنبؤ الثنائي المباشر binary (SECURITY_RELEVANT أو NON_SECURITY) والتصنيف التفصيلي متعدد الفئات multiclass السياقي (ثلاث تسميات — انظر التسميات الثلاث). يمكن تشغيل كل مهمة في الوضع الصفري (zero-shot) أو الوضع الوكيل (agentic).
تتطلب فقط:
artifact_id.artifact_id.لا تدرّب ولا تضبط على أي بيانات تقييم مُعلَّمة. تُستخدم البيانات المُعلَّمة فقط بعد الاستدلال، لتقييم التنبؤات، ولا تراها المصنّفة أبدًا. لا تنفّذ SAFE كود القطع الأثرية أبدًا؛ يُعامل نص المستودع كدليل غير موثوق، وليس كتعليمات.
يحتوي هذا الإصدار على كود safe_audit الكامل، وواجهة الأوامر (CLI)، والاختبارات، بالإضافة إلى demo/ قائم بذاته يضم ثلاث قطع أثرية اصطناعية بالكامل يمكنك تشغيلها من البداية إلى النهاية دون أي بيانات خارجية. يستثني هذا الإصدار مجموعة القطع البحثية الحقيقية، والتسميات الأرضية (ground-truth)، ونتائج التقييم المستخدمة في الورقة البحثية.
بداية سريعة: بعد التثبيت، شغّل العرض التوضيحي — يعمل فورًا دون أي إعداد للبيانات. config.example.yaml، المُغطّى لاحقًا تحت الإعداد، هو قالب لنتائجك وقطعك الأثرية الخاصة ولن يعمل حتى تقوم بتحريره.
cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
عيّن مفتاح API:
export OPENAI_API_KEY="your-key"
بالنسبة لوكيل LiteLLM تابع للمؤسسة، استخدم config.litellm.example.yaml بدلًا من ذلك — وهو مُعلَّق عليه داخل الملف. تُقرأ بيانات الاعتماد وقيم الترويسات المخصصة من متغيرات البيئة ولا تُخزَّن أبدًا في إعدادات SAFE أو ملفات النتائج.
يحتوي demo/ على ثلاث قطع أثرية صغيرة اصطناعية بالكامل — لا تُشتق من أو تطابق أي قطعة بحثية منشورة حقيقية — واحدة لكل تسمية تصنيف، حتى يتمكن المراجعون من تجربة خط الأنابيب الكامل دون أي بيانات خارجية:
demo-contextual-risk/ — مُجمِّع نقاط تفتيش تعلم موزّع (federated learning) تجريبي يقوم بإلغاء تسلسل نقطة تفتيش تم تنزيلها من عنوان URL يوفّره المتصل باستخدام torch.load. يصل إدخال غير موثوق قادم من الشبكة إلى نقطة إغراق إلغاء تسلسل غير آمنة، ومن المتوقع أن تصنّفه SAFE كـ CONTEXTUAL_RISK.demo-hardening-recommendation/ — بيئة اختبار معيارية تجريبية تشغّل subprocess.run(..., shell=True) على أسطر أوامر جميعها قيم حرفية Python مكتوبة يدويًا (hardcoded)، دون أي إدخال يتحكم به المتصل. من المتوقع أن تصنّف SAFE هذا كـ HARDENING_RECOMMENDATION: نمط الصدفة (shell) حقيقي ويستحق التنبيه، لكن لا يمكن لأي شيء خارجي الوصول إليه أو التأثير عليه.demo-false-positive/ — مولّد تجهيزات اختبارية مثبّت على إصدار أقدم من Pillow مع استشارة افتراضية حول قنبلة فك ضغط. ينشئ الكود فقط صورًا جديدة في الذاكرة ولا يفتح بيانات خارجية أبدًا، لذا لا يُصل إلى مسار الكود الفعلي للاستشارة أبدًا. من المتوقع أن تصنّف SAFE هذا كـ FALSE_POSITIVE.يحمل demo/findings.csv نتيجة واحدة لكل قطعة أثرية، وdemo/demo-zero-shot.yaml / demo/demo-agentic.yaml هما ملفا إعداد جاهزان للتشغيل (artifact_root: . يُحلّ نسبيًا إلى ملف الإعداد، لذا شغّلهما من داخل demo/):
cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml
تظهر النتائج في demo/runs/demo-zero-shot/ وdemo/runs/demo-agentic/ على التوالي (انظر المخرجات).
CONTEXTUAL_RISKHARDENING_RECOMMENDATIONFALSE_POSITIVEلا تُستخدم أي فئة إضافية ولا أي قاعدة تغيير تسمية حتمية. تُصنَّف آلية بحث/أمنية موثّقة ومعزولة في كود القطعة الأثرية نفسها كـ HARDENING_RECOMMENDATION، لأن الممارسة الأساسية تظل حقيقية حتى عندما يحدّ العزل من قابلية الاستغلال الواقعية.
SECURITY_RELEVANT: خطر سياقي صالح أو مصدر قلق تحصيني، بما في ذلك سلوك البحث الأمني المتعمد والمعزول.NON_SECURITY: نتيجة خاطئة، أو غير متطابقة، أو غير قابلة للتطبيق، أو غائبة، أو لميزة متأثرة ثبت عدم استخدامها.يشتق المُقيِّم أيضًا عرضًا ثنائيًا من التنبؤات متعددة الفئات: تتحول FALSE_POSITIVE إلى NON_SECURITY؛ وكل تسمية أخرى متعددة الفئات تتحول إلى SECURITY_RELEVANT. تبقى النتائج الثنائية المباشرة والمشتقة منفصلة بوضوح.
project/
├── config.yaml
├── data/
│ └── findings.csv
└── artifacts/
├── artifact_001/
├── artifact_002/
└── artifact_003/
الربط دقيق: artifact_id = artifact_001 يُحلّ إلى artifacts/artifact_001/.
أعمدة CSV المطلوبة:
artifact_id;tool;finding_id
الأعمدة الاختيارية:
artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
يُتجاهل عمود فهرس أولي بدون اسم. تُحافظ بنية الإدخال على الأعمدة الإضافية.
مثال:
artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes
تُنتج scripts/run_scanners.py وscripts/build_findings_csv.py ملف findings.csv وبنية القطع الأثرية الموصوفة أعلاه مباشرة من كودك الخاص، باستخدام Semgrep وTrivy.
ثبّت Semgrep (يعمل بنفس الطريقة على أي نظام تشغيل، بما في ذلك Linux):
pip install semgrep
ثبّت Trivy على Linux — إما عبر مستودع apt (Debian/Ubuntu):
sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy
أو عبر سكربت التثبيت الرسمي، الذي يعمل على أي توزيعة Linux ويُثبّت إصدارًا ثنائيًا في /usr/local/bin (لا يتطلب حزم جذرية تتجاوز sudo لذلك الدليل):
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin
تحقق من وجود كلاهما في PATH قبل المتابعة:
semgrep --version
trivy --version
ثم رتّب دليلًا واحدًا لكل قطعة أثرية تحت artifact_root/ وشغّل:
python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv
يشغّل الأمر الأول Semgrep وTrivy (فحص الثغرات والأسرار) ضد كل دليل قطعة أثرية ويحفظ ملفات JSON الأولية للماسحات. يحلّل الأمر الثاني ملف JSON هذا إلى findings.csv متوافق مع SAFE (تطابق الأعمدة بنية الإدخال؛ يُبلَّغ file نسبيًا إلى كل دليل قطعة أثرية). مرّر --skip-semgrep/--skip-trivy لأي من السكربتين لتشغيل أداة واحدة فقط. يثبّت --config في run_scanners.py مجموعة قواعد Semgrep محددة بدلًا من auto الافتراضية، وهي مريحة لكنها غير مثبّتة بشكل قابل للتكرار.
هذا القسم مخصص لتشغيل SAFE ضد ملف نتائج CSV ومجلدات القطع الأثرية الخاصة بك (انظر بنية الإدخال أعلاه). إذا كنت تريد فقط رؤية SAFE يعمل، استخدم العرض التوضيحي بدلًا من ذلك — config.example.yaml أدناه قالب ولن يعمل كما هو.
انسخ config.example.yaml:
cp config.example.yaml config.yaml
ثم حرّر input_csv وartifact_root (واختياريًا paper_root) للإشارة إلى بياناتك الخاصة قبل التشغيل.
الإعدادات الرئيسية:
model / provider: معرّف نموذج OpenAI الدقيق (أو اسم مستعار LiteLLM)، وopenai أو litellm مع عنوان URL للوكيل واسم متغير بيئة بيانات الاعتماد.analysis_mode: zero_shot أو agentic.classification_task: binary أو multiclass؛ مستقل عن analysis_mode.max_agent_steps: مطلوب فقط في إعداد وكيل.max_workers / max_output_tokens / : التزامن، وسقف المخرجات لكل استجابة، وميزانية إعادة محاولة استدعاء النموذج للاستجابات غير الصالحة للمخطط.النموذج الافتراضي هو gpt-5.6-sol. غيّره صراحةً إذا اختلفت متطلبات التوفر أو التكلفة أو زمن الاستجابة.
safe-audit run --config config.yaml
أو دون تثبيت أمر وحدة التحكم:
PYTHONPATH=src python -m safe_audit.cli run --config config.yaml
لمقارنة قابلة للتشغيل ومطابقة ضد البيانات الاصطناعية المرفقة، انظر العرض التوضيحي (demo/demo-zero-shot.yaml وdemo/demo-agentic.yaml). يختلفان فقط في analysis_mode وrun_name. يقوم الوضع الصفري باستدعاء نموذج واحد على الأدلة الأساسية. يبدأ الوضع الوكيل من نفس الأدلة وقد يستدعي أدوات مستودع للقراءة فقط محدودة قبل إرجاع نفس النتيجة المنظمة.
runs/<run_name>/
├── config.resolved.yaml
├── run_metadata.json
├── summary.json
├── results.jsonl
├── results.csv
├── profiles/
├── evidence/
├── raw/<finding_uid>/
│ ├── 0001-request.json
│ ├── 0001-response.json (أو 0001-error.json)
│ └── final-output.txt
└── logs/
├── events.jsonl
├── result_attempts.jsonl
└── run_sessions.jsonl
results.csv مخصص للتحليل. يحافظ results.jsonl على السجلات المنظمة الكاملة. تدعم الأدلة والمخرجات الأولية للنموذج التدقيق وتحليل الأخطاء. كلاهما أساسي: يحتويان فقط على أحدث سجل لكل نتيجة، بينما logs/result_attempts.jsonl للإلحاق فقط ويحافظ على كل نتيجة تاريخية.
عند الاستئناف، تعيد SAFE أولًا تحليل الاستجابات الأولية المحفوظة لكل نتيجة فاشلة باستخدام المحلل الصارم الحالي؛ يُستعاد تصنيف صالح فريد دون استدعاء API. تُجدول فقط الإخفاقات غير القابلة للاسترداد لاستدلال النموذج. لاستمرار فاشل فقط لتشغيل مكتمل جزئيًا، أبقِ نفس output_root وrun_name وعيّن:
resume: true
resume_policy: failed_only
لتقييم التنبؤات ضد ملف CSV ذهبي مُعلَّم (بعمود security_label أو security_class):
safe-audit evaluate --results runs/<run_name>/results.jsonl --gold GOLD.csv --output runs/<run_name>/evaluation.json
PYTHONPATH=src python -m unittest discover -s tests -v
تستخدم مجموعة الاختبارات مزوّدًا وهميًا وبالتالي لا تتطلب مفتاح API.
max_schema_retriesresume / resume_policy: incomplete يعيد محاولة الإخفاقات والقطع الأثرية المفقودة والنتائج غير المُجرَّبة؛ failed_only يعيد محاولة الإخفاقات فقط مع الاحتفاظ بالنجاحات المسجلة.cost: محاسبة تكلفة مباشرة اختيارية وmax_run_cost_usd لإنهاء التشغيل.