pentest-agents-bug-bounty-framework

name	pentest-agents-bug-bounty-framework
description	Autonomous bug bounty agent framework with 50 agents, hunt loops, exploit chains, MCP servers for platform integration and writeup search
triggers	["set up pentest agents framework","configure bug bounty hunting agents","start autonomous hunt loop","search writeup database for vulnerabilities","build exploit chain for security finding","submit bug bounty report","install pentest agents for Claude Code","validate security finding with 7-question gate"]

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", 
         
        
        
      
       
         
      
    
  

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.