threatray/threatray-mcp
GitHub: threatray/threatray-mcp
连接 AI 助手与 Threatray 恶意软件情报平台的 MCP 服务器，允许通过统一工具接口查询样本和执行恶意软件分析。
Stars: 0 | Forks: 0
# threatray-mcp
[](https://github.com/threatray/threatray-mcp/blob/main/LICENSE)
针对 [Threatray](https://www.threatray.com) 恶意软件情报平台的 MCP server。允许支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor、Cline、Windsurf 等）通过统一的工具接口查询样本、运行代码相似性追溯搜索（retrohunt）、获取 CAPA 功能、提取 AI 分析结果并聚合 IOC。
## 快速开始
需要 Threatray API key 和 Python 3.11+。从 PyPI 安装：
```
uvx threatray-mcp # run directly, no install
# 或
pip install threatray-mcp
```
### Claude Code
```
claude mcp add threatray -s user \
-e THREATRAY_API_KEY=YOUR_API_KEY \
-e THREATRAY_API_URL=https://api-.analysis.threatray.com \
-- uvx threatray-mcp
claude mcp list # should show "threatray: ... connected"
```
这两个环境变量都是必需的 —— 没有默认 URL。请将 `` 替换为您的 API key 所属的 realm（由您的 Threatray 客户团队提供）。
### 通用 MCP 客户端配置
大多数支持 MCP 的编辑器都接受相同的 JSON 结构。将此代码块放入相应的配置文件中（路径如下所示）：
```
{
"mcpServers": {
"threatray": {
"command": "uvx",
"args": ["threatray-mcp"],
"env": {
"THREATRAY_API_KEY": "YOUR_API_KEY",
"THREATRAY_API_URL": "https://api-.analysis.threatray.com"
}
}
}
}
```
此代码片段的副本位于 [`examples/mcp-config.json`](https://github.com/threatray/threatray-mcp/blob/main/examples/mcp-config.json)。
| 客户端 | 配置文件 |
|---|---|
| Claude Code | `~/.claude.json`（通过 `claude mcp add ...` 管理） |
| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`。Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json`（全局）或 `/.cursor/mcp.json`（单个项目） |
| Cline (VS Code) | Cline UI → "MCP Servers" → 编辑 JSON，或 `~/.cline/mcp_settings.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
编辑后，请重启客户端。
## 配置
所有设置均通过环境变量进行（前缀为 `THREATRAY_`）：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `THREATRAY_API_KEY` | （必需） | 来自您 Threatray realm 的 API key |
| `THREATRAY_API_URL` | （必需） | 您的 key 所属 realm 的 API endpoint（格式：`https://api-.analysis.threatray.com`）。选错 realm 只会遇到身份验证错误 —— 没有默认值。由您的 Threatray 客户团队提供。 |
| `THREATRAY_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR`（仅限 stderr，绝不输出到 stdout —— stdout 用于传输 JSON-RPC 流） |
| `THREATRAY_TRANSPORT` | `stdio` | `stdio`（默认，server 作为 MCP 客户端的子进程运行）或 `http`（独立 server，参见下文的部署说明） |
| `THREATRAY_HOST` | `0.0.0.0` | 绑定地址，仅在 `THREATRAY_TRANSPORT=http` 时使用 |
| `THREATRAY_PORT` | `8000` | TCP 端口，仅在 `THREATRAY_TRANSPORT=http` 时使用 |
Markdown 输出会将哈希包装在指向 Threatray UI 的可点击链接中；UI URL 会根据 `THREATRAY_API_URL` 自动推导。
### 部署
支持两种传输方式：
- **`stdio`**（默认）—— MCP 客户端将 `threatray-mcp` 作为子进程启动。这是 `uvx threatray-mcp` 和 `claude mcp add` 提供的默认方式。
- **`http`** —— 位于 `THREATRAY_HOST:THREATRAY_PORT/mcp` 的持久独立 server（可流式传输的 HTTP）。在调用方客户端无法启动 server 时使用（容器化客户端、网络分段部署）。示例：`docker compose --profile http up`。**没有应用层身份验证** —— 请在网络层限制 ingress。
## 工具
按 [Threatray 公共 API 分类](https://docs.threatray.com/reference/overview-api) 分组。以下展示了全部 28 个工具；有关每个工具的详细说明，请参见 [`src/threatray_mcp/README.md`](https://github.com/threatray/threatray-mcp/blob/main/src/threatray_mcp/README.md)。
| 分类 | 工具 |
|---|---|
| 搜索 | `threatray_search`, `threatray_retrohunt_sample` |
| 样本 | `threatray_get_sample` |
| 提交（读取） | `threatray_list_submissions`, `threatray_get_task`, `threatray_get_task_by_analysis`, `threatray_list_tasks` |
| 提交（写入） | `threatray_submit_sample`, `threatray_submit_url`, `threatray_submit_endpoint_scan_archive`, `threatray_submit_minidump`, `threatray_submit_mans_file` |
| 分析 | `threatray_get_analysis`, `threatray_get_osint`, `threatray_list_analyses`, `threatray_list_endpoint_scan_analyses` |
| 文件 | `threatray_get_file_metadata`, `threatray_get_strings`, `threatray_download_file` |
| 函数 | `threatray_list_functions`, `threatray_get_code_detections`, `threatray_retrohunt_functions`, `threatray_diff_functions` |
| CAPA 分析 | `threatray_get_capa` |
| AI 分析 | `threatray_get_ai_analysis`, `threatray_get_ai_analysis_by_id`, `threatray_list_ai_analyses`, `threatray_get_latest_ai_job` |
所有工具均接受 `response_format=markdown`（默认）或 `response_format=json`。
您的账号未启用的功能（例如某些 realm 上的 AI 分析）将以明确的 `ThreatrayFeatureUnavailable` 工具错误形式呈现，而不是返回空结果，从而让代理获得可操作的信号，而不是陷入死循环。
## 安全
MCP server 在您的编辑器下以本地用户的身份作为子进程运行 —— 它会继承您对该文件的读取权限。`threatray_submit_*` 工具接受 `file_path` 参数，并将文件内容上传到您配置的 Threatray realm 中。结合提示词注入（样本的字符串、OSINT 报告、编辑器中渲染的网页），攻击者可能会尝试诱导代理调用例如 `threatray_submit_sample(file_path="~/.ssh/id_rsa")` 等操作。
在共享或无人值守环境中集成时建议采取的缓解措施：
1. **不要让对机密信息有读取权限的用户运行 server** —— 应在最小权限账号下运行，或者在没有访问您 `~`/凭证/git 工作树权限的沙箱/容器中运行。
2. **警惕异常的 `threatray_submit_*` 工具调用** —— Claude Code 在发送之前会展示每一次工具调用；在批准之前请务必注意 `file_path` 参数。
保护读取端的同一个最小权限账号也限制了 `threatray_download_file` 的写入位置 —— 该工具依赖于操作系统的文件系统权限，而不是应用层的目录白名单。
## 故障排除
**MCP server 未连接** —— 请使用 `claude mcp list`（或您客户端的等效命令）进行验证。如果未连接：
1. 确认 Python 3.11+ 已在 `PATH` 中。
2. 直接测试入口点：`THREATRAY_API_KEY=xxx uvx threatray-mcp`（它会因为等待 stdio 输入而挂起 —— 使用 Ctrl-C 退出；没有报错则意味着启动成功）。
3. 设置 `THREATRAY_LOG_LEVEL=DEBUG` 并通过客户端重新启动；检查 stderr。
**`ThreatrayAuthError`** —— API key 缺失/无效，或者您的 key 属于 `THREATRAY_API_URL` 所指向的其他 realm。错误消息包含 server 尝试连接的 URL —— 请确认它与您的 realm 匹配。
**`ThreatrayForbiddenError`** —— 已通过身份验证，但该 key 缺少所需的权限范围。
**`ThreatrayFeatureUnavailable`** —— 该功能（AI 分析、函数差异比对等）未针对您的账号启用。请联系您的 Threatray 客户团队。
**连接错误** —— `ThreatrayConnectionError` 包含它尝试连接的 URL；请确认从 MCP server 运行的位置可以访问 `THREATRAY_API_URL`。
## 开发
```
git clone https://github.com/threatray/threatray-mcp
cd threatray-mcp
pip install -e ".[dev]"
# 运行所有测试（单元 + 集成）
make test
make unit-tests # respx-mocked client + formatters + models
make int-tests # in-process fastmcp.Client end-to-end
# Lint 和 type check
make lint
make type-check
# 不使用 Docker
python -m unittest discover tests
```
有关面向贡献者的架构和各模块的包布局，请参见 [`src/threatray_mcp/README.md`](https://github.com/threatray/threatray-mcp/blob/main/src/threatray_mcp/README.md)。发布说明位于 [CHANGELOG.md](https://github.com/threatray/threatray-mcp/blob/main/CHANGELOG.md)。
## 许可证
MIT —— 详见 [LICENSE](https://github.com/threatray/threatray-mcp/blob/main/LICENSE)。
标签：API集成, DAST, MCP服务, SOC Prime, 人工智能, 可观测性, 威胁情报, 开发工具, 开发者工具, 恶意软件分析, 用户模式Hook绕过, 请求拦截, 逆向工具