Pentest Agents Bug Bounty Framework

reason-machines/security-skills/skills/pentest-agents-bug-bounty-framework

by reason-machines304c245fe992No license11 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 2 months ago

Autonomous bug bounty agent framework with 50 agents, hunt loops, exploit chains, MCP servers for platform integration and writeup search

Instructions onlySecurityAI & Agents
AI-generated overview

Autonomous bug bounty framework with hunting agents, validation gates, exploit chains and platform MCP servers.

What it does
Provides an agent framework for bug bounty hunting: 50 agents, 26 commands, payload rules, a persistent brain for endpoints and findings, a 7-Question Gate validator, and an A-to-B exploit chain builder. It also documents two MCP servers for bounty platform integration and writeup search, plus scaffolding and installer tooling. Deliverables are hunting workflows, validated findings, exploit chains and draft or submitted reports.
When to use it
Use when setting up or running an autonomous bug bounty workflow, such as scaffolding a program workspace, syncing program scope, hunting for vulnerability classes, validating findings, chaining exploits or preparing platform submissions. Also relevant when searching prior writeups or payloads for a vulnerability class.
Requirements
Requires an AI coding tool that supports agents or skills (Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, OpenClaw), Python 3 with uv, and MCP support for the servers. Platform credentials are needed for API access (HackerOne username and token, Bugcrowd email and token, Intigriti token, YesWeHack API key). Optional semantic writeup search needs faiss-cpu and sentence-transformers plus a local metadata.db and index.faiss. The skill is instructions only and ships no scripts itself.

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)

bash
# Clone the repositorygit clone https://github.com/H-mmer/pentest-agents-suitecd pentest-agents-suite/pentest-agents
# Quick start with MCP servers (no global pip install)export HACKERONE_USERNAME=your_usernameexport HACKERONE_TOKEN=your_api_token
# Scaffold a new bounty workspaceuv run python3 tools/scaffold.py hackerone teslacd ~/bounties/hackerone-tesla
# Launch Claude Codeclaude

For Other AI Coding Tools

bash
# Use pre-rendered bundles directlycd pentest-agents-suite/pentest-agents/providers/codex  # or gemini, cursor, etc.codex  # or: gemini, cursor, windsurf
# OR install into your projectpython3 -m tools.installer install --targets all --scope projectpython3 -m tools.installer install --targets codex --scope global

Installer Commands

bash
# List installed targetspentest-agents list
# Install to specific targetspentest-agents install --targets claude_code,codex --scope globalpentest-agents install --dry-run  # Preview before installing
# Verify installationpentest-agents verify
# Uninstall (safe rollback)pentest-agents uninstall
# Regenerate provider bundlespentest-agents render --targets allpentest-agents render --check  # Check for drift

MCP Servers

Bounty Platforms Server (16 Platforms)

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

Configuration:

bash
# HackerOne (full API support)export HACKERONE_USERNAME=your_usernameexport HACKERONE_TOKEN=your_api_token
# Bugcrowdexport BUGCROWD_EMAIL=your_emailexport BUGCROWD_TOKEN=your_token
# Intigritiexport INTIGRITI_TOKEN=your_token
# YesWeHackexport 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):

ModeRequiresSearches
FAISS (semantic)faiss-cpu, sentence-transformers, your metadata.db + index.faissYour writeup corpus via vector embeddings
SQLite (keyword)Your metadata.db onlyYour writeup corpus via LIKE over text
Local (default)Nothingrules/payloads.md + shipped skills

Configuration:

bash
# Point to your index directoryexport 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:

bash
cd rag-builder
# 1. Inspect the plan (dry-run, no writes)python3 build.py statuspython3 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.yamlpython3 build.py ingest --execute
# 4. Point MCP server at the outputexport 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

bash
# 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

bash
# 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

python
# Create new bounty workspaceimport subprocess
# Scaffold for HackerOne programsubprocess.run([    "uv", "run", "python3", "tools/scaffold.py",    "hackerone", "tesla"])
# Scaffold for Bugcrowd programsubprocess.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)

json
{  "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:

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:

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)

bash
# 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:

python
from tools.brain import Brain
brain = Brain("tesla.com")brain.init()
# Track endpointsbrain.add_endpoint("https://api.tesla.com/v1/users", {    "method": "GET",    "auth": "Bearer token",    "params": ["user_id", "include_deleted"]})
# Store findingsbrain.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"})
# Queryjwt_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:

python
# 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:

markdown
# 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:

python
# 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

bash
# 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:

python
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

python
# Via MCP tools in agent session
# List programsprograms = await mcp.call_tool("list_platforms", {})
# Get Tesla scopescope = await mcp.call_tool("get_program_scope", {    "platform": "hackerone",    "program": "tesla"})
# Search for similar reportssimilar = await mcp.call_tool("search_hacktivity", {    "platform": "hackerone",    "query": "IDOR users endpoint",    "limit": 10})
# Submit reportreport = 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

python
# Sync program to local brainawait mcp.call_tool("sync_program", {    "platform": "bugcrowd",    "program": "acme-corp"})
# Get submission policypolicy = await mcp.call_tool("get_program_policy", {    "platform": "bugcrowd",    "program": "acme-corp"})

Autonomous Hunt Loop

bash
# 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

bash
# Test manuallycd mcp-bounty-serveruv run --with mcp python3 server.py --test
cd mcp-writeup-serveruv run --with mcp --with faiss-cpu --with sentence-transformers python3 server.py --test
# Check env varsecho $HACKERONE_TOKENecho $WRITEUP_DB_DIR
# Verify .mcp.json paths are absolutecat .mcp.json | grep command

Writeup Search Falls Back to Local

bash
# Check if metadata.db existsls -lh ~/.local/share/pentest-writeups/metadata.db
# Verify schemasqlite3 ~/.local/share/pentest-writeups/metadata.db "PRAGMA table_info(writeups);"
# Expected columns: id, title, url, content/text/body/writeup
# Test FAISS dependenciespython3 -c "import faiss; import sentence_transformers; print('OK')"

Brain Not Persisting

bash
# Check brain directoryls -la ~/.pentest-agents/brains/
# Manually initializepython3 -c "from tools.brain import Brain; b = Brain('tesla.com'); b.init(); print(b.stats())"
# Verify permissionschmod -R u+w ~/.pentest-agents/

Cost Tracking Not Working

bash
# Verify hook is registeredcat ~/.claude/settings.json | grep hooks
# Check hook outputpython3 hooks/cost_hook.py  # Should emit JSON
# View tracking logcat cost-tracking.json | python3 -m json.tool

Installer Conflicts

bash
# Show what would be installedpentest-agents install --dry-run --targets all
# Check for driftpentest-agents verify
# Safe rollbackpentest-agents uninstall  # Restores .pa-backup files

Provider Bundle Out of Sync

bash
# Check driftpython3 -m tools.installer render --check
# Regenerate all providerspython3 -m tools.installer render --targets all
# Regenerate specific targetpython3 -m tools.installer render --targets codex

Cross-IDE Compatibility

FeatureClaude CodeCodexGeminiCursorWindsurfCopilotOpenClaw
Native agents✅✅✅Skills onlySkills only✅ (30KB limit)Skills only
Slash commands✅✅✅SkillsWorkflowsPromptsSkills
Rules files✅✅ (32KB)✅✅✅ (12KB/file)✅✅
MCP servers✅✅✅✅✅ (user-level)✅✅ (user-level)
Model inheritance✅Via model_reasoning_effortN/AN/AN/AN/AN/A

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

Source and attribution

Source:reason-machines/security-skillsinskills/pentest-agents-bug-bounty-frameworkat commit304c245

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal