flowchart TD
    A["hack(handle)"] --> B["Fetch fresh scope from HackerOne API"]
    B --> C["Pull your reports on this program from SQLite"]
    C --> D["Analyze weakness patterns across ALL programs"]
    D --> E["Identify untouched bounty-eligible assets"]
    E --> F["Cross-reference public disclosed reports for this program"]
    F --> G["Generate attack briefing with agent instructions"]
    style A fill:#ff5c5c,stroke:#ff5c5c,color:#fff
    style G fill:#ff5c5c,stroke:#ff5c5c,color:#fff
    style B fill:#1a1d27,stroke:#555,color:#fff
    style C fill:#1a1d27,stroke:#555,color:#fff
    style D fill:#1a1d27,stroke:#555,color:#fff
    style E fill:#1a1d27,stroke:#555,color:#fff
    style F fill:#1a1d27,stroke:#555,color:#fff

Requirements

• Python 3.10+
• A HackerOne API token (generate one here)

Setup

git clone https://github.com/PatrikFehrenbach/h1-brain.git
cd h1-brain
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

The public disclosed reports database (disclosed_reports.db) is included in the repo — no extra setup needed.

Connecting to Claude

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "h1-brain": {
      "command": "/path/to/h1-brain/venv/bin/python",
      "args": ["/path/to/h1-brain/server.py"],
      "env": {
        "H1_USERNAME": "your_hackerone_username",
        "H1_API_TOKEN": "your_api_token"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add h1-brain \
  -e H1_USERNAME=your_hackerone_username \
  -e H1_API_TOKEN=your_api_token \
  -- /path/to/h1-brain/venv/bin/python /path/to/h1-brain/server.py

First Run

After connecting, populate your personal database:

1. fetch_rewarded_reports — Pulls all your bounty-awarded reports with full vulnerability write-ups. This is the most important step.
2. fetch_programs — Pulls all programs you have access to.

These only need to be run once. Re-run periodically to sync new reports.

The public disclosed reports are ready to query immediately — no setup needed.

Tools

hack(handle)

The primary entry point. One call does everything:

1. Fetches fresh program scopes from the HackerOne API
2. Pulls your past rewarded reports for that program
3. Cross-references your full report history for weakness patterns
4. Identifies untouched bounty-eligible assets
5. Pulls public disclosed reports for this program — what other researchers found and got paid for
6. Suggests attack vectors based on weaknesses that paid elsewhere but haven't been found here
7. Returns an attack briefing that puts the AI in offensive mode

Briefing structure:

• Scope — bounty-eligible and non-bounty assets with severity caps
• Your Past Findings — rewarded reports with severity, weakness type, and bounty amounts
• Weakness Types That Worked — what's been rewarded here before
• Untouched Scope — bounty-eligible assets with zero findings from you
• Suggested Attack Vectors — weaknesses rewarded on other programs but not yet found here
• Public Disclosed Reports — what other researchers found on this program, weakness patterns from public disclosures
• Instructions — puts the AI in attack mode with specific directives

Your Reports

These query your personal data (h1_data.db). No API calls, instant results.

| Tool | Description | |------|-------------| | search_reports(query, program, weakness, severity, limit) | Search your rewarded reports by title, program, weakness type, or severity | | get_report(report_id) | Full report details with vulnerability write-up and attachments | | get_report_summary() | Reports grouped by program with totals | | search_programs(query, bounty_only, limit) | Search your stored programs | | search_scopes(program, asset, bounty_only, limit) | Search in-scope assets across programs | | fetch_attachment(report_id, attachment_id?) | Fresh download URLs for report attachments (expire in ~1 hour) |

Public Disclosed Reports

These query the pre-built database of 3,600+ bounty-awarded public disclosures (disclosed_reports.db).

| Tool | Description | |------|-------------| | search_disclosed_reports(query, program, weakness, limit) | Full-text search across public reports — titles and vulnerability write-ups | | get_disclosed_report(report_id) | Full details of a public disclosed report |

Data Sync

| Tool | Description | |------|-------------| | fetch_rewarded_reports | Sync your bounty-awarded reports from the API | | fetch_programs | Sync your accessible programs | | fetch_program_scopes(handle) | Sync scopes for a program (called automatically by hack()) |

Architecture

server.py              MCP server
hack_instructions.md   Attack briefing instructions (loaded by hack())
h1_data.db             Your personal reports, programs, scopes (auto-created, gitignored)
disclosed_reports.db   3,600+ public disclosed bounty reports (ships with repo)
requirements.txt       Python dependencies (mcp, httpx)

Two Databases

| Database | Contains | Source | |----------|----------|--------| | h1_data.db | Your personal reports, programs, scopes, attachments | HackerOne API (your account) | | disclosed_reports.db | Public disclosed reports that paid a bounty | Pre-built, ships with repo |

The AI knows the difference. Your personal tools (search_reports, get_report) query your data. Public tools (search_disclosed_reports, get_disclosed_report) query community data. hack() uses both.

Public Reports Database

The disclosed_reports.db contains publicly disclosed HackerOne reports that:

• Paid a bounty
• Have actual vulnerability write-ups (redacted/empty reports are excluded)

Each report includes: title, vulnerability details, weakness type, program, asset, CVEs, and bounty amount (when available).

Author

Patrik Grobshäuser — LinkedIn · X

License

MIT