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

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 text
Local (default)	Nothing	rules/payloads.md + shipped skills

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
/brain export findings.json

Python API:

from tools.brain import Brain

brain = Brain("tesla.com")
brain.init()

# Track endpoints
brain.add_endpoint("https://api.tesla.com/v1/users", {
    "method": "GET",
    "auth": "Bearer token",
    "params": ["user_id", "include_deleted"]
})

# Store findings
brain.add_finding({
    "vuln_class": "IDOR",
    "severity": "high",
    "endpoint": "/v1/users/{id}",
    "description": "Lack of authz check allows cross-account access",
    "poc": "curl -H 'Authorization: Bearer USER_A' https://api.tesla.com/v1/users/USER_B_ID"
})

# Query
jwt_findings = brain.search("jwt")
all_endpoints = brain.get_endpoints()
stats = brain.stats()

Payload System

Rules Engine

Framework ships rules/payloads.md with 2,500 lines of categorized payloads:

# Query via MCP
# In Claude Code session:
# Agent calls search_payloads("sqli mysql")

# Returns context-aware payloads from rules/payloads.md

Payload categories:

• SQL injection (MySQL, PostgreSQL, MSSQL, Oracle)
• XSS (reflected, stored, DOM)
• SSRF (cloud metadata, internal endpoints)
• XXE, SSTI, command injection
• JWT manipulation
• GraphQL introspection/batching
• NoSQL injection

Custom Payloads

Add to workspace payloads/<vuln-class>.md:

# Custom SQLi Payloads for Tesla

## Time-based blind (WAF bypass)
' AND (SELECT * FROM (SELECT(SLEEP(5)))a)-- -
' AND SLEEP(5) AND '1'='1

Agents will query both shipped and custom payloads.

7-Question Gate (Validation)

Every finding must pass before submission:

# Triggered via /validate command

questions = [
    "What is the exact attack vector?",
    "What is the business impact?",
    "Can you reproduce it 3 times?",
    "Is it in scope per program policy?",
    "Have you checked for duplicates?",
    "Is there a clear fix recommendation?",
    "Does the PoC include only test data?"
]

# Agent validates each finding against all 7
# Blocks submission if any answer is unclear

Exploit Chain Builder

# After finding multiple related issues
/chain

# Agent analyzes:
# 1. Finding A: SSRF in PDF renderer
# 2. Finding B: Admin panel on internal IP
# 3. Finding C: CSRF on admin delete user

# Builds chain:
# A (SSRF) → B (access admin) → C (delete users)
# Calculates combined severity: CRITICAL
# Generates unified PoC

Python API:

from tools.chain_builder import ChainBuilder

builder = ChainBuilder()

builder.add_finding("ssrf", {
    "endpoint": "/render-pdf",
    "impact": "Access internal network"
})

builder.add_finding("csrf", {
    "endpoint": "/admin/delete-user",
    "impact": "Delete arbitrary users",
    "requires": "Admin session"
})

chain = builder.build()
# Returns: dependency graph, combined severity, unified PoC

Platform Integration Examples

HackerOne

# Via MCP tools in agent session

# List programs
programs = await mcp.call_tool("list_platforms", {})

# Get Tesla scope
scope = await mcp.call_tool("get_program_scope", {
    "platform": "hackerone",
    "program": "tesla"
})

# Search for similar reports
similar = await mcp.call_tool("search_hacktivity", {
    "platform": "hackerone",
    "query": "IDOR users endpoint",
    "limit": 10
})

# Submit report
report = await mcp.call_tool("submit_report", {
    "platform": "hackerone",
    "program": "tesla",
    "title": "IDOR in /v1/users allows cross-account access",
    "severity": "high",
    "description": "...",
    "poc": "...",
    "impact": "..."
})

Bugcrowd

# Sync program to local brain
await mcp.call_tool("sync_program", {
    "platform": "bugcrowd",
    "program": "acme-corp"
})

# Get submission policy
policy = await mcp.call_tool("get_program_policy", {
    "platform": "bugcrowd",
    "program": "acme-corp"
})

Autonomous Hunt Loop

# Start autopilot mode
/autopilot tesla.com

# Agent loop:
# 1. Query writeup DB for techniques
# 2. Test endpoints from brain
# 3. Execute payloads from rules/
# 4. Validate findings (7-Question Gate)
# 5. Build exploit chains
# 6. Log to brain
# 7. Repeat with new techniques

Modes:

• --paranoid - Extra validation, slower
• --normal - Balanced (default)
• --aggressive - Fast, more false positives

Troubleshooting

MCP Server Not Starting

# Test manually
cd mcp-bounty-server
uv run --with mcp python3 server.py --test

cd mcp-writeup-server
uv run --with mcp --with faiss-cpu --with sentence-transformers python3 server.py --test

# Check env vars
echo $HACKERONE_TOKEN
echo $WRITEUP_DB_DIR

# Verify .mcp.json paths are absolute
cat .mcp.json | grep command

Writeup Search Falls Back to Local

# Check if metadata.db exists
ls -lh ~/.local/share/pentest-writeups/metadata.db

# Verify schema
sqlite3 ~/.local/share/pentest-writeups/metadata.db "PRAGMA table_info(writeups);"

# Expected columns: id, title, url, content/text/body/writeup

# Test FAISS dependencies
python3 -c "import faiss; import sentence_transformers; print('OK')"

Brain Not Persisting

# Check brain directory
ls -la ~/.pentest-agents/brains/

# Manually initialize
python3 -c "from tools.brain import Brain; b = Brain('tesla.com'); b.init(); print(b.stats())"

# Verify permissions
chmod -R u+w ~/.pentest-agents/

Cost Tracking Not Working

# Verify hook is registered
cat ~/.claude/settings.json | grep hooks

# Check hook output
python3 hooks/cost_hook.py  # Should emit JSON

# View tracking log
cat cost-tracking.json | python3 -m json.tool

Installer Conflicts

# Show what would be installed
pentest-agents install --dry-run --targets all

# Check for drift
pentest-agents verify

# Safe rollback
pentest-agents uninstall  # Restores .pa-backup files

Provider Bundle Out of Sync

# Check drift
python3 -m tools.installer render --check

# Regenerate all providers
python3 -m tools.installer render --targets all

# Regenerate specific target
python3 -m tools.installer render --targets codex

Cross-IDE Compatibility

Feature	Claude Code	Codex	Gemini	Cursor	Windsurf	Copilot	OpenClaw
Native agents	✅	✅	✅	Skills only	Skills only	✅ (30KB limit)	Skills only
Slash commands	✅	✅	✅	Skills	Workflows	Prompts	Skills
Rules files	✅	✅ (32KB)	✅	✅	✅ (12KB/file)	✅	✅
MCP servers	✅	✅	✅	✅	✅ (user-level)	✅	✅ (user-level)
Model inheritance	✅	Via model_reasoning_effort	N/A	N/A	N/A	N/A	N/A

All targets get the same 50 agents, 26 commands, 2 MCP servers — only the file format differs.