**Como funciona:**

1. **Claude Code** lê `CLAUDE.md` para a metodologia completa de pentest e orquestra o fluxo de trabalho de 7 fases
2. **Subagentes especializados por função** (Scout, Analyzer, Exploiter, Reporter) executam tarefas focadas com modelos de prompt dedicados, orientação de ferramentas e antipadrões
3. **Servidor MCP WSTG** (mais de 68 ferramentas) fornece procedimentos de teste OWASP, 31 guias de técnicas do PortSwigger, árvore de tarefas hierárquica, grafo de conhecimento, evasão de WAF, priorização de endpoints, verificação de resultados, compressão de contexto, portões de qualidade e geração de relatórios
4. **Contêiner Docker** executa todas as 27 ferramentas de segurança — o tráfego opcionalmente roteia pelo Burp Suite para monitoramento passivo
5. **Playwright MCP** lida com testes baseados em navegador (DOM XSS, clickjacking, páginas de login renderizadas por JS)

---

## Funcionalidades

### Cobertura Abrangente OWASP
- **109 casos de teste WSTG** em 12 categorias — desde coleta de informações até testes de API
- Cada teste inclui procedimentos CLI passo a passo, payloads específicos de contexto, critérios de detecção e rubricas de gravidade
- Testes são priorizados (DEVE/DEVERIA) com gatilhos condicionais para que nada relevante seja ignorado

### 31 Guias de Técnicas de Ataque do PortSwigger
- Obtidos da [PortSwigger Web Security Academy](https://portswigger.net/web-security) — métodos de detecção, técnicas de exploração, payloads, folhas de dicas e padrões de bypass de WAF
- Organizados por classe de vulnerabilidade (SQLi, XSS, SSRF, JWT, OAuth, etc.) para uso direto durante os testes
- Integrados em cada fase de teste — os agentes carregam automaticamente o guia de técnica relevante antes de testar cada classe de vulnerabilidade
- Tabelas de payloads específicas por banco de dados/plataforma (Oracle vs MySQL vs PostgreSQL vs MSSQL para SQLi, Jinja2 vs Twig vs Freemarker para SSTI, etc.)
- Padrões de bypass de WAF organizados por nível de bypass (básico → intermediário → avançado)

### 27 Ferramentas de Segurança Pré-Configuradas
- Todas as ferramentas pré-instaladas em uma única imagem Docker — `make setup` e você está pronto
- Ferramentas organizadas por fase: descoberta, teste de injeção, autenticação, criptografia, teste de API
- Integração automática com proxy Burp Suite para monitoramento passivo de tráfego

### Fluxo de Trabalho Estruturado em 7 Fases
- **Fase 0:** Descoberta e Mapeamento da Aplicação
- **Fase 1:** Coleta de Informações e Reconhecimento
- **Fase 2:** Teste de Configuração e Implantação
- **Fase 3:** Gerenciamento de Identidade, Autenticação, Autorização e Sessão
- **Fase 4:** Teste de Validação de Entrada (pipelines de XSS/SQLi/SSRF)
- **Fase 5:** Teste de Tratamento de Erros, Criptografia, Lógica de Negócios, Cliente e API
- **Fase 6:** Verificação de Cobertura e Relatoria
- **Fase 7:** Revisão Final do Juiz e Remediação

### Sistema de Garantia de Qualidade
- **Portões de fase automatizados** — cada fase deve passar por verificações de qualidade antes de prosseguir
- **Subagente Revisor de Qualidade** em cada transição de fase identifica lacunas e sugere melhorias
- **Juiz Final** — um agente sem contexto revisa todo o engajamento a frio, como um revisor de QA externo
- **Portões de exaustão** — "não vulnerável" requer prova de esforço de teste suficiente (técnicas mínimas e tentativas de bypass)

### Descobertas Baseadas em Evidências
- Cada descoberta requer comandos curl reproduzíveis e evidências completas de requisição/resposta
- **Classificação de três níveis:** EXPLORADO (impacto comprovado), POTENCIAL (bloqueado por controle), FALSO_POSITIVO (controle se mantém)
- **Estrutura anti-alucinação** — "sem exploração = sem descoberta" aplicado em todos os níveis
- Listas de verificação de evidências por classe de vulnerabilidade verificadas antes de qualquer descoberta ser registrada

### Subagentes Especializados por Função
- **4 funções dedicadas** com modelos de prompt focados, orientação de ferramentas e antipadrões:
  - **Scout** — apenas reconhecimento, mapeia a superfície de ataque sem enviar payloads (Fase 0-1)
  - **Analyzer** — identifica sinks potenciais com payloads canário/testemunha, constrói filas de exploração (Fase 2-5 análise)
  - **Exploiter** — consome a saída do Analyzer, comprova exploração com evidências, registra descobertas confirmadas (Fase 4 exploração)
  - **Reporter** — revisão de qualidade e Juiz Final, revisa dados sem enviar requisições (QA + pós-relatório)
- Ponto de verificação de validação entre análise e exploração evita esforço desperdiçado
- Cada função tem listas de ferramentas permitidas/restritas explícitas e contratos de entrada/saída

### Exploração em Pipeline (Fase 4)
- 3 **pipelines de dois estágios** independentes executados em paralelo: XSS, Injeção (SQLi/CMDi), SSRF/SSTI
- Cada pipeline: Analyzer (descobrir → analisar → enfileirar) → ponto de verificação de validação → Exploiter (explorar → registrar)
- Cada pipeline carrega seu guia de técnicas do PortSwigger para métodos de detecção, folhas de dicas e padrões de bypass de WAF
- Inteligência de WAF compartilhada entre todos os pipelines
- Payloads testemunha sensíveis ao contexto para 13 tipos de sink

### Evasão Adaptativa de WAF
- **Identificação automática de WAF** a partir de cabeçalhos de resposta, corpo e códigos de status — identifica 12 fornecedores de WAF (Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5, FortiWeb, Sucuri, Barracuda, Wordfence, NAXSI, Citrix)
- **Payloads de bypass específicos por fornecedor** organizados por nível de complexidade (básico → intermediário → avançado)
- Inteligência de WAF compartilhada entre todos os agentes via sistema de entregáveis
- Agentes identificam automaticamente o WAF na primeira resposta de bloqueio e alternam para payloads de bypass personalizados

### Grafo de Conhecimento Entre Fases
- **Grafo entidade-relacionamento** rastreia endpoints, parâmetros, tecnologias, descobertas, cookies, domínios e funções de usuário
- **Encadeamento automatizado de vulnerabilidades** via busca de caminho BFS com 7 padrões de cadeia predefinidos:
  - XSS + CSP ausente, XSS + cookie fraco (sem HttpOnly), Redirecionamento aberto + callback OAuth
  - IDOR + função de admin, SSRF + metadados de nuvem, Sem bloqueio + sem MFA, CORS + endpoint sensível
- Aumentos de gravidade quando o encadeamento aumenta materialmente o impacto
- Preenchido durante todo o teste, consultado após a Fase 4 para descoberta de cadeias

### Árvore de Tarefas Hierárquica
- Estrutura de árvore persistente (fases como ramos, testes como folhas) evita viés de profundidade LLM e perda de contexto
- O agente principal mantém uma visão macro estratégica; subagentes atualizam apenas seus nós folha atribuídos
- Propagação automática: quando todos os filhos completam, o pai completa automaticamente
- Percentuais de conclusão por fase para tomada de decisão informada

### Priorização de Risco de Endpoint
- Pontue e ordene endpoints por risco para teste priorizado — maior risco testado primeiro
- Fatores de pontuação: contagem de parâmetros, indicadores de risco tecnológico, confiança na cadeia de taint, convergência de ferramentas, requisitos de autenticação, nomes de parâmetros injetáveis
- Integrado na geração do mapa de endpoints da Fase 0

### Análise de Saída de Ferramentas
- **13 analisadores internos** para ferramentas CLI comuns (nmap, nuclei, sqlmap, ffuf, httpx, whatweb, testssl, nikto, dalfox, katana, gau, wapiti, commix)
- Condensa a saída bruta da ferramenta em 3-5x, preservando descobertas, endpoints e erros principais
- Nível de detalhes configurável: resumo (~15 linhas), detalhado (~50 linhas), completo (saída analisada completa)

### Verificação de Resultados de Ferramentas CLI
- Validação automática da qualidade da saída de ferramentas CLI — detecta saída vazia, erros de proxy, problemas de permissão e resultados suspeitos
- **10 validadores por ferramenta** (nmap, nuclei, sqlmap, ffuf, feroxbuster, testssl, dalfox, wapiti, katana, httpx) com sugestões de comandos corrigidos
- Quando uma ferramenta produz saída vazia ou suspeita, o validador sugere correções (ex.: adicionar `-Pn` para nmap, remover variáveis de ambiente de proxy, tentar flags diferentes)
- Integrado ao fluxo de trabalho de execução de ferramentas — agentes chamam `verify_tool_result()` após cada execução de ferramenta CLI

### Compressão Progressiva de Contexto
- **Resumos de fase** (~500-800 palavras) gerados automaticamente quando os portões de fase passam — capturando descobertas, cobertura, resultados de ferramentas e superfície de ataque de forma comprimida
- Previne degradação de contexto em engajamentos longos, substituindo dados históricos brutos por resumos estruturados
- `get_engagement_summary()` combina todos os resumos de fase em uma visão geral única para injetar em novos prompts de subagentes
- Resumos armazenados como entregáveis — acessíveis por qualquer agente downstream sem exigir histórico completo do engajamento

### Análise Contrafactual (Descoberta de Segunda Passagem)
- Após um Analyzer concluir com vulnerabilidades encontradas, um **segundo Analyzer** é gerado com instruções para "assumir que essas vulnerabilidades estão corrigidas"
- O Analyzer contrafactual busca por vulnerabilidades **adicionais**: endpoints diferentes, parâmetros diferentes, contextos de injeção diferentes, falhas de lógica
- Resultados são anexados à fila de exploração existente (mesclagem automática com deduplicação por endpoint+parâmetro e IDs auto-incrementados)
- Baseado na pesquisa PenHeal ablation mostrando +71% de cobertura de vulnerabilidades com prompting contrafactual

### Suporte a Múltiplos Domínios
- Detecção e tratamento automáticos de SSO/OAuth/OIDC/SAML
- Registro de escopo por domínio, rastreamento e teste
- Gerenciamento de cookie jar para persistência de sessão entre domínios
- Escalonamento de falha de autenticação em 6 níveis (concessões alternativas → PKCE → navegador headless → extração de token → provisionamento de usuário → não autenticado)

### Gerenciamento de Engajamento à Prova de Falhas
- `findings.md` e `progress.log` somente anexação sobrevivem a falhas
- Checkpointing de workspace Git com capacidade de reversão
- **Retomada automática em caso de interrupção** — `resume-prompt.md` gerado automaticamente em cada checkpoint com contexto completo (alvo, credenciais, fase atual, testes restantes, escopo). Cole em uma nova sessão para continuar exatamente de onde parou
- Granularidade de checkpoint entre fases — rastreia quais testes dentro de uma fase estão concluídos, não apenas o estado no nível da fase
- Trilha de auditoria completa de cada chamada de ferramenta MCP com carimbos de data/hora

### Relatoria Profissional
- Relatórios em Markdown com resumo executivo, descobertas por gravidade, matriz de cobertura de testes e cobertura de ferramentas
- Percentuais de cobertura por categoria e análise de lacunas
- Análise de encadeamento de vulnerabilidades documentada
- Observações do Juiz Final e notas de qualidade incluídas

---

## Sistema de Funções de Agentes

AutoPentest utiliza 4 funções de agentes especializadas em vez de subagentes genéricos. Cada função tem um modelo de prompt dedicado com orientação de ferramentas focada, contratos de entrada/saída e antipadrões.

| Função | Modelo | Propósito | Fases |
|--------|--------|-----------|--------|
| **Scout** | `templates/agent-roles/scout.md` | Reconhecimento e mapeamento da superfície de ataque | Fase 0-1, descoberta de código fonte |
| **Analyzer** | `templates/agent-roles/analyzer.md` | Descoberta de vulnerabilidades com payloads canário/testemunha | Fase 2-5 análise |
| **Exploiter** | `templates/agent-roles/exploiter.md` | Prova de exploração com evidências | Fase 4 exploração |
| **Reporter** | `templates/agent-roles/reporter.md` | Revisão de qualidade e Juiz Final | Transições de fase, pós-relatório |

### Como o Pipeline Funciona

A Fase 4 (teste de maior impacto) usa um pipeline de dois estágios por classe de vulnerabilidade:```
┌──────────────────────────────────────────────────────────────┐
│                    Pipeline 1: XSS                           │
│                                                              │
│  Analyzer (75 turns)          Exploiter (75 turns)           │
│  ┌─────────────────────┐      ┌─────────────────────┐        │
│  │ Discover endpoints  │      │ Load Analyzer queue │        │
│  │ Send canary payloads│─────▶│ Attempt exploitation│        │
│  │ Build exploit queue │ gate │ Prove impact        │        │
│  │ Save deliverable    │      │ Log findings        │        │
│  └─────────────────────┘      └─────────────────────┘        │
│                          ▲                                   │
│               validate_exploitation_queue()                  │
└──────────────────────────────────────────────────────────────┘

É isso. Todas as 27 ferramentas de segurança estão agora instaladas e prontas dentro do contêiner Docker.

### Verificar Instalação```bash
# Check all tools are installed
make verify-tools

# Expected output:
# [+] nuclei: installed
# [+] httpx: installed
# [+] katana: installed
# ... (27 tools total)

Então, diga ao Claude o que testar:```
Run a full WSTG assessment against https://target.example.com

Claude solicitará qualquer informação ausente (como credenciais) e iniciará o fluxo de trabalho de 7 fases.

### Opção B: Modo Orientado por Configuração (Recomendado)

Crie um arquivo de configuração YAML para avaliações repetíveis e consistentes:```yaml
# configs/my-target.yaml
target:
  url: https://app.example.com
  scope:
    - app.example.com
    - api.example.com
  exclude:
    - cdn.example.com

authentication:
  login_type: form
  login_url: https://app.example.com/login
  credentials:
    username: [email protected]
    password: secret123
  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
  success_condition:
    type: url_contains
    value: "/dashboard"

rules:
  avoid:
    - description: "Do not test logout"
      type: path
      url_path: "/logout"
  focus:
    - description: "Prioritize API endpoints"
      type: path
      url_path: "/api"

reporting:
  tester_name: "Security Team"

### Opção C: Testes Direcionados

Execute testes WSTG específicos contra endpoints específicos:```
Run WSTG-INPV-05 (SQL Injection) against https://app.example.com/search?q=

## Concluindo

Esta ferramenta foi projetada para ajudar pesquisadores de segurança e testadores de penetração a avaliar a segurança de aplicações web. Use-a com responsabilidade e apenas em sistemas que você possui ou tem permissão explícita para testar.

Os autores não são responsáveis por qualquer uso indevido ou dano causado por esta ferramenta.

> **Nota:** Sempre certifique-se de cumprir as leis e regulamentos aplicáveis ao usar ferramentas de segurança.```
Run all authentication tests (WSTG-ATHN) against https://app.example.com

---

## Fases de Teste

### Fase 0: Descoberta e Mapeamento da Aplicação

A fase fundamental crítica. Claude autonomamente:

1. **Verificações de pré-voo** — verifica a alcançabilidade do alvo, detecta redirecionamentos e autenticação entre domínios
2. **Lança 10+ ferramentas em segundo plano** em paralelo (katana, ffuf, nuclei, whatweb, gau, nmap, feroxbuster, wapiti, httpx)
3. **Rastreamento recursivo** — segue links até profundidade 2-3, analisa HTML/JS em busca de endpoints
4. **Força bruta de diretórios** — caminhos comuns + wordlists específicas de tecnologia
5. **Ingestão de resultados das ferramentas** — lê todas as saídas das ferramentas em segundo plano e mescla em um mapa unificado de endpoints
6. **Constrói inventário estruturado de endpoints** com parâmetros, requisitos de autenticação e classificações de prioridade

**Saída:** Um mapa completo de endpoints organizado por domínio, pronto para testes sistemáticos.

### Fase 1-2: Reconhecimento e Configuração

- Fingerprinting de servidor, detecção de tecnologia, revisão de metadados
- Análise de cabeçalhos de segurança (HSTS, CSP, CORS, X-Frame-Options)
- Teste de configuração TLS, descoberta de interface administrativa
- Teste de métodos HTTP, manipulação de extensões de arquivo

### Fase 3: Autenticação, Autorização e Gerenciamento de Sessão

- **Grade de funções/ privilégios** construída antes dos testes (mapeia proteções, middleware e testes de bypass)
- Teste de IDOR com múltiplos IDs alternativos por endpoint
- Teste de CSRF em cada endpoint que altera estado
- Fixação de sessão, sequestro e análise de tokens
- Teste de vulnerabilidade JWT (se aplicável)
- Teste de fraqueza OAuth/OIDC (se aplicável)

### Fase 4: Validação de Entrada (Maior Impacto)

Três pipelines independentes de dois estágios são executados em paralelo, cada um usando a divisão de papéis Analisador→Explorador:

| Pipeline | Classes de Vulnerabilidade | Ferramentas | Guias de Técnica |
|----------|----------------------|-------|-----------------|
| Pipeline XSS | XSS Refletido, XSS Armazenado, XSS DOM | dalfox, Playwright | XSS, DOM |
| Pipeline de Injeção | Injeção SQL, Injeção de Comandos, Injeção NoSQL | sqlmap, commix, nosqli | SQLI, CMDI, NOSQLI |
| Pipeline SSRF/SSTI | SSRF, SSTI, Path Traversal | sstimap, ssrfmap | SSRF, SSTI, PTRAV |

Cada pipeline: **Analisador** (descobrir → analisar → construir fila de exploração) → ponto de verificação de validação → **Explorador** (tentar exploração → provar impacto → registrar descobertas). A inteligência de evasão de WAF é compartilhada entre todos os pipelines.

### Fase 5: Tratamento de Erros, Criptografia, Lógica de Negócio, Lado do Cliente e APIs

- Divulgação de stack trace e mensagens de erro
- Teste TLS/SSL via testssl.sh
- Bypass de lógica de negócio (burla de fluxo de trabalho, falsificação de requisição)
- Teste do lado do cliente (clickjacking, redirecionamentos abertos, manipulação DOM)
- Teste de API GraphQL e REST
- Análise de encadeamento de vulnerabilidades em todas as descobertas

### Fase 6: Relatórios

- Verificação de cobertura (cobertura de teste + cobertura de ferramenta)
- Deduplicação de descobertas e calibração de severidade
- Geração de relatório Markdown com resumo executivo, descobertas, matrizes de cobertura

### Fase 7: Revisão Final do Juiz

Um agente de contexto zero revisa todo o engajamento friamente — sem conhecimento das decisões ou dificuldades dos testes. Ele examina:

- **Integridade da cobertura** — testes carimbados, endpoints ausentes
- **Detecção de cascata N/A** — categorias com marcações excessivas de 'não aplicável'
- **Qualidade das descobertas** — completude das evidências, consistência de severidade, oportunidades de encadeamento
- **Utilização de ferramentas** — ferramentas executadas mas saída nunca revisada, razões preguiçosas para pular
- **Superfície de ataque perdida** — endpoints não testados, parâmetros não testados, domínios não testados

O veredito (PASS/CONDITIONAL_PASS/FAIL) aciona ações específicas de remediação antes da entrega do relatório.

---

## Ferramentas de Segurança

### Descoberta e Reconhecimento (Fase 0)

| Ferramenta | Propósito | Flags Principais |
|------|---------|-----------|
| **katana** | Rastreador web com renderização JS | `-jc` para rastreamento JavaScript |
| **httpx** | Sondagem HTTP, detecção de tecnologia | `-tech-detect -status-code -title` |
| **ffuf** | Fuzzing de diretório/parâmetro | `-w wordlist -mc all -fc 404` |
| **feroxbuster** | Enumeração recursiva de diretórios | `--smart --auto-tune` |
| **nuclei** | Scanner de vulnerabilidades baseado em templates | `-t cves/ -t misconfigurations/` |
| **nikto** | Má configuração de servidor web | `-Tuning 1234567890` |
| **whatweb** | Fingerprinting de tecnologia | `--aggression 3` |
| **nmap** | Varredura de portas e serviços | `-sV -sC --top-ports 1000` |
| **gau** | Descoberta de URLs históricos | `--blacklist png,jpg,gif` |
| **subfinder** | Enumeração de subdomínios | `-silent -all` |

### Teste de Injeção (Fase 4)

| Ferramenta | Propósito | Flags Principais |
|------|---------|-----------|
| **sqlmap** | Injeção SQL (todas as técnicas) | `--batch --risk 3 --level 5` |
| **dalfox** | Varredura e exploração XSS | `--skip-bav --deep-domxss` |
| **commix** | Injeção de comandos | `--batch --all` |
| **sstimap** | Injeção de Template no Lado do Servidor | `-u <url>` |
| **ssrfmap** | Exploração SSRF | `-r request.txt` |
| **nosqli** | Injeção NoSQL | `-u <url>` |
| **crlfuzz** | Injeção CRLF / divisão HTTP | `-u <url>` |
| **smuggler** | Contrabando de requisição HTTP | `-u <url>` |

### Autenticação e Sessão (Fase 3)

| Ferramenta | Propósito | Flags Principais |
|------|---------|-----------|
| **hydra** | Força bruta de credenciais | `-L users.txt -P pass.txt` |
| **jwt_tool** | Análise e exploração de tokens JWT | `-t <token> -M at` |

### Criptografia e APIs (Fase 5)

| Ferramenta | Propósito | Flags Principais |
|------|---------|-----------|
| **testssl.sh** | Teste de configuração TLS/SSL | `--severity HIGH --sneaky` |
| **graphql-cop** | Teste de segurança GraphQL | `-t <url>` |
| **websocat** | Teste de WebSocket | `ws://<url>` |

### Infraestrutura (Fase 2)

| Ferramenta | Propósito |
|------|---------|
| **corscanner** | Varredura de má configuração CORS |
| **dnsreaper** | Detecção de takeover de subdomínio |

### Automação de Navegador

| Ferramenta | Propósito |
|------|---------|
| **Playwright** | Prova de XSS DOM, clickjacking, login renderizado por JS, inspeção de armazenamento do lado do cliente |

---

## Base de Conhecimento WSTG

109 casos de teste em 12 categorias OWASP, cada um com procedimentos específicos de CLI:

| Código | Categoria | Testes | Exemplos |
|------|----------|:-----:|---------|
| **INFO** | Coleta de Informações | 10 | Descoberta em motores de busca, fingerprinting de servidor, revisão de metadados |
| **CONF** | Configuração e Implantação | 14 | Cabeçalhos de segurança, CORS, CSP, HSTS, interfaces administrativas |
| **IDNT** | Gerenciamento de Identidade | 5 | Definições de papéis, registro, enumeração de contas |
| **ATHN** | Autenticação | 11 | Credenciais padrão, bloqueio, bypass de autenticação, MFA, política de senhas |
| **ATHZ** | Autorização | 5 | Directory traversal, bypass de autenticação, escalonamento de privilégio, IDOR |
| **SESS** | Gerenciamento de Sessão | 11 | Atributos de cookie, CSRF, fixação/sequestro de sessão, JWT |
| **INPV** | Validação de Entrada | 20 | XSS, SQLi, CMDi, SSTI, SSRF, path traversal, XXE, LDAP |
| **ERRH** | Tratamento de Erros | 2 | Mensagens de erro, stack traces |
| **CRYP** | Criptografia | 4 | Configuração TLS, padding oracle, criptografia fraca |
| **BUSL** | Lógica de Negócio | 10 | Bypass de fluxo de trabalho, falsificação de requisição, upload de arquivo, limites de taxa |
| **CLNT** | Lado do Cliente | 14 | XSS DOM, clickjacking, redirecionamentos abertos, WebSockets, armazenamento |
| **APIT** | Teste de API | 3 | GraphQL, REST, SOAP |

Cada arquivo de teste inclui:
- Procedimentos CLI passo a passo (comandos curl, invocações de ferramentas)
- Payloads organizados por nível de bypass (básico, intermediário, avançado)
- Critérios de detecção com rubricas de avaliação de severidade
- Orientação de remediação com referências

---

## Guias de Técnica PortSwigger

31 guias de referência de técnicas de ataque provenientes da [PortSwigger Web Security Academy](https://portswigger.net/web-security), organizados por classe de vulnerabilidade para uso direto durante engajamentos reais de pentest.

### O que está Incluído

| Código | Categoria | Mapeamento WSTG | Conteúdo Principal |
|------|----------|-------------|-------------|
| **SQLI** | Injeção SQL | INPV-05 | Técnicas UNION/cega/baseada em erro/temporal/OOB, folhas de dicas específicas de banco de dados (Oracle, MySQL, PostgreSQL, MSSQL), bypass de WAF |
| **XSS** | Cross-Site Scripting | INPV-01, INPV-02, CLNT-01 | Contextos refletido/armazenado/DOM, payloads de tags e manipuladores de eventos, bypass de CSP, evasão de filtros |
| **CMDI** | Injeção de Comandos do SO | INPV-12 | Caracteres separadores, técnicas cegas (atraso de tempo, OOB), payloads específicos de SO |
| **SSTI** | Injeção de Template no Lado do Servidor | INPV-18 | Detecção e exploração Jinja2/Twig/Freemarker/Velocity/ERB, escapes de sandbox |
| **SSRF** | Server-Side Request Forgery | INPV-19 | Truques de esquema de URL, ofuscação de IP, rebinding de DNS, metadados de nuvem, bypass de filtro |
| **PTRAV** | Path Traversal | INPV-04 | Variações de codificação, injeção de byte nulo, bypass de wrapper |
| **XXE** | Entidades Externas XML | INPV-07 | Recuperação de arquivo, SSRF via XXE, XXE cego com OOB, entidades de parâmetro |
| **AUTHN** | Autenticação | ATHN-01 a ATHN-07 | Força bruta, bypass de 2FA, envenenamento de redefinição de senha, credential stuffing |
| **AUTHZ** | Controle de Acesso | ATHZ-01 a ATHZ-04 | IDOR, escalonamento de privilégio, bypass horizontal/vertical, controles baseados em referer |
| **JWT** | JSON Web Tokens | SESS-10 | Confusão de algoritmo (none/HS256→RS256), injeção kid, exploração JWK/JKU |
| **OAUTH** | OAuth 2.0 | ATHZ-05 | Roubo de código de autorização, redirecionamento aberto, upgrade de escopo, CSRF em fluxos OAuth |
| **CSRF** | Cross-Site Request Forgery | SESS-05 | Bypass de token, bypass de SameSite, bypass de validação de referer |
| **SMUGGLE** | Contrabando de Requisição HTTP | INPV-15 | CL.TE, TE.CL, TE.TE, downgrade HTTP/2, tunelamento de requisição |
| **DOM** | Vulnerabilidades Baseadas em DOM | CLNT-01 | Fontes/destinos, DOM clobbering, gadgets de poluição de protótipo |
| **CORS** | Compartilhamento de Recursos entre Origens | CONF-13, CLNT-07 | Reflexão de origem, origem nula, exploração de confiança em subdomínio |
| **NOSQLI** | Injeção NoSQL | INPV-05 | Injeção de operador MongoDB, injeção JavaScript, extração cega |
| **GRAPHQL** | GraphQL | APIT-01 | Introspecção, sugestão de campo, ataques de loteamento, bypass de autorização |
| **RACE** | Condições de Corrida | BUSL-04 | Estouro de limite, TOCTOU, corridas de endpoint único, sincronização de último quadro |
| **UPLOAD** | Upload de Arquivo | BUSL-08, BUSL-09 | Bypass de extensão, manipulação de content-type, web shells, arquivos poliglotas |
| **HOST** | Injeção de Cabeçalho Host | INPV-17 | Envenenamento de redefinição de senha, envenenamento de cache, SSRF baseado em roteamento |

Mais 11: CLICK, WS, CACHEPOIS, CACHEDEC, DESER, INFO, BUSL, PROTO, API, LLM, SKILLS.

### Como São Usados

Os guias de técnica são integrados em cada fase de teste através da ferramenta MCP `get_technique_guide()`:```
Phase 2 → CORS guide for CONF-13 testing
Phase 3 → AUTHN, AUTHZ, CSRF, JWT, OAUTH guides for auth/session testing
Phase 4 → SQLI, XSS, CMDI, SSTI, SSRF, PTRAV, XXE guides for input validation
Phase 5 → DOM, CLICK, GRAPHQL, RACE, UPLOAD guides for client-side & business logic

O solver tem dois modos:
- **autopentest** (padrão): Executa Claude Code a partir da raiz do projeto, carregando `.mcp.json` (servidor MCP com 68+ ferramentas) e `CLAUDE.md` (metodologia de pentest). Mede a capacidade total do AutoPentest.
- **raw** (`RAW=1`): Executa Claude Code puro, sem servidor MCP ou metodologia. Linha de base para medir o valor agregado do AutoPentest em relação à capacidade bruta do LLM.

Cada desafio é um aplicativo Docker Compose com uma flag injetada no momento da compilação. A extração da flag da saída do Claude determina aprovação/reprovação. Os resultados são pontuados por desafio, por tag e por nível de dificuldade.

### Modo CTF

Para desafios CTF e aplicativos pequenos, ative o modo CTF para gates de qualidade mais relaxados:```yaml
mode: ctf
target:
  url: https://target.com

### Exemplo de Descoberta (SQL Injection)

Do relatório — uma descoberta crítica de SQL injection com evidência completa de exploração:```
FINDING-017: SQL Injection in /catalog category parameter — Full Data Extraction

Severity: Critical
WSTG Reference: WSTG-INPV-05

The category parameter is vulnerable to UNION-based SQL injection.
The attacker can:
  1. Inject a single quote to cause a 500 error (confirming injection)
  2. Use UNION SELECT with 8 columns to extract arbitrary data
  3. Enumerate tables: PRODUCTS, TRACKING, USERS
  4. Extract credentials from the USERS table

Evidence (reproducible curl command):
  curl -sk "https://ginandjuice.shop/catalog?category='+UNION+SELECT+1,USERNAME,PASSWORD,
  1,1,USERNAME,1,USERNAME+FROM+USERS+LIMIT+10--"

### Configuração do Servidor MCP

O arquivo `.mcp.json` registra dois servidores MCP:```json
{
  "mcpServers": {
    "wstg-pentest": {
      "command": "uv",
      "args": ["--directory", "./server", "run", "server.py"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Todos os domínios são automaticamente registrados no escopo com seus respectivos tipos (app, auth_provider, api, cdn).

### Testes por Domínio

Cada teste WSTG é avaliado por domínio — não apenas o principal:

- Ferramentas de descoberta (katana, ffuf, nuclei) são executadas contra **todos** os domínios
- Ferramentas de validação de entrada (sqlmap, dalfox) têm como alvo endpoints em **todos** os domínios com processamento no servidor
- Um teste é "não aplicável" apenas quando **nenhum** domínio possui a funcionalidade testada

### Autenticação entre Domínios

Protocolos SSO suportados:
- **OAuth 2.0 / OIDC** (Authorization Code, PKCE, Password Grant, Client Credentials)
- **SAML** (fluxo iniciado pelo SP)
- **Keycloak**, **Auth0**, **Okta**, **Azure AD**
- **SSO Personalizado** (seguimento de cadeia de redirecionamento com cookie jar)

O procedimento de escalonamento de autenticação (6 níveis) garante que os testes possam prosseguir mesmo com fluxos de autenticação complexos.

---

## Recuperação de Falhas

O AutoPentest foi projetado para sobreviver a interrupções:

### Checkpointing Automático
- Os portões de fase salvam checkpoints automaticamente ao PASSAR
- `git_checkpoint()` cria snapshots git do workspace do engajamento
- Logs somente anexação (`findings.md`, `progress.log`) sobrevivem a falhas

### Retomada Automática via resume-prompt.md (Recomendado)

Cada checkpoint e portão de fase gera automaticamente `engagements/<eid>/resume-prompt.md` — um prompt completo e autocontido com tudo que uma nova sessão precisa:

- URL alvo, credenciais de autenticação e domínios de escopo
- Fase atual e quais testes específicos permanecem (precisão no meio da fase)
- Status do cookie jar e instruções de reautenticação
- Regras de evitar/foco e referências do mapa de endpoints

**Para retomar após uma interrupção:**
1. Abra uma nova sessão do Claude Code
2. Cole o conteúdo de `engagements/<eid>/resume-prompt.md`
3. O Claude retoma exatamente de onde parou — nenhum contexto manual necessário

### Retomar do Checkpoint (Alternativo)```
Resume engagement pentest-2026-02-11-myapp

### Reversão em Caso de Falha

Se uma fase produzir maus resultados, reverta para o checkpoint anterior:```
Roll back the engagement to the last checkpoint

---

## Requisitos

| Requisito | Versão | Notas |
|-------------|---------|-------|
| Docker | 20.10+ | Docker Desktop no macOS/Windows |
| Claude Code | Última | `npm install -g @anthropic-ai/claude-code` |
| uv | 0.1+ | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Node.js | 18+ | Para o servidor MCP do Playwright |
| Python | 3.10+ | Gerenciado pelo uv (sem instalação manual necessária) |
| Burp Suite Pro | Última | **Opcional** — para monitoramento passivo de tráfego |

**Plataformas suportadas:** macOS (Apple Silicon & Intel), Linux (x86_64 & ARM64)

---

## FAQ

**P: Isso substitui um testador de penetração humano?**

R: Não. O AutoPentest automatiza as partes sistemáticas e orientadas por metodologia de um pentest. Ele se destaca em cobertura (garantindo que nada seja perdido) e consistência (cada teste segue o mesmo procedimento). No entanto, lógica de negócios complexa, cadeias de exploração criativas e avaliação de risco dependente de contexto ainda se beneficiam da expertise humana. Pense nisso como um multiplicador de força.

**P: Quanto tempo leva uma avaliação completa?**

R: Depende do tamanho e complexidade da aplicação. Uma aplicação web típica de médio porte (50-100 endpoints) leva algumas horas. Aplicações com múltiplos domínios e SSO levam mais tempo. A arquitetura pipeline da Fase 4 paraleliza os testes mais intensivos em tempo.

**P: Posso executar sem o Burp Suite?**

R: Sim. O Burp Suite é opcional e usado apenas para monitoramento passivo de tráfego. Todas as requisições HTTP passam por `docker exec curl` e todas as ferramentas de segurança executam dentro do container Docker. Sem o Burp, você perde a capacidade de revisar o tráfego no histórico de proxy do Burp, mas toda a funcionalidade de teste funciona.

**P: O que são os guias de técnica do PortSwigger?**

R: 31 guias de referência de ataque que cobrem detecção, técnicas de exploração, payloads, cheat sheets e padrões de bypass de WAF — provenientes da PortSwigger Web Security Academy. Durante os testes, os agentes carregam automaticamente o guia relevante (por exemplo, o guia de SQLi ao testar injeção SQL) para referência abrangente de técnicas e payloads. Consulte [`docs/adding-knowledge-base-resources.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/docs/adding-knowledge-base-resources.md) para adicionar seus próprios guias.

**P: Como adiciono wordlists ou payloads personalizados?**

R: Coloque wordlists em `templates/wordlists/` e elas estarão disponíveis dentro do container Docker via montagem de volume. Os arquivos de teste WSTG em `knowledge-base/` também podem ser personalizados com payloads adicionais. Para adicionar novos guias de técnicas de ataque, siga as instruções em [`docs/adding-knowledge-base-resources.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/docs/adding-knowledge-base-resources.md).

**P: Posso testar aplicações atrás de uma VPN?**

R: Sim. O container Docker herda a rede do host (no Linux com `--network host`) ou acessa o host via `host.docker.internal` (no macOS/Windows). Se sua VPN estiver em execução no host, o container pode alcançar alvos protegidos por VPN.

**P: O que acontece se um pentest for interrompido (falha, limite de uso, timeout)?**

R: O AutoPentest gera automaticamente um arquivo `resume-prompt.md` em cada ponto de verificação com tudo necessário para continuar. Abra uma nova sessão do Claude Code, cole o conteúdo de `engagements/<eid>/resume-prompt.md`, e o teste retoma exatamente de onde parou — incluindo progresso no meio da fase, credenciais, escopo e testes restantes.

**P: E sobre limitação de taxa (rate limiting)?**

R: O AutoPentest inclui classificação de erro em três níveis (Transitório/Limite de Taxa/Permanente) com backoff automático. Se o alvo limitar requisições, as ferramentas automaticamente diminuem. Você também pode definir regras de evitação no config para pular endpoints específicos.

**P: Quais são os papéis dos agentes?**

R: O AutoPentest usa 4 papéis especializados (Scout, Analyzer, Exploiter, Reporter) em vez de subagentes genéricos. Cada papel possui um modelo de prompt dedicado com orientação focada em ferramentas, listas restritas de ferramentas e antipadrões. Isso impede que os agentes confundam reconhecimento, análise, exploração e relatório — melhorando o foco e o isolamento de falhas. Veja [`templates/agent-roles/README.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/templates/agent-roles/README.md) para o índice completo de papéis.

**P: Como funciona a evasão de WAF?**

R: Quando um payload é bloqueado (403, página de bloqueio), o AutoPentest automaticamente identifica o fornecedor do WAF a partir das características da resposta e carrega payloads de bypass específicos do fornecedor, organizados por nível de complexidade. 12 fornecedores de WAF são suportados (Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5 e mais). A inteligência de WAF é compartilhada entre todos os agentes através do sistema de entregáveis.

**P: O que é análise contrafactual?**

R: Após a primeira passagem de análise encontrar vulnerabilidades, o AutoPentest pode gerar um segundo Analyzer que assume que todas as vulnerabilidades conhecidas foram corrigidas. Isso força o agente a procurar vetores de ataque diferentes — endpoints, parâmetros, contextos de injeção e falhas lógicas diferentes. Os resultados são mesclados na fila de exploração existente com desduplicação automática. Esta técnica é baseada em pesquisa acadêmica (estudo de ablação PenHeal) que mostra um ganho de +71% na cobertura de vulnerabilidades.

**P: Como funciona a verificação de resultados?**

R: Quando ferramentas de CLI (nmap, nuclei, sqlmap, etc.) produzem saída vazia ou suspeita, a ferramenta `verify_tool_result()` detecta problemas comuns (erros de proxy, permissão negada, flags erradas) e sugere comandos corrigidos. Isso impede que agentes contem silenciosamente execuções de ferramentas quebradas como "concluídas" — um modo de falha comum em pentest automatizado.

**P: Como funciona o encadeamento de vulnerabilidades?**

R: O grafo de conhecimento rastreia entidades (endpoints, parâmetros, achados, cookies, domínios) e relacionamentos descobertos durante os testes. Após a Fase 4, `find_chains()` usa BFS para descobrir caminhos de ataque com múltiplos saltos e verifica 7 padrões de cadeia predefinidos (ex.: XSS + CSP ausente, SSRF + metadados de nuvem, IDOR + função admin). Cadeias que aumentam o impacto acionam upgrades automáticos de severidade.

---

## Aviso Legal

**Esta ferramenta é destinada apenas para testes de segurança autorizados.** Utilize o AutoPentest apenas contra aplicações para as quais você tenha permissão explícita para testar. O acesso não autorizado a sistemas de computador é ilegal. Os autores não são responsáveis por qualquer uso indevido desta ferramenta.

Sempre certifique-se de ter:
- Autorização por escrito do proprietário da aplicação
- Um escopo claramente definido do que pode e não pode ser testado
- Uma compreensão do ambiente de teste (produção vs homologação)
- Regras de evitação apropriadas configuradas para endpoints destrutivos ou sensíveis

---

<p align="center">
  Construído com <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
</p>