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](https://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 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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