F --> G1[Passive scanners]
F --> G2[Active scanners]

I[template-tool] --> H[CVE templates]
H --> G2

G1 --> J[Findings]
G2 --> J
J --> K[Reporter]
K --> L[Auto Reports]
K --> M[CI/CD Controls]

## Por que ApiHunter?

### Vantagens Principais

- **Arquitetura Focada em API**: Construída especificamente para APIs REST/GraphQL, não adaptada de scanners de aplicações web
- **Redução Inteligente de Falsos Positivos**: 
  - Detecção de catch-all SPA com sondagem canary
  - Validação de segredos sensível ao contexto (frontend vs backend)
  - Validação de conteúdo do corpo e verificação de referer
  - Identificação de respostas para evitar achados duplicados
- **Seguro para Produção por Concepção**:
  - Concorrência adaptativa (AIMD) que reduz em caso de erros
  - Limitação de taxa por host com atrasos configuráveis
  - Controles de educação (retentativas, timeouts, evasão de WAF)
  - Modo de simulação (dry-run) para verificações ativas
- **Sigilo e Evasão**:
  - Rotação de User-Agent em tempo de execução a partir de uma lista curada (assets/user_agents.txt)
  - Atrasos aleatórios nas requisições com variação (jitter)
  - Imposição de atraso por host (evita padrões de rajada)
  - Lógica de retentativa com backoff exponencial
  - Injeção de cabeçalhos personalizados para se misturar com tráfego legítimo
  - Temporização adaptativa baseada nas respostas do servidor
  - Sem impressões digitais de scanner codificadas no modo padrão

### Aprofundamento nas Técnicas de Sigilo

O ApiHunter utiliza várias técnicas de sigilo para evitar detecção por WAF (Firewall de Aplicação Web) e sistemas de proteção contra bots:

#### 1. Rotação de User-Agent
**O que faz:** Percorre aleatoriamente mais de 100 strings de User-Agent de navegadores reais a partir de um ficheiro (`assets/user_agents.txt`)

**Por que funciona:** Bots normalmente usam o mesmo User-Agent (como `curl/7.68.0`). Ao fingir ser Chrome, Firefox, Safari, etc., você se mistura com o tráfego legítimo

**Analogia simples:** Como usar disfarces diferentes em vez de usar sempre o mesmo uniforme

#### 2. Temporização Aleatória e Variação
**O que faz:** Adiciona atrasos aleatórios entre requisições (controlado por `--delay-ms`) com variação (pequenas alterações aleatórias)

**Por que funciona:** Bots enviam requisições em intervalos perfeitos (exatamente 100ms de diferença). Humanos são imprevisíveis. A temporização aleatória faz o tráfego parecer orgânico

**Analogia simples:** Andar com passos irregulares em vez de marchar como um robô

#### 3. Imposição de Atraso por Host
**O que faz:** Monitora o atraso separadamente para cada domínio, não globalmente

**Por que funciona:** Previne padrões de rajada onde você atinge um host 50 vezes instantaneamente. Cada host vê requisições educadas e espaçadas

**Analogia simples:** Falar por turnos em diferentes conversas em vez de gritar com uma pessoa repetidamente

#### 4. Concorrência Adaptativa (AIMD)
**O que faz:** Abranda automaticamente quando recebe erros 429 (limitação de taxa) ou 503 (servidor ocupado), acelera quando tem sucesso

**Por que funciona:** Reduz quando é detetado, imita como os navegadores fazem retentativas. WAFs veem "este cliente respeita os nossos limites"

**Analogia simples:** Abrandar quando o trânsito está congestionado, acelerar em estradas abertas

#### 5. Retentativa com Backoff Exponencial
**O que faz:** Quando uma requisição falha, espera 1s, depois 2s, depois 4s antes de tentar novamente

**Por que funciona:** Clientes legítimos fazem retentativas de forma educada. Bots frequentemente insistem imediatamente ou desistem

**Analogia simples:** Bater a uma porta, esperar mais tempo de cada vez em vez de bater continuamente

#### 6. Sem Impressões Digitais de Scanner
**O que faz:** Não envia cabeçalhos como `X-Scanner: ApiHunter` ou padrões previsíveis

**Por que funciona:** Muitas ferramentas deixam assinaturas (modelos Nuclei, padrões sqlmap). O ApiHunter evita marcadores óbvios

**Analogia simples:** Não usar um crachá que diz "Testador de Segurança"

#### 7. Reutilização e Pooling de Conexões
**O que faz:** Usa pools de clientes HTTP por host, mantém conexões ativas

**Por que funciona:** Navegadores reutilizam conexões. Abrir/fechar para cada requisição parece suspeito

**Analogia simples:** Manter a porta aberta em vez de a bater e tocar à campainha novamente

#### 8. Injeção de Cabeçalhos Personalizados
**O que faz:** Pode adicionar cabeçalhos como `Referer`, `X-Forwarded-For`, cookies personalizados

**Por que funciona:** Faz as requisições parecerem que vieram de um fluxo de aplicação legítimo (clicou num link, tem cookies de sessão)

**Analogia simples:** Mostrar um bilhete ao entrar num recinto em vez de saltar a vedação

#### Comparação de Deteção

| Técnica | Sem Evasão | Com Evasão |
|-----------|----------------|-------------|
| **User-Agent** | `python-requests/2.28.0` (bot óbvio) | `Mozilla/5.0 (Windows NT 10.0; Win64; x64)...` (parece Chrome) |
| **Temporização** | Intervalos perfeitos de 100ms → WAF bloqueia | 120ms, 95ms, 180ms → parece humano |
| **Retentativas** | Retentativa instantânea → banimento | Espera 1s→2s→4s → "cliente paciente" |
| **Concorrência** | 100 acessos paralelos → alarme | Adaptativo 5→10→3 baseado na resposta → "navegador educado" |

#### Quando usar `--waf-evasion`

- Testar APIs em produção com Cloudflare/Akamai/AWS WAF
- Evitar banimentos de IP durante grandes verificações
- Testes de penetração onde precisa ficar fora do radar

- **Nativo para CI/CD**:
  - Diferenciação com baseline (apenas reportar novos achados)
  - Saída NDJSON em streaming para monitorização em tempo real
  - SARIF 2.1.0 para Code Scanning do GitHub/GitLab
  - Máscara de bits do código de saída para controlo de pipeline
  - Filtragem por gravidade e limites de falha
- **Desempenho em Escala**:
  - Runtime assíncrono Rust (tokio) com abstrações de custo zero
  - Verificação concorrente com paralelismo limitado por semáforo
  - Pools de clientes HTTP por host para evitar gargalos de conexão
  - Uso eficiente de memória (sem pausas GC)
- **Suporte Abrangente para Autenticação**:
  - Fluxos de autenticação baseados em JSON com extração de cookies/cabeçalhos
  - Teste IDOR/BOLA com identidade dupla
  - Importação de ficheiros de sessão (integração com Excalibur)
  - Autenticação Bearer, Basic e cabeçalho personalizado
  - Cliente não autenticado automático para verificações de escalada de privilégios

## Módulos do Scanner

O ApiHunter inclui 13 módulos de scanner integrados. Consulte [docs/scanners.md](https://github.com/teycir/apihunter/blob/main/docs/scanners.md) para lógica de deteção detalhada.

| Scanner | Tipo | O que Deteta |
|---------|------|----------------|
| **CORS** | Passivo | Origens wildcard, origens refletidas com credenciais, aceitação de origem nula, vulnerabilidades de bypass regex (ataques de sufixo/prefixo), falta de Vary: Origin, métodos preflight inseguros |
| **CSP** | Passivo | Falta de Content-Security-Policy, diretivas unsafe-inline/unsafe-eval, origens wildcard, hosts CDN contornáveis (gadgets JSONP), falta de frame-ancestors |
| **GraphQL** | Passivo | Introspeção ativada, campos de esquema sensíveis (tipos user/password/token), sugestões de campo (fuga de esquema), agrupamento de consultas, amplificação de alias (DoS), exposição de GraphiQL/Playground |
| **JWT** | Passivo | Tokens com alg=none, segredos HS256 fracos (baseado em wordlist), expiração ausente/excessiva, claims sensíveis no payload, vulnerabilidades de confusão de algoritmo |
| **OpenAPI** | Passivo | Esquemas de segurança ausentes, operações sem requisitos de autenticação, endpoints de upload de ficheiros, operações obsoletas ainda presentes, endpoints sensíveis não protegidos |
| **API Versioning** | Passivo | Divulgação de cabeçalho de versão, versões de API legadas/novas concorrentes, cabeçalhos de depreciação e deriva de resposta entre variantes benignas de consulta/versão (mais modo profundo via `--response-diff-deep`) |
| **gRPC/Protobuf** | Passivo + Ativo | Sinais de transporte/content-type gRPC, dicas de superfície protobuf e sinais opcionais de sonda de reflexão/saúde |
| **API Security** | Passivo + Ativo | Falta de cabeçalhos de segurança (X-Content-Type-Options, X-Frame-Options), divulgação de versão do servidor, acesso não autenticado a caminhos sensíveis, enumeração de métodos HTTP, endpoints de depuração, padrões de exposição de segredos, verificações IDOR/BOLA ativas (comparação de corpo + cabeçalho selecionado), sondas de callback SSRF cego e sinais de sonda de gateway/bypass |
| **Mass Assignment** | Ativo | Campos sensíveis refletidos (is_admin, role, permissions), mudanças de estado persistidas, escalada de privilégios via injeção de campo |
| **OAuth/OIDC** | Ativo | Bypass de validação de URI de redirecionamento, parâmetro state ausente, problemas de suporte PKCE (falta de S256, plain permitido), fluxo implícito ativado, concessão de password ativada |
| **Rate Limit** | Ativo | Falta de limitação de taxa (sondas de rajada), cabeçalhos Retry-After ausentes, bypass de spoofing de cabeçalho IP (X-Forwarded-For) |
| **WebSocket** | Ativo | Aceitação de upgrade WebSocket em caminhos comuns, validação de origem ausente, conexões WebSocket não autenticadas |
| **CVE Templates** | Ativo | Deteção de CVE baseada em modelos a partir de `assets/cve_templates/*.toml` (168 modelos atualmente), correspondência diferencial baseline vs bypass |

**Scanners passivos** são executados por padrão e analisam respostas sem enviar requisições personalizadas.  
**Scanners/verificações ativas** requerem `--active-checks` e enviam sondas potencialmente invasivas (IDOR/BOLA, mutação, testes de bypass).  
IDOR/BOLA está sob o scanner `API Security` (não existe um sinalizador dedicado `--no-idor`; use `--no-api-security` para desativá-lo).

### Notas sobre Saída e Sinal do Módulo

Estas notas resumem como os achados são emitidos e o que tipicamente causa ruído:

| Módulo | Prefixo do Achado / Forma | Falsos Positivos Comuns | Falsos Negativos Comuns |
|---------|-------------------------|-------------------------|-------------------------|
| CORS | `cors/*` com campos de origem/evidência | Reflexão em rotas não sensíveis | Verificações de origem aplicadas apenas em rotas autenticadas |
| CSP | `csp/*` com evidência de diretiva | CSP legado aplicado intencionalmente durante migração | CSP entregue apenas no caminho de edge CDN de produção |
| GraphQL | `graphql/*` com endpoint + sinal de capacidade | Playground público destinado a inquilinos internos/teste | Controlos de esquema ativados apenas após autenticação |
| JWT | `jwt/*` com evidência de claim/cabeçalho do token | Tokens de teste/demo em respostas sintéticas | Token nunca aparece nas respostas digitalizadas |
| OpenAPI | `openapi/*` com contexto de operação/segurança | Especificação inclui intencionalmente endpoints obsoletos mas bloqueados | Especificação indisponível ou dividida entre documentação privada |
| API Versioning | `api_versioning/*` + `response_diff/*` | Várias versões suportadas durante migrações controladas | Caminhos versionados não detetáveis a partir do conjunto de sementes atual |
| gRPC/Protobuf | `grpc_protobuf/*` com evidência de transporte/reflexão | Metadados semelhantes a gRPC em proxies de edge sem superfície RPC exposta | Endpoints gRPC em host/caminho separado não alcançados a partir do conjunto de sementes |
| API Security | `api_security/*` com evidência de cabeçalho/caminho/método | Endpoints de depuração/teste intencionalmente expostos em não-produção | Controlos aplicados atrás de contexto de autenticação/sessão |
| Mass Assignment | `mass_assignment/*` com deltas refletidos/persistidos | Comportamento de eco que não persiste estado do backend | Mutações rejeitadas por regras de validação ocultas |
| OAuth/OIDC | `oauth/*` com evidência de redirecionamento/metadados | Configuração de IdP não produtivo com políticas relaxadas | Imposição de política dinâmica não visível em metadados |
| Rate Limit | `rate_limit/*` com comportamento de rajada/429 | Modelação de tráfego global mascara comportamento do limitador a nível de aplicação | Limitadores de janela longa não acionados por janela de sonda curta |
| WebSocket | `websocket/*` com verificações de upgrade/origem | Endpoints WS públicos intencionalmente anónimos | Autenticação necessária via cabeçalhos de handshake não fornecidos na sonda |
| CVE Templates | `cve/<id>/<check>` com evidência de modelo | Colisão de impressão digital em endpoints genéricos | Caminho/contexto vulnerável não alcançado a partir de URLs de semente |

Para detalhe verificação a verificação e orientação de remediação, consulte [docs/scanners.md](https://github.com/teycir/apihunter/blob/main/docs/scanners.md) e [docs/findings.md](https://github.com/teycir/apihunter/blob/main/docs/findings.md).
A documentação do scanner agora inclui um [Catálogo de Verificações do Módulo](https://github.com/teycir/apihunter/blob/main/docs/scanners.md#module-check-catalog) alinhado à fonte e um [Modelo de Expectativa de Falsos Positivos](https://github.com/teycir/apihunter/blob/main/docs/scanners.md#false-positive-expectation-model).

## Funcionalidades

### Análise de Segurança Passiva
- **Deteção de Má Configuração CORS**:
  - Geração dinâmica de origem com base no domínio alvo
  - Teste de bypass regex (ataques de sufixo/prefixo)
  - Pontuação de gravidade sensível a credenciais
  - Deteção de origem wildcard e nula
- **Análise de Política CSP**:
  - Deteção de Content Security Policy ausente/fraca
  - Diretivas unsafe inline/eval
  - Deteção de fontes wildcard
  - Padrões de bypass de política
- **Segurança GraphQL**:
  - Deteção de consulta de introspeção
  - Análise de nomes de tipo/campo sensíveis
  - Deteção de suporte a agrupamento de consultas
  - Sondagem de amplificação de alias (DoS)
  - Fuzzing de mutação ativa (`--active-checks`, suporta `--dry-run`)
  - Exposição de GraphiQL/Playground
- **Análise de Token JWT**:
  - Confusão de algoritmo (alg=none, HS256→RS256)
  - Deteção de segredo fraco (wordlist curada)
  - Deteção de token de longa duração (exp ausente/excessiva)
  - Exposição de claims sensíveis
  - Extração de token de cabeçalhos e cookies
- **Análise OpenAPI/Swagger**:
  - Validação de esquema de segurança
  - Deteção de endpoint de upload de ficheiro
  - Sinalização de operações obsoletas
  - Definições de segurança ausentes
  - Cache de especificação para desempenho
- **Cobertura gRPC/Protobuf**:
  - Deteção de metadados/content-type de resposta gRPC
  - Deteção de dicas de superfície protobuf a partir de metadados/formato de caminho do endpoint
  - Sinais opcionais de sonda ativa de reflexão/saúde em caminhos gRPC conhecidos
- **Deteção de Exposição de Segredos**:
  - Chaves AWS (AKIA*, chaves secretas)
  - Chaves de API Google (AIza*)
  - Tokens GitHub (ghp_*, github_pat_*)
  - Tokens Slack (xox*)
  - Chaves Stripe (sk_live_*, pk_live_*)
  - URLs de base de dados, chaves privadas, tokens bearer
  - Validação sensível ao contexto (reduz falsos positivos)
- **Verificações de Segurança API**:
  - Enumeração de métodos HTTP
  - Deteção de endpoint de depuração
  - Exposição de listagem de diretório
  - Presença de security.txt
  - Análise de cabeçalhos de resposta (HSTS, X-Frame-Options, etc.)
  - Divulgação de mensagens de erro

### Teste de Segurança Ativo (--active-checks)
- **Verificações IDOR/BOLA de Segurança API** (abordagem de 3 níveis):
  - Teste de acesso não autenticado
  - Comparação de respostas via impressões digitais do corpo mais capturas de cabeçalhos estáveis
  - Enumeração de ID (caminhada de intervalo ±2)
  - Bypass de autorização entre utilizadores (identidade dupla)
  - Sondagem de callback SSRF cego via parâmetros de consulta estilo callback (`APIHUNTER_OAST_BASE`, suporta `--dry-run`)
  - Sondagem de impressão digital e bypass de gateway (`api_security/gateway-*`)
- **Vulnerabilidades de Mass Assignment**:
  - Injeção de campo sensível refletido
  - Deteção de mudança de estado persistida
  - Verificação Baseline→Mutate→Confirm
  - Escalada de privilégios via injeção de campo
- **Segurança OAuth/OIDC**:
  - Bypass de validação de URI de redirecionamento
  - Manipulação do parâmetro state
  - Deteção de suporte PKCE
  - Reforço de configuração de metadados
  - Deteção de fluxo implícito e concessão de password
- **Limitação de Taxa**:
  - Sondagem de requisições em rajada
  - Deteção de falta de limitação de taxa
  - Validação do cabeçalho Retry-After
  - Testes de bypass de spoofing de cabeçalho IP
- **Segurança WebSocket**:
  - Aceitação de upgrade em caminhos comuns
  - Teste de validação de origem
  - Verificações de autenticação ausentes
- **Motor de Modelos CVE**:
  - Catálogo de modelos baseado em TOML
  - Suporte para importação de YAML Nuclei
  - Correspondência diferencial baseline vs bypass
  - Deduplicação de host+modelo
  - Controlos de qualidade do carregador ignoram modelos de requisição inválidos/inseguros (por exemplo, placeholders de requisição não resolvidos)
  - Correspondência de contexto consciente de segmento reduz ativação excessiva de substring de caminho ampla
  - Catálogo local atual: 168 modelos (inclui verificações robustas curadas como CVE-2022-22947, CVE-2021-29442, CVE-2021-29441, CVE-2020-13945, CVE-2021-45232, CVE-2022-24288)

### Descoberta e Enumeração
- **Descoberta de Endpoints**:
  - Análise de robots.txt
  - Análise de sitemap.xml
  - Importação de especificação OpenAPI/Swagger
  - Importação de ficheiro HAR (integração Excalibur)
  - Importação de coleção Postman/Insomnia (`--collection`)
  - Extração de endpoints JavaScript
  - Filtragem por mesmo host
- **Pré-filtragem de Acessibilidade de URL**:
  - Pré-verificação rápida para ignorar endpoints mortos
  - Timeout configurável
  - Bypass opcional com --no-filter

### Desempenho e Fiabilidade
- **Concorrência Adaptativa (AIMD)**:
  - Ajuste automático de taxa baseado em erros
  - Aumento aditivo (a cada 5s)
  - Diminuição multiplicativa em 429/503/timeouts
- **Sigilo e Evasão WAF**:
  - Rotação de User-Agent a partir de pool em tempo de execução (assets/user_agents.txt com mais de 100 UAs reais)
  - UAs de fallback incorporados se ficheiro indisponível
  - Variação de atraso aleatório para evitar padrões de deteção
  - Imposição de temporização por host (não global)
  - Lógica de retentativa com backoff exponencial
  - Injeção de cabeçalhos personalizados (X-Forwarded-For, Referer, etc.)
  - Temporização adaptativa baseada em respostas 429/503
  - Modo de educação para teste cooperativo
  - Sem impressões digitais de scanner em User-Agent ou cabeçalhos por padrão
- **Gestão de Recursos**:
  - Paralelismo limitado por semáforo
  - Pools de clientes HTTP por host
  - Reutilização e pooling de conexões
  - Timeouts e retentativas configuráveis
- **Tratamento de Erros**:
  - Recuperação de pânico via JoinSet
  - Erros capturados reportados separadamente
  - Degradação graciosa em falhas de scanner

### Saída e Relatórios
- **Vários Formatos de Saída**:
  - Pretty JSON (legível por humanos)
  - NDJSON (streaming, analisável)
  - SARIF 2.1.0 (Code Scanning GitHub/GitLab)
- **Diferenciação com Baseline**:
  - Gerar instantâneos de baseline
  - Comparar digitalizações para reportar apenas novos achados
  - Perfeito para teste de regressão
- **Guardar Relatórios Automaticamente** (ativado por padrão, desativar com `--no-auto-report`):
  - Guardado em ~/Documents/ApiHunterReports/<timestamp>/
  - findings.json (achados estruturados)
  - summary.md (relatório markdown)
  - scan.log (registo de execução)
- **Streaming em Tempo Real**:
  - Transmitir achados à medida que são descobertos
  - Formato NDJSON para análise ao vivo
  - Acompanhamento de progresso
- **Filtragem por Gravidade**:
  - Filtrar por gravidade mínima (info/low/medium/high/critical)
  - Limite de falha para CI/CD
  - Máscara de bits do código de saída (0x01 achados, 0x02 erros)

### Integração e Extensibilidade
- **Arquitetura de Scanner Plugável**:
  - Implementar trait Scanner para adicionar módulos
  - Design assíncrono primeiro
  - Execução independente do scanner
  - Isolamento de pânico por scanner
- **Extensibilidade Baseada em TOML**:
  - Catálogo de modelos CVE em assets/cve_templates/*.toml
  - Nenhuma alteração de código necessária para adicionar novas verificações
  - Deteção de vulnerabilidade baseada em modelos
  - Formato de modelo partilhável pela comunidade
- **Importação de Modelos Nuclei**:
  - Binário template-tool para conversão YAML → TOML
  - Tradução automática de correspondentes (status, word, regex, dsl)
  - Extração segura de cadeia de requisição preflight
  - Preserva a lógica de deteção dos modelos upstream
- **Modelo de Extensão Dupla**:
  - **Baseado em código**: Escrever scanners Rust implementando trait Scanner para lógica complexa
  - **Baseado em modelo**: Escrever modelos TOML para verificações baseadas em assinaturas (CVEs, má configurações)
  - O melhor dos dois mundos: desempenho + flexibilidade
- **Ferramentas Complementares**:
  - Extensão de navegador Excalibur (captura HAR)
  - BurpAPIsecuritysuite (teste manual)
  - Fluxo de trabalho: Capturar → Automatizar → Teste Profundo

### Configuração e Controlo
- **Entrada Flexível**:
  - Listas de URLs baseadas em ficheiro
  - stdin (pipe de outras ferramentas)
  - Importação de ficheiro HAR
  - Importação de coleção Postman/Insomnia
  - Importação de especificação OpenAPI
- **Controlo Granular do Scanner**:
  - Ativar/desativar scanners individuais
  - Modo ativo vs passivo
  - Simulação (dry-run) para verificações ativas
  - Configuração por scanner
- **Configuração de Rede**:
  - Suporte para proxy HTTP/HTTPS
  - Controlo de validação de certificado TLS
  - Cabeçalhos e cookies personalizados
  - Timeouts e retentativas configuráveis
- **Perfis de Digitalização**:
  - quickscan.sh (rápido, baixo impacto)
  - deepscan.sh (abrangente, verificações ativas)
  - inaccessiblescan.sh (reverificar alvos previamente inacessíveis com configurações mais lentas)
  - baselinescan.sh (gerar baseline)
  - diffscan.sh (comparar com baseline)
  - authscan.sh (digitalização autenticada)
  - sarifscan.sh (integração CI/CD)
  - scan-and-report.sh (executar digitalização + imprimir caminho do relatório mais recente)
  - split-by-host.sh (dividir alvos por host e opcionalmente distribuir digitalizações)

## Comparação com Outras Ferramentas| Feature | ApiHunter | Nuclei | ZAP | Burp Suite | ffuf |
|---------|-----------|--------|-----|------------|------|
| **Language** | Rust | Go | Java | Java | Go |
| **Performance** | ⚡⚡⚡ Assíncrono, concorrência adaptativa | ⚡⚡ Rápido paralelo | ⚡ Moderado | ⚡ Moderado | ⚡⚡⚡ Muito rápido |
| **API-First Design** | ✅ Construído para APIs | ❌ Web geral | ⚠️ Híbrido | ⚠️ Híbrido | �️ Foco em fuzzing |
| **False Positive Filtering** | ✅ Detecção de SPA, validação de corpo, verificações de referer | ⚠️ Dependente de template | ⚠️ Muitos FPs | ✅ Bom | N/A |
| **CORS/CSP Analysis** | ✅ Análise profunda de políticas | ⚠️ Templates básicos | ✅ Bom | ✅ Bom | ❌ |
| **GraphQL Introspection** | ✅ Exposição de esquema + verificações de campos sensíveis | ⚠️ Detecção básica | ⚠️ Limitado | ✅ Via extensões | ❌ |
| **OpenAPI/Swagger** | ✅ Análise de esquemas de segurança | ❌ | ✅ Apenas importação | ✅ Importação + varredura | ❌ |
| **JWT Analysis** | ✅ alg=none, segredos fracos, expiração | ⚠️ Via templates | ⚠️ Limitado | ✅ Via extensões | ❌ |
| **IDOR/BOLA Detection** | ✅ 3 camadas (não autenticado/escopo/entre usuários) | ⚠️ Templates manuais | ⚠️ Limitado | ✅ Teste manual | ❌ |
| **Secret Detection** | ✅ Sensível ao contexto (frontend vs backend) | ⚠️ Baseado em regex | ⚠️ Básico | ⚠️ Básico | ❌ |
| **Active Checks** | ✅ Opt-in (IDOR, mass-assignment, OAuth/OIDC, websocket, rate-limit, templates CVE) | ✅ Baseado em templates | ✅ Varredura ativa | ✅ Varredura ativa | ✅ Fuzzing |
| **WAF Evasion** | ✅ Rotação de UA, atrasos, retentativas, temporização adaptativa | ⚠️ Básico | ⚠️ Limitado | ✅ Bom | ⚠️ Básico |
| **CI/CD Integration** | ✅ NDJSON, SARIF, códigos de saída | ✅ JSON, SARIF | ⚠️ Relatórios XML | ⚠️ XML/JSON | ✅ JSON |
| **Baseline Diffing** | ✅ Embutido | ❌ Ferramentas externas | ❌ | ❌ | ❌ |
| **Auth Flows** | ✅ Login pré-varredura baseado em JSON | ⚠️ Injeção de cabeçalho | ✅ Gerenciamento de sessão | ✅ Gerenciamento de sessão | ⚠️ Injeção de cabeçalho |
| **Streaming Output** | ✅ NDJSON em tempo real | ❌ Apenas em lote | ❌ | ❌ | ✅ |
| **Resource Usage** | 🟢 Baixo (Rust) | 🟢 Baixo (Go) | 🟡 Alto (Java) | 🟡 Alto (Java) | 🟢 Baixo (Go) |
| **Learning Curve** | 🟢 CLI simples | 🟢 Sintaxe de template | 🟡 Complexidade GUI | 🔴 Íngreme | 🟢 Simples |
| **Extensibility** | ✅ Sistema de traits Rust | ✅ Templates YAML | ✅ Complementos | ✅ Extensões | ⚠️ Limitado |
| **License** | MIT (Gratuito) | MIT (Gratuito) | Apache 2.0 (Gratuito) | Comercial | MIT (Gratuito) |
| **Best For** | Segurança de API em CI/CD, testes de regressão, análise de CORS/GraphQL/JWT | Varredura geral de vulnerabilidades, detecção de CVEs | Testes completos de aplicações web | Teste manual de penetração, fluxos complexos | Fuzzing de diretórios/parâmetros |

### Principais Diferenciadores

**ApiHunter:** Design focado em API, detecção de SPA, diferenciação de baseline, IDOR/BOLA de 3 camadas, segredos sensíveis ao contexto, concorrência AIMD, **evasão de stealth/WAF (rotação de UA, jitter, temporização adaptativa)**, **extensibilidade dupla (templates TOML + módulos Rust)**  
**Nuclei:** Cobertura mais ampla de CVEs, apenas templates YAML, evasão básica  
**ZAP/Burp:** Testes manuais, fluxos de proxy, extensões baseadas em GUI, stealth limitado  
**ffuf:** Fuzzing puro, descoberta de conteúdo, extensibilidade limitada, evasão básica

## Início Rápido```bash
cargo build --release

# Scan URLs from a file (newline-delimited)
./target/release/apihunter --urls ./targets/cve-regression-real-public.txt --format ndjson --output ./results.ndjson

# Or scan URLs from stdin
cat ./targets/cve-regression-real-public.txt | ./target/release/apihunter --stdin --min-severity medium

A entrada de digitalização de desktop suporta:
- Entrada manual de múltiplos alvos (uma URL por linha ou separada por vírgula)
- Importação CSV via `Load CSV` (máx. 307.200 bytes / 300 KiB)
- Predefinições de digitalização guiadas: `Quick Passive` e `Deep Active`
- Limite máximo: até 3.000 alvos por execução (deduplicados + validados como URLs `http/https` absolutas)
- Controles de escopo: descoberta liga/desliga, filtragem de acessibilidade + tempo limite, máx. de endpoints por site
- Controles de versionamento de API: alternância opcional de sondagem profunda de diferenças de resposta
- Controles avançados: proxy, cabeçalhos, cookies, autenticação bearer/basic, alternância de certificado TLS inválido
- Entrada de correlação de callback SSRF cega (`OAST callback base`) para verificações ativas
- Controles de desempenho: clientes por host, concorrência adaptativa, evasão de WAF com pool de user-agent personalizado
- Cobertura total de alternância do scanner incluindo `API Versioning` e `gRPC/Protobuf`
- Seções de digitalização recolhíveis com setas alinhadas à direita; `Safety and Scan Behavior`, `Runtime Limits` e `Scanner toggles` estão recolhidas por padrão
- Cartões de progresso de execução paralela com instantâneos de conclusão/descobertas por alvo
- Painel de análise de resultados: mapa de calor de severidade, cartão do pior alvo, eficiência da digitalização, cobertura do scanner, principais caminhos vulneráveis, detalhamento de severidade de verificação
- Persistência de sessão: restauração automática dos últimos resultados de digitalização no próximo lançamento
- Painel de Modo de Enriquecimento: carregar descobertas NDJSON, executar enriquecimento de inteligência de ameaças, promover hosts com alta pontuação diretamente para Digitalização Completa com predefinição Deep Active
- UX de exportação: rótulos de tamanho + `Save All Reports` + nomes de arquivos com timestamp por execução; exportações incluem pacotes JSON por alvo, NDJSON, SARIF, coleção Insomnia e dados do Insomnia Runner

Veja [HOWTO.md](https://github.com/teycir/apihunter/blob/main/HOWTO.md) para uso detalhado, [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/main/docs/lab-setup.md) para laboratórios de validação CVE baseados em Vulhub e [docs/](https://github.com/teycir/apihunter/blob/main/docs) para detalhes internos.

Se você deseja um binário de desktop de versão:```bash
cd apps/desktop
npm run tauri build
./src-tauri/target/release/apihunter-desktop

Note: a inicialização do desenvolvimento da área de trabalho agora usa os ativos de frontend compilados diretamente e não requer um servidor `localhost:1420` separado.

Consulte [HOWTO.md](https://github.com/teycir/apihunter/blob/main/HOWTO.md) para uso detalhado, [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/main/docs/lab-setup.md) para laboratórios de validação de CVE baseados no Vulhub e [docs/](https://github.com/teycir/apihunter/blob/main/docs) para detalhes internos.

### Exemplo de Descoberta NDJSON```json
{
  "url": "https://api.example.com/graphql",
  "check": "graphql/introspection-enabled",
  "title": "GraphQL introspection is enabled",
  "severity": "MEDIUM",
  "detail": "Introspection query returned schema metadata from a public endpoint.",
  "evidence": "POST /graphql -> HTTP 200 with __schema fields in response body",
  "scanner": "graphql",
  "timestamp": "2026-03-19T14:02:11.824Z"
}

**Fluxo:** CLI args → Config → Runner orquestra Discovery + Scanners → HTTP Client (com Auth/WAF) → Reports

## Ferramentas de Template

ApiHunter suporta **extensibilidade dupla**: adicione verificações via **modelos TOML** (sem código) ou **módulos Rust** (controle total).

### Formato de Template TOML
Crie verificações personalizadas em `assets/cve_templates/*.toml`:```toml
id = "custom-api-check"
name = "Custom API Vulnerability"
severity = "high"

[[requests]]
method = "GET"
path = "/api/vulnerable"

[[requests.matchers]]
type = "status"
values = [200]

[[requests.matchers]]
type = "word"
part = "body"
words = ["sensitive_data", "exposed"]

### Adicionar Scanners Rust Personalizados
Implemente o trait `Scanner` para lógica complexa:```rust
#[async_trait]
impl Scanner for MyCustomScanner {
    async fn scan(
        &self,
        url: &str,
        client: &HttpClient,
        config: &Config,
    ) -> (Vec<Finding>, Vec<CapturedError>) {
        // Your custom scanning logic
    }
}

Todos os scripts wrapper, exceto `split-by-host.sh`, suportam `--stdin` e flags finais do ApiHunter.

## Estratégia de Testes

Os testes do ApiHunter são divididos por intenção:

- **Testes unitários** (`tests/*_scanner.rs`, testes de parser/config): lógica do scanner e casos limite.
- **Testes de integração** (`tests/integration_runner.rs`, comportamento de inicialização/CLI): orquestração e conexão em tempo de execução.
- **Testes de regressão de fixtures** (`tests/cve_templates_real_data.rs`, `tests/cve_templates_upstream_parity.rs`): reprodução de payloads reais e comparação com modelos upstream fixados.
- **Testes com servidor mock** (várias suítes de scanner): verificações de comportamento determinístico sem depender de alvos na internet.
- **Verificações em alvos reais**: opcionais/manuais apenas (não fazem parte do `cargo test` padrão).

Consulte o [Guia de Testes](https://github.com/teycir/apihunter/blob/main/docs/testing.md) dedicado para a matriz completa de testes e mapa de cobertura.

Execute suites focadas:```bash
cargo test --test cors_scanner
cargo test --test graphql_scanner
cargo test --test cve_templates_runtime_ext
cargo test --test integration_runner

Execute o gate de integração com dados reais (fixtures + suítes ignoradas ao vivo):```bash
# Fixture-backed real payload regression suites
cargo test --test cve_templates_real_data --test cve_templates_upstream_parity --test cve_templates_runtime_ext

# Manual live internet integration suites (ignored by default)
cargo test --test live_vulnerable_apis --test live_real_world_targets -- --ignored

### Artefatos de Lançamento Pré-construídos

Lançamentos com tags (`v*`) publicam binários pré-construídos do `apihunter` para:

- Linux (`x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`)
- macOS (`x86_64-apple-darwin`)
- Windows (`x86_64-pc-windows-msvc`)

Cada lançamento também publica artefatos da cadeia de suprimentos:

- Arquivos de soma de verificação SHA256 (`*.sha256`)
- Materiais de assinatura sem chave Sigstore (`*.sig`, `*.pem`, `*.sigstore.json`)
- SBOM JSON SPDX (`apihunter-release-assets-sbom.spdx.json`)
- Atestados de artefato do GitHub (metadados de proveniência e atestado de SBOM)

Baixe em [GitHub Releases](https://github.com/Teycir/ApiHunter/releases).

### Instalação no Desktop (Tauri + React)

O código-fonte do aplicativo desktop está em `apps/desktop`.

Compile e execute um binário desktop de produção:```bash
cd apps/desktop
npm install
npm run tauri build
./src-tauri/target/release/apihunter-desktop

Instale um ícone de inicialização clicável do Linux:```bash
cd apps/desktop
npm run desktop:install-icon

Execute uma verificação a partir de arquivos no seu diretório atual:```bash
docker run --rm -v "$PWD:/work" apihunter:local \
  --urls /work/targets/cve-regression-real-public.txt \
  --format ndjson \
  --output /work/results.ndjson

**P: Diffing de baseline?**```bash
./target/release/apihunter --urls targets/cve-regression-real-public.txt --format ndjson --output baseline.ndjson
./target/release/apihunter --urls targets/cve-regression-real-public.txt --baseline baseline.ndjson --format ndjson