内容
# hackerone-mcp
一个本地的**只读**MCP服务器，连接您的HackerOne研究人员账户到Claude Desktop和Claude Code。它帮助您找到最佳目标，分析程序范围，查看您的报告/收益，并草拟漏洞报告（您自己提交 - 服务器从不写入您的账户）。
## 工作原理
Claude Desktop或Claude Code作为本地子进程启动此服务器，并通过stdio使用模型上下文协议与其通信。每个工具都是只读的。服务器通过**两条独立路径**访问HackerOne：您的私有账户数据通过**身份验证的官方API**，公共披露报告数据通过**未经身份验证的公共端点**（因此，您的账户从不涉及这些请求）。
```
┌──────────────────┐ ┌──────────────────┐
│ Claude Desktop │ │ Claude Code │
└────────┬─────────┘ └────────┬─────────┘
└───────────┬───────────────┘
│ MCP over stdio
│ （启动：python -m hackerone_mcp）
▼
┌───────────────────────────────────────────────────────────────────── ┐
│ hackerone-mcp （本地服务器） │
│ │
│ server.py ── FastMCP 工具 │
│ │ 程序 · 范围 · 计数/筛选 · 排名 · 弱点 │
│ │ 我的报告 · 收益 · 草拟报告 · 原始获取 │
│ │ 搜索公开报告 · 列出CWE类型 · 目录 │
│ │ │
│ ├── config.py ◄──────── .env （H1_ENV_FILE: H1_USERNAME / TOKEN） │
│ │ │
│ └── tools.py ── 协调每个请求 │
│ │ │
│ ├── cache.py ......... 磁盘缓存（1小时TTL）— 命中？返回 │
│ │ │
│ ├── analysis.py ...... 排名 / 筛选 / 总结 │
│ ├── hacktivity.py .... 构建查询 / 项目 │
│ │ （无I/O） │
│ │ │
│ ├── client.py ........ httpx + HTTP基本身份验证 ─────────┐ │
│ │ （仅GET，429重试） │ │
│ └── graphql_client.py httpx POST，无身份验证 ──────────┐ │ │
│ （仅读取查询） │ │ │
└────────────────────────────────────────────────────────────-----│--│--┘
│ │
身份验证， 只读GET（HTTPS） ────────┼──┘
您的账户数据 │
▼
┌──────────────────────────────┐
│ api.hackerone.com/v1 │
│ /hackers/programs … │
└──────────────────────────────┘
无身份验证， 只读POST（HTTPS）
公共披露报告 │
▼
┌──────────────────────────────┐
│ hackerone.com/graphql │
│ （公共黑客活动） │
└──────────────────────────────┘
```
**两个流程，一个模式：**Claude调用工具 → `tools.py`检查`cache.py` → 未命中时访问正确的后端 → 纯函数（`analysis.py` / `hacktivity.py`）塑形结果 → 返回给Claude。
- **账户路径** （您的程序、范围、报告、收益）：`client.py`向`api.hackerone.com/v1`发出身份验证的只读**GET**请求。您的令牌从不离开您的机器，除了作为基本身份验证头。
- **公共路径** （公开报告 / CWE / 目录搜索）：`graphql_client.py`向`hackerone.com/graphql`发出**无身份验证**的只读**POST**请求 — 从不附加令牌或cookie，因此这些请求不承担账户风险。
## 要求
- Python 3.10+（测试到3.13）
- HackerOne API令牌：hackerone.com → 设置 → **API令牌**。使用可用的最窄读取范围。
## 安装
```bash
git clone <此仓库> hackerone-mcp
cd hackerone-mcp
python -m pip install -e .
```
## 配置凭证
设置两个环境变量（这些变量位于下面的MCP客户端配置中）：
- `H1_USERNAME` — 您的HackerOne用户名
- `H1_API_TOKEN` — 您生成的API令牌
可选：`H1_CACHE_DIR`，`H1_CACHE_TTL`（秒，默认3600）。
验证您的令牌是否有效：
```bash
H1_USERNAME=您 H1_API_TOKEN=xxxx python -m hackerone_mcp --check-auth
```
在Windows PowerShell上：
```powershell
$env:H1_USERNAME="您"; $env:H1_API_TOKEN="xxxx"; python -m hackerone_mcp --check-auth
```
预期输出：`OK: 以您身份验证。N个程序（s）可访问。`
## 连接到Claude Desktop
编辑`claude_desktop_config.json`
（Windows：`%APPDATA%\Claude\claude_desktop_config.json`）：
```json
{
"mcpServers": {
"hackerone": {
"command": "python",
"args": ["-m", "hackerone_mcp"],
"env": {
"H1_USERNAME": "您的用户名",
"H1_API_TOKEN": "您的API令牌"
}
}
}
}
```
重启Claude Desktop。
## 连接到Claude Code
```bash
claude mcp add hackerone --env H1_USERNAME=您的用户名 --env H1_API_TOKEN=您的API令牌 -- python -m hackerone_mcp
```
或添加具有相同`command`/`args`/`env`的`.mcp.json`条目。
## 工具
- `list_programs` — 您的账户可以访问的程序（`compact=true`获取小型句柄/名称/赏金/状态列表；完整列表有几MB）
- `count_programs` — 仅总数：程序计数，赏金程序，VDP和提交状态分解（用于“多少...”问题）
- `get_program` — 句柄的完整策略/详细信息
- `get_program_scopes` — 结构化范围，总结范围内/范围外
- `get_program_weaknesses` — 程序跟踪的CWE/弱点类型
- `filter_programs` — 按提供赏金/提交状态/书签筛选的紧凑列表（例如所有VDP）
- `list_my_reports` — 您自己的提交报告（紧凑；使用`get_report`获取完整详细信息）
- `search_scopes` — 在您的程序中搜索资产（`limit`用于快速扫描）
- `rank_programs` — 排名程序用于狩猎（赏金，范围，严重性；`limit`用于快速扫描）
- `get_balance`，`list_earnings` — 您的付款
- `get_report` — 按ID读取报告
- `draft_report` — 以markdown格式格式化报告（您自己提交）
- `raw_get` — 对任何v1 API路径的身份验证只读GET
- `search_disclosed_reports` — 按关键词/严重性/CWE/CVE/程序搜索公共披露报告；`sort`（“相关性”/“最近”，默认为关键词搜索的相关性）和`since`/`until`（YYYY-MM-DD）日期范围
- `list_cwe_types` — `cwe`筛选器的有效CWE名称
- `search_directory` — 按名称搜索公共程序目录
> **注意：** `search_scopes`和`rank_programs`扫描您可以访问的每个程序（冷缓存时每个程序一个API调用 — 可能有数百个）。结果缓存一小时，因此第一次调用较慢，后续调用较快。传递`limit`（例如50）进行快速部分扫描，或`refresh=true`绕过缓存。
## 安全
您的API令牌以纯文本形式存储在客户端配置文件中。保护该文件（限制权限），使用窄范围令牌，并在令牌暴露时从HackerOne撤销/轮换它。此服务器仅发出**只读请求**（对官方API进行身份验证的GET，以及对公共黑客活动端点的无身份验证只读GraphQL POST） — 它无法提交，编辑或删除您的账户中的任何内容。
## 公共黑客活动搜索（第2部分）
`search_disclosed_reports`，`list_cwe_types`和`search_directory`通过其未公开的GraphQL端点读取HackerOne的**公共**披露报告数据，**未经身份验证** — 不发送令牌或cookie，因此这些调用不承担账户风险。它们是只读的（服务器从不发送突变）。
由于端点未公开记录，因此内置查询可能会在HackerOne更改其模式时中断。确切的查询于2026-06-28捕获并保存到`docs/superpowers/reference/hackerone-graphql-captures-2026-06-28.json`；如果黑客活动工具停止工作，请从浏览器重新捕获并更新`graphql_client.py`。
## 开发
```bash
python -m pip install -e ".[dev]"
python -m pytest -v
```
