security-pentest-planner 1.0.2__tar.gz

security_pentest_planner-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saulo Filho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

security_pentest_planner-1.0.2/PKG-INFO

@@ -0,0 +1,164 @@
+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).
+

security_pentest_planner-1.0.2/README.md

@@ -0,0 +1,141 @@
+# 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).
+

security_pentest_planner-1.0.2/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "security-pentest-planner"
+version = "1.0.2"
+description = "Generate pentest action plans from OpenAPI specifications"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Saulo Filho", email = "saulofilho@users.noreply.github.com" }
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://saulofilho.github.io/security-pentest-planner/"
+Repository = "https://github.com/saulofilho/security-pentest-planner-python"
+
+[project.scripts]
+security-pentest-planner = "security_pentest_planner.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

security_pentest_planner-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

security_pentest_planner-1.0.2/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+setup()
+

security_pentest_planner-1.0.2/src/security_pentest_planner/__init__.py

@@ -0,0 +1,48 @@
+"""security_pentest_planner package.
+
+Gera Planos de Ação de Pentest a partir de especificações OpenAPI/Swagger.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .contract_analyzer import ContractAnalyzer
+from .errors import Error, InputError, ParseError
+from .models import Category, Endpoint, Parameter, RedFlag, Vector
+from .openapi_parser import OpenAPIParser
+from .plan_renderer import PlanRenderer
+from .planner import Planner
+from .vector_catalog import VectorCatalog
+from .version import __version__
+
+
+def generate(input_path: str, **options: Any) -> str:
+    """Generate a pentest action plan from an OpenAPI specification file."""
+    return Planner(input_path=input_path, **options).call()
+
+
+def generate_from_spec(spec: dict[str, Any], **options: Any) -> str:
+    """Generate a pentest action plan from an in-memory OpenAPI specification dict."""
+    return Planner(spec=spec, **options).call()
+
+
+__all__ = [
+    "__version__",
+    "generate",
+    "generate_from_spec",
+    "Planner",
+    "OpenAPIParser",
+    "ContractAnalyzer",
+    "VectorCatalog",
+    "PlanRenderer",
+    "Endpoint",
+    "Parameter",
+    "RedFlag",
+    "Vector",
+    "Category",
+    "Error",
+    "ParseError",
+    "InputError",
+]
+

security_pentest_planner-1.0.2/src/security_pentest_planner/__main__.py

@@ -0,0 +1,8 @@
+"""Main entry point when invoked as python -m security_pentest_planner."""
+
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())
+

security_pentest_planner-1.0.2/src/security_pentest_planner/cli.py

@@ -0,0 +1,65 @@
+"""CLI entry point for security-pentest-planner."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .errors import Error
+from .planner import Planner
+from .version import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Builds the argument parser for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="security-pentest-planner",
+        description="Gera um Plano de Ação de Pentest a partir de especificação OpenAPI.",
+    )
+    parser.add_argument("input", nargs="?", help="Caminho do arquivo OpenAPI (.yaml, .yml, .json)")
+    parser.add_argument("-t", "--team", help="Nome do time no título do documento")
+    parser.add_argument("-s", "--scope", help="Limitar escopo a um path (ex: /api/v1/metrics)")
+    parser.add_argument("-d", "--datalake", action="store_true", help="Incluir vetores de Data Lake no plano")
+    parser.add_argument("--api-layer", default="API", help="Nome da camada de API no documento (default: API)")
+    parser.add_argument("--data-layer", default="Data Lake", help="Nome da camada de Data Lake no documento (default: Data Lake)")
+    parser.add_argument("-o", "--output", help="Salvar plano em arquivo (default: stdout)")
+    parser.add_argument("-v", "--version", action="version", version=f"security_pentest_planner {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main CLI execution method."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.input:
+        parser.print_help(sys.stderr)
+        return 1
+
+    try:
+        planner = Planner(
+            input_path=args.input,
+            team=args.team,
+            scope=args.scope,
+            include_datalake=args.datalake,
+            api_layer=args.api_layer,
+            data_layer=args.data_layer,
+        )
+        plan = planner.call()
+
+        if args.output:
+            Path(args.output).write_text(plan, encoding="utf-8")
+            print(f"Plano de Ação gerado em {args.output}", file=sys.stderr)
+        else:
+            print(plan)
+        return 0
+    except Error as e:
+        print(f"Erro: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+