VulTriage

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

📋 جدول المحتويات

• مقدمة
• الميزات الرئيسية
• متطلبات النظام
• بدء سريع
• الاستخدام
• مجموعات البيانات والنماذج
• الأسئلة الشائعة

مقدمة

هذا المشروع هو إطار عمل ذكي لكشف الثغرات الأمنية يعتمد على نموذجي GPT-4o وBGE-M3، ويجمع بين:

• تحليل البنية الثابتة: الرسوم البيانية لتدفق التحكم (CFG)، والرسوم البيانية لتدفق البيانات (DFG)، وأشجار البنية المجردة (AST)
• التوليد المعزز بالاسترجاع (RAG): مطابقة أنماط الثغرات استناداً إلى قاعدة المعرفة CWE
• فهم الشيفرة البرمجية: تحليل دلالي باستخدام نماذج اللغة الكبيرة
• الكشف الثنائي/الفردي: دعم أوضاع تقييم متعددة

الميزات الرئيسية

• ✅ دعم مجموعتي بيانات PrimeVul وKotlin
• ✅ استرجاع مدمج لقاعدة معرفة الثغرات CWE
• ✅ دراسات اجتثاث قابلة للتكوين
• ✅ تتبع فوري للمقاييس
• ✅ دعم مرن لتجارب فرط المعلمات

متطلبات النظام

• Python >= 3.9
• CUDA (اختياري، لتسريع GPU)

بدء سريع

1. تثبيت التبعيات

pip install -r requirements.txt

2. تجهيز الموارد

تنزيل نموذج BGE-M3

سيتم تنزيل النموذج تلقائياً، أو يمكنك تنزيله يدوياً:

git clone https://huggingface.co/BAAI/bge-m3
# Note: BGE-M3 related dependencies can be installed via FlagEmbedding. For details, refer to: pip install -U FlagEmbedding

تجهيز بيانات CWE

تأكد من وجود الملفات cwec_latest.xml/cwec_v4.19.1.xml و1435.csv/1435_filtered_columns.csv (بيانات فهرس CWE) في الدليل الجذر للمشروع.

ملاحظة: يستخدم هذا المشروع قائمة CWE لأخطر 25 نقطة ضعف برمجية. الملفات ذات الصلة مضمّنة بالفعل في الدليل الجذر للمشروع.

تجهيز مجموعات البيانات

ضع الملفات التالية في الدليل الجذر للمشروع:

• primevul_test_paired.jsonl (مجموعة بيانات PrimeVul)
• LLM4Vul-main/LLM4Vul-main/data/kotlin_data.csv (مجموعة بيانات Kotlin)

3. تكوين مفتاح API

عدّل إعدادات OpenAI API في main.py أو hyperparam_exp.py:

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.poixe.com/v1"
)

ملاحظة: تعذّر تحليل الرابط الحالي https://api.poixe.com/v1. قد يكون نوع صفحة ويب غير مدعوم أو رابطاً معطلاً. يُرجى التحقق من صحة الرابط أو التبديل إلى مزوّد API آخر.

4. تشغيل كشف الثغرات

الوضع الأساسي (الوظائف الكاملة)

python main.py --wotask all --jsonl_file primevul_test_paired.jsonl

وضع دراسة الاجتثاث

# Without control flow information
python main.py --wotask wo_ctrl_info_pth --jsonl_file primevul_test_paired.jsonl
# Without RAG knowledge
python main.py --wotask wo_rag_pth --jsonl_file primevul_test_paired.jsonl
# Without code understanding
python main.py --wotask wo_exp_pth --jsonl_file primevul_test_paired.jsonl
# Without any auxiliary information
python main.py --wotask nan --jsonl_file primevul_test_paired.jsonl

تجارب فرط المعلمات

# Pairwise evaluation mode
python hyperparam_exp.py --mode pairwise --input_file primevul_test_paired.jsonl --detail_level C --info_comb all --desc_level concise --max_vuln 2
# Single-sample evaluation mode
python hyperparam_exp.py --mode single --input_file LLM4Vul-main/LLM4Vul-main/data/kotlin_data.csv

5. عرض النتائج

يتم حفظ نتائج الكشف في الوقت الفعلي في metrics_log.txt وتُعرض ملخصات التقييم النهائية على الطرفية:

• تتضمن مقاييس التقييم الدقة، الاستدعاء، معدل الإيجابيات الكاذبة، وغيرها.
• تقارن نتائج دراسة الاجتثاث الاختلافات في الأداء عبر الأوضاع المختلفة لتحليل إسهام كل وحدة.

الاستخدام

نظرة عامة على السكربتات الرئيسية

السكربت	الغرض
main.py	السكربت الرئيسي لكشف الثغرات مع دعم دراسة الاجتثاث
hyperparam_exp.py	تجارب فرط المعلمات والتقييم متعدد الأوضاع
retrieval.py	وحدة استرجاع قاعدة معرفة CWE (استرجاع هجين يعتمد على نموذج BGE-M3)
metrics_tracker.py	متتبع فوري للمقاييس مع دعم حفظ السجلات والتصور البياني

وصف المعلمات

معلمات main.py

المعامل	الافتراضي	الوصف
--wotask	all	وضع الاجتثاث: all (الوظائف الكاملة)، wo_ctrl_info_pth (بدون معلومات البنية الثابتة)، wo_rag_pth (بدون معرفة RAG)، wo_exp_pth (بدون فهم الشيفرة)، nan (بدون معلومات مساعدة)
--jsonl_file	primevul_test_paired.jsonl	مسار مجموعة بيانات JSONL
--metrics_file	metrics_log.txt	ملف إخراج المقاييس

معلمات hyperparam_exp.py

المعامل	الافتراضي	الوصف
--mode	pairwise	وضع التقييم: pairwise أو single
--input_file	مطلوب	مسار ملف الإدخال (بتنسيق JSONL أو CSV)
--detail_level	C	مستوى تفصيل تحليل الشيفرة: C (كامل)، B (قياسي)، A (مختصر)
--info_comb	all	تركيبة المعلومات: all، no_ast، no_cfg، no_dfg
--desc_level	concise	مستوى الوصف: concise، normal، detailed
--max_vuln	2	الحد الأقصى لعدد الثغرات: 2 أو 4

مجموعات البيانات والنماذج

📊 مجموعات البيانات

1. مجموعة بيانات PrimeVul

• الاستشهاد: Yangruibo Ding, Yanjun Fu, Omniyyah Ibrahim, Chawin Sitawarin, Xinyun Chen, Basel Alomair, David Wagner, Baishakhi Ray, and Yizheng Chen. 2025. Vulnerability detection with code language models: How far are we? ISSTA 2025 (2025).
• الغرض: معيار مرجعي لكشف الثغرات الثنائي
• التنسيق: JSONL (يحتوي على الحقلين func وtarget)
• المصدر: مؤتمر ISSTA 2025 (الموقع الرسمي لـISSTA). يُرجى مراجعة الورقة الأصلية للحصول على أذونات الوصول إلى مجموعة البيانات.

2. مجموعة بيانات Kotlin

• الاستشهاد: Triet Huynh Minh Le, M Ali Babar, and Tung Hoang Thai. 2024. Software vulnerability prediction in low-resource languages: An empirical study of codebert and chatgpt. In Proceedings of the 28th International Conference on Evaluation and Assessment in Software Engineering, 679–685.
• الغرض: بحث في التنبؤ بالثغرات في اللغات منخفضة الموارد
• التنسيق: CSV (يحتوي على العمودين code وlabel)
• المصدر: مؤتمر EASE 2024 (الموقع الرسمي لمؤتمر EASE 2024). يُرجى مراجعة الورقة الأصلية للحصول على أذونات الوصول إلى مجموعة البيانات.

3. قاعدة بيانات CWE

• الإصدار: CWE v4.19.1
• المصدر: MITRE CWE
• الغرض: قاعدة معرفة بأنماط الثغرات وتعزيز الاسترجاع
• ملاحظة: يمكن استخدام CWE بحرية للأغراض البحثية والتطويرية والتجارية. يجب الاحتفاظ بنسبة حقوق النشر إلى MITRE.

🤖 النماذج

1. نموذج التضمين BGE-M3

• المطوّر: BAAI (أكاديمية بكين للذكاء الاصطناعي)
• HuggingFace: BAAI/bge-m3
• الترخيص: رخصة MIT (ملاحظة: تعذّر تحليل صفحة ترخيص النموذج الحالية. راجع ترخيص مشروع FlagEmbedding وهو رخصة MIT)
• الغرض: استرجاع هجين للمتجهات الكثيفة والمتفرقة، يدعم الاسترجاع متعدد اللغات، ومتعدد الدقة (أقصى طول للإدخال 8192 رمزاً)، ومتعدد الوظائف
• المشروع ذو الصلة: FlagEmbedding (مستودع مفتوح المصدر لنماذج سلسلة BGE)

2. GPT-4o

• المطوّر: OpenAI
• إصدار النموذج: gpt-4o-2024-11-20
• الترخيص: يتبع شروط استخدام OpenAI (سارية اعتباراً من 1 يناير 2026)
• الغرض: فهم الشيفرة البرمجية، وتحديد الثغرات، والاستدلال والحكم
• ملاحظة: يجب أن يتوافق الاستخدام مع شروط خدمة OpenAI. يُحظر الأنشطة غير القانونية أو الضارة والهندسة العكسية للنموذج.

📦 مكتبات التبعية

المكتبة	الإصدار	الترخيص
FlagEmbedding	1.4.0	MIT
openai	2.26.0	Apache 2.0

الأسئلة الشائعة

س1: كيف يمكن تغيير مزوّد OpenAI API؟

عدّل base_url وapi_key في main.py أو hyperparam_exp.py.