Vulnhalla

تحليل CodeQL آلي مع تصنيف LLM

للحصول على نظرة عامة مفصلة حول البحث والدافع وراء Vulnhalla، راجع مقالة مدونة CyberArk لبحوث التهديدات الرسمية:

Vulnhalla: انتقاء الثغرات الحقيقية من كومة قش CodeQL

Vulnhalla تؤتمت مسار تحليل الأمان الكامل:

1. جلب المستودعات للغة برمجة معينة من GitHub
2. تنزيل قواعد بيانات CodeQL المقابلة (إذا كانت متوفرة)
3. تشغيل استعلامات CodeQL على قواعد البيانات تلك لاكتشاف مشكلات الأمان أو جودة الكود
4. معالجة لاحقة للنتائج باستخدام LLM (ChatGPT، Gemini، إلخ) لتصنيف المشكلات وتصفيتها

---

🚀 بداية سريعة

الخطوة 1: المتطلبات الأساسية

قبل البدء، تأكد من أن لديك:

• Python 3.10 – 3.13 (يوصى باستخدام Python 3.11 أو 3.12)

  • Python 3.14+ غير مدعومة (تستخدم هذه الأداة grpcio الذي لا يدعم Python 3.14+)
  • التحميل من python.org

• CodeQL CLI

  • التحميل من إصدارات CodeQL CLI
  • تأكد من أن codeql موجود في PATH، أو ستقوم بتعيين المسار في .env (انظر الخطوة 2)

• (اختياري) رمز GitHub API

  • للحصول على حدود معدل أعلى عند تنزيل قواعد البيانات
  • احصل عليه من GitHub Settings > Tokens

• مفتاح API لـ LLM

  • بيانات اعتماد OpenAI، Azure، Gemini، أو Bedrock (حسب المزود الذي تختاره)

الخطوة 2: تكوين البيئة

كل الإعدادات موجودة في ملف واحد: .env

1. استنساخ المستودع:

git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla

2. انسخ .env.example إلى .env:

cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)

3. حرّر .env واملأ القيم الخاصة بك:

مثال لـ OpenAI:

CODEQL_PATH=codeql
GITHUB_TOKEN=ghp_your_token_here
PROVIDER=openai
MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.2

# اختياري: تكوين التسجيل
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # اختياري: مسار ملف السجل (مثل logs/vulnhalla.log)
LOG_FORMAT=default              # default أو json
# LOG_VERBOSE_CONSOLE=false     # إذا كان true، WARNING/ERROR يستخدمان التنسيق الكامل (الطابع الزمني - المسجل - المستوى - الرسالة)

📖 للمرجعية الكاملة للتكوين: انظر مرجع التكوين أدناه لجميع المزودين المدعومين (OpenAI، Azure، Gemini، Bedrock)، والمتغيرات المطلوبة/الاختيارية، والأمثلة التفصيلية.

الخطوة 3: تثبيت Poetry (موصى به: pipx)

Windows (PowerShell):

# قائمة إصدارات Python المتاحة
py -0p

# اختر أي إصدار Python مدعوم: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# أغلق وأعد فتح الطرفية (مطلوب)
pipx install poetry
poetry --version

macOS / Linux:

# تحقق من إصدار Python
python3 --version

# استخدم أي Python مدعوم: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# أعد تشغيل الطرفية (مطلوب)
pipx install poetry
poetry --version

الخطوة 4: تثبيت التبعيات والإعداد

Windows (PowerShell):

# اختر إصدارًا واحدًا مدعومًا لديك: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # فرض Poetry لاستخدام إصدار Python مدعوم إذا كان لديك عدة إصدارات مثبتة
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# اختر إصدارًا واحدًا مدعومًا لديك: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # فرض Poetry لاستخدام إصدار Python مدعوم إذا كان لديك عدة إصدارات مثبتة
poetry install
poetry run vulnhalla-setup

الخطوة 5: تشغيل المسار

# تحليل مستودع معين، على سبيل المثال:
poetry run vulnhalla redis/redis

# إعادة التنزيل حتى لو كانت قاعدة البيانات موجودة بالفعل
poetry run vulnhalla redis/redis --force

# عرض المساعدة
poetry run vulnhalla --help

هذا سيقوم تلقائيًا بما يلي:

1. جلب قواعد بيانات CodeQL
2. تشغيل استعلامات CodeQL على جميع قواعد البيانات التي تم تنزيلها
3. تحليل النتائج باستخدام LLM وحفظها في output/results/
4. فتح واجهة المستخدم لتصفح النتائج

استخدام قاعدة بيانات CodeQL محلية

إذا كان لديك بالفعل قاعدة بيانات CodeQL على القرص (على سبيل المثال، تم إنشاؤها يدويًا أو من تشغيل سابق)، يمكنك تخطي خطوة جلب GitHub باستخدام العلم --local / -l:

Windows (PowerShell):

poetry run vulnhalla --local C:\path\to\my-codeql-db

macOS / Linux:

poetry run vulnhalla --local /path/to/my-codeql-db

ملاحظة: العلم --local يتوقع دليل قاعدة بيانات CodeQL، وليس مجلد كود مصدر. يمكنك التحقق من ذلك عن طريق التأكد من أن المجلد يحتوي على ملف codeql-database.yml.

أوامر إضافية

# فتح واجهة المستخدم لعرض النتائج الموجودة (دون تشغيل التحليل)
poetry run vulnhalla-ui

# التحقق من صحة التكوين: CodeQL, LLM, التسجيل (دون تشغيل التحليل)
poetry run vulnhalla-validate

# عرض قائمة المستودعات التي تم تحليلها وأعداد المشكلات فيها
poetry run vulnhalla-list

# تشغيل المسار النموذجي (يحلل videolan/vlc وredis/redis)
poetry run vulnhalla-example

---

🖥️ واجهة المستخدم (UI)

تتضمن Vulnhalla واجهة مستخدم كاملة المواصفات لتصفح واستكشاف نتائج التحليل.

تشغيل واجهة المستخدم

poetry run vulnhalla-ui

تخطيط واجهة المستخدم

تعرض واجهة المستخدم منطقة علوية بلوحين مع شريط تحكم سفلي:

المنطقة العلوية (جنبًا إلى جنب، قابلة لتغيير الحجم):

• اللوحة اليسرى (قائمة المشكلات):

  • جدول بيانات يعرض: المعرف، المستودع، اسم المشكلة، الملف، قرار LLM، القرار اليدوي
  • عدد المشكلات ومؤشر الفرز
  • مربع إدخال بحث في الأسفل، يتم التحديث أثناء الكتابة (غير حساس لحالة الأحرف).

• اللوحة اليمنى (التفاصيل):

  • قسم قرار LLM: يعرض تصنيف LLM (إيجابي حقيقي، إيجابي كاذب، أو يحتاج إلى مزيد من البيانات)
  • قسم البيانات الوصفية: اسم المشكلة، المستودع، الملف، السطر، النوع، اسم الدالة
  • قسم الكود:
    • 📌 سياق الكود الأولي (أول مقتطف كود رآه LLM)
    • 📥 كود إضافي (الكود الذي طلبه LLM أثناء المحادثة) - يظهر فقط إذا كان هناك كود إضافي
    • السطر الضعيف مُظلل باللون الأحمر
  • قسم الملخص: الإجابة/القرار النهائي لـ LLM
  • تحديد القرار اليدوي: قائمة منسدلة في الأسفل لتعيين الحكم اليدوي (إيجابي حقيقي، إيجابي كاذب، غير مؤكد، أو غير معين)

شريط التحكم السفلي:

• اللغة: C (اللغة الوحيدة المدعومة حاليًا)
• قائمة تصفية حسب قرار LLM: الكل، إيجابي حقيقي، إيجابي كاذب، يحتاج إلى مزيد من المعلومات للبت
• أزرار الإجراءات: تحديث، تشغيل التحليل
• نص مساعدة ربط المفاتيح

روابط المفاتيح

• ↑/↓ - التنقل في قائمة المشكلات (صفًا تلو الآخر)
• Tab / Shift+Tab - تبديل التركيز بين اللوحات
• Enter - عرض التفاصيل للمشكلة المحددة
• / - تركيز مربع إدخال البحث (في اللوحة اليسرى)
• Esc - مسح البحث وإعادة التركيز إلى جدول المشكلات
• r - إعادة تحميل النتائج من القرص
• [ / ] - تغيير حجم اللوحات اليسرى/اليمنى (ضبط موضع الانقسام)
• q - إنهاء التطبيق

الميزات التفاعلية

فرز الأعمدة

• انقر على أي رأس عمود للفرز حسب هذا العمود
• الفرز الافتراضي: حسب المستودع (تصاعدي)، ثم حسب المعرف (تصاعدي)

اللوحات القابلة لتغيير الحجم

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

---

📊 هيكل المخرجات

بعد تشغيل المسار، يتم تنظيم النتائج في output/results/<LANG>/<ISSUE_TYPE>/:

output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # بيانات مشكلة CodeQL الأصلية
├── 1_final.json    # محادثة LLM وتصنيفه
├── 2_raw.json
├── 2_final.json
└── ...

يحتوي كل ملف *_final.json على:

• محادثة LLM كاملة (أوامر النظام، رسائل المستخدم، ردود المساعد، استدعاءات الأدوات)
• رمز الحالة النهائي (1337 = ضعيف، 1007 = آمن، 7331/3713 = يحتاج إلى مزيد من المعلومات)