VulnReach

SCA المدرِك لوقت التشغيل — يُثبت أيّ ثغرات CVE يمكن الوصول إليها فعليًا، وليس فقط المثبّتة منها.

أصبح VulnReach الآن مشروع OWASP رسميًا. 🎉

عرض توضيحي

الخطوة 1 — يكشف SCA عن 74 ثغرة CVE عبر التبعيات

الخطوة 2 — يُثبت VulnReach أيّ منها يمكن الوصول إليه فعليًا

النتائج — سلسلة الأدلة لكل CVE

لوحة المعلومات — 42 ثغرة مؤكدة الوصول عبر 9 مستودعات

دعم اللغات: بايثون جاهزة تمامًا للإنتاج (طبقات taint وAST وroute وruntime). جافا وجافاسكريبت تملكان تحليل مخطط استدعاءات فعّالًا لكنهما تجريبيتان. Go وC# وPHP مدرجة على خارطة الطريق. راجع ROADMAP.md للتفاصيل.

يبني VulnReach على مخرجات SCA القياسية بإضافة سياق الوصولية — مُثبتًا عبر التحليل الساكن وتتبع التلوث والتغطية الحيّة لوقت التشغيل أيّ من ثغرات CVE المكتشفة يمكن الوصول إليها فعليًا في تطبيقك.

حالة المشروع

أحدث التطورات (المُنجزة)

• خط أنابيب تشغيل متوازٍ مدرِك للتبعيات لمسح أسرع
• وصولية بايثون — جاهزة للإنتاج (طبقات taint وAST وroute وruntime جميعها فعّالة)
• وصولية جافا — مخطط استدعاءات فعّال مع تحليل تبعيات Maven/Gradle (تجريبي)
• وصولية جافاسكريبت — مخطط استدعاءات فعّال مع كشف نقاط دخول المسارات (تجريبي)
• إلغاء المسح — POST /scan/{id}/cancel يوقف عمليات المسح الجارية
• عقد استجابة مسح مستقر: summary + فئات مصنّفة عبر GET /scan/{id}
• توحيد استجابة المسح بين واجهة API والوضع المحلي للحزمة (تكافؤ)
• حدود وقت تشغيل آمنة افتراضيًا:
  • يعمل compose الأساسي دون تركيب مقبس Docker
  • تتطلب عمليات المسح الديناميكي اشتراكًا صريحًا عبر VULNREACH_ALLOW_DOCKER_DAEMON=true
  • يستخدم ملف runtime وكيل docker-socket-proxy المقيد
• بوابات جودة حتمية لبيانات الاختبار الثابتة (fixtures) للغات Java/JavaScript/Go في CI
• قُبل كمشروع OWASP رسمي — owasp.community/projects/vulnreach
• نقطة نهاية «الخطوات التالية» بالذكاء الاصطناعي — تُنتج POST /findings/{id}/next-steps إرشادات معالجة موجّهة للمحلل (إجراءات فورية، فحوصات تحقق، مسارات ترقية، مراقبة) لنتيجة حتمية. كسول / عند الطلب: لا تستدعي عمليات المسح LLM أبدًا، وتُدار أعطال LLM بتدهور أنيق. الحكم الحتمي للقراءة فقط. راجع docs/api.md.

تجريبي

• وضع التتبع scan.runtime.ebpf (موجّه إلى Linux، اشتراك صريح)
• توليد OpenAPI بمساعدة الذكاء الاصطناعي وتدفقات DAST الذكية

انظر:

• docs/incubator-readiness.md
• docs/threat-model.md

كيف يعمل

تُصنَّف كل ثغرة CVE عبر سلسلة أدلة من خمس طبقات:

1. SCA (Trivy)              → is the package installed and vulnerable?
2. Taint analysis (tainter) → does user input flow to the vulnerable sink?
3. AST analysis             → is the vulnerable function in your call graph?
4. Route exposure           → is the call path reachable from an HTTP endpoint?
5. Runtime coverage         → was the vulnerable code actually executed?

والنتيجة قائمة نتائج مرتّبة حسب الأولوية ضمن أربع فئات:

بدء سريع

باستخدام Docker Compose (موصى به)

إشعار أمني — قبل البدء، انسخ .env.example إلى .env.local واستبدِل كل قيمة CHANGE_ME بسر عشوائي قوي.
لا تعرّض VulnReach على شبكة عامة دون تعيين بيانات اعتماد حقيقية وضبط CORS_ORIGINS.

git clone https://github.com/ihrishikesh0896/vulnreach.git
cd vulnreach

# 1. Create your local config
cp .env.example .env.local

# 2. Fill in every CHANGE_ME — generate secrets with: openssl rand -hex 32
$EDITOR .env.local

# 3. Start the stack
docker compose up --build

# Optional: enable dynamic runtime scans (Docker daemon access via restricted socket proxy)
# docker compose -f docker-compose.yml -f docker-compose.runtime.yml up --build

تشغيل مسح

خيارات المصادقة:

• JWT قصير الأمد: POST /login
• رمز API طويل الأمد (مفتاح API): أنشئه في الواجهة Settings -> API Keys، ثم استخدمه بصيغة Authorization: Bearer <API_KEY>

# Get a token (replace with the credentials you set in .env.local)
TOKEN=$(curl -s -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<your-admin-user>","password":"<your-admin-password>"}' | jq -r .access_token)

# Start scan from a GitHub repo
curl -X POST http://localhost:8000/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/yourorg/yourapp"}'

# Poll for results
curl http://localhost:8000/scan/<scan_id> \
  -H "Authorization: Bearer $TOKEN" | jq .summary

الميزات

• SCA مفلتر حسب الوصولية — يصنّف كل CVE وفق قوة الأدلة، وليس درجة CVSS فقط
• تأكيد وقت التشغيل — جمع تغطية الكود قائم على Docker عبر coverage.py
• تتبع التلوث — يتتبع مدخلات المستخدم → النقاط الحساسة القابلة للاستغلال (SQL، subprocess، YAML، pickle)
• DAST موجَّه بـ LLM — يولّد Claude/OpenAI/Ollama حمولات الاستغلال ويتحقق منها (اختياري)
• بوابات CI/CD — policy.block_if يُفشل البناءات عند وجود نتائج حرجة مؤكدة
• مصادقة JWT — متعددة المستخدمين، وصول قائم على الأدوار (admin / analyst)
• رموز API (مفاتيح API) — مصادقة آلية طويلة الأمد لـ curl/CI (Authorization: Bearer <API_KEY>)
• تصدير PDF — GET /scan/{id}/export/pdf
• لا ارتباط بمورّد — ميزات LLM مضبوطة افتراضيًا على provider: none؛ وOllama مدعوم للاستخدام دون اتصال

في الممارسة العملية

هدف المسح: multi-tier-dvpa — تطبيق Python/Django ضعيف عن قصد، يحتوي على 72 ثغرة CVE خام موزعة على 11 حزمة.

أُخرجت 46% من النتائج من قائمة «أصلِح كل شيء» غير المميَّزة إلى قائمة إجراءات مرتّبة حسب الأولوية. وفي خدمة الإنتاج النموذجية (حيث لا تُستدعى كثير من التبعيات غير المباشرة أبدًا)، ترتفع هذه النسبة إلى 70–90%.

المنهجية الكاملة وتفاصيل سلسلة الأدلة والتفصيل على مستوى الحزم: docs/benchmark.md

التوثيق

الاستخدام

• USAGE_PACKAGE.md — تثبيت الحزمة/CLI، التبعيات، بدء التشغيل، الاستخدام
• USAGE_UI.md — تثبيت الواجهة/الخادم، التبعيات، بدء التشغيل، الاستخدام

المشغّلون / الناشرون

• docs/deployment.md — إعداد Docker Compose، متغيرات البيئة، ملاحظات الإنتاج
• docs/configuration.md — مرجع إعدادات scan.yml الكامل
• docs/api.md — نقاط نهاية REST والمخططات

البنية / الأمان

• docs/architecture.md — تصميم خط الأنابيب ونموذج التنفيذ
• docs/threat-model.md — حدود الثقة، STRIDE، حالات إساءة الاستخدام
• docs/incubator-readiness.md — حالة الجاهزية لـ OSS/OWASP
• docs/DAST.md — مفاهيم DAST وتدفق العمل

المساهمون

• ROADMAP.md — الميزات المخطط لها، القيود المعروفة، حالة دعم اللغات
• docs/development.md — التفاصيل الداخلية، الوكلاء، التخزين، نقاط التوسعة
• OWASP.md — ملاحظات مشروع OWASP
• SECURITY.md — الإفصاح عن الثغرات وتدوير المفاتيح
• CONTRIBUTING.md — عملية المساهمة
• CHANGELOG.md — سجل الإصدارات

المتطلبات

• Python 3.11+
• PostgreSQL 13+
• Docker + Docker Compose v2 (للتحليل الديناميكي)
• trivy في PATH (التثبيت)
• jq (مستخدم في أمثلة البدء السريع — التثبيت)

اختياري (تُتخطى جميعها بأناقة عند غيابها):

• semgrep — pip install semgrep
• tainter — pip install tainter (تحليل تدفق التلوث؛ راجع دليل التطوير)

الترخيص

Apache 2.0 — راجع LICENSE.