security-pentest-planner

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

Gera planos de ação de pentest a partir de OpenAPI/Swagger — como CLI, biblioteca Python e plugin de agente (skills + MCP) no estilo obra/superpowers: escopo autorizado → riscos do contrato → plano determinístico → remediações → RFCs seletivos.

Novidades da 1.2.0: CHANGELOG.md — sete skills, hook de session-start e plugins para Claude, Cursor, Codex e Gemini.

Precisa de Claude Pro?

• Publicar no Directory: sim — Pro, Max, Team ou Enterprise (docs). Free não submete.
• PyPI, GitHub, Pages, instalar plugin local / marketplace self-host: não.

Detalhes: docs/PUBLISH.md.

What it does

• Parses OpenAPI 3.x (YAML/JSON)
• Detects risk signals (tenant headers, dates, enums, free-form timezones, Data Lake)
• Selects OWASP API vectors via taxonomy
• Emits a Markdown design/action plan (procedures, payloads as examples, matrix, remediations hints)
• MCP server: generate_pentest_plan and planner_version (pip install "security-pentest-planner[mcp]")
• Agent skill pipeline: scope → contract risks → plan → remediations → selective RFCs → handoff
• Session-start hook injects using-pentest-planner

What it does NOT do

• Executable attack scripts
• PASS/FAIL test results
• Merge-ready implementation PRs

Installation (Python)

pip install security-pentest-planner
# MCP for agents:
pip install "security-pentest-planner[mcp]"

CLI

security-pentest-planner openapi.yaml -o pentest-action-plan.md
security-pentest-planner openapi.yaml --team "Platform" --scope /api/v1/metrics --datalake -o plan.md

Install by harness (skills + MCP)

Harness	Install
Claude Code (local)	claude plugin validate ./plugin then claude --plugin-dir ./plugin
Claude marketplace (self-host)	/plugin marketplace add saulofilho/security-pentest-planner-python → /plugin install security-pentest-planner@security-pentest-planner-python
Claude Directory	After listing — see docs/MARKETPLACE.md (Pro+ to submit)
Cursor	.cursor-plugin/ present — /add-plugin from marketplace when listed, or open this repo
Codex	.codex-plugin/ — install from OpenAI plugin marketplace when listed, or local path
Gemini CLI	gemini extensions install https://github.com/saulofilho/security-pentest-planner-python

Requires uv on PATH so the plugin can start MCP via uvx.

Skills (methodology)

Skill	Role
using-pentest-planner	Bootstrap — when/how to invoke skills
scoping-authorized-pentest	Authorization + bounds
reviewing-openapi-risks	Contract red-flags
security-pentest-planner	MCP plan + pipeline
writing-remediations	remediacoes.md
writing-security-rfcs	Selective P0 RFCs
verifying-pentest-handoff	Close AppSec → eng handoff

Session-start hook injects using-pentest-planner (same idea as Superpowers).

Programmatic usage

import security_pentest_planner

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

From an in-memory spec (FastAPI, Flask, or any dict):

from fastapi.openapi.utils import get_openapi
import security_pentest_planner
from my_app.main import app

spec = get_openapi(title=app.title, version=app.version, routes=app.routes)
plan = security_pentest_planner.generate_from_spec(
    spec=spec,
    team="API Security Team",
    include_datalake=False,
)

MCP

Stdio server: security-pentest-planner-mcp (the plugin manifests already start it with uvx).

Tool	Role
generate_pentest_plan	Markdown plan from an OpenAPI path (team, scope, include_datalake, optional output_path)
planner_version	Installed package version

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "security-pentest-planner": {
      "command": "uvx",
      "args": [
        "--from",
        "security-pentest-planner[mcp]",
        "security-pentest-planner-mcp"
      ]
    }
  }
}

CI

Example workflow that uploads the plan when the contract changes:

# .github/workflows/pentest-plan.yml
name: Generate Pentest Plan
on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'swagger/**'

jobs:
  pentest-plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install security-pentest-planner
      - run: security-pentest-planner openapi.yaml -o PR_PENTEST_PLAN.md
      - uses: actions/upload-artifact@v4
        with:
          name: pentest-plan
          path: PR_PENTEST_PLAN.md

Publish everywhere

See docs/PUBLISH.md (PyPI, Pages, Directory, Cursor, Codex, Gemini, Partners vs Connectors).

Development

git clone https://github.com/saulofilho/security-pentest-planner-python.git
cd security-pentest-planner-python
pytest -v
python3 scripts/validate_plugin.py

License

MIT — see LICENSE.