pentest-agents

~760 files · ~118k lines · 50 agents · 26 commands · 19 CLI tools · 11 skills · 2 MCP servers (16 bug-bounty platforms + BYO writeup search) · 2,500 payload lines

A complete bug bounty framework. Battle-tested hunting methodology with concrete payloads, 7-Question Gate validation, autonomous hunt loops, A→B exploit chain building, persistent brain with endpoint tracking, optional semantic writeup search (bring your own index), automatic cost tracking via CC hooks, live platform integration, and a cross-IDE installer that emits the native format for Claude Code, Codex, Gemini, Cursor, Windsurf, VS Code Copilot, and OpenClaw.

Quick Start

# MCP servers are launched via `uv run --with mcp` — no global pip install required.
export HACKERONE_USERNAME=you HACKERONE_TOKEN=your_token
uv run python3 tools/scaffold.py hackerone tesla
cd ~/bounties/hackerone-tesla && claude
/model opus             # Opus 4.7 [1M] — subagents inherit via model: "inherit"
/sync hackerone tesla
/brain init && /status
/hunt tesla.com

scaffold.py provisions the workspace for every supported project-scoped client, not only Claude Code: CLAUDE.md, AGENTS.md, .codex/, .agents/skills/, .gemini/, .cursor/, .windsurf/, .github/, and .vscode/mcp.json are generated from the copied workspace assets so paths resolve inside the bounty workspace.

Install (Claude Code + 6 other AI coding tools)

The framework ships pre-rendered for every supported tool. There are two ways to use it:

1. Use the bundles directly (no install step)

git clone https://github.com/H-mmer/pentest-agents-suite
cd pentest-agents-suite/pentest-agents/providers/codex
codex                       # or: cd ../gemini && gemini, etc.

The providers/<id>/ tree contains a fully-translated, ready-to-use bundle for each non-Claude target. Path references inside use .. to reach the repo's tools/, rules/, and mcp-*-server/ — so the bundle works as long as it stays inside the cloned repo.

2. Run the installer (writes into your own project or ~/.codex/ etc.)

python3 -m tools.installer install --targets all --scope project
python3 -m tools.installer install --targets codex --scope global

Install mode rewrites paths to absolute references back into the cloned pentest-agents repo, so the install works no matter where the user's own project lives.

Cursor, Windsurf, and OpenClaw have no native subagent concept; Claude-format agents render as skills/rules. Codex commands are emitted as AgentSkills under .agents/skills/; the deprecated .codex/prompts/ path is not used.

providers/ directory (in the cloned repo):

providers/
├── codex/    AGENTS.md + .codex/{agents,config.toml} + .agents/skills
├── gemini/   GEMINI.md + .gemini/{agents,commands} + settings.json
├── cursor/   AGENTS.md + .cursor/{rules,skills,mcp.json}
├── windsurf/ AGENTS.md + .windsurf/{rules,workflows,skills} + mcp_config.json
├── copilot/  .github/{copilot-instructions.md,instructions,prompts,agents} + .vscode/mcp.json
└── openclaw/ AGENTS.md + .agents/skills/ + openclaw.json

providers/ is generated, not edited by hand. Re-render after editing .claude/, rules/, or skills/ source:

python3 -m tools.installer render --targets all
python3 -m tools.installer render --check        # exits 1 if drift

The test_committed_providers_match_render pytest case enforces drift detection locally — there is no GitHub Actions CI by project policy.

What gets translated

When .claude/ content is rendered for non-Claude targets, the translator:

• Drops the model: field — each target uses its own default model.
• Strips Claude-specific prose — "Claude Code" → "the AI coding tool", "the Agent tool" → "the subagent dispatch tool", model: "inherit" is removed entirely.
• Rewrites $CLAUDE_PROJECT_DIR — to .. in providers/ (relative to the cloned repo), or to absolute paths into the cloned source repo when installing into a user's project.
• Maps effort: frontmatter to model_reasoning_effort in Codex TOML.
• Caps body length — Copilot agents are truncated at 30,000 chars (Copilot's hard limit). Windsurf rules are chunked at 12,000 chars (workspace) / 6,000 chars (global).
• Adds Copilot subagent links — orchestrator agents (chain-builder, correlator, recon-ranker) get an agents: list of siblings so Copilot wires the dispatch graph.

Installer management

pentest-agents list                      # detect which targets are installed
pentest-agents install --targets claude_code,codex --scope global
pentest-agents install --dry-run         # preview every file + JSON merge
pentest-agents verify                    # check manifest vs. disk (drift)
pentest-agents uninstall                 # reverse, restore .pa-backup files
pentest-agents render --targets all      # regenerate providers/<id>/
pentest-agents render --check            # drift gate (exit 1 if dirty)

Every install records a manifest (.pentest-agents/manifest.json for project scope, ~/.config/pentest-agents/manifest.json for global). Uninstall only removes files we wrote and surgically strips only the MCP/JSON keys we merged — your other settings are never touched. Conflicting writes back up the original as <path>.pa-backup and are restored on uninstall.

Workflow

New program:   /new → /sync → /brain init → /analyze → /surface → /hunt
Returning:     /resume <target> → /hunt or /autopilot
After finding: /validate → /chain → /report → /dupcheck → /submit → /learn
Batch triage:  /triage (7-Question Gate on all findings)

MCP Servers (2)

bounty-platforms (16 platforms)

HackerOne (full API), Bugcrowd, Intigriti, Immunefi (public), YesWeHack + 11 stubs. 7 MCP tools: list_platforms, get_program_scope, get_program_policy, search_hacktivity, sync_program, draft_report, submit_report.

writeup-search (BYO index)

Searchable knowledge base agents query during hunting and validation. 4 MCP tools:

• search_writeups — semantic search (FAISS) or keyword search for prior art
• get_writeup — full writeup content by ID
• search_techniques — exploitation techniques by vuln class
• search_payloads — curated payloads from rules/payloads.md

The writeup index is not bundled. Bulk-redistributing scraped hacktivity violates most platform ToS, so this repo ships the server only. The search_payloads + search_techniques fallback works out of the box; the semantic/keyword layers activate once you point the server at your own index.

Three search modes (auto-detected, graceful fallback):

Point the server at your index by dropping metadata.db (+ optionally index.faiss) into ~/.local/share/pentest-writeups/, or set WRITEUP_DB_DIR=/path/to/dir.

Expected schema (metadata.db): a SQLite file with at least one table containing columns id, title, url, and one text column (content / text / body / writeup). Row order in the table must match vector order in index.faiss when using semantic mode.

Build your own index — rag-builder/

The repo now ships a local RAG/FAISS builder under rag-builder/ that turns a list of GitHub / GitLab repositories into a metadata.db + index.faiss pair the writeup-search MCP server consumes. Destructive operations (clone, embed,