Skip to content
Back to search

h1-brain

MCP server that connects AI assistants to HackerOne for bug bounty hunting

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/patrikfehrenbach--h1-brain/badge.svg)](/listings/patrikfehrenbach--h1-brain)

HTML

<a href="/listings/patrikfehrenbach--h1-brain"><img src="/api/listings/patrikfehrenbach--h1-brain/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 203 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # h1-brain
  2. An MCP server that connects your AI assistant to HackerOne. It pulls your bug bounty history, program scopes, and report details into a local SQLite database, then exposes tools that let any MCP-compatible client (Claude Desktop, Claude Code, etc.) search, analyze, and build on your past work.
  3. It also ships with a **pre-built database of 3,600+ publicly disclosed bounty-awarded reports** from the HackerOne community — full vulnerability write-ups, weakness types, and bounty amounts. The AI uses both your personal data and public knowledge to generate attack briefings.
  4. The primary tool, `hack(handle)`, generates a full hacking session briefing in a single call: fresh scope from the API, your past findings, public disclosures for that program, weakness patterns, untouched assets, and suggested attack vectors — all formatted as actionable instructions that put the AI in offensive mode.
  5. ![h1-brain demo](demo.gif)
  6. ## How It Works
  7. For a full walkthrough, check out the three-part **[Bug Bounty Goldfish](https://clawd.it/series/bug-bounty-goldfish/)** series:
  8. 1. **[Teaching Claude Everything You've Hacked](https://clawd.it/posts/11-teaching-claude-everything-youve-hacked/)** — Why I built h1-brain and how to set it up
  9. 2. **[What h1-brain Actually Does](https://clawd.it/posts/12-what-h1-brain-actually-does/)** — Every tool explained, from search to the `hack()` briefing
  10. 3. **[Running h1-brain Against a Real Target](https://clawd.it/posts/13-running-h1-brain-against-a-real-target/)** — A start-to-finish walkthrough on an actual program
  11. ```mermaid
  12. graph LR
  13. A["Claude Desktop / Code"] -->|MCP Protocol| B["h1-brain server"]
  14. B -->|API calls| C["HackerOne API"]
  15. B -->|reads / writes| D["Your Reports DB"]
  16. B -->|reads| E["Public Reports DB"]
  17. C -->|reports, programs, scopes| B
  18. D -->|your history + analysis| A
  19. E -->|community knowledge| A
  20. style A fill:#ff5c5c,stroke:#ff5c5c,color:#fff
  21. style B fill:#1a1d27,stroke:#ff5c5c,color:#fff
  22. style C fill:#1a1d27,stroke:#555,color:#fff
  23. style D fill:#1a1d27,stroke:#555,color:#fff
  24. style E fill:#1a1d27,stroke:#555,color:#fff
  25. ```
  26. ```mermaid
  27. flowchart TD
  28. A["hack(handle)"] --> B["Fetch fresh scope from HackerOne API"]
  29. B --> C["Pull your reports on this program from SQLite"]
  30. C --> D["Analyze weakness patterns across ALL programs"]
  31. D --> E["Identify untouched bounty-eligible assets"]
  32. E --> F["Cross-reference public disclosed reports for this program"]
  33. F --> G["Generate attack briefing with agent instructions"]
  34. style A fill:#ff5c5c,stroke:#ff5c5c,color:#fff
  35. style G fill:#ff5c5c,stroke:#ff5c5c,color:#fff
  36. style B fill:#1a1d27,stroke:#555,color:#fff
  37. style C fill:#1a1d27,stroke:#555,color:#fff
  38. style D fill:#1a1d27,stroke:#555,color:#fff
  39. style E fill:#1a1d27,stroke:#555,color:#fff
  40. style F fill:#1a1d27,stroke:#555,color:#fff
  41. ```
  42. ## Requirements
  43. - Python 3.10+
  44. - A HackerOne API token ([generate one here](https://hackerone.com/settings/api_token/edit))
  45. ## Setup
  46. ```bash
  47. git clone https://github.com/PatrikFehrenbach/h1-brain.git
  48. cd h1-brain
  49. python -m venv venv
  50. source venv/bin/activate
  51. pip install -r requirements.txt
  52. ```
  53. The public disclosed reports database (`disclosed_reports.db`) is included in the repo — no extra setup needed.
  54. ## Connecting to Claude
  55. ### Claude Desktop
  56. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "h1-brain": {
  61. "command": "/path/to/h1-brain/venv/bin/python",
  62. "args": ["/path/to/h1-brain/server.py"],
  63. "env": {
  64. "H1_USERNAME": "your_hackerone_username",
  65. "H1_API_TOKEN": "your_api_token"
  66. }
  67. }
  68. }
  69. }
  70. ```
  71. Restart Claude Desktop after saving.
  72. ### Claude Code
  73. ```bash
  74. claude mcp add h1-brain \
  75. -e H1_USERNAME=your_hackerone_username \
  76. -e H1_API_TOKEN=your_api_token \
  77. -- /path/to/h1-brain/venv/bin/python /path/to/h1-brain/server.py
  78. ```
  79. ## First Run
  80. After connecting, populate your personal database:
  81. 1. **`fetch_rewarded_reports`** — Pulls all your bounty-awarded reports with full vulnerability write-ups. This is the most important step.
  82. 2. **`fetch_programs`** — Pulls all programs you have access to.
  83. These only need to be run once. Re-run periodically to sync new reports.
  84. To pull your **full** history on a specific program — including non-rewarded reports (`informative`, `triaged`, `duplicate`, `new`, etc.) and every comment/activity thread — use **`fetch_program_reports(handle)`**. Pass an `out_dir` to also export each report as a markdown file.
  85. The public disclosed reports are ready to query immediately — no setup needed.
  86. ## Tools
  87. ### `hack(handle)`
  88. The primary entry point. One call does everything:
  89. 1. Fetches fresh program scopes from the HackerOne API
  90. 2. Pulls your past rewarded reports for that program
  91. 3. Cross-references your full report history for weakness patterns
  92. 4. Identifies untouched bounty-eligible assets
  93. 5. Pulls public disclosed reports for this program — what other researchers found and got paid for
  94. 6. Suggests attack vectors based on weaknesses that paid elsewhere but haven't been found here
  95. 7. Returns an attack briefing that puts the AI in offensive mode
  96. **Briefing structure:**
  97. - **Scope** — bounty-eligible and non-bounty assets with severity caps
  98. - **Your Past Findings** — rewarded reports with severity, weakness type, and bounty amounts
  99. - **Weakness Types That Worked** — what's been rewarded here before
  100. - **Untouched Scope** — bounty-eligible assets with zero findings from you
  101. - **Suggested Attack Vectors** — weaknesses rewarded on other programs but not yet found here
  102. - **Public Disclosed Reports** — what other researchers found on this program, weakness patterns from public disclosures
  103. - **Instructions** — puts the AI in attack mode with specific directives
  104. ### Your Reports
  105. These query your personal data (`h1_data.db`). No API calls, instant results.
  106. | Tool | Description |
  107. |------|-------------|
  108. | `search_reports(query, program, weakness, severity, limit)` | Search your rewarded reports by title, program, weakness type, or severity |
  109. | `get_report(report_id)` | Full report details with vulnerability write-up and attachments |
  110. | `get_report_thread(report_id)` | Full comment/activity timeline (oldest→newest) for a report, as stored by `fetch_program_reports` |
  111. | `get_report_summary()` | Reports grouped by program with totals |
  112. | `search_programs(query, bounty_only, limit)` | Search your stored programs |
  113. | `search_scopes(program, asset, bounty_only, limit)` | Search in-scope assets across programs |
  114. | `fetch_attachment(report_id, attachment_id?)` | Fresh download URLs for report attachments (expire in ~1 hour) |
  115. ### Public Disclosed Reports
  116. These query the pre-built database of 3,600+ bounty-awarded public disclosures (`disclosed_reports.db`).
  117. | Tool | Description |
  118. |------|-------------|
  119. | `search_disclosed_reports(query, program, weakness, limit)` | Full-text search across public reports — titles and vulnerability write-ups |
  120. | `get_disclosed_report(report_id)` | Full details of a public disclosed report |
  121. ### Data Sync
  122. | Tool | Description |
  123. |------|-------------|
  124. | `fetch_rewarded_reports` | Sync your bounty-awarded reports from the API |
  125. | `fetch_program_reports(handle, out_dir?, include_internal?)` | Sync **all** your reports for a program — every state, not just rewarded — each with its full comment/activity timeline. Optionally export one markdown file per report (plus `raw/<id>.json` and `index.md`) to `out_dir`. |
  126. | `fetch_programs` | Sync your accessible programs |
  127. | `fetch_program_scopes(handle)` | Sync scopes for a program (called automatically by `hack()`) |
  128. ## Architecture
  129. ```
  130. server.py MCP server
  131. hack_instructions.md Attack briefing instructions (loaded by hack())
  132. h1_data.db Your personal reports, programs, scopes, activity timelines (auto-created, gitignored)
  133. disclosed_reports.db 3,600+ public disclosed bounty reports (ships with repo)
  134. requirements.txt Python dependencies (mcp, httpx)
  135. ```
  136. ### Two Databases
  137. | Database | Contains | Source |
  138. |----------|----------|--------|
  139. | `h1_data.db` | Your personal reports, programs, scopes, attachments, activity timelines | HackerOne API (your account) |
  140. | `disclosed_reports.db` | Public disclosed reports that paid a bounty | Pre-built, ships with repo |
  141. 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.
  142. ### Public Reports Database
  143. The `disclosed_reports.db` contains publicly disclosed HackerOne reports that:
  144. - Paid a bounty
  145. - Have actual vulnerability write-ups (redacted/empty reports are excluded)
  146. Each report includes: title, vulnerability details, weakness type, program, asset, CVEs, and bounty amount (when available).
  147. ## Author
  148. **Patrik Grobshäuser** — [LinkedIn](https://www.linkedin.com/in/patrikfehrenbach/) · [X](https://x.com/itsecurityguard)
  149. ## License
  150. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.