pentest-agents-bug-bounty-framework

# 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

# 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

# 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

# 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

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

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

# 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

# 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

# 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"
])

{
  "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"
      }
    }
  }
}

{
  "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"
  }
}

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

# 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

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

# Query via MCP
# In Claude Code session:
# Agent calls search_payloads("sqli mysql")
 
# Returns context-aware payloads from rules/payloads.md

# Custom SQLi Payloads for Tesla
 
## Time-based blind (WAF bypass)
' AND (SELECT * FROM (SELECT(SLEEP(5)))a)-- -
' AND SLEEP(5) AND '1'='1

# 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

# 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

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

# 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": "..."
})

# 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"
})

# 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

# 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

# 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')"

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

# 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

# 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

# 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