Metadata-Version: 2.4
Name: security-pentest-planner
Version: 1.0.2
Summary: Generate pentest action plans from OpenAPI specifications
Author-email: Saulo Filho <saulofilho@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://saulofilho.github.io/security-pentest-planner/
Project-URL: Repository, https://github.com/saulofilho/security-pentest-planner-python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# security-pentest-planner

[![PyPI version](https://badge.fury.io/py/security-pentest-planner.svg)](https://badge.fury.io/py/security-pentest-planner)
[![Python Versions](https://img.shields.io/pypi/pyversions/security-pentest-planner.svg)](https://pypi.org/project/security-pentest-planner/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Site:** [saulofilho.github.io/security-pentest-planner](https://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

```bash
pip install security-pentest-planner
```

Ou usando `uv` / `poetry`:

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

## Uso via CLI

```bash
# 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

| Flag | Descrição |
|------|-----------|
| `-t, --team TEAM` | Nome do time no título |
| `-s, --scope PATH` | Limitar a um endpoint |
| `-d, --datalake` | Incluir vetores de Data Lake |
| `--api-layer NAME` | Nome da camada API (default: API) |
| `--data-layer NAME` | Nome da camada Data Lake (default: Data Lake) |
| `-o, --output FILE` | Salvar em arquivo |
| `-v, --version` | Exibe a versão |
| `-h, --help` | Exibe a ajuda |

## Uso programático

```python
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

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

## Desenvolvimento e Testes

```bash
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](LICENSE).

