SAFE

تنفّذ SAFE تقييمًا أمنيًا مُتحكَّمًا ومراعيًا لمستودعات الأكواد لنتائج Semgrep وTrivy في القطع البحثية.

تدعم مهمتَي تصنيف مستقلتين: التنبؤ الثنائي المباشر binary (SECURITY_RELEVANT أو NON_SECURITY) والتصنيف التفصيلي متعدد الفئات multiclass السياقي (ثلاث تسميات — انظر التسميات الثلاث). يمكن تشغيل كل مهمة في الوضع الصفري (zero-shot) أو الوضع الوكيل (agentic).

تتطلب فقط:

1. ملف CSV للنتائج مفصول بفاصلة منقوطة.
2. دليلًا يحتوي على مجلد واحد لكل قطعة بحثية لكل artifact_id.
3. اختياريًا، مجموعة ملفات PDF/نصوص للورقة البحثية مرتبطة بـ artifact_id.
4. مفتاح OpenAI API أو وصولًا إلى وكيل LiteLLM تابع للمؤسسة.

لا تدرّب ولا تضبط على أي بيانات تقييم مُعلَّمة. تُستخدم البيانات المُعلَّمة فقط بعد الاستدلال، لتقييم التنبؤات، ولا تراها المصنّفة أبدًا. لا تنفّذ 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_RISK
• HARDENING_RECOMMENDATION
• FALSE_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) للإشارة إلى بياناتك الخاصة قبل التشغيل.

الإعدادات الرئيسية: