maxpentest

Sistema de apoio a pentest guiado pelas metodologias OWASP WSTG, OWASP Top 10:2025, OWASP API Security Top 10:2023 e PTES. Ele organiza clientes, projetos, escopo, termos de autorização, checklists, achados com CVSS v3.1, importação de saídas de ferramentas e geração de relatórios DOCX.

O guia completo de construção, com as 7 etapas, a arquitetura e as considerações éticas, está em docs/GUIA.md. O checklist operacional de campo está em GUIA_EXECUCAO.md.

O que o sistema faz e o que ele não faz

• Importa resultados já coletados (nmap XML, Nikto XML, JSON/JSON Lines genérico, CSV genérico).
• Não tem terminal web e não dispara ataques automaticamente. A única exceção é o Nikto, e só com tudo ligado (ver Execução do Nikto): feature habilitada por configuração, projeto em andamento com termo assinado, alvo dentro do escopo autorizado, papel pentester/admin e binário nikto no PATH.
• Nenhum projeto vai para "em andamento" sem termo de autorização assinado (gate obrigatório). Registrar resultados de checklist, gerar achados e importar exigem projeto em andamento.
• Toda ação relevante gera registro de auditoria: quem, quando, o quê e IP.
• A IA (Anthropic, Groq ou Gemini, com a chave do próprio usuário) é opcional. Ela só devolve um rascunho de triagem. Nada é aplicado ao achado sem aceite humano, e o aceite é auditado.

Executar localmente

python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env              # defina SECRET_KEY
export FLASK_APP=wsgi.py          # Windows PowerShell: $env:FLASK_APP="wsgi.py"
flask db upgrade
flask seed-checklists
flask create-user admin --role admin
flask run

Ambiente opcional com PostgreSQL: docker compose up --build (defina SECRET_KEY e POSTGRES_PASSWORD no .env).

Testes

python -m pytest -q

A suíte cobre:

• a completude dos checklists contra as listas oficiais OWASP;
• a calculadora CVSS v3.1 com vetores de referência;
• o gate de autorização e o controle de acesso por projeto;
• o workflow de achados, os parsers e a importação auditada;
• o relatório determinístico;
• o parser e o executor do Nikto, sempre com subprocess.run mockado (nenhum teste executa binário);
• a integração com IA, sempre com mock. Os testes bloqueiam qualquer chamada de rede real.

Estrutura

app/
  models/         Client, Project, Scope, AuthorizationDocument, Checklist*, Finding, Evidence, Asset, TriageSuggestion, AuditLog, User
  routes/         blueprints: core, auth, clients, projects, checklists, findings, imports, reports, ai
  methodologies/  seeds JSON (WSTG, Top 10:2025, API Top 10:2023, PTES)
  parsers/        nmap_parser.py, nikto_parser.py, json_parser.py, csv_parser.py
  execution/      nikto.py (subprocesso opt-in, alvo validado contra o escopo)
  reports/        geração DOCX + gráfico de severidade
  ai/             AIClient fino + prompts com guard-rails
  cvss.py         calculadora CVSS v3.1 (função pura)
  scope.py        verificação de alvo dentro/fora do escopo
migrations/       Flask-Migrate (Alembic)
tests/            pytest
tools/            utilitários de desenvolvimento (gerador de seeds, catálogo de ferramentas)
docs/GUIA.md      guia de construção

Execução do Nikto (opt-in)

O Nikto é a única ferramenta que o sistema pode executar, e nada acontece por padrão (EXEC_NIKTO_ENABLED=0). Para ligar, defina no .env:

EXEC_NIKTO_ENABLED=1
EXEC_NIKTO_TIMEOUT=600          # limite em segundos (5..3600)

Instale o Nikto no servidor: apt install nikto (Linux/Docker) ou, no Windows com Perl, nikto.pl no PATH. A aba Nikto do projeto então:

• aceita um alvo http(s)://host[:porta][/caminho] e recusa localhost, loopback e metadata endpoints, mesmo que o escopo os contenha;
• exige projeto em andamento (termo de autorização assinado) e alvo dentro do escopo;
• roda nikto -h <alvo> -Format xml -nointeractive -timeout 10 [-ssl] [-Tuning x] -output <tmp> como subprocesso, com tempo limite, e interrompe no estouro;
• importa o XML: cada <item> vira um Finding aberto com origem nikto <alvo>; o XML bruto fica anexado ao projeto como evidência; início, sucesso, recusa por escopo e falha vão para a auditoria.

O resto das ferramentas (nuclei, ZAP, Burp, ffuf, sqlmap, testssl...) não é executado: quem usa roda fora e importa a saída (nmap XML, Nikto XML, JSON/JSONL, CSV). Para orientar esse passo, cada item de checklist carrega em ferramentas_sugeridas as ferramentas adequadas, com nota de cuidado quando aplicável (ex.: sqlmap só em modo detecção, sem --dump).

tools/enriquecer_ferramentas.py mantém essa lista: mapeia palavras-chave e códigos WSTG/PTES para ferramentas open source conhecidas (Burp, ZAP, nuclei, ffuf, sqlmap, dalfox, testssl.sh, gitleaks, Impacket, LinPEAS e outras), com o link do projeto e a forma de instalação. Ele só reescreve os JSON de seed, não instala nada.

python tools/enriquecer_ferramentas.py --dry   # mostra o que mudaria
python tools/enriquecer_ferramentas.py         # aplica
flask seed-checklists                          # recarrega os itens no banco

Uso ético

Use apenas em alvos com autorização formal e escrita, dentro do escopo e da janela acordados. Veja a seção "Considerações éticas e legais" em docs/GUIA.md.