Tutti gli strumenti di scansione e l'esecuzione dei PoC vengono eseguiti all'interno di un container Docker **BlackArch Linux** — non viene installato nulla sull'host.

---

## Strumenti

86 strumenti organizzati per categoria. Ogni strumento dichiara i tipi di target supportati; l'orchestratore salta automaticamente le combinazioni incompatibili.

### Scansione di Rete e Porte
| Tool | Note |
|------|-------|
| `nmap` | Scansione completa delle porte con rilevamento di servizi/versioni |
| `rustscan` | Scanner di porte veloce, alimenta nmap |
| `masscan` | Scanner TCP/UDP ad alta velocità |
| `naabu` | Scanner di porte con rilevamento dei servizi |
| `netdiscover` | Scoperta host basata su ARP |

### Applicazioni Web
| Tool | Note |
|------|-------|
| `nuclei` | Scanner di vulnerabilità basato su template |
| `nikto` | Scanner di configurazioni errate del server web |
| `wapiti` | Scanner di vulnerabilità web black-box |
| `ffuf` | Fuzzer web veloce (directory, parametri, header) |
| `feroxbuster` | Scoperta di contenuti con ricorsione |
| `gobuster` | Brute-forcer per URI/DNS/vhost |
| `wfuzz` | Fuzzer per applicazioni web |
| `dalfox` | Scanner XSS con analisi dei parametri |
| `xsstrike` | Motore avanzato di rilevamento XSS |
| `commix` | Exploiter di command injection |
| `sqlmap` | SQL injection automatizzata e takeover |
| `nosqlmap` | Scanner per injection NoSQL |
| `httpx` | Probing HTTP e fingerprinting |
| `whatweb` | Fingerprinter delle tecnologie web |
| `wafw00f` | Rilevamento e fingerprinting WAF |
| `wpscan` | Scanner di vulnerabilità WordPress |
| `acunetix` | Scanner di vulnerabilità web (basato su API) |
| `arachni` | Scanner di sicurezza per applicazioni web |
| `zap` | Scanner DAST OWASP ZAP |
| `wapiti` | Scanner di vulnerabilità black-box |
| `drheader` | Analizzatore di header di sicurezza HTTP |
| `humble` | Controllo sicurezza header HTTP |
| `hakrawler` | Crawler web veloce per URL ed endpoint |
| `katana` | Framework di web crawling di nuova generazione |
| `gau` | Collettore di URL noti (AlienVault, WaybackMachine) |
| `jsluice` | Estrattore di segreti e URL da JavaScript |
| `corscanner` | Scanner di configurazioni errate CORS |
| `crlfuzz` | Scanner di injection CRLF |
| `smuggler` | Rilevatore di HTTP request smuggling |
| `linkfinder` | Scoperta di endpoint in sorgenti JavaScript/HTML |
| `cariddi` | Crawler web con rilevamento di segreti ed endpoint |

### API e GraphQL
| Tool | Note |
|------|-------|
| `kiterunner` | Scoperta di rotte API con file kite |
| `graphql_cop` | Auditor di sicurezza GraphQL |
| `restler` | Fuzzer API REST stateful |
| `apifuzzer` | Fuzzer basato su OpenAPI/Swagger |
| `cherrybomb` | Linter di sicurezza per specifiche OpenAPI |
| `arjun` | Scoperta di parametri HTTP |
| `paramspider` | Mining di parametri da wayback/sorgenti |

### DNS e Ricognizione
| Tool | Note |
|------|-------|
| `amass` | Enumerazione di sottodomini (passiva + attiva) |
| `subfinder` | Enumerazione passiva di sottodomini veloce |
| `dnsx` | Toolkit di resolver e probe DNS |
| `dnsrecon` | Enumerazione DNS e zone transfer |
| `fierce` | Ricognizione DNS e scoperta host |
| `theharvester` | OSINT: email, nomi, host, sottodomini |
| `puredns` | Brute-forcer veloce di sottodomini con filtro wildcard |
| `alterx` | Motore di permutazione dei sottodomini |
| `waybackurls` | Raccolta di URL storici da Wayback Machine |
| `httprobe` | Prober di host HTTP/HTTPS attivi |

### TLS / SSL
| Tool | Note |
|------|-------|
| `testssl` | Audit della configurazione TLS e delle suite di cifratura |
| `sslyze` | Scanner TLS (suite di cifratura, Heartbleed, ROBOT) |
| `sslscan` | Scanner per servizi SSL/TLS |
| `tlsx` | Probing TLS veloce |
| `tls_attacker` | Strumento di attacco al protocollo TLS |
| `ssh_audit` | Auditor di configurazione e algoritmi SSH |

### SMB e Servizi di Rete
| Tool | Note |
|------|-------|
| `smbmap` | Enumerazione di condivisioni SMB e permessi |
| `enum4linux` | Enumerazione SMB/NetBIOS |
| `crackmapexec` | Valutazione di Active Directory e SMB |
| `openvas` | Scanner di vulnerabilità OpenVAS |

### SAST e Analisi del Codice
| Tool | Note |
|------|-------|
| `bandit` | SAST Python — anti-pattern di sicurezza comuni |
| `semgrep` | SAST multi-linguaggio con regole della community |
| `gosec` | Controllo di sicurezza per Go |
| `bearer` | SAST data-flow con regole di privacy e sicurezza |
| `horusec` | Motore SAST multi-linguaggio |
| `brakeman` | Scanner SAST per Ruby on Rails |
| `flawfinder` | Analisi statica C/C++ per difetti comuni |
| `dependency_check` | Scanner di vulnerabilità delle dipendenze OWASP |
| `pip_audit` | Controllo vulnerabilità dei pacchetti Python |

### Software Composition Analysis (SCA)
| Tool | Note |
|------|-------|
| `osv-scanner` | Scanner del database di vulnerabilità open source |
| `npm-audit` | Audit di vulnerabilità dei pacchetti Node.js |
| `govulncheck` | Controllo vulnerabilità dei moduli Go |

### Rilevamento Segreti
| Tool | Note |
|------|-------|
| `gitleaks` | Scanner di segreti nella cronologia Git |
| `trufflehog` | Trova segreti basato su entropia profonda |
| `secretfinder` | Segreti in file JS ed endpoint |
| `detect-secrets` | Scanner di segreti basato su baseline |
| `noseyparker` | Scanner di segreti ad alta velocità con regole di pattern |

### IaC e Configurazione
| Tool | Note |
|------|-------|
| `checkov` | Scanner IaC per Terraform/K8s/Dockerfile |
| `tfsec` | Analisi statica Terraform |
| `terrascan` | Scanner di sicurezza IaC multi-cloud |
| `hadolint` | Linter delle best practice per Dockerfile |

### Infrastruttura Cloud
| Tool | Note |
|------|-------|
| `prowler` | Valutazione della postura di sicurezza AWS/GCP/Azure |
| `kube-bench` | Controllo del CIS Kubernetes Benchmark |

### Container e Supply Chain
| Tool | Note |
|------|-------|
| `trivy` | Scanner di vulnerabilità per immagini container + filesystem |
| `grype` | Corrispondenza di vulnerabilità per container e pacchetti |

---

## Filtro per Tipo di Target

L'orchestratore classifica ogni target in uno o più tipi ed esegue solo gli strumenti che dichiarano supporto per quel tipo. Ciò elimina il rumore, ad esempio, degli strumenti SMB eseguiti su URL web.

| Tipo | Esempio | Strumenti corrispondenti |
|------|---------|-----------------|
| `HOST` | `example.com` | strumenti DNS, SSL, web, SMB |
| `IP` | `10.0.0.1` | strumenti di rete, porte, SMB |
| `CIDR` | `10.0.0.0/24` | scanner di rete |
| `URL` | `https://app.example.com` | strumenti web, API, SSL |
| `PATH` | `/src/myapp` | strumenti SAST, SCA, segreti, IaC |
| `REPO` | `https://github.com/org/repo` | strumenti per segreti, SAST, SCA |
| `IMAGE` | `myapp:latest` | scanner per container |
| `CLOUD` | `aws:profile=prod`, `arn:aws:…` | strumenti per la postura cloud (prowler, kube-bench, terrascan) |

La classificazione è automatica: basta passare la stringa del target; lo scanner determina il tipo.

Formati di target cloud riconosciuti:
- ARN AWS: `arn:aws:iam::123456789012:root`
- Abbreviazione per profilo nominato: `aws:profile=production`
- Progetto GCP: `projects/my-project-id`
- UUID di sottoscrizione Azure: `00000000-0000-0000-0000-000000000000`

---

## Modalità di Scansione

| Modalità | Descrizione |
|------|-------------|
| `paranoid` | Massima stealth — probing passivo, impronta minima |
| `passive` | Nessun attacco attivo — solo enumerazione e banner grabbing **(predefinita)** |
| `active` | Controlli di vulnerabilità standard abilitati |
| `aggressive` | Scansione completa: tutti i template, brute-force, timing rapido |

---

## Scansione Autenticata

Le credenziali vengono inoltrate a tutti gli strumenti web applicabili (nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx).

### Credenziali globali

Applicate a ogni target, a meno che non esista un override specifico per target.

**Tramite config:**```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** (solo globale):```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

**Resolution:** `per-target config > global config`

---

## LLM Analysis

Quando è presente una chiave API, il livello LLM si attiva automaticamente. Esegue quattro passaggi sui risultati della scansione:

| Pass | Name | What it does |
|------|------|-------------|
| 1 | **Triage** | Assegna CWE, confidenza, flag di falso positivo, riepilogo di sfruttabilità e progetta un PoC per ogni risultato |
| 2 | **PoC generation** | Scrive script Python/Bash autocontenuti che confermano il risultato utilizzando strumenti già presenti nel container |
| 3 | **Mitigation** | Produce mitigazioni concrete a breve termine e remediation permanenti, eventualmente basate sulle evidenze del PoC |
| 4 | **Clustering** | Raggruppa i risultati per causa principale, scrive remediation condivise e produce un riepilogo esecutivo |

### Configurazione del provider

Il client LLM è compatibile con l'API OpenAI — funziona con OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter e qualsiasi altro endpoint compatibile.```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

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

**Feature precedence:** `tool override > category override > global`

### Prompt personalizzati

Tutti i prompt LLM sono sovrascrivibili:```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}

---

## Generazione ed esecuzione del PoC

### Generazione (sempre sicura per l'host)

L'LLM scrive script Python e/o Bash autocontenuti per ogni finding. Gli script utilizzano strumenti già presenti nell'immagine BlackArch (`curl`, `sqlmap`, `nuclei`, `dalfox`, ecc.) e vengono scritti in `<report>_assets/poc/`. La generazione non esegue mai codice — si limita a scrivere file.```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

---

## Sistema di Plugin

Inserisci un file `.py` che definisce una o più sottoclassi di `AbstractTool` in `./plugins/` (o `~/.vuln-scanner/plugins/`) e verranno scoperti automaticamente all'avvio — nessuna modifica al codice necessaria.

**Ordine di rilevamento** (le voci successive sovrascrivono in caso di collisione di nomi):
1. `./plugins/` (relativo alla CWD)
2. `~/.vuln-scanner/plugins/`
3. Directory extra configurate tramite `[plugins] dirs` o `--plugin-dir`

**Plugin di esempio** (`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

Non esiste un filtro plugin per-target a livello di configurazione — quella logica appartiene al plugin stesso.

---

## Formati di report

Tre formati vengono generati in parallelo. Seleziona qualsiasi combinazione:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

| Step | Action |
|------|--------|
| 1 | Verifica i prerequisiti |
| 2 | Carica `.env` (lo copia da `.env.example` se mancante) |
| 3 | Avvia lo stack DefectDojo |
| 4 | Attende che l'API di DefectDojo sia pronta |
| 5 | Ottiene il token API tramite le credenziali admin |
| 6 | Avvia i container dei target vulnerabili |
| 7 | Attende che ogni target sia raggiungibile |
| 8 | Costruisce l'immagine Docker dello scanner |
| 9 | Esegue lo scanner, genera i report e li invia a DefectDojo |
| 10 | Mostra il riepilogo con URL e istruzioni di teardown |

**Con analisi 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

**Smontaggio:**```bash
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

## scanner.sh — Wrapper Docker

`scanner.sh` è l'interfaccia consigliata per l'uso quotidiano dello scanner. Incapsula `docker compose run` così non devi mai digitare manualmente l'invocazione di compose — basta passare direttamente target e flag.```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

### Cosa fa automaticamente

- Carica `.env` (copia da `.env.example` se manca)
- Copia `config.example.toml` → `config.toml` se non esiste alcuna configurazione
- Crea la rete Docker `vuln_scanner_network` se non è presente
- Monta un file `--config` personalizzato nel container in `/app/config.toml`
- Ricostruisce l'immagine quando viene passato `--build`

---

## Configurazione

Copia il modello annotato:```bash
cp config.example.toml config.toml

**Precedenza di unione della configurazione:** `CLI > env vars > config.toml > defaults`

---

## Variabili d'ambiente

### Core

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | Elenco di target separati da spazi |
| `VS_MODE` | `--mode` | Modalità di scansione |
| `VS_TIMEOUT` | `--timeout` | Timeout per strumento (secondi) |
| `VS_RATE_LIMIT` | `--rate-limit` | Limite di frequenza (req/s) |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | Slot strumenti paralleli |
| `VS_INCLUDE_TOOLS` | `--include-tools` | Strumenti in whitelist per nome |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | Strumenti in blacklist per nome |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | Categorie in whitelist |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | Categorie in blacklist |
| `VS_OUTPUT_DIR` | `--output-dir` | Directory di output dei report |

### Report

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | Formati di report: `markdown html json` |

### LLM

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | Chiave API (variabile d'ambiente standard, usata come fallback) |
| `OPENAI_BASE_URL` | — | URL di base di fallback (per endpoint non OpenAI) |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | Nome del modello (richiesto quando attivo) |
| `VS_LLM_TEMPERATURE` | — | Temperatura di campionamento |
| `VS_LLM_MAX_TOKENS` | — | Token massimi di output |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | Interruttore globale per le funzionalità, ad es. `VS_LLM_FEATURE_GENERATE_POC=false` |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | Abilita l'esecuzione di PoC (solo container) |

### Scansione autenticata

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | Token Bearer (`Authorization: Bearer …`) |
| `VS_AUTH_USERNAME` | `--auth-user` | Nome utente HTTP Basic |
| `VS_AUTH_PASSWORD` | `--auth-pass` | Password HTTP Basic |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | URL di accesso basato su modulo |

I cookie e le intestazioni aggiuntive devono essere impostati tramite file di configurazione o flag CLI `--auth-cookie` / `--auth-header`.

### Plugin

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | Abilita/disabilita l'auto-discovery dei plugin |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | Directory plugin aggiuntive (separate da spazi) |

### DefectDojo

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | URL di base di DefectDojo |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | Token API |
| `VS_DEFECTDOJO_PRODUCT` | — | Nome del prodotto |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | Nome dell'engagement |

---

## Struttura del progetto```
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. Registralo in `vuln_scanner/tools/__init__.py`:```python
from vuln_scanner.tools.mytool import MyTool

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

**Suggerimenti:**
- Per gli strumenti che scrivono su un file invece che su stdout, usa `OUTPUT_FILE_SENTINEL` in `build_command()` e ridefinisci `run()` per chiamare `self._run_with_tempfile()`.
- Gli strumenti con `applicable_targets = frozenset(TargetType)` (l'impostazione predefinita) vengono eseguiti su tutti i tipi di target — usala solo per strumenti davvero universali.
- Binario non trovato → `ScanStatus.SKIPPED` (non mostrato nel report). Errore dello strumento → `ScanStatus.FAILED` (mostrato nell'Appendice A).

---

## Sviluppo```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 .