vuln-scanner

منصة تقييم ثغرات آلية تنسّق 86 أداة أمنية مفتوحة المصدر، وتجمّع النتائج وتزيل تكرارها، وتشغّل طبقة تحليل LLM متوافقة مع OpenAI اختيارية للفرز والتجميع والمعالجة، وتولّد نصوص إثبات المفهوم، وتنتج تقارير احترافية بصيغ Markdown وHTML وJSON — كل ذلك من صورة Docker واحدة تعمل بنظام BlackArch Linux.

البنية
الأدوات
تقييد نوع الهدف
أوضاع الفحص
الفحص المصادق عليه
تحليل LLM
توليد وتنفيذ PoC
نظام الإضافات
صيغ التقارير
بدء سريع
scanner.sh — غلاف Docker
التهيئة
متغيرات البيئة
بنية المشروع
إضافة أداة جديدة
التطوير
التكامل مع DefectDojo

البنية```

config.toml / env vars / CLI args ↓ AppConfig (pydantic, 3-layer merge: TOML < env < CLI) ↓ Plugin loader — auto-discovers ./plugins/ + ~/.vuln-scanner/plugins/ ↓ ScanOrchestrator • classify_target() → TargetType • tool.applies_to(target) — skips mismatched pairs • asyncio + ThreadPoolExecutor — parallel (tool × target) tasks • AuthConfig forwarded to every applicable tool ↓ ScanResult[] → Assessment ↓ LLMAnalyzer (optional) • Pass 1: triage + PoC design (threaded, per result) • Pass 2: PoC generation (PocGenerator, host-safe) • Pass 3: mitigation (evidence-informed) • Pass 4: clustering + exec summary ↓ PocRunner (container-only, VS_IN_CONTAINER=1 guard) ↓ ┌────────┬────────┬────────┐ │ .md │ .html │ .json │ (all formats written in parallel) └────────┴────────┴────────┘ ↓ DefectDojo (optional)

جميع أدوات الفحص وتنفيذ PoC تعمل داخل حاوية Docker بنظام **BlackArch Linux** — لا يتم تثبيت أي شيء على المضيف.

---

## الأدوات

86 أداة مُنظَّمة حسب الفئة. كل أداة تُعلن عن أنواع الأهداف التي تدعمها؛ ويتجاوز المُنسِّق الاقترانات غير المتوافقة تلقائيًا.

### فحص الشبكة والمنافذ
| الأداة | ملاحظات |
|------|-------|
| `nmap` | فحص شامل للمنافذ مع كشف الخدمات والإصدارات |
| `rustscan` | ماسح منافذ سريع، يغذّي nmap بالنتائج |
| `masscan` | ماسح TCP/UDP فائق السرعة |
| `naabu` | ماسح منافذ مع كشف الخدمات |
| `netdiscover` | اكتشاف المضيفين عبر ARP |

### تطبيقات الويب
| الأداة | ملاحظات |
|------|-------|
| `nuclei` | ماسح ثغرات قائم على القوالب |
| `nikto` | ماسح سوء إعداد خوادم الويب |
| `wapiti` | ماسح ثغرات ويب من نوع الصندوق الأسود |
| `ffuf` | أداة تخمين ويب سريعة (المجلدات، الباراميترات، الترويسات) |
| `feroxbuster` | اكتشاف المحتوى مع التكرار العودي |
| `gobuster` | أداة تخمين URI/DNS/vhost بالقوة الغاشمة |
| `wfuzz` | أداة تخمين لتطبيقات الويب |
| `dalfox` | ماسح XSS مع تحليل الباراميترات |
| `xsstrike` | محرك متقدم لكشف XSS |
| `commix` | أداة استغلال حقن الأوامر |
| `sqlmap` | أتمتة حقن SQL والاستيلاء على قواعد البيانات |
| `nosqlmap` | ماسح حقن NoSQL |
| `httpx` | استكشاف HTTP وبصمات الخوادم |
| `whatweb` | أداة بصمات تقنيات الويب |
| `wafw00f` | كشف جدران الحماية WAF وبصماتها |
| `wpscan` | ماسح ثغرات ووردبريس |
| `acunetix` | ماسح ثغرات ويب (قائم على API) |
| `arachni` | ماسح أمان لتطبيقات الويب |
| `zap` | ماسح OWASP ZAP للاختبار الديناميكي DAST |
| `wapiti` | ماسح ثغرات من نوع الصندوق الأسود |
| `drheader` | محلل ترويسات أمان HTTP |
| `humble` | فاحص أمان ترويسات HTTP |
| `hakrawler` | زاحف ويب سريع للروابط والنقاط الطرفية |
| `katana` | إطار زحف ويب من الجيل التالي |
| `gau` | جامع روابط معروفة (AlienVault, WaybackMachine) |
| `jsluice` | مستخرج أسرار JavaScript والروابط |
| `corscanner` | ماسح سوء إعداد CORS |
| `crlfuzz` | ماسح حقن CRLF |
| `smuggler` | كاشف تهريب طلبات HTTP |
| `linkfinder` | اكتشاف النقاط الطرفية في مصدر JavaScript/HTML |
| `cariddi` | زاحف ويب مع كشف الأسرار والنقاط الطرفية |

### API وGraphQL
| الأداة | ملاحظات |
|------|-------|
| `kiterunner` | اكتشاف مسارات API باستخدام ملفات kite |
| `graphql_cop` | مدقق أمان GraphQL |
| `restler` | أداة تخمين REST API مع الحفاظ على الحالة |
| `apifuzzer` | أداة تخمين قائمة على OpenAPI/Swagger |
| `cherrybomb` | مدقق أمان لمواصفات OpenAPI |
| `arjun` | اكتشاف باراميترات HTTP |
| `paramspider` | استخراج الباراميترات من wayback والمصادر |

### DNS والاستطلاع
| الأداة | ملاحظات |
|------|-------|
| `amass` | تعداد النطاقات الفرعية (سلبي + نشط) |
| `subfinder` | تعداد نطاقات فرعية سلبي سريع |
| `dnsx` | مجموعة أدوات حل DNS والاستكشاف |
| `dnsrecon` | تعداد DNS ونقل المناطق |
| `fierce` | استطلاع DNS واكتشاف المضيفين |
| `theharvester` | OSINT: رسائل بريد إلكتروني، أسماء، مضيفين، نطاقات فرعية |
| `puredns` | أداة تخمين نطاقات فرعية سريعة مع تصفية أحرف البدل |
| `alterx` | محرك تبديل النطاقات الفرعية |
| `waybackurls` | جمع روابط تاريخية من Wayback Machine |
| `httprobe` | فاحص مضيفات HTTP/HTTPS النشطة |

### TLS / SSL
| الأداة | ملاحظات |
|------|-------|
| `testssl` | تدقيق إعدادات TLS وحزم التشفير |
| `sslyze` | ماسح TLS (حزم التشفير، Heartbleed، ROBOT) |
| `sslscan` | ماسح خدمات SSL/TLS |
| `tlsx` | استكشاف TLS سريع |
| `tls_attacker` | أداة هجمات بروتوكول TLS |
| `ssh_audit` | مدقق إعدادات SSH والخوارزميات |

### SMB وخدمات الشبكة
| الأداة | ملاحظات |
|------|-------|
| `smbmap` | تعداد مشاركات SMB والصلاحيات |
| `enum4linux` | تعداد SMB/NetBIOS |
| `crackmapexec` | تقييم Active Directory وSMB |
| `openvas` | ماسح ثغرات OpenVAS |

### SAST وتحليل الكود
| الأداة | ملاحظات |
|------|-------|
| `bandit` | SAST للبايثون — الأنماط الأمنية المضادة الشائعة |
| `semgrep` | SAST متعدد اللغات مع قواعد المجتمع |
| `gosec` | فاحص أمان Go |
| `bearer` | SAST بتدفق البيانات مع قواعد الخصوصية والأمان |
| `horusec` | محرك SAST متعدد اللغات |
| `brakeman` | ماسح SAST لـ Ruby on Rails |
| `flawfinder` | تحليل ثابت لـ C/C++ للعيوب الشائعة |
| `dependency_check` | ماسح ثغرات التبعيات OWASP |
| `pip_audit` | فاحص ثغرات حزم البايثون |

### تحليل تركيب البرمجيات (SCA)
| الأداة | ملاحظات |
|------|-------|
| `osv-scanner` | ماسح قاعدة بيانات الثغرات مفتوحة المصدر |
| `npm-audit` | تدقيق ثغرات حزم Node.js |
| `govulncheck` | فاحص ثغرات وحدات Go |

### كشف الأسرار
| الأداة | ملاحظات |
|------|-------|
| `gitleaks` | ماسح أسرار سجل Git |
| `trufflehog` | باحث أسرار عميق قائم على الإنتروبيا |
| `secretfinder` | الأسرار في ملفات JS والنقاط الطرفية |
| `detect-secrets` | ماسح أسرار قائم على خط الأساس |
| `noseyparker` | ماسح أسرار عالي السرعة مع قواعد أنماط |

### البنية التحتية ككود (IaC) والإعدادات
| الأداة | ملاحظات |
|------|-------|
| `checkov` | ماسح IaC لـ Terraform/K8s/Dockerfile |
| `tfsec` | تحليل ثابت لـ Terraform |
| `terrascan` | ماسح أمان IaC متعدد السحابات |
| `hadolint` | مدقق أفضل الممارسات لـ Dockerfile |

### البنية التحتية السحابية
| الأداة | ملاحظات |
|------|-------|
| `prowler` | تقييم الوضع الأمني لـ AWS/GCP/Azure |
| `kube-bench` | فاحص معيار CIS Kubernetes |

### الحاويات وسلسلة التوريد
| الأداة | ملاحظات |
|------|-------|
| `trivy` | ماسح ثغرات صور الحاويات وأنظمة الملفات |
| `grype` | مطابقة ثغرات الحاويات والحزم |

---

## تصفية نوع الهدف

يقوم المُنسِّق بتصنيف كل هدف إلى نوع واحد أو أكثر ولا يشغّل إلا الأدوات التي تُعلن دعمها لذلك النوع. هذا يلغي الضوضاء الناتجة عن مثلاً أدوات SMB عند تشغيلها ضد روابط ويب.

| النوع | مثال | الأدوات المتوافقة |
|------|---------|-----------------|
| `HOST` | `example.com` | أدوات DNS، SSL، الويب، SMB |
| `IP` | `10.0.0.1` | أدوات الشبكة، المنافذ، SMB |
| `CIDR` | `10.0.0.0/24` | أدوات فحص الشبكة |
| `URL` | `https://app.example.com` | أدوات الويب، API، SSL |
| `PATH` | `/src/myapp` | أدوات SAST، SCA، الأسرار، IaC |
| `REPO` | `https://github.com/org/repo` | أدوات الأسرار، SAST، SCA |
| `IMAGE` | `myapp:latest` | ماسحات الحاويات |
| `CLOUD` | `aws:profile=prod`, `arn:aws:…` | أدوات الوضع السحابي (prowler, kube-bench, terrascan) |

التصنيف تلقائي — فقط مرّر نص الهدف؛ والماسح يحدد النوع بنفسه.

صيغ الأهداف السحابية المدعومة:
- AWS ARN: `arn:aws:iam::123456789012:root`
- صيغة ملف التعريف المسمى: `aws:profile=production`
- مشروع GCP: `projects/my-project-id`
- معرّف اشتراك Azure UUID: `00000000-0000-0000-0000-000000000000`

---

## أوضاع الفحص

| الوضع | الوصف |
|------|-------------|
| `paranoid` | أقصى تكتّم — استكشاف سلبي، بصمة دنيا |
| `passive` | لا هجمات نشطة — تعداد وجمع اللافتات فقط **(الافتراضي)** |
| `active` | تفعيل فحوصات الثغرات القياسية |
| `aggressive` | فحص شامل: كل القوالب، التخمين القسري، توقيت سريع |

---

## الفحص المُصادَق

تُمرَّر بيانات الاعتماد إلى جميع أدوات الويب المنطبقة (nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx).

### بيانات الاعتماد العامة

تُطبَّق على كل هدف ما لم توجد قيمة تجاوز لكل هدف على حدة.

**عبر الإعدادات:**```toml
[scan.auth]
bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
username     = "admin"
password     = "secret"

[scan.auth.cookies]
session = "abc123"

[scan.auth.headers]
X-API-Key = "my-api-key"

عبر متغيرات البيئة (عام فقط):```bash VS_AUTH_BEARER_TOKEN=eyJ... VS_AUTH_USERNAME=admin VS_AUTH_PASSWORD=secret

**عبر CLI** (عام فقط):```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

بيانات الاعتماد لكل هدف

عند فحص أهداف متعددة تتطلب بيانات اعتماد مختلفة، حدد تجاوزات لكل هدف تحت [scan.auth.targets."<target>"]. أي إدخال مطابق يستبدل الإعداد العام لهذا الهدف بالكامل — لا يوجد دمج. مصادقة كل هدف تكون عبر ملف الإعداد فقط (متغيرات البيئة وخيارات سطر الأوامر تحدد الإعداد الافتراضي العام فقط).```toml [scan.auth]

Global fallback — used for any target without a specific entry

bearer_token = "default-token"

JWT for the main app

[scan.auth.targets."https://app.example.com"] bearer_token = "app-specific-jwt"

[scan.auth.targets."https://admin.example.com"] [scan.auth.targets."https://admin.example.com".cookies] session = "s%3Aabc123" csrftoken = "xyz789"

HTTP Basic for an internal API

[scan.auth.targets."10.0.0.50"] username = "apiuser" password = "s3cret"

[scan.auth.targets."https://legacy.example.com"] login_url = "https://legacy.example.com/login" username = "admin" password = "password123" [scan.auth.targets."https://legacy.example.com".login_data] _token = "csrf-value-here"

**الحسم:** `per-target config > global config`

---

## تحليل LLM

عندما يكون مفتاح API موجودًا، يتم تنشيط طبقة LLM تلقائيًا. وتقوم بأربع مراحل على نتائج الفحص:

| المرحلة | الاسم | الوظيفة |
|------|------|-------------|
| 1 | **الفرز** | يحدد CWE ومستوى الثقة وعلامة الإيجابية الكاذبة وملخص قابلية الاستغلال، ويصمم PoC لكل اكتشاف |
| 2 | **توليد PoC** | يكتب نصوص Python/Bash مكتفية بذاتها تؤكد الاكتشاف باستخدام أدوات موجودة بالفعل في الحاوية |
| 3 | **التخفيف** | ينتج تخفيفات ملموسة قصيرة المدى وإصلاحات دائمة، تستند اختياريًا إلى أدلة PoC |
| 4 | **التجميع** | يجمع الاكتشافات حسب السبب الجذري، ويكتب إصلاحات مشتركة، وينتج ملخصًا تنفيذيًا |

### إعداد المزوّد

عميل LLM متوافق مع OpenAI-API — يعمل مع OpenAI وAzure OpenAI وOllama وvLLM وLM Studio وOpenRouter وأي نقطة نهاية متوافقة أخرى.```toml
[llm]
enabled   = "auto"          # "auto" | true | false  (auto = on when api_key present)
api_key   = ""              # or set OPENAI_API_KEY env var
base_url  = ""              # leave empty for OpenAI; set for Ollama/vLLM/etc.
model     = "gpt-4o"        # REQUIRED when LLM is active — no default

# Sampling parameters (all OpenAI-compatible)
temperature = 0.2
top_p       = 0.95
max_tokens  = 4096
# top_k and other non-standard params go in extra_body:
# [llm.extra_body]
# top_k = 40

مثال Ollama:```toml [llm] base_url = "http://localhost:11434/v1" api_key = "ollama" model = "llama3.2"

**مثال vLLM:**```toml
[llm]
base_url = "http://localhost:8000/v1"
api_key  = "token-abc123"
model    = "meta-llama/Meta-Llama-3-8B-Instruct"

مصفوفة الميزات

كل قدرة من قدرات LLM هي ميزة مسماة، يمكن تفعيلها أو تعطيلها عالمياً وتجاوزها لكل أداة أو لكل فئة.

الإعداد العام للميزات:```toml [llm.features] generate_poc = true execute_poc = false # enable only inside Docker

Per-tool override — disable PoC for bandit (SAST, no runtime target)

[llm.features.tool.bandit] generate_poc = false

Per-category override — disable log analysis for noisy crawlers

[llm.features.category.web] logs_analysis = false

**أولوية الميزات:** `tool override > category override > global`

### المطالبات المخصصة

جميع مطالبات LLM قابلة للتجاوز:```toml
[llm.prompts]
enrich_system    = "You are a senior penetration tester..."
mitigation_user  = "Write remediation steps for: {title}..."
# Available placeholders: {title} {severity} {description} {cwe}
#   {exploitability} {tool} {target} {cves} {raw_output}

مرشحات النطاق```toml

[llm] include_tools = [] # empty = all tools exclude_tools = ["hakrawler", "gau"] include_categories = [] exclude_categories = ["dns"]

---

## توليد وتنفيذ PoC

### التوليد (دائمًا آمن على المضيف)

يكتب نموذج LLM نصوصًا برمجية مكتفية بذاتها بلغة Python و/أو Bash لكل اكتشاف. تستخدم النصوص البرمجية أدوات موجودة مسبقًا في صورة BlackArch (`curl`, `sqlmap`, `nuclei`, `dalfox`, إلخ) وتُكتب إلى `<report>_assets/poc/`. لا يقوم التوليد بتنفيذ الكود أبدًا — بل يكتب الملفات فقط.```toml
[llm.poc]
languages        = ["python", "bash"]
only_severities  = ["critical", "high", "medium"]
max_pocs         = 20
allow_git_clone  = false   # permit cloning official exploit PoCs from GitHub

التنفيذ (داخل الحاوية فقط)

تنفيذ PoC مشروط بحارسين مستقلين:

execute_poc = true في [llm.features]
متغير البيئة VS_IN_CONTAINER=1 (مضمّن في صورة Docker)

يرفض المشغّل بصمت إذا كان أي من الحارسين مفقودًا، لذا لا يمكنه التنفيذ على المضيف. ترفض قائمة حظر ثابتة النصوص البرمجية التي تحتوي على أنماط مدمرة (rm -rf /، mkfs.، قنابل الشوكة، إلخ) قبل التنفيذ.```bash

Enable PoC execution inside the container

VS_LLM_FEATURE_EXECUTE_POC=true docker compose ... run --rm scanner ...

---

## نظام الإضافات

ضع ملف `.py` يعرّف صنفاً واحداً أو أكثر من `AbstractTool` داخل `./plugins/` (أو `~/.vuln-scanner/plugins/`) وسيتم اكتشافها تلقائياً عند الإقلاع — دون الحاجة إلى أي تغييرات في الكود.

**ترتيب الاكتشاف** (الإدخالات اللاحقة تلغي السابقة عند تعارض الأسماء):
1. `./plugins/` (بالنسبة إلى مسار العمل الحالي CWD)
2. `~/.vuln-scanner/plugins/`
3. مجلدات إضافية يُعدّها عبر `[plugins] dirs` أو `--plugin-dir`

**مثال إضافة** (`plugins/my_scanner.py`):```python
from vuln_scanner.tools.abstract import AbstractTool
from vuln_scanner.tools.enums import Severity, ScanStatus, TargetType
from vuln_scanner.tools.models import Finding, ScanInput, ScanResult

class MyScannerTool(AbstractTool):
    name: str = "my-scanner"
    category: str = "web"
    # Only runs against URL targets — skipped automatically for IPs, paths, etc.
    applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL})

    def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
        return ["my-scanner", "--target", target, "--json"]

    def parse_output(self, raw: str, target: str) -> list[Finding]:
        ...

الإعدادات:```toml [plugins] enabled = true dirs = ["/opt/company-scanners"]

**CLI:**```bash
vuln-scanner --plugin-dir /opt/company-scanners --targets https://app.example.com

سلوك كل هدف

أدوات الإضافات (Plugins) تُسجَّل عالميًا، لكن التحكم في الأنواع من قِبل المُنسِّق (orchestrator) يحدد أي الأهداف تشغَّل عليها كل إضافة فعليًا. الإضافة التي تُصرِّح بـ applicable_targets = frozenset({TargetType.URL}) لن تعمل أبدًا ضد عنوان IP أو مسار نظام ملفات.

لتقييد إضافةٍ ما بسلاسل أهداف محددة تتجاوز التحكم في الأنواع (مثل: التشغيل فقط ضد مضيف مرحلة معروف)، أرجِع ScanStatus.SKIPPED داخل run():```python def run(self, target: str, scan_input: ScanInput) -> ScanResult: if "staging" not in target: return ScanResult(tool=self.name, target=target, status=ScanStatus.SKIPPED) return super().run(target, scan_input)

لا يوجد عامل تصفية للمكونات الإضافية على مستوى الإعدادات لكل هدف — هذا المنطق يقع على عاتق المكوّن الإضافي نفسه.

---

## تنسيقات التقارير

يتم إنشاء ثلاثة تنسيقات بالتوازي. اختر أي مجموعة:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

أو عبر سطر الأوامر: --formats markdown html json

Markdown (`.md`)

تقرير احترافي منظم يتبع اصطلاحات اختبار الاختراق الصناعية:

الملخص التنفيذي — نص موجّه للإدارة
النطاق والمنهجية — قائمة الأهداف، الأدوات المستخدمة، إعدادات الفحص
دليل تصنيف الخطورة — نطاقات CVSS
نظرة عامة على النتائج — مصفوفة توزيع المخاطر + تفصيل حسب الهدف
مجموعات الثغرات — تجميعات السبب الجذري (مولّدة بواسطة LLM)
النتائج التفصيلية — لكل نتيجة: المعرّف، الخطورة، النظام المتأثر، الوصف، الأثر التجاري، ملاحظة المحلل، التخفيف، المعالجة الدائمة، مراجع PoC
الملحق أ — أخطاء الفحص
الملحق ب — فهرس أصول إثبات المفهوم (PoC)

يتم دمج النتائج من أدوات متعددة تُبلغ عن نفس المشكلة على نفس الهدف في إدخال واحد يعرض جميع الأدوات المساهمة.

HTML (`.html`)

تقرير أحادي الملف قائم بذاته (بدون تبعيات خارجية) مع:

مبدّل السمة الفاتحة/الداكنة
بطاقات نتائج مرمّزة بالألوان حسب الخطورة
أقسام مجموعات قابلة للطي
شبكة إحصائيات وقسم بارز للملخص التنفيذي

JSON (`.json`)

تفريغ هيكلي كامل لنموذج Assessment — النتائج، الإثراء عبر LLM، المجموعات، الإحصاءات، سجلات PoC. مناسب للتغذية في خطوط CI/CD وللأدوات النهائية.

بدء سريع

يقوم سكربت poc.sh بتشغيل DefectDojo وثلاثة أهداف ضعيفة والماسح الضوئي في أمر واحد.

المتطلبات الأساسية: docker، إضافة docker compose، curl، `python3````bash ./poc.sh

| الخطوة | الإجراء |
|------|--------|
| 1 | التحقق من المتطلبات الأساسية |
| 2 | تحميل `.env` (ينسخ من `.env.example` إذا كان مفقودًا) |
| 3 | بدء مجموعة DefectDojo |
| 4 | الانتظار حتى تصبح DefectDojo API جاهزة |
| 5 | الحصول على رمز API عبر بيانات اعتماد المسؤول |
| 6 | بدء حاويات الأهداف الضعيفة |
| 7 | الانتظار حتى يمكن الوصول إلى كل هدف |
| 8 | بناء صورة Docker الخاصة بالماسح الضوئي |
| 9 | تشغيل الماسح الضوئي، إنشاء التقارير، وإرسالها إلى DefectDojo |
| 10 | طباعة ملخص مع عناوين URL وتعليمات التفكيك |

**مع تحليل LLM:**```bash
# Copy the example env and add your key
cp .env.example .env
# Edit .env: set OPENAI_API_KEY and VS_LLM_MODEL
./poc.sh

تجاوز وضع الفحص:```bash SCAN_MODE=active ./poc.sh

**التفكيك:**```bash
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

الأهداف الضعيفة

محلي (Docker — يتم تشغيله بواسطة `poc.sh`)

التطبيق	الرابط	الوصف
OWASP Juice Shop	http://localhost:3000	تطبيق Node.js حديث يغطي OWASP Top 10

المختبر البعيد — pentest-ground.com

أنظمة متاحة للعموم وذات ثغرات مقصودة، تتم صيانتها بواسطة pentest-ground.com. لا حاجة إلى أي إعداد — افحص مباشرةً للتحقق من الأدوات وتوليد PoC.

---

## scanner.sh — غلاف Docker

`scanner.sh` هو الواجهة اليومية الموصى بها لتشغيل الماسح الضوئي. وهو يغلّف `docker compose run` بحيث لا تحتاج أبدًا إلى كتابة استدعاء compose يدويًا — فقط مرّر الأهداف والخيارات مباشرة.```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

Options

كل ما بعد -- يُمرَّر حرفيًا إلى نقطة دخول الماسح الضوئي، متجاوزًا جميع منطق الغلاف.```bash

Scan using ./config.toml (targets and mode come from the config)

./scanner.sh

Quick scan with explicit targets and mode

./scanner.sh -t https://app.example.com 192.168.1.0/24 -m active

Use a custom config file

./scanner.sh -c /path/to/prod.toml

Enable LLM enrichment with a specific model

./scanner.sh -t https://app.example.com --llm-model gpt-4o

Run only specific tools

./scanner.sh -t https://app.example.com --include-tools nuclei,dalfox,ffuf

Rebuild the image first, then scan

./scanner.sh --build -t https://app.example.com -m active

Full manual passthrough to the scanner entrypoint

./scanner.sh -- --targets https://t.example.com --mode aggressive --formats markdown html json

Open an interactive shell (all tools, volumes, and env available)

./scanner.sh --shell ./scanner.sh --build --shell

### ما يفعله تلقائيًا

- يحمّل `.env` (ينسخ من `.env.example` إذا كان مفقودًا)
- ينسخ `config.example.toml` → `config.toml` إذا لم يوجد ملف إعدادات
- ينشئ شبكة Docker `vuln_scanner_network` إذا لم تكن موجودة
- يثبّت ملف `--config` مخصصًا داخل الحاوية في `/app/config.toml`
- يعيد بناء الصورة عند تمرير `--build`

---

## الإعدادات

انسخ القالب المشروح:```bash
cp config.example.toml config.toml

المرجع الكامل:```toml [scan] targets = ["192.168.1.1", "https://app.example.com", "/src/myapp"] mode = "passive" # paranoid | passive | active | aggressive timeout = 300 # per-tool timeout in seconds rate_limit = null # requests/sec; null = no limit

Authenticated scanning — forwarded to all applicable web tools

[scan.auth] bearer_token = "" # Authorization: Bearer username = "" # HTTP Basic username password = "" # HTTP Basic password login_url = "" # Form-based login URL

[scan.auth.cookies]

session = "abc123"

[scan.auth.headers]

X-API-Key = "secret"

[tools] exclude = ["nikto"] # skip specific tools by name

[categories] include = ["web", "ssl"] # limit to these categories; empty = all

[plugins] enabled = true

dirs = ["/opt/company-scanners"]

[report] formats = ["markdown", "html", "json"] output_dir = "./reports"

[defectdojo] url = "http://localhost:8080" api_key = "" product_name = "My Product" engagement_name = "Automated Scan"

── LLM Analysis ─────────────────────────────────────────────────────────────

[llm] enabled = "auto" # "auto" | true | false api_key = "" # or OPENAI_API_KEY env var base_url = "" # leave empty for OpenAI model = "" # required when active, e.g. "gpt-4o" or "llama3.2" temperature = 0.2 top_p = 0.95 max_tokens = 4096

extra_body = { top_k = 40 } # for Ollama/vLLM top_k support

exclude_tools = [] exclude_categories = []

[llm.features] logs_analysis = true enrich = true classify = true cluster = true mitigation = true generate_poc = true execute_poc = false # container-only; set VS_LLM_FEATURE_EXECUTE_POC=true false_positive_filter = true

Per-tool feature overrides (tool > category > global precedence)

[llm.features.tool.bandit] generate_poc = false

[llm.features.category.dns] logs_analysis = false

[llm.poc] languages = ["python", "bash"] only_severities = ["critical", "high", "medium"] max_pocs = 20 allow_git_clone = false

**أولوية دمج الإعدادات:** `CLI > env vars > config.toml > defaults`

---

## متغيرات البيئة

### الأساسية

| المتغير | علامة CLI | الوصف |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | قائمة الأهداف مفصولة بمسافات |
| `VS_MODE` | `--mode` | وضع الفحص |
| `VS_TIMEOUT` | `--timeout` | مهلة كل أداة (بالثواني) |
| `VS_RATE_LIMIT` | `--rate-limit` | حد المعدل (طلب/ثانية) |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | فتحات الأدوات المتوازية |
| `VS_INCLUDE_TOOLS` | `--include-tools` | قائمة أدوات مسموح بها بالاسم |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | قائمة أدوات ممنوعة بالاسم |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | قائمة فئات مسموح بها |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | قائمة فئات ممنوعة |
| `VS_OUTPUT_DIR` | `--output-dir` | دليل إخراج التقارير |

### التقارير

| المتغير | علامة CLI | الوصف |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | صيغ التقارير: `markdown html json` |

### LLM

| المتغير | علامة CLI | الوصف |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | مفتاح API (متغير بيئة قياسي، يُستخدم كاحتياطي) |
| `OPENAI_BASE_URL` | — | عنوان URL أساسي احتياطي (لنقاط نهاية غير OpenAI) |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | اسم النموذج (مطلوب عند التفعيل) |
| `VS_LLM_TEMPERATURE` | — | درجة حرارة أخذ العينات |
| `VS_LLM_MAX_TOKENS` | — | الحد الأقصى لرموز الإخراج |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | مفتاح تبديل عام للميزة، مثال: `VS_LLM_FEATURE_GENERATE_POC=false` |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | تفعيل تنفيذ PoC (للحاويات فقط) |

### الفحص المُصادَق

| المتغير | علامة CLI | الوصف |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | رمز Bearer (`Authorization: Bearer …`) |
| `VS_AUTH_USERNAME` | `--auth-user` | اسم مستخدم HTTP Basic |
| `VS_AUTH_PASSWORD` | `--auth-pass` | كلمة مرور HTTP Basic |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | رابط تسجيل الدخول المستند إلى نموذج |

يجب تعيين ملفات تعريف الارتباط والترويسات الإضافية عبر ملف الإعدادات أو علامات CLI `--auth-cookie` / `--auth-header`.

### الإضافات

| المتغير | علامة CLI | الوصف |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | تفعيل/تعطيل الاكتشاف التلقائي للإضافات |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | أدلة إضافية للإضافات (مفصولة بمسافات) |

### DefectDojo

| المتغير | علامة CLI | الوصف |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | عنوان URL الأساسي لـ DefectDojo |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | رمز API |
| `VS_DEFECTDOJO_PRODUCT` | — | اسم المنتج |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | اسم المشاركة |

---

## هيكل المشروع```
vuln_scanner/
├── config/
│   ├── models.py        # AppConfig, AppLLMConfig, PluginsConfig (pydantic)
│   └── loader.py        # 3-layer merge: TOML + env (VS_*) + CLI
│
├── tools/
│   ├── enums.py         # Severity, Confidence, ScanStatus, ScanMode, TargetType
│   ├── models.py        # Finding, ScanInput, ScanResult, AuthConfig (pydantic)
│   ├── target.py        # classify_target() — maps target string to TargetType set
│   ├── abstract.py      # AbstractTool ABC + subprocess execution helpers
│   ├── __init__.py      # TOOL_REGISTRY (86 tools)
│   └── <tool>.py        # One file per tool (86 total)
│
├── llm/
│   ├── models.py        # LLMConfig, LLMFeatures, PocConfig (pydantic)
│   ├── features.py      # resolve_features() — tool > category > global merge
│   ├── client.py        # LLMClient — thin openai SDK wrapper
│   ├── analyzer.py      # LLMAnalyzer — 4-pass analysis pipeline
│   └── prompts.py       # Default prompt templates (all overridable)
│
├── poc/
│   ├── models.py        # Poc, PocVerdict
│   ├── generator.py     # PocGenerator — writes scripts, never executes (host-safe)
│   └── runner.py        # PocRunner — executes scripts (VS_IN_CONTAINER guard)
│
├── reports/
│   ├── base.py          # AbstractReporter
│   ├── markdown.py      # Professional structured Markdown report
│   ├── html.py          # Self-contained HTML with light/dark theme
│   └── json_reporter.py # Full Assessment JSON dump
│
├── defectdojo/
│   └── client.py        # DefectDojoClient — push findings via REST API
│
├── plugins.py           # Plugin auto-discovery (./plugins/, ~/.vuln-scanner/plugins/)
├── model.py             # Assessment, Cluster, AssessmentStats
└── orchestrator.py      # ScanOrchestrator — type-gated, async concurrent execution

plugins/                 # Drop .py plugin files here (auto-discovered at startup)
main.py                  # Entry point
config.example.toml      # Fully documented configuration template
.env.example             # Environment variable reference
Dockerfile               # BlackArch-based image; bakes VS_IN_CONTAINER=1
docker-compose.yaml                # DefectDojo stack
docker-compose.scanner.yaml        # Scanner service
docker-compose.target.yaml        # Vulnerable test targets (Juice Shop, WebGoat)
scanner.sh                        # Convenience wrapper — runs the scanner via docker compose
poc.sh                            # End-to-end quick-start script (DefectDojo + targets + scanner)

إضافة أداة جديدة

بالنسبة للأدوات لمرة واحدة أو الأدوات الخاصة، استخدم نظام الإضافات — ضع ملف .py في ./plugins/ دون أي تغييرات على الكود. بالنسبة للأدوات التي يجب تضمينها مع المشروع:

أنشئ vuln_scanner/tools/mytool.py:```python from vuln_scanner.tools.abstract import AbstractTool from vuln_scanner.tools.enums import Severity, TargetType from vuln_scanner.tools.models import Finding, ScanInput

class MyTool(AbstractTool): name: str = "mytool" category: str = "web" # Declare which target types this tool supports. # The orchestrator skips mismatched (tool, target) pairs automatically. applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL, TargetType.HOST})

def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
    return ["mytool", "--target", target]

def parse_output(self, raw: str, target: str) -> list[Finding]:
    findings = []
    for line in raw.splitlines():
        if "VULN" in line:
            findings.append(Finding(
                title="Example finding",
                severity=Severity.HIGH,
                description=line,
                tool=self.name,
                target=target,
            ))
    return findings

2. سجّله في `vuln_scanner/tools/__init__.py`:```python
from vuln_scanner.tools.mytool import MyTool

TOOL_REGISTRY: dict[str, type[AbstractTool]] = {
    ...
    "mytool": MyTool,
}

أضف الملف الثنائي إلى Dockerfile:```dockerfile RUN pacman -Sy --noconfirm mytool

**نصائح:**
- بالنسبة للأدوات التي تكتب إلى ملف بدلاً من stdout، استخدم `OUTPUT_FILE_SENTINEL` في `build_command()` وتجاوز `run()` لاستدعاء `self._run_with_tempfile()`.
- الأدوات ذات `applicable_targets = frozenset(TargetType)` (الافتراضي) تعمل على جميع أنواع الأهداف — استخدم هذا فقط للأدوات الشاملة حقًا.
- عدم العثور على الملف الثنائي → `ScanStatus.SKIPPED` (لا يظهر في التقرير). خطأ في الأداة → `ScanStatus.FAILED` (يظهر في الملحق أ).

---

## التطوير```bash
# Install with dev dependencies
uv sync

# Run tests (host-safe only — no real tool execution)
uv run pytest tests/ -v

# Lint
uv run ruff check .
uv run ruff format .

فئات الاختبار:

tests/test_config.py — دمج الإعدادات والتحقق منها
tests/test_target_typing.py — classify_target() و applies_to()
tests/test_orchestrator_gating.py — التحكم حسب النوع باستخدام أدوات وهمية
tests/test_llm.py — ميزات LLM، عميل مُحاكى، حارس حاوية مشغّل PoC
tests/test_reports.py — أدوات إعداد التقارير الثلاث (Markdown وHTML وJSON)
tests/test_nmap.py — محلل مخرجات nmap

قاعدة الأمان: لا تقم أبدًا بتشغيل أدوات الفحص الحقيقية على المضيف. جميع عمليات تنفيذ الأدوات تتم داخل حاوية Docker ضد حاويات الأهداف المعزولة. يفرض PocRunner ذلك — فهو يتحقق من VS_IN_CONTAINER=1 قبل تنفيذ أي سكربت PoC، وتتضمّن صورة Docker هذا المتغير داخليًا.

تكامل DefectDojo

يتم دفع النتائج تلقائيًا عند تكوين api_key و product_name.

الحصول على مفتاح API الخاص بك:

افتح DefectDojo على http://localhost:8080
سجّل الدخول (الافتراضي: admin / admin)
انتقل إلى Profile → API v2 Key

الدفع اليدوي:```bash VS_DEFECTDOJO_API_KEY=your-key
VS_DEFECTDOJO_PRODUCT="My App"
uv run vuln-scanner --targets 192.168.1.1

`logs_analysis`	on	إدخال المخرجات الخام للأداة إلى LLM
`enrich`	on	فرز CWE / مستوى الثقة / الإيجابيات الكاذبة / قابلية الاستغلال
`classify`	on	تصنيف نوع النتيجة ومستوى المخاطر
`cluster`	on	تجميع النتائج حسب السبب الجذري
`mitigation`	on	توليد إجراءات التخفيف والمعالجة
`generate_poc`	on	كتابة سكربتات PoC كأصول للتقرير
`execute_poc`	off	تشغيل PoCs داخل الحاوية (يتطلب `VS_IN_CONTAINER=1`)
`false_positive_filter`	on	استبعاد الإيجابيات الكاذبة المحتملة من التقرير

DVWA	`https://pentest-ground.com:4280`	تطبيق ويب كلاسيكي	CSRF, XSS, SQLi
DVGQL	`https://pentest-ground.com:5013`	GraphQL API	CMDi, XSS, SQLi
RestFlaw	`https://pentest-ground.com:9000`	REST API	SQLi, حقن الكود, XXE
GuardianLeaks	`https://pentest-ground.com:81`	تطبيق ويب	XSS, SSRF, حقن الكود
vuln-scanner --targets \
https://pentest-ground.com:4280 \
https://pentest-ground.com:5013 \
https://pentest-ground.com:9000 \
https://pentest-ground.com:81 \
--mode active

`-t`, `--targets HOST...`	هدف أو أكثر للمسح (URL، IP، CIDR، مسار، صورة)
`-m`, `--mode MODE`	وضع المسح: `passive` \| `active` \| `aggressive` \| `paranoid`
`-c`, `--config FILE`	ملف الإعدادات للتركيب (الافتراضي: `./config.toml`)
`-f`, `--formats FMT`	صيغ التقرير، مفصولة بفواصل: `markdown,html,json`؛ قابلة للتكرار
`--no-llm`	تعطيل إثراء LLM
`--llm-model MODEL`	تجاوز نموذج LLM (مثل `gpt-4o`, `claude-sonnet-4-5`)
`--llm-min-severity SEV`	الحد الأدنى للخطورة لـ LLM: `info\|low\|medium\|high\|critical`
`--include-tools TOOLS`	قائمة الأدوات للتشغيل مفصولة بفواصل
`--exclude-tools TOOLS`	قائمة الأدوات للتخطي مفصولة بفواصل
`-e`, `--env KEY=VALUE`	تمرير متغير بيئة إضافي إلى الحاوية
`-b`, `--build`	إعادة بناء صورة Docker قبل التشغيل
`-n`, `--no-defectdojo`	تخطي تكامل DefectDojo
`--shell`	فتح قشرة تفاعلية داخل الحاوية بدلاً من المسح
`-h`, `--help`	عرض المساعدة

الأكثر شعبية

vuln-scanner

vuln-scanner

Table of Contents

البنية```

بيانات الاعتماد لكل هدف

Global fallback — used for any target without a specific entry

JWT for the main app

Cookie session for the admin panel

HTTP Basic for an internal API

Form login for a legacy app

مصفوفة الميزات

Per-tool override — disable PoC for bandit (SAST, no runtime target)

Per-category override — disable log analysis for noisy crawlers

مرشحات النطاق```toml

التنفيذ (داخل الحاوية فقط)

Enable PoC execution inside the container

سلوك كل هدف

Markdown (.md)

HTML (.html)

JSON (.json)

بدء سريع

الأهداف الضعيفة

محلي (Docker — يتم تشغيله بواسطة poc.sh)

المختبر البعيد — pentest-ground.com

Options

Scan using ./config.toml (targets and mode come from the config)

Quick scan with explicit targets and mode

Use a custom config file

Enable LLM enrichment with a specific model

Run only specific tools

Rebuild the image first, then scan

Full manual passthrough to the scanner entrypoint

Open an interactive shell (all tools, volumes, and env available)

Authenticated scanning — forwarded to all applicable web tools

[scan.auth.cookies]

session = "abc123"

[scan.auth.headers]

X-API-Key = "secret"

dirs = ["/opt/company-scanners"]

── LLM Analysis ─────────────────────────────────────────────────────────────

extra_body = { top_k = 40 } # for Ollama/vLLM top_k support

Per-tool feature overrides (tool > category > global precedence)

إضافة أداة جديدة

تكامل DefectDojo

Markdown (`.md`)

HTML (`.html`)

JSON (`.json`)

محلي (Docker — يتم تشغيله بواسطة `poc.sh`)