# pentest-agents: An AI-Assisted Bug Bounty Framework for Claude Code and Six Other Tools

> H-mmer/pentest-agents is a Python framework that turns AI coding tools into bug bounty hunting assistants. It provides 50 agents, 26 slash commands, 19 CLI tools, and 2 MCP servers, and installs into Claude Code, OpenAI Codex, Google Gemini, Cursor, Windsurf, VS Code Copilot, and OpenClaw from a single source tree.

**H-mmer/pentest-agents** — Bug bounty agent framework for Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, and OpenClaw — 48 agents, 26 commands, 19 CLI tools, 2 MCP servers, autonomous hunt loops, exploit chain builder.

- Repository: https://github.com/H-mmer/pentest-agents
- Stars: 977 · Forks: 183
- Language: Python
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/h-mmer-pentest-agents

## What pentest-agents Provides and Who It Is For

pentest-agents targets bug bounty researchers who already use AI coding tools like Claude Code or Cursor and want a structured, agent-based methodology rather than running ad-hoc prompts. The README describes it as a complete bug bounty framework with a battle-tested hunting methodology, concrete payloads, 7-Question Gate validation, autonomous hunt loops, and A-to-B exploit chain building.

The framework integrates directly with the native agent formats of seven AI coding tools: Claude Code, OpenAI Codex, Google Gemini, Cursor, Windsurf, VS Code Copilot, and OpenClaw. The source is maintained in Claude Code format and rendered into each tool's native format by the installer. This means updating the methodology once in the source tree regenerates all seven tool-specific bundles.

The scope is bug bounty hunting specifically, not general security auditing. The two MCP servers connect to 16 bug bounty platforms (mcp-bounty-server) and an optional semantic writeup search index (mcp-writeup-server). The persistent brain tracks endpoints and findings across sessions. Cost tracking via hooks records API spend automatically.

## Framework Architecture: Agents, Commands, and MCP Servers

The README lists 50 agents, 26 commands, 19 CLI tools, and 11 skills across approximately 760 files and 118,000 lines. The agent definitions live in .claude/agents/ for Claude Code, and the installer renders equivalent files for each other supported tool.

The two MCP servers serve different functions. The mcp-bounty-server provides live integration with bug bounty platforms, giving agents programmatic access to scope, submissions, and program data. The mcp-writeup-server supports bringing your own writeup index: with the optional faiss-cpu and sentence-transformers dependencies (writeup-search-faiss extra in pyproject.toml), the server enables semantic search over a local writeup collection so agents can find relevant prior reports during a hunt.

The pyproject.toml shows that the main installer has no runtime dependencies beyond the Python standard library, which means it can be installed via uvx or pipx without pulling additional packages. The MCP servers ship with their own dependency lists. The installer script also records a manifest at .pentest-agents/manifest.json (project scope) or ~/.config/pentest-agents/manifest.json (global scope) so that uninstall can reverse every file it wrote and remove only the JSON keys it merged, without touching unrelated settings.

The 2,500 payload lines and the wordlists/ directory at the repository root indicate concrete attack payloads are included rather than just prompt templates.

## Quick Start: Scaffolding a Bug Bounty Workspace

The README's quick start uses the scaffold.py tool to provision a workspace for a specific bug bounty program:

```bash
export HACKERONE_USERNAME=you HACKERONE_TOKEN=your_token
uv run python3 tools/scaffold.py hackerone tesla
cd ~/bounties/hackerone-tesla && claude
```

The scaffold generates a complete project directory with the correct files for every supported tool, including CLAUDE.md, AGENTS.md, .codex/, .agents/skills/, .gemini/, .cursor/, .windsurf/, .github/, and .vscode/mcp.json. Path references inside each file resolve correctly because scaffold writes them relative to the bounty workspace.

Once inside the workspace, the README shows the initial session flow:

```bash
/model opus
/sync hackerone tesla
/brain init && /status
/hunt tesla.com
```

The /sync command pulls current program scope from HackerOne; /brain init sets up persistent endpoint tracking; /hunt begins the autonomous hunt loop for the target domain.

## Cross-IDE Installation and Provider Rendering

The framework can be used in two ways. The first is using the pre-rendered bundles directly from the cloned repository without any installation step:

```bash
git clone https://github.com/H-mmer/pentest-agents-suite
cd pentest-agents-suite/pentest-agents/providers/codex
codex
```

The second is running the installer to write files into a project or the user's global config directory:

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

The installer CLI exposes management commands:

```bash
pentest-agents list
pentest-agents verify
pentest-agents uninstall
pentest-agents render --targets all
pentest-agents render --check
```

The providers/ directory structure shows the six non-Claude outputs:

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

The README documents what the translator changes when rendering for non-Claude targets: it drops the model: field, strips Claude-specific prose (replacing 'Claude Code' with 'the AI coding tool'), rewrites path variables to the correct relative or absolute form, maps effort: frontmatter to model_reasoning_effort in Codex TOML, caps Copilot agents at 30,000 characters, and chunks Windsurf rules at the platform-imposed file size limits.

## Scope and Limitations

The framework targets authorized bug bounty programs on supported platforms like HackerOne and Bugcrowd. The README does not document use outside of authorized bug bounty scope, and the scaffold.py workflow is built around program-specific tokens and scope files.

The framework has no GitHub Actions CI by project policy, according to the README. The drift detection between source and rendered providers runs as a pytest case (test_committed_providers_match_render) in the local test suite, not in automated CI. Teams that want CI enforcement must set it up themselves.

The pyproject.toml lists Linux, macOS, and Windows as supported operating systems. The MCP servers ship their own dependencies, but the README does not document the specific Python version or dependency requirements for the MCP servers themselves. For the optional writeup search, faiss-cpu and sentence-transformers are listed as extras but no model download process is documented.

The pyproject.toml records the license as MIT. However, the pack metadata for this repository shows the license as unknown, which suggests the LICENSE file may not be present at the repository root or may not be detected correctly. The source for the MIT claim is the pyproject.toml file, which is the authoritative declaration in the repository's own files.

The last push to the main branch was on 2026-06-12. The repository is not archived.

## Comparison with Manual Bug Bounty Tooling, Maintenance, and License

The standard bug bounty stack uses Burp Suite as the central proxy and manual analysis tool, combined with CLI reconnaissance tools like nuclei, subfinder, and amass. Burp Suite is proxy-based: a researcher intercepts HTTP traffic, modifies requests, and reviews responses manually. Each test step requires deliberate human action.

pentest-agents takes a different approach. AI agents plan and sequence tests based on the scope, brain context, and skill definitions. The hunt loop runs autonomously once started, with the agent selecting which tools to invoke and in what order. This means a researcher can delegate the reconnaissance and initial scanning phases to the framework while focusing human attention on the findings that require judgment.

The trade-off is that the autonomous loop produces output that requires human review before any finding is submitted. The 7-Question Gate validation described in the README is a check the agent applies before escalating a finding, but the researcher remains responsible for the submission. A false positive submitted to a bug bounty program as a valid finding reflects on the researcher.

pentest-agents is released under the MIT license, as declared in pyproject.toml. The MIT license permits modification and redistribution without restriction. The MCP servers connect to third-party platforms (HackerOne, Bugcrowd, and others), and use of those platforms is subject to each platform's terms of service.

## Conclusion

Bug bounty researchers who already use Claude Code or another of the seven supported tools and want a structured, agent-driven hunting workflow will find pentest-agents immediately usable after running scaffold.py for a target program. The wrong fit is anyone looking to automate unauthorized security testing: the framework is designed around authorized bug bounty program scope files and platform API tokens, not general-purpose network scanning. Before submitting any finding generated by an agent's hunt loop, verify the finding manually against the program's scope and rules of engagement, since the AI agent's 7-Question Gate is a filter, not a replacement for researcher judgment.

## FAQ

### How do I install pentest-agents for Claude Code?

Clone the repository and run python3 -m tools.installer install --targets claude_code --scope project from the repository root. The installer writes the agent definitions, skills, and MCP configuration into your project's .claude/ directory and records a manifest for clean uninstall later.

### Does pentest-agents work with tools other than Claude Code?

Yes. The installer supports Claude Code, OpenAI Codex, Google Gemini, Cursor, Windsurf, VS Code Copilot, and OpenClaw. Pre-rendered bundles for each tool are available in the providers/ directory of the cloned repository. Cursor, Windsurf, and OpenClaw have no native subagent concept, so Claude-format agents are translated to skills and rules for those tools.

### What are the two MCP servers in pentest-agents for?

The mcp-bounty-server provides live integration with 16 bug bounty platforms, giving agents access to program scope and submission data. The mcp-writeup-server supports optional semantic search over a local writeup index; it requires the faiss-cpu and sentence-transformers extras to enable vector-based search.

## Sources

- [H-mmer/pentest-agents on GitHub](https://github.com/H-mmer/pentest-agents)
- [Issues](https://github.com/H-mmer/pentest-agents/issues)
- [README](https://github.com/H-mmer/pentest-agents/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/h-mmer-pentest-agents