All scanning tools and PoC execution run inside a **BlackArch Linux** Docker container — nothing is installed on the host.

---

## Outils

86 outils organisés par catégorie. Chaque outil déclare les types de cibles qu'il prend en charge ; l'orchestrateur ignore automatiquement les combinaisons incompatibles.

### Scan réseau et ports
| Outil | Notes |
|------|-------|
| `nmap` | Scan complet des ports avec détection de services/versions |
| `rustscan` | Scanner de ports rapide, alimente nmap |
| `masscan` | Scanner TCP/UDP haute vitesse |
| `naabu` | Scanner de ports avec détection de services |
| `netdiscover` | Découverte d'hôtes basée sur ARP |

### Application web
| Outil | Notes |
|------|-------|
| `nuclei` | Scanner de vulnérabilités basé sur des templates |
| `nikto` | Scanner de mauvaise configuration de serveur web |
| `wapiti` | Scanner de vulnérabilités web en boîte noire |
| `ffuf` | Fuzzer web rapide (répertoires, paramètres, en-têtes) |
| `feroxbuster` | Découverte de contenu avec récursion |
| `gobuster` | Brute-force d'URI/DNS/vhosts |
| `wfuzz` | Fuzzer d'applications web |
| `dalfox` | Scanner XSS avec analyse des paramètres |
| `xsstrike` | Moteur avancé de détection XSS |
| `commix` | Exploiteur d'injection de commandes |
| `sqlmap` | Injection SQL automatisée et prise de contrôle |
| `nosqlmap` | Scanner d'injection NoSQL |
| `httpx` | Sondage HTTP et prise d'empreintes |
| `whatweb` | Outil d'identification de technologies web |
| `wafw00f` | Détection et prise d'empreintes WAF |
| `wpscan` | Scanner de vulnérabilités WordPress |
| `acunetix` | Scanner de vulnérabilités web (basé sur API) |
| `arachni` | Scanner de sécurité d'applications web |
| `zap` | Scanner DAST OWASP ZAP |
| `wapiti` | Scanner de vulnérabilités en boîte noire |
| `drheader` | Analyseur d'en-têtes de sécurité HTTP |
| `humble` | Vérificateur de sécurité des en-têtes HTTP |
| `hakrawler` | Crawler web rapide pour URLs et endpoints |
| `katana` | Framework de crawling web nouvelle génération |
| `gau` | Collecteur d'URL connues (AlienVault, WaybackMachine) |
| `jsluice` | Extracteur de secrets et URLs dans JavaScript |
| `corscanner` | Scanner de mauvaise configuration CORS |
| `crlfuzz` | Scanner d'injection CRLF |
| `smuggler` | Détecteur de contrebande de requêtes HTTP |
| `linkfinder` | Découverte d'endpoints dans les sources JavaScript/HTML |
| `cariddi` | Crawler web avec détection de secrets et d'endpoints |

### API et GraphQL
| Outil | Notes |
|------|-------|
| `kiterunner` | Découverte de routes API avec fichiers kite |
| `graphql_cop` | Auditeur de sécurité GraphQL |
| `restler` | Fuzzer d'API REST avec état |
| `apifuzzer` | Fuzzer basé sur OpenAPI/Swagger |
| `cherrybomb` | Linter de sécurité de spécifications OpenAPI |
| `arjun` | Découverte de paramètres HTTP |
| `paramspider` | Extraction de paramètres depuis wayback/sources |

### DNS et reconnaissance
| Outil | Notes |
|------|-------|
| `amass` | Énumération de sous-domaines (passif + actif) |
| `subfinder` | Énumération passive rapide de sous-domaines |
| `dnsx` | Boîte à outils de résolution et de sondage DNS |
| `dnsrecon` | Énumération DNS et transfert de zone |
| `fierce` | Reconnaissance DNS et découverte d'hôtes |
| `theharvester` | OSINT : e-mails, noms, hôtes, sous-domaines |
| `puredns` | Brute-force rapide de sous-domaines avec filtrage par wildcard |
| `alterx` | Moteur de permutation de sous-domaines |
| `waybackurls` | Collecte d'URL historiques depuis Wayback Machine |
| `httprobe` | Sonde d'hôtes HTTP/HTTPS actifs |

### TLS / SSL
| Outil | Notes |
|------|-------|
| `testssl` | Audit de configuration TLS et de suites de chiffrement |
| `sslyze` | Scanner TLS (suites de chiffrement, Heartbleed, ROBOT) |
| `sslscan` | Scanner de services SSL/TLS |
| `tlsx` | Sondage TLS rapide |
| `tls_attacker` | Outil d'attaque du protocole TLS |
| `ssh_audit` | Auditeur de configuration et d'algorithmes SSH |

### SMB et services réseau
| Outil | Notes |
|------|-------|
| `smbmap` | Énumération des partages SMB et des permissions |
| `enum4linux` | Énumération SMB/NetBIOS |
| `crackmapexec` | Évaluation Active Directory et SMB |
| `openvas` | Scanner de vulnérabilités OpenVAS |

### SAST et analyse de code
| Outil | Notes |
|------|-------|
| `bandit` | SAST Python — anti-modèles de sécurité courants |
| `semgrep` | SAST multi-langages avec règles communautaires |
| `gosec` | Vérificateur de sécurité Go |
| `bearer` | SAST par flux de données avec règles de confidentialité et de sécurité |
| `horusec` | Moteur SAST multi-langages |
| `brakeman` | Scanner SAST Ruby on Rails |
| `flawfinder` | Analyse statique C/C++ pour failles courantes |
| `dependency_check` | Scanner de vulnérabilités de dépendances OWASP |
| `pip_audit` | Vérificateur de vulnérabilités de paquets Python |

### Analyse de composition logicielle (SCA)
| Outil | Notes |
|------|-------|
| `osv-scanner` | Scanner de la base de vulnérabilités Open Source |
| `npm-audit` | Audit de vulnérabilités de paquets Node.js |
| `govulncheck` | Vérificateur de vulnérabilités de modules Go |

### Détection de secrets
| Outil | Notes |
|------|-------|
| `gitleaks` | Scanner de secrets dans l'historique Git |
| `trufflehog` | Recherche de secrets basée sur l'entropie |
| `secretfinder` | Secrets dans les fichiers JS et endpoints |
| `detect-secrets` | Scanner de secrets basé sur une référence |
| `noseyparker` | Scanner de secrets haute vitesse avec règles de motifs |

### IaC et configuration
| Outil | Notes |
|------|-------|
| `checkov` | Scanner IaC Terraform/K8s/Dockerfile |
| `tfsec` | Analyse statique Terraform |
| `terrascan` | Scanner de sécurité IaC multi-cloud |
| `hadolint` | Linter de bonnes pratiques Dockerfile |

### Infrastructure cloud
| Outil | Notes |
|------|-------|
| `prowler` | Évaluation de la posture de sécurité AWS/GCP/Azure |
| `kube-bench` | Vérificateur CIS Kubernetes Benchmark |

### Conteneurs et chaîne d'approvisionnement
| Outil | Notes |
|------|-------|
| `trivy` | Scanner de vulnérabilités d'images de conteneurs + systèmes de fichiers |
| `grype` | Mise en correspondance de vulnérabilités de conteneurs et de paquets |

---

## Filtrage par type de cible

L'orchestrateur classe chaque cible en un ou plusieurs types et n'exécute que les outils qui déclarent prendre en charge ce type. Cela élimine le bruit, par exemple les outils SMB exécutés contre des URL web.

| Type | Exemple | Outils correspondants |
|------|---------|-----------------|
| `HOST` | `example.com` | Outils DNS, SSL, web, SMB |
| `IP` | `10.0.0.1` | Outils réseau, ports, SMB |
| `CIDR` | `10.0.0.0/24` | Scanners réseau |
| `URL` | `https://app.example.com` | Outils web, API, SSL |
| `PATH` | `/src/myapp` | Outils SAST, SCA, secrets, IaC |
| `REPO` | `https://github.com/org/repo` | Outils secrets, SAST, SCA |
| `IMAGE` | `myapp:latest` | Scanners de conteneurs |
| `CLOUD` | `aws:profile=prod`, `arn:aws:…` | Outils de posture cloud (prowler, kube-bench, terrascan) |

La classification est automatique — il suffit de fournir la chaîne de la cible ; le scanner détermine le type.

Formats de cible cloud reconnus :
- ARN AWS : `arn:aws:iam::123456789012:root`
- Raccourci de profil nommé : `aws:profile=production`
- Projet GCP : `projects/my-project-id`
- UUID d'abonnement Azure : `00000000-0000-0000-0000-000000000000`

---

## Modes de scan

| Mode | Description |
|------|-------------|
| `paranoid` | Furtivité maximale — sondage passif, empreinte minimale |
| `passive` | Aucune attaque active — énumération et collecte de bannières uniquement **(par défaut)** |
| `active` | Vérifications de vulnérabilités standard activées |
| `aggressive` | Scan complet : tous les templates, force brute, timing rapide |

---

## Scan authentifié

Les identifiants sont transmis à tous les outils web applicables (nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx).

### Identifiants globaux

Appliqués à chaque cible sauf si une substitution par cible existe.

**Via la configuration :**```toml
[scan.auth]
bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
username     = "admin"
password     = "secret"

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

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

**Via CLI** (global uniquement) :```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

**Résolution :** `per-target config > global config`

---

## Analyse LLM

Lorsqu'une clé API est présente, la couche LLM s'active automatiquement. Elle effectue quatre passes sur les résultats du scan :

| Passe | Nom | Ce qu'elle fait |
|------|------|-------------|
| 1 | **Triage** | Attribue le CWE, le niveau de confiance, l'indicateur de faux positif, le résumé d'exploitabilité et conçoit un PoC pour chaque constat |
| 2 | **Génération de PoC** | Écrit des scripts Python/Bash autonomes qui confirment le constat à l'aide d'outils déjà présents dans le conteneur |
| 3 | **Atténuation** | Produit des atténuations concrètes à court terme et des remédiations permanentes, éventuellement étayées par les preuves du PoC |
| 4 | **Regroupement** | Regroupe les constats par cause racine, rédige des remédiations partagées et produit un résumé exécutif |

### Configuration du fournisseur

Le client LLM est compatible avec l'API OpenAI — il fonctionne avec OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter et tout autre point de terminaison compatible.```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

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

**Précédence des fonctionnalités :** `tool override > category override > global`

### Prompts personnalisés

Tous les prompts LLM sont remplaçables :```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}

---

## Génération et exécution de PoC

### Génération (toujours sûre pour l'hôte)

Le LLM écrit des scripts Python et/ou Bash autonomes pour chaque constat. Les scripts utilisent des outils déjà présents dans l'image BlackArch (`curl`, `sqlmap`, `nuclei`, `dalfox`, etc.) et sont écrits dans `<report>_assets/poc/`. La génération n'exécute jamais de code — elle écrit uniquement des fichiers.```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

## Plugin System

Déposez un fichier `.py` définissant une ou plusieurs sous-classes de `AbstractTool` dans `./plugins/` (ou `~/.vuln-scanner/plugins/`) et elles sont automatiquement découvertes au démarrage — aucune modification de code nécessaire.

**Ordre de découverte** (les entrées ultérieures remplacent en cas de collision de noms) :
1. `./plugins/` (relatif au répertoire de travail courant, CWD)
2. `~/.vuln-scanner/plugins/`
3. Répertoires supplémentaires configurés via `[plugins] dirs` ou `--plugin-dir`

**Exemple de plugin** (`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]:
        ...

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

Il n'existe pas de filtre de plugin par cible au niveau de la configuration — cette logique appartient au plugin lui-même.

---

## Formats de rapport

Trois formats sont générés en parallèle. Sélectionnez n'importe quelle combinaison :```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

| Étape | Action |
|------|--------|
| 1 | Vérifie les prérequis |
| 2 | Charge `.env` (copie depuis `.env.example` si absent) |
| 3 | Démarre la pile DefectDojo |
| 4 | Attend que l'API DefectDojo soit prête |
| 5 | Obtient le jeton API via les identifiants admin |
| 6 | Démarre les conteneurs cibles vulnérables |
| 7 | Attend que chaque cible soit accessible |
| 8 | Construit l'image Docker du scanner |
| 9 | Exécute le scanner, génère les rapports, les pousse vers DefectDojo |
| 10 | Affiche un résumé avec les URL et les instructions de démantèlement |

**Avec analyse 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

**Démontage:**```bash
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

---

## scanner.sh — Wrapper Docker

`scanner.sh` est l'interface recommandée au quotidien pour exécuter le scanner. Il encapsule `docker compose run` afin que vous n'ayez jamais à saisir manuellement l'invocation compose — transmettez simplement les cibles et les drapeaux directement.```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

### Ce qu'il fait automatiquement

- Charge `.env` (copie depuis `.env.example` si absent)
- Copie `config.example.toml` → `config.toml` si aucune configuration n'existe
- Crée le réseau Docker `vuln_scanner_network` s'il n'est pas présent
- Monte un fichier `--config` personnalisé dans le conteneur à `/app/config.toml`
- Reconstruit l'image lorsque `--build` est passé

---

## Configuration

Copiez le modèle annoté :```bash
cp config.example.toml config.toml

**Précédence de fusion des configurations :** `CLI > env vars > config.toml > defaults`

---

## Variables d'environnement

### Noyau

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | Liste de cibles séparées par des espaces |
| `VS_MODE` | `--mode` | Mode d'analyse |
| `VS_TIMEOUT` | `--timeout` | Délai d'expiration par outil (secondes) |
| `VS_RATE_LIMIT` | `--rate-limit` | Limite de débit (req/s) |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | Emplacements d'outils en parallèle |
| `VS_INCLUDE_TOOLS` | `--include-tools` | Outils en liste blanche par nom |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | Outils en liste noire par nom |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | Catégories en liste blanche |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | Catégories en liste noire |
| `VS_OUTPUT_DIR` | `--output-dir` | Répertoire de sortie des rapports |

### Rapports

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | Formats de rapport : `markdown html json` |

### LLM

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | Clé API (variable d'environnement standard, utilisée comme repli) |
| `OPENAI_BASE_URL` | — | URL de base de repli (pour les points de terminaison non-OpenAI) |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | Nom du modèle (requis lorsqu'il est actif) |
| `VS_LLM_TEMPERATURE` | — | Température d'échantillonnage |
| `VS_LLM_MAX_TOKENS` | — | Nombre maximal de jetons de sortie |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | Bascule globale de fonctionnalité, ex. `VS_LLM_FEATURE_GENERATE_POC=false` |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | Activer l'exécution des PoC (conteneur uniquement) |

### Analyse authentifiée

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | Jeton Bearer (`Authorization: Bearer …`) |
| `VS_AUTH_USERNAME` | `--auth-user` | Nom d'utilisateur HTTP Basic |
| `VS_AUTH_PASSWORD` | `--auth-pass` | Mot de passe HTTP Basic |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | URL de connexion par formulaire |

Les cookies et en-têtes supplémentaires doivent être définis via le fichier de configuration ou les indicateurs CLI `--auth-cookie` / `--auth-header`.

### Plugins

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | Activer/désactiver la découverte automatique des plugins |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | Répertoires de plugins supplémentaires (séparés par des espaces) |

### DefectDojo

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | URL de base DefectDojo |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | Jeton API |
| `VS_DEFECTDOJO_PRODUCT` | — | Nom du produit |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | Nom de l'engagement |

---

## Structure du projet```
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)

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. Enregistrez-le dans `vuln_scanner/tools/__init__.py`:```python
from vuln_scanner.tools.mytool import MyTool

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

**Conseils :**
- Pour les outils qui écrivent dans un fichier plutôt que sur stdout, utilisez `OUTPUT_FILE_SENTINEL` dans `build_command()` et surchargez `run()` pour appeler `self._run_with_tempfile()`.
- Les outils avec `applicable_targets = frozenset(TargetType)` (par défaut) s'exécutent sur tous les types de cibles — utilisez ceci uniquement pour des outils véritablement universels.
- Binaire introuvable → `ScanStatus.SKIPPED` (masqué du rapport). Erreur d'outil → `ScanStatus.FAILED` (affiché dans l'annexe A).

---

## Développement```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 .