Pentest Agents Bug Bounty Framework

Pentest Agents Bug Bounty Framework

Skill by ara.so — Security Skills collection.

Autonomous bug-bounty framework for Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, and OpenClaw. Ships 50 agents, 26 commands, 19 CLI tools, 11 skills, and 2 MCP servers (bounty platforms + writeup search). Includes 2,500 lines of concrete payloads, 7-Question Gate validation, autonomous hunt loops, A→B exploit chain building, persistent brain with endpoint tracking, and cross-IDE installer.

Installation

For Claude Code (Native)

# Clone the repository
git clone https://github.com/H-mmer/pentest-agents-suite
cd pentest-agents-suite/pentest-agents

# Quick start with MCP servers (no global pip install)
export HACKERONE_USERNAME=your_username
export HACKERONE_TOKEN=your_api_token

# Scaffold a new bounty workspace
uv run python3 tools/scaffold.py hackerone tesla
cd ~/bounties/hackerone-tesla

# Launch Claude Code
claude

For Other AI Coding Tools

# Use pre-rendered bundles directly
cd pentest-agents-suite/pentest-agents/providers/codex  # or gemini, cursor, etc.
codex  # or: gemini, cursor, windsurf

# OR install into your project
python3 -m tools.installer install --targets all --scope project
python3 -m tools.installer install --targets codex --scope global

Installer Commands

# List installed targets
pentest-agents list

# Install to specific targets
pentest-agents install --targets claude_code,codex --scope global
pentest-agents install --dry-run  # Preview before installing

# Verify installation
pentest-agents verify

# Uninstall (safe rollback)
pentest-agents uninstall

# Regenerate provider bundles
pentest-agents render --targets all
pentest-agents render --check  # Check for drift

MCP Servers

Bounty Platforms Server (16 Platforms)

HackerOne (full API), Bugcrowd, Intigriti, Immunefi, YesWeHack + 11 stubs.

Configuration:

# HackerOne (full API support)
export HACKERONE_USERNAME=your_username
export HACKERONE_TOKEN=your_api_token

# Bugcrowd
export BUGCROWD_EMAIL=your_email
export BUGCROWD_TOKEN=your_token

# Intigriti
export INTIGRITI_TOKEN=your_token

# YesWeHack
export YWH_API_KEY=your_api_key

7 MCP Tools:

• list_platforms - List all configured platforms
• get_program_scope - Fetch in/out-of-scope assets
• get_program_policy - Get submission rules
• search_hacktivity - Find similar reports
• sync_program - Download scope to local brain
• draft_report - Prepare submission
• submit_report - Submit to platform

Writeup Search Server (BYO Index)

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

Configuration:

# Point to your index directory
export WRITEUP_DB_DIR="$HOME/.local/share/pentest-writeups"

# OR place files in default location:
# ~/.local/share/pentest-writeups/metadata.db
# ~/.local/share/pentest-writeups/index.faiss (optional)

Build Your Own Index:

cd rag-builder

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

# 2. Pre-flight check (probe URLs with git ls-remote)
python3 build.py ingest --check-remotes

# 3. Clone + index repos from repos.yaml
python3 build.py ingest --execute

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

Edit rag-builder/repos.yaml to customize the 146-entry seed list of CTF archives, bug-bounty reports, and payload collections.

4 MCP Tools:

• search_writeups - Semantic/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

Core 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

Key Commands (26 Total)

In Claude Code Session

# Set model and sync program
/model opus
/sync hackerone tesla

# Initialize brain and check status
/brain init
/status

# Hunt for vulnerabilities
/hunt tesla.com
/hunt tesla.com --vuln-class sqli
/autopilot tesla.com  # Autonomous loop

# Validate findings
/validate  # 7-Question Gate
/chain     # Build exploit chain
/triage    # Batch validate all findings

# Report submission
/report
/dupcheck
/submit
/learn     # Update brain with learnings

# Brain management
/brain show endpoints
/brain add endpoint https://api.tesla.com/v1/users
/brain note "Found rate limit bypass in auth flow"
/brain search "jwt"

# Cost tracking
/cost      # Show session costs

Scaffold Tool

# Create new bounty workspace
import subprocess

# Scaffold for HackerOne program
subprocess.run([
    "uv", "run", "python3", "tools/scaffold.py",
    "hackerone", "tesla"
])

# Scaffold for Bugcrowd program
subprocess.run([
    "uv", "run", "python3", "tools/scaffold.py",
    "bugcrowd", "acme-corp"
])

This generates:

• ~/bounties/<platform>-<program>/ directory
• CLAUDE.md, AGENTS.md, .codex/, .gemini/, .cursor/ configs
• .mcp.json with platform + writeup server config
• .agents/skills/ with all framework skills

Agent System (50 Agents)

Key orchestrator agents:

• chain-builder - Links findings into exploit chains (A→B)
• correlator - Cross-references findings with brain
• recon-ranker - Prioritizes attack surface
• hunt-orchestrator - Coordinates active hunting
• validator - 7-Question Gate compliance

Specialized hunters:

• sqli-hunter, xss-hunter, ssrf-hunter
• authz-hunter, jwt-hunter, idor-hunter
• api-hunter, graphql-hunter, websocket-hunter

Agents inherit model via model: "inherit" frontmatter. Orchestrators dispatch to specialized agents automatically.

Configuration Files

.mcp.json (Claude Code)

{
  "mcpServers": {
    "bounty-platforms": {
      "command": "uv",
      "args": [
        "run",
        "--with", "mcp",
        "python3",
        "mcp-bounty-server/server.py"
      ],
      "env": {
        "HACKERONE_USERNAME": "your_username",
        "HACKERONE_TOKEN": "your_token"
      }
    },
    "writeup-search": {
      "command": "uv",
      "args": [
        "run",
        "--with", "mcp",
        "--with", "faiss-cpu",
        "--with", "sentence-transformers",
        "python3",
        "mcp-writeup-server/server.py"
      ],
      "env": {
        "WRITEUP_DB_DIR": "/home/user/.local/share/pentest-writeups"
      }
    }
  }
}

cost_hook.py (Automatic Cost Tracking)

Add to Claude Code settings.json:

{
  "hooks": {
    "SubagentStop": "python3 /path/to/pentest-agents/hooks/cost_hook.py",
    "Stop": "python3 /path/to/pentest-agents/hooks/cost_hook.py",
    "SessionStart": "python3 /path/to/pentest-agents/hooks/welcome.py"
  }
}

Logs to cost-tracking.json:

{
  "sessions": [
    {
      "timestamp": "2026-05-17T10:30:00Z",
      "agent": "sqli-hunter",
      "input_tokens": 15000,
      "output_tokens": 2500,
      "cost_usd": 0.12
    }
  ]
}

Brain System (Persistent Memory)

# Initialize brain for target
/brain init

# Add discoveries
/brain add endpoint https://api.example.com/v1/users
/brain add finding "JWT lacks signature verification in /auth"
/brain add technique "SSRF via PDF renderer"

# Query brain
/brain search "jwt"
/brain show endpoints
/brain show findings
/brain stats

# Export for reporting