pentest-agents

| Target | Agents | Commands | Rules | MCP | Scopes | |---|---|---|---|---|---| | Claude Code | native .claude/agents/*.md | .claude/skills/<name>/SKILL.md | CLAUDE.md | .mcp.json / ~/.claude.json | global + project | | OpenAI Codex | native .codex/agents/*.toml | .codex/commands/*.md | AGENTS.md | [mcp_servers.*] in config.toml | global + project | | Google Gemini | native .gemini/agents/*.md | TOML in .gemini/commands/ | GEMINI.md | mcpServers in settings.json | global + project | | Cursor | → Skills | → Skills | .cursor/rules/*.mdc + AGENTS.md | .cursor/mcp.json | global + project | | Windsurf | → Skills | Workflows | .windsurf/rules/*.md (≤12K / file) | ~/.codeium/windsurf/mcp_config.json | global + project | | VS Code Copilot | .github/agents/*.agent.md | .github/prompts/*.prompt.md | .github/copilot-instructions.md + .github/instructions/* | .vscode/mcp.json | project + global-MCP | | OpenClaw | → Skills | → Skills | ~/.openclaw/workspace/AGENTS.md or <proj>/AGENTS.md | mcp.servers in ~/.openclaw/openclaw.json | global + project (skills/rules only; MCP is user-level) |

Cursor, Windsurf, and OpenClaw have no native subagent concept, so Claude-format agents are rendered as Skills for those three (the closest analogue). Every target's rule digest is a single canonical AGENTS.md-compatible file when supported.

OpenClaw specifics (verified against docs.openclaw.ai, April 2026): skills install into ~/.openclaw/skills/<name>/SKILL.md (global) or <project>/.agents/skills/<name>/SKILL.md (project — AgentSkills convention). MCP is always wired into the user-level ~/.openclaw/openclaw.json under mcp.servers.*; project-scope installs emit a warning reminding you to run --scope global once if you need the MCP servers.

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

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):

| Mode | Requires | Searches | |------|----------|----------| | FAISS (semantic) | faiss-cpu, sentence-transformers, your metadata.db + index.faiss | Your writeup corpus via vector embeddings | | SQLite (keyword) | Your metadata.db only | Your writeup corpus via LIKE over the text column | | Local (default) | Nothing — zero deps | rules/payloads.md + skills/ shipped in this repo |

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, write) are always gated behind --execute — running the CLI without it prints the plan and changes nothing, so you can never wipe an existing index by accident.

cd rag-builder

# 1. Inspect the plan — no network, no writes.
python3 build.py status
python3 build.py ingest                    # dry-run (the default)

# 2. Opt-in pre-flight: probe every URL with `git ls-remote` (network).
python3 build.py ingest --check-remotes    # ~5s for 141 repos at 16 workers

# 3. Actually clone + index every repo from repos.yaml into ./data/.
python3 build.py ingest --execute
python3 build.py ingest --execute --check-remotes   # skip unreachable first

# 4. Point the MCP server at the output.
export WRITEUP_DB_DIR="$PWD/data"
python3 ../mcp-writeup-server/server.py --test

rag-builder/repos.yaml ships with a 146-entry seed covering CTF archives, bug-bounty reports, payload collections, and research aggregators — edit freely. repos-skipped.yaml is loaded automatically as an exclusion list (override with --skip-list or --no-skip-list). config.yaml controls the embedding model (all-MiniLM-L6-v2 by default), host allowlist, clone size cap, and file-size ceiling. See rag-builder/README.md for the full reference.

CC Hooks (automatic cost tracking)

Configured in settings.json, fires automatically:

• SubagentStop → cost_hook.py logs agent name + session to cost-tracking.json
• Stop → logs session end
• SessionStart → welcome message

Statusline shows live cost from session token data: $0.57

Commands (26)

Hunting & Analysis

| Command | Description | |---------|-------------| | /hunt <target> [--vuln-class] | Active hunting — searches writeup DB for techniques first, then tests with concrete payloads | | /autopilot <target> | Autonomous loop with --paranoid/--normal/--yolo checkpoints | | /surface <target> | P1/P2/Kill ranked attack surface | | /chain | Build A→B→C exploit chains (12 patterns, 6 high-value templates) | | /analyze <target> | AI analysis: crown jewels, attack paths, blind spots | | /mindmap <target> | Attack surface tree with brain status | | /sast <repo> | Source-code vulnerability hunting (entry → flow → gap → exploit pipeline) |

Validation & Reporting

| C