Todas as ferramentas de varredura e a execução de PoC são executadas dentro de um contêiner Docker **BlackArch Linux** — nada é instalado no host.

---

## Ferramentas

86 ferramentas organizadas por categoria. Cada ferramenta declara os tipos de alvo que suporta; o orquestrador ignora automaticamente combinações incompatíveis.

### Varredura de Rede e Portas
| Tool | Notes |
|------|-------|
| `nmap` | Varredura completa de portas com detecção de serviço/versão |
| `rustscan` | Scanner de portas rápido, alimenta o nmap |
| `masscan` | Scanner TCP/UDP de alta velocidade |
| `naabu` | Scanner de portas com detecção de serviços |
| `netdiscover` | Descoberta de hosts baseada em ARP |

### Aplicações Web
| Tool | Notes |
|------|-------|
| `nuclei` | Scanner de vulnerabilidades baseado em templates |
| `nikto` | Scanner de má configuração do servidor web |
| `wapiti` | Scanner de vulnerabilidades web caixa-preta |
| `ffuf` | Fuzzer web rápido (diretórios, parâmetros, cabeçalhos) |
| `feroxbuster` | Descoberta de conteúdo com recursão |
| `gobuster` | Forçador bruto de URI/DNS/vhost |
| `wfuzz` | Fuzzer de aplicações web |
| `dalfox` | Scanner de XSS com análise de parâmetros |
| `xsstrike` | Mecanismo avançado de detecção de XSS |
| `commix` | Explorador de injeção de comandos |
| `sqlmap` | Injeção SQL automatizada e tomada de controle |
| `nosqlmap` | Scanner de injeção NoSQL |
| `httpx` | Sondagem e fingerprinting HTTP |
| `whatweb` | Fingerprinter de tecnologias web |
| `wafw00f` | Detecção e fingerprinting de WAF |
| `wpscan` | Scanner de vulnerabilidades WordPress |
| `acunetix` | Scanner de vulnerabilidades web (baseado em API) |
| `arachni` | Scanner de segurança para aplicações web |
| `zap` | Scanner DAST OWASP ZAP |
| `wapiti` | Scanner de vulnerabilidades caixa-preta |
| `drheader` | Analisador de cabeçalhos de segurança HTTP |
| `humble` | Verificador de segurança de cabeçalhos HTTP |
| `hakrawler` | Rastreador web rápido para URLs e endpoints |
| `katana` | Framework de rastreamento web de próxima geração |
| `gau` | Coletor de URLs conhecidas (AlienVault, WaybackMachine) |
| `jsluice` | Extrator de segredos e URLs de JavaScript |
| `corscanner` | Scanner de má configuração de CORS |
| `crlfuzz` | Scanner de injeção CRLF |
| `smuggler` | Detector de contrabando de requisições HTTP |
| `linkfinder` | Descoberta de endpoints em código JavaScript/HTML |
| `cariddi` | Rastreador web com detecção de segredos e endpoints |

### API e GraphQL
| Tool | Notes |
|------|-------|
| `kiterunner` | Descoberta de rotas de API com arquivos kite |
| `graphql_cop` | Auditor de segurança GraphQL |
| `restler` | Fuzzer de API REST com estado |
| `apifuzzer` | Fuzzer baseado em OpenAPI/Swagger |
| `cherrybomb` | Linter de segurança de especificações OpenAPI |
| `arjun` | Descoberta de parâmetros HTTP |
| `paramspider` | Mineração de parâmetros a partir do wayback/fontes |

### DNS e Reconhecimento
| Tool | Notes |
|------|-------|
| `amass` | Enumeração de subdomínios (passiva + ativa) |
| `subfinder` | Enumeração passiva rápida de subdomínios |
| `dnsx` | Conjunto de ferramentas de resolução e sondagem DNS |
| `dnsrecon` | Enumeração DNS e transferência de zona |
| `fierce` | Reconhecimento DNS e descoberta de hosts |
| `theharvester` | OSINT: e-mails, nomes, hosts, subdomínios |
| `puredns` | Forçador bruto de subdomínios rápido com filtragem de curingas |
| `alterx` | Mecanismo de permutação de subdomínios |
| `waybackurls` | Coleta de URLs históricas da Wayback Machine |
| `httprobe` | Sondador de hosts HTTP/HTTPS ativos |

### TLS / SSL
| Tool | Notes |
|------|-------|
| `testssl` | Auditoria de configuração TLS e suítes de cifras |
| `sslyze` | Scanner TLS (suítes de cifras, Heartbleed, ROBOT) |
| `sslscan` | Scanner de serviços SSL/TLS |
| `tlsx` | Sondagem TLS rápida |
| `tls_attacker` | Ferramenta de ataque ao protocolo TLS |
| `ssh_audit` | Auditor de configuração SSH e algoritmos |

### SMB e Serviços de Rede
| Tool | Notes |
|------|-------|
| `smbmap` | Enumeração de compartilhamentos SMB e permissões |
| `enum4linux` | Enumeração SMB/NetBIOS |
| `crackmapexec` | Avaliação de Active Directory e SMB |
| `openvas` | Scanner de vulnerabilidades OpenVAS |

### SAST e Análise de Código
| Tool | Notes |
|------|-------|
| `bandit` | SAST Python — antipadrões de segurança comuns |
| `semgrep` | SAST multilíngue com regras da comunidade |
| `gosec` | Verificador de segurança Go |
| `bearer` | SAST de fluxo de dados com regras de privacidade e segurança |
| `horusec` | Mecanismo SAST multilíngue |
| `brakeman` | Scanner SAST Ruby on Rails |
| `flawfinder` | Análise estática C/C++ para falhas comuns |
| `dependency_check` | Scanner de vulnerabilidades de dependências OWASP |
| `pip_audit` | Verificador de vulnerabilidades de pacotes Python |

### Análise de Composição de Software (SCA)
| Tool | Notes |
|------|-------|
| `osv-scanner` | Scanner do banco de dados de Vulnerabilidades de Código Aberto |
| `npm-audit` | Auditoria de vulnerabilidades de pacotes Node.js |
| `govulncheck` | Verificador de vulnerabilidades de módulos Go |

### Detecção de Segredos
| Tool | Notes |
|------|-------|
| `gitleaks` | Scanner de segredos no histórico do Git |
| `trufflehog` | Localizador de segredos profundo baseado em entropia |
| `secretfinder` | Segredos em arquivos JS e endpoints |
| `detect-secrets` | Scanner de segredos baseado em baseline |
| `noseyparker` | Scanner de segredos de alta velocidade com regras de padrões |

### IaC e Configuração
| Tool | Notes |
|------|-------|
| `checkov` | Scanner IaC para Terraform/K8s/Dockerfile |
| `tfsec` | Análise estática Terraform |
| `terrascan` | Scanner de segurança IaC multi-nuvem |
| `hadolint` | Linter de boas práticas para Dockerfile |

### Infraestrutura em Nuvem
| Tool | Notes |
|------|-------|
| `prowler` | Avaliação da postura de segurança AWS/GCP/Azure |
| `kube-bench` | Verificador do CIS Kubernetes Benchmark |

### Contêiner e Cadeia de Suprimentos
| Tool | Notes |
|------|-------|
| `trivy` | Scanner de vulnerabilidades de imagens de contêiner + sistema de arquivos |
| `grype` | Correspondente de vulnerabilidades de contêineres e pacotes |

---

## Seleção por Tipo de Alvo

O orquestrador classifica cada alvo em um ou mais tipos e executa apenas ferramentas que declaram suporte para esse tipo. Isso elimina ruído, por exemplo, de ferramentas SMB executadas contra URLs web.

| Tipo | Exemplo | Ferramentas que correspondem |
|------|---------|-----------------|
| `HOST` | `example.com` | Ferramentas de DNS, SSL, web, SMB |
| `IP` | `10.0.0.1` | Ferramentas de rede, portas, SMB |
| `CIDR` | `10.0.0.0/24` | Scanners de rede |
| `URL` | `https://app.example.com` | Ferramentas de web, API, SSL |
| `PATH` | `/src/myapp` | Ferramentas de SAST, SCA, segredos, IaC |
| `REPO` | `https://github.com/org/repo` | Ferramentas de segredos, SAST, SCA |
| `IMAGE` | `myapp:latest` | Scanners de contêineres |
| `CLOUD` | `aws:profile=prod`, `arn:aws:…` | Ferramentas de postura em nuvem (prowler, kube-bench, terrascan) |

A classificação é automática — basta passar a string do alvo; o scanner descobre o tipo.

Formatos de alvo em nuvem reconhecidos:
- AWS ARN: `arn:aws:iam::123456789012:root`
- Forma abreviada de perfil nomeado: `aws:profile=production`
- Projeto GCP: `projects/my-project-id`
- UUID de assinatura do Azure: `00000000-0000-0000-0000-000000000000`

---

## Modos de Varredura

| Modo | Descrição |
|------|-------------|
| `paranoid` | Máximo stealth — sondagem passiva, pegada mínima |
| `passive` | Sem ataques ativos — apenas enumeração e captura de banner **(padrão)** |
| `active` | Verificações padrão de vulnerabilidades habilitadas |
| `aggressive` | Varredura completa: todos os templates, força bruta, temporização rápida |

---

## Varredura Autenticada

As credenciais são encaminhadas para todas as ferramentas web aplicáveis (nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx).

### Credenciais globais

Aplicadas a todos os alvos, a menos que exista uma sobreposição por alvo.

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

**Resolução:** `per-target config > global config`

---

## Análise com LLM

Quando uma chave de API está presente, a camada de LLM é ativada automaticamente. Ela executa quatro passagens sobre os resultados da varredura:

| Pass | Nome | O que faz |
|------|------|-------------|
| 1 | **Triagem** | Atribui CWE, confiança, sinalizador de falso positivo, resumo de explorabilidade e elabora um PoC para cada descoberta |
| 2 | **Geração de PoC** | Escreve scripts Python/Bash autônomos que confirmam a descoberta usando ferramentas já presentes no contêiner |
| 3 | **Mitigação** | Produz mitigações concretas de curto prazo e remediações permanentes, opcionalmente informadas pelas evidências do PoC |
| 4 | **Agrupamento** | Agrupa descobertas por causa raiz, escreve remediações compartilhadas e produz um resumo executivo |

### Configuração do provedor

O cliente de LLM é compatível com a API da OpenAI — funciona com OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter e qualquer outro endpoint compatível.```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

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

**Precedência de recursos:** `tool override > category override > global`

### Prompts personalizados

Todos os prompts de LLM são substituíveis:```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}

---

## Geração e Execução de PoC

### Geração (sempre segura para o host)

O LLM escreve scripts Python e/ou Bash autocontidos para cada achado. Os scripts usam ferramentas já presentes na imagem BlackArch (`curl`, `sqlmap`, `nuclei`, `dalfox`, etc.) e são gravados em `<report>_assets/poc/`. A geração nunca executa código — ela apenas grava arquivos.```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 de Plugins

Coloque um arquivo `.py` definindo uma ou mais subclasses de `AbstractTool` em `./plugins/` (ou `~/.vuln-scanner/plugins/`) e eles serão descobertos automaticamente na inicialização — nenhuma alteração de código é necessária.

**Ordem de descoberta** (as entradas posteriores substituem em caso de colisão de nomes):
1. `./plugins/` (relativo ao CWD)
2. `~/.vuln-scanner/plugins/`
3. Diretórios extras configurados por meio de `[plugins] dirs` ou `--plugin-dir`

**Exemplo 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

Não há filtro de plugin por alvo em nível de configuração — essa lógica pertence ao próprio plugin.

---

## Formatos de Relatório

Três formatos são gerados em paralelo. Selecione qualquer combinação:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

| Etapa | Ação |
|------|--------|
| 1 | Verifica pré-requisitos |
| 2 | Carrega `.env` (copia de `.env.example` se ausente) |
| 3 | Inicia a stack DefectDojo |
| 4 | Aguarda a API do DefectDojo ficar pronta |
| 5 | Obtém o token da API por meio das credenciais de administrador |
| 6 | Inicia os contêineres de alvos vulneráveis |
| 7 | Aguarda cada alvo ficar acessível |
| 8 | Constrói a imagem Docker do scanner |
| 9 | Executa o scanner, gera relatórios, envia para o DefectDojo |
| 10 | Exibe o resumo com URLs e instruções de desmontagem |

**Com análise de 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

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

---

## scanner.sh — Wrapper do Docker

`scanner.sh` é a interface recomendada para o uso diário na execução do scanner. Ele envolve o `docker compose run` para que você nunca precise digitar a invocação do compose manualmente — basta passar alvos e flags diretamente.```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

### O que faz automaticamente

- Carrega o `.env` (copia de `.env.example` se estiver ausente)
- Copia `config.example.toml` → `config.toml` se não existir nenhuma configuração
- Cria a rede Docker `vuln_scanner_network` se não estiver presente
- Monta um arquivo `--config` personalizado no contêiner em `/app/config.toml`
- Reconstrói a imagem quando `--build` é passado

---

## Configuração

Copie o modelo anotado:```bash
cp config.example.toml config.toml

**Precedência de mesclagem de configuração:** `CLI > env vars > config.toml > defaults`

---

## Variáveis de Ambiente

### Núcleo

| Variável | Flag CLI | Descrição |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | Lista de alvos separada por espaços |
| `VS_MODE` | `--mode` | Modo de varredura |
| `VS_TIMEOUT` | `--timeout` | Tempo limite por ferramenta (segundos) |
| `VS_RATE_LIMIT` | `--rate-limit` | Limite de taxa (req/s) |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | Slots paralelos de ferramentas |
| `VS_INCLUDE_TOOLS` | `--include-tools` | Ferramentas na lista de permissões por nome |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | Ferramentas na lista de bloqueio por nome |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | Categorias na lista de permissões |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | Categorias na lista de bloqueio |
| `VS_OUTPUT_DIR` | `--output-dir` | Diretório de saída dos relatórios |

### Relatórios

| Variável | Flag CLI | Descrição |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | Formatos de relatório: `markdown html json` |

### LLM

| Variável | Flag CLI | Descrição |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | Chave de API (variável de ambiente padrão, usada como fallback) |
| `OPENAI_BASE_URL` | — | URL base de fallback (para endpoints não-OpenAI) |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | Nome do modelo (obrigatório quando ativo) |
| `VS_LLM_TEMPERATURE` | — | Temperatura de amostragem |
| `VS_LLM_MAX_TOKENS` | — | Máximo de tokens de saída |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | Alternância global de recursos, ex.: `VS_LLM_FEATURE_GENERATE_POC=false` |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | Habilita execução de PoC (somente contêiner) |

### Varredura Autenticada

| Variável | Flag CLI | Descrição |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | Token Bearer (`Authorization: Bearer …`) |
| `VS_AUTH_USERNAME` | `--auth-user` | Nome de usuário HTTP Basic |
| `VS_AUTH_PASSWORD` | `--auth-pass` | Senha HTTP Basic |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | URL de login baseado em formulário |

Cookies e cabeçalhos extras devem ser definidos via arquivo de configuração ou flags CLI `--auth-cookie` / `--auth-header`.

### Plugins

| Variável | Flag CLI | Descrição |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | Habilita/desabilita descoberta automática de plugins |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | Diretórios extras de plugins (separados por espaços) |

### DefectDojo

| Variável | Flag CLI | Descrição |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | URL base do DefectDojo |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | Token de API |
| `VS_DEFECTDOJO_PRODUCT` | — | Nome do produto |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | Nome do engajamento |

---

## Estrutura do Projeto```
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. Registre-o em `vuln_scanner/tools/__init__.py`:```python
from vuln_scanner.tools.mytool import MyTool

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

**Dicas:**
- Para ferramentas que gravam em um arquivo em vez de stdout, use `OUTPUT_FILE_SENTINEL` em `build_command()` e sobrescreva `run()` para chamar `self._run_with_tempfile()`.
- Ferramentas com `applicable_targets = frozenset(TargetType)` (o padrão) são executadas em todos os tipos de alvo — use isso apenas para ferramentas genuinamente universais.
- Binário não encontrado → `ScanStatus.SKIPPED` (oculto do relatório). Erro de ferramenta → `ScanStatus.FAILED` (mostrado no Apêndice A).

---

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