h1-brain is a Python MCP server that connects AI assistants like Claude Desktop to HackerOne, letting authorized bug bounty researchers mine their own report history and public disclosures for structured attack briefings.
| Tool | PatrikFehrenbach/h1-brain — MCP server connecting AI assistants to HackerOne for bug bounty analysis and briefing generation |
| Category | AI-integrated bug bounty workflow tooling (MCP server, Python, SQLite) |
| Primary Use | Authorized bug bounty research: syncing your own HackerOne reports, programs, and scopes into local SQLite, querying 3,600+ public disclosed reports, and generating program briefings via hack(handle) |
| Safe Use | Intended for researchers operating strictly within the written scope of HackerOne programs they are authorized to test; also useful defensively for understanding what weakness classes platforms pay for and disclose |
| Telemetry Note | The tool authenticates with your own H1_API_TOKEN and generates visible API traffic against HackerOne endpoints; all activity is attributable to your account and logged platform-side, and all testing guided by its briefings remains subject to program monitoring |
h1-brain is an MCP server written in Python that bridges AI assistants to the HackerOne bug bounty platform. Rather than acting as a scanner or an attack tool itself, it functions as a knowledge layer: it synchronizes your personal bounty history, program scopes, and report threads into a local SQLite database, pairs that with a pre-built corpus of 3,600+ publicly disclosed bounty-awarded reports, and exposes both as queryable tools to any MCP-compatible client such as Claude Desktop or Claude Code. The interesting design decision here is treating an AI assistant's context window as the real bottleneck — the tool's job is to stuff that context with the right evidence at the right moment.
The architecture is refreshingly simple and worth studying. A single server.py implements the MCP server, backed by two distinct SQLite databases. The first, h1_data.db, is your personal store — reports, programs, scopes, attachments, and activity timelines pulled from the HackerOne API under your own credentials; it is auto-created and gitignored. The second, disclosed_reports.db, ships with the repository and contains only public disclosures that actually paid a bounty and include a real vulnerability write-up, with redacted or empty reports filtered out. Each disclosure carries the title, vulnerability details, weakness type, program, asset, CVEs, and bounty amount where available. The README is explicit that the AI is made aware of which database it is querying — personal tools hit your data, public tools hit community data, and the flagship hack() function blends both.
The primary entry point is hack(handle), which the README describes as generating a full hacking session briefing in one call. Internally it follows a sensible pipeline: fetch fresh scope from the HackerOne API, pull your past rewarded reports for the target program from SQLite, analyze weakness patterns across your entire report history, identify bounty-eligible assets you have never touched, cross-reference what other researchers were publicly paid for on the same program, and finally suggest attack vectors based on weaknesses that paid elsewhere but have not yet surfaced here. The output is a structured briefing covering scope with severity caps, your past findings, proven weakness types, untouched scope, suggested vectors, public disclosure patterns, and a set of agent instructions loaded from hack_instructions.md that, in the author's words, put the AI into offensive mode.
That last phrase deserves professional scrutiny. The offensive posture is scoped entirely by the program's own bounty eligibility rules — the briefing explicitly separates bounty-eligible from non-bounty assets and respects severity caps, which means the AI is being pointed at assets the program has authorized researchers to test. Still, anyone deploying this in an enterprise or team context should read hack_instructions.md before first use, because that file is the actual prompt driving the assistant's behavior, and prompt-driven tooling inherits whatever bias the instruction file encodes. Treating it as reviewable configuration rather than magic is the correct operational posture.
The supporting tool surface is well organized. On the personal side, search_reports(query, program, weakness, severity, limit) offers filtered search over your rewarded reports, get_report(report_id) returns full write-ups and attachments, get_report_thread(report_id) reconstructs the oldest-to-newest comment and activity timeline for triage archaeology, get_report_summary() groups reports by program with totals, and search_scopes(program, asset, bounty_only, limit) lets you slice in-scope assets across programs. fetch_attachment(report_id, attachment_id?) generates fresh download URLs for attachments, with the README noting those URLs expire in roughly an hour.
The public corpus gets its own pair: search_disclosed_reports(query, program, weakness, limit) performs full-text search across titles and vulnerability write-ups of disclosed reports, and get_disclosed_report(report_id) retrieves full details. This is arguably the most reusable component even outside bounty hunting — it is effectively a curated, bounty-verified weakness dataset, useful to defenders who want to know which vulnerability classes programs are actually paying for and how they manifest in write-ups. Filtering to rewarded reports only removes a lot of the noise that plagues raw disclosure scrapes.
Data synchronization is deliberately separated from querying. fetch_rewarded_reports pulls all bounty-awarded reports once at setup, fetch_programs pulls the programs your account can access, and fetch_program_reports(handle, out_dir?, include_internal?) is the deep option — syncing every report state, not just rewarded ones (informative, triaged, duplicate, new), each with its complete comment and activity thread, with optional markdown export per report plus raw/<id>.json and index.md to an out_dir. fetch_program_scopes(handle) syncs scopes and is invoked automatically by hack(). The README recommends re-running syncs periodically to capture new reports, which is a reasonable cadence for anyone actively hunting.
Setup is minimal: git clone the repository, create a venv, and pip install -r requirements.txt. Dependencies are listed as just mcp and httpx, which keeps the attack surface of the tool itself small — always a good sign for something holding an API token. Authentication requires a HackerOne API token generated from your account settings, passed via H1_USERNAME and H1_API_TOKEN environment variables in the MCP client configuration for Claude Desktop, or via claude mcp add h1-brain with -e flags for Claude Code. The disclosed reports database needs no setup at all since it ships in the repo.
From a defensive perspective, there are two useful observations. First, all of h1-brain's platform interaction flows through your legitimate HackerOne API token, meaning every automated fetch is attributable and logged platform-side — there is no anonymized scraping layer. Second, the corpus of weakness patterns and bounty amounts is itself threat intelligence: security teams running HackerOne programs can reason about what classes of findings competitors' programs reward and how disclosed write-ups read, which informs their own triage and detection engineering. The tool is a good example of MCP-era workflow design where the value is in structured retrieval, not in raw capability.
Caveats are the usual ones for token-holding local servers: the API credentials sit in client configuration files like claude_desktop_config.json, so filesystem access equals platform access, and the quality of any briefing depends on the freshness of your synced databases. With 357 stars, an MIT license, and an accompanying three-part walkthrough series by the author (Patrik Grobshäuser) covering setup, every tool, and a real-target session, the project is small but well documented. For authorized bounty researchers who have accumulated years of reports, h1-brain turns that history from a trophy cabinet into a queryable knowledge base — and for everyone else, it is a clean reference implementation of how to wire an MCP server into a domain-specific dataset.
PatrikFehrenbach/h1-brain.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.