security-pentest-planner

Site: saulofilho.github.io/security-pentest-planner

Gera Planos de Ação de Pentest a partir de especificações OpenAPI/Swagger.

Ferramenta open source para times de engenharia e AppSec que precisam estruturar testes ofensivos antes da execução — com vetores OWASP, procedimentos, payloads e critérios de validação.

O que ela faz

• Analisa contratos OpenAPI 3.x (YAML ou JSON)
• Detecta sinais de risco: tenant headers, parâmetros de data, enums, timezone livre
• Seleciona vetores OWASP API Security aplicáveis via taxonomia
• Gera um design doc em Markdown com:
  • Procedimentos passo a passo por vetor
  • Payloads e exemplos HTTP/SQL
  • Tabela resumo (Acesso · Entrada · Disponibilidade · Informação)
  • Recomendações imediatas de remediação
  • Red flags do contrato

O que ela NÃO faz

• Scripts executáveis (Requests, Python, SQL runnable)
• Resultados de teste (APROVADO/REPROVADO)
• RFCs de implementação

Esses artefatos pertencem à fase de execução do pentest.

Instalação

pip install security-pentest-planner

Ou usando uv / poetry:

uv add security-pentest-planner
# ou
poetry add security-pentest-planner

Uso via CLI

# Gerar plano no stdout
security-pentest-planner swagger/v2/swagger.json

# Salvar em arquivo
security-pentest-planner openapi.yaml -o plano-de-acao-pentest.md

# Com escopo e Data Lake
security-pentest-planner openapi.yaml \
  --team "Platform Team" \
  --scope /api/v1/metrics \
  --datalake \
  -o plano.md

Opções

Uso programático

import security_pentest_planner

# A partir de arquivo
plan = security_pentest_planner.generate(
    input_path="openapi.yaml",
    team="Platform Team",
    scope="/api/v1/metrics",
    include_datalake=True,
)

with open("plano-de-acao-pentest.md", "w", encoding="utf-8") as f:
    f.write(plan)

# A partir de um dicionário (spec já carregada)
import yaml

with open("openapi.yaml", "r", encoding="utf-8") as f:
    spec_data = yaml.safe_load(f)

plan = security_pentest_planner.generate_from_spec(
    spec=spec_data,
    team="Security Team",
)

Publicar no PyPI

python -m pip install build twine
python -m build
python -m twine upload dist/*

Desenvolvimento e Testes

git clone https://github.com/saulofilho/security-pentest-planner-python.git
cd security-pentest-planner-python

# Executar testes unitários
python3 -m unittest discover -s tests -v

# Ou com pytest
pytest -v

Fluxo recomendado

OpenAPI spec  →  security-pentest-planner  →  Plano de Ação (Markdown)
                                                       ↓
                                               Execução manual / CI
                                                       ↓
                                               Resultados + RFCs

O pacote cobre a fase de planejamento de forma determinística — ideal para CI/CD, pipelines e integração em projetos Python/FastAPI/Django/Flask.

Licença

MIT — veja LICENSE.