mukul975/Malware-Sandbox-mcp

# malware-sandbox-mcp  [](https://github.com/mukul975/Malware-Sandbox-mcp/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) [](https://modelcontextprotocol.io) [](https://github.com/astral-sh/ruff) [](https://github.com/mukul975/Malware-Sandbox-mcp/stargazers) **直接在 Claude 中引爆云恶意软件沙箱里的可疑文件和 URL —— 并获取标准化后的判定结果、IOC 和 MITRE ATT&CK 技术。** ## 问题所在 分诊一个可疑样本意味着要在四个浏览器标签页之间来回切换：提交给沙箱、等待、复制判定结果、将 C2 轮转到威胁情报数据库、在 VirusTotal 上查找哈希，然后手动将行为映射到 ATT&CK。每个报告都有不同的 schema，原始 JSON 大小高达数百 KB —— 远超可以直接粘贴到 LLM 的极限。 ## 解决方案 使用一个 MCP 服务器，通过 20 个工具封装了 **9 个后端**，并采用统一的标准化报告 schema。Claude 提交样本、进行异步轮询，并获取一份紧凑的（约 4K token）报告：判定结果、威胁评分、恶意软件家族、热门特征码、提取的 IOC，以及丰富了战术名称和链接的 ATT&CK 技术 —— 此外还提供了用于检索产物（释放的文件、PCAP、截图）、跨六个情报源丰富 IOC、轮转到相关样本、比较不同沙箱间的判定结果以及导出 ATT&CK Navigator 层级的工具。 引爆过程需要 2-10 分钟，但 Claude Desktop 强制执行硬编码的约 60 秒 MCP 工具超时限制。因此，此服务器采用**异步提交 → 轮询**模式：`submit_sample` 会在几秒内返回 `task_id`，而每次 `get_report(task_id)` 调用仅执行一次状态轮询 —— 没有任何工具调用会在等待沙箱时发生阻塞。 ## 为什么选择此工具 - **9 个后端，20 个工具** —— 引爆、产物、丰富信息、轮转、比较、ATT&CK 导出。 - **严格 BYOK** —— 每个后端都使用从环境变量中提取的*你自己的* API key；缺少 key 只会禁用该后端，而服务器仍会正常启动。 - **异步、避免超时** —— 提交 → 轮询 (handleId) 确保每次调用都在 MCP 超时上限之内。 - **标准化 + token 预算控制** —— 跨供应商的统一 schema，并进行摘要以适应 LLM 上下文。 - **MITRE ATT&CK 丰富化** —— 将技术解析为战术名称、链接以及 Navigator 层级。 - **设计安全** —— 二进制产物（活跃恶意软件、PCAP、内存转储）保存至磁盘，绝不内联；下载需要明确的确认；所有沙箱字符串均被视为不受信任的数据。 ## 架构 ``` Claude ──submit_sample──▶ malware-sandbox-mcp ──▶ Detonation sandboxes │ │ Hybrid Analysis · tria.ge · ANY.RUN │ ◀──── task_id ──────── │ │ │ normalize ──▶ MITRE ATT&CK enrich ──▶ summarize (<4K tok) │ ──get_report(task_id)──▶ │ │ ├──▶ Intel sources (enrich / pivot / C2) │ ◀── working | report ── │ MalwareBazaar · ThreatFox · URLhaus · Feodo · URLScan · VirusTotal │ │ │ ◀── artifacts saved to disk (PCAP, dropped files, screenshots, memory strings) ``` ## 工具 所有工具都会优雅降级：如果它们所需的后端没有 API key，它们将返回明确的“未配置”消息，而不是报错失败。 ### 引爆与报告 | 工具 | 描述 | |---|---| | `submit_sample` | 将文件或 URL 提交至引爆沙箱（Hybrid Analysis / tria.ge / ANY.RUN）。立即返回 `task_id`。 | | `get_report` | 对提交进行一次异步轮询；返回 `working` 或最终的标准化 + ATT&CK 丰富化报告。 | | `get_analysis_state` | 对提交进行轻量级状态轮询（及原始生命周期详情）。 | | `get_quota` | 获取某一个后端的 API 配额 / 使用限制。 | ### 哈希与样本情报 | 工具 | 描述 | |---|---| | `search_hash` | 在 MalwareBazaar、Hybrid Analysis、tria.ge 中快速静态查找 MD5/SHA1/SHA256。 | | `bulk_hash_lookup` | 一次性查找多个哈希，用于 IOC 清理。 | | `compare_verdicts` | 跨沙箱和 VirusTotal 查找某个哈希，并比对判定结果、评分和家族。 | | `download_sample` | 获取原始样本（活跃恶意软件 —— 需要明确确认；保存至磁盘）。 | ### 引爆产物 | 工具 | 描述 | |---|---| | `get_dropped_files` | 从已完成的分析中检索释放/提取的二进制文件。 | | `get_pcap` | 下载某项分析的网络抓包（PCAP）。 | | `get_screenshots` | 提取执行截图以供视觉分诊。 | | `get_memory_strings` | 从进程内存转储中提取字符串（Hybrid Analysis）。 | | `export_iocs` | 将报告的 IOC 导出为 STIX / MISP / OpenIOC / CSV 格式。 | | `export_attack_layer` | 根据报告中的技术生成 MITRE ATT&CK Navigator 层级 JSON。 | ### IOC 丰富化与轮转 | 工具 | 描述 | |---|---| | `enrich_ioc` | 跨 ThreatFox、URLhaus、VirusTotal、Feodo 丰富 IP / 域名 / URL / 哈希。 | | `check_c2_blocklist` | 检查 IP/域名是否为已知的僵尸网络 C2（Feodo + ThreatFox + URLhaus）。 | | `search_samples` | 跨沙箱和 ThreatFox 按家族 / 标签 / 特征码 / IOC 进行搜索。 | | `pivot_ioc` | 给定一个 IOC，在 HA、tria.ge、MalwareBazaar、ThreatFox 中查找所有相关样本。 | ### URL 分析 | 工具 | 描述 | |---|---| | `scan_url` | 将 URL 提交至 URLScan.io（默认不公开；公开需要确认）。 | | `get_url_scan_result` | 检索 URLScan 结果（判定结果、截图 URL、联系过的基础设施）。 | ## 安装说明 要求 **Python 3.11+** 和 [**uv**](https://docs.astral.sh/uv/)。 ``` git clone https://github.com/mukul975/Malware-Sandbox-mcp.git cd Malware-Sandbox-mcp uv sync # create the venv and install dependencies uv run python server.py # run over stdio (Ctrl-C to stop) ``` Pip 备选方案： ``` python -m venv .venv && . .venv/Scripts/activate # Windows; use .venv/bin/activate elsewhere pip install -e . python server.py ``` ## 配置（BYOK —— 自带密钥） 每个后端都会从环境变量中读取**你自己的** API key。只需设置你拥有的即可 —— 任何未设置的都会被禁用，而服务器仍会启动。复制 [`.env.example`](.env.example) 并填写你已有的内容，或者直接在下面的 MCP 客户端配置中设置 key。 | 后端 | 环境变量 | 免费层级？ | 获取 key 的地址 | |---|---|---|---| | **Hybrid Analysis** (Falcon Sandbox) | `HA_API_KEY` | 是 —— 但需要进行一次性的**审核(vetting)**，才能将受限（仅限搜索）的 key 升级为完全提交/下载权限。 | [hybrid-analysis.com](https://hybrid-analysis.com) → 个人资料 → API key | | **tria.ge** (Recorded Future Sandbox) | `TRIAGE_API_KEY` | 是 —— 公共层级；**提交内容是公开的且无法删除**。 | [tria.ge](https://tria.ge) → 账户 → API 访问 | | **ANY.RUN** | `ANYRUN_API_KEY` | **否** —— API 需要付费的 Hunter/Enterprise 计划（或试用）。 | [app.any.run](https://app.any.run/plans) → API 与限制 | | **MalwareBazaar** (abuse.ch) | `MALWAREBAZAAR_API_KEY` 或 `ABUSECH_API_KEY` | 是 —— 合理使用；下载上限为 2,000/IP/天。 | [auth.abuse.ch](https://auth.abuse.ch/) | | **ThreatFox** (abuse.ch) | `THREATFOX_API_KEY` 或 `ABUSECH_API_KEY` | 是 —— 合理使用；超过 6 个月的 IOC 将过期。 | [auth.abuse.ch](https://auth.abuse.ch/) | | **URLhaus** (abuse.ch) | `URLHAUS_API_KEY` 或 `ABUSECH_API_KEY` | 是 —— 合理使用。 | [auth.abuse.ch](https://auth.abuse.ch/) | | **Feodo Tracker** (abuse.ch) | *(无)* | 是 —— 公共黑名单，无 key。 | 不适用 | | **URLScan.io** | `URLSCAN_API_KEY` | 是 —— 按分钟/小时/天进行速率限制。 | [urlscan.io](https://urlscan.io) → 设置 → API | | **VirusTotal** | `VT_API_KEY` 或 `VIRUSTOTAL_API_KEY` | 是 —— 公共 API：**4 次请求/分钟，500 次/天，仅供非商业用途**。 | [virustotal.com](https://www.virustotal.com) → API key | abuse.ch 现在为其所有服务签发**统一的 Auth-Key** —— 只需设置一次 `ABUSECH_API_KEY`，MalwareBazaar、ThreatFox 和 URLhaus 即可共同使用它（如果需要，各服务的独立变量会覆盖它）。 可选：`SANDBOX_ARTIFACTS_DIR` 用于设置下载的样本、PCAP 和截图的写入位置（默认为 `data/artifacts/`）。`TRIAGE_BASE_URL` 可将 tria.ge 指向私有云。 ### Claude Desktop / Claude Code 配置 将 [`.mcp.json.example`](.mcp.json.example) 复制到 `.mcp.json`（Claude Code，项目本地），或者将该代码块粘贴到 `claude_desktop_config.json` 中（Claude Desktop —— Windows 上为 `%APPDATA%\Claude\claude_desktop_config.json`）： ``` { "mcpServers": { "malware-sandbox": { "command": "uv", "args": ["run", "--directory", "D:\\Malware-Sandbox-mcp", "python", "server.py"], "timeout": 600000, "env": { "HA_API_KEY": "", "TRIAGE_API_KEY": "", "ABUSECH_API_KEY": "", "URLSCAN_API_KEY": "", "VT_API_KEY": "" } } } } ``` 在 Windows 上，如果你的客户端在 PATH 中找不到 `uv`，请使用 `cmd /c` 将其包裹起来： ``` "command": "cmd", "args": ["/c", "uv", "run", "--directory", "D:\\Malware-Sandbox-mcp", "python", "server.py"] ``` `timeout`（仅适用于 Claude Code）可防止长时间轮询会话和一次性的 MITRE ATT&CK 数据集下载被中断。如果报告被截断，请在运行 Claude Code 的环境中提高 `MAX_MCP_OUTPUT_TOKENS=50000` 的值。 ## 使用示例 连接服务器后可以使用自然语言提示词： - “将 `http://example.com` 提交到 tria.ge，并在完成后给我判定结果。” - “在所有地方查找哈希 `ed01ebfbc9eb5bbea545af4d01bf5f1071661840480439c6e5babe8e080e41aa` 并比较判定结果。” - “`8.8.8.8` 是已知的僵尸网络 C2 吗？” - “跨所有威胁情报源丰富域名 `example.com`。” - “查找与 AgentTesla 家族相关的样本。” - “为任务 `triage:240611-abc123` 导出 ATT&CK Navigator 层级。” 请参阅 [`TEST_QUERIES.md`](TEST_QUERIES.md) 获取覆盖每个工具的、可直接粘贴的参数。 ## 安全、法律及负责任的使用 - **仅限授权和防御性使用。** 这是为安全研究人员和 SOC/DFIR 分析师提供的分诊工具。 - **第三方提交。** 文件和 URL 将被发送至外部云沙箱。在免费/社区层级（tria.ge 公共版、abuse.ch 社区版、Hybrid Analysis 公共版），提交内容及其结果可能是**公开且不可删除的**。`submit_sample` 和公开的 `scan_url` 需要明确的确认标志。切勿提交机密、个人或专有数据。 - **此仓库中无活跃恶意软件。** 所有测试均使用模拟的 HTTP 响应（respx）；没有任何样本会离开测试运行器。 - **活跃恶意软件处理。** `download_sample` 会将真实的恶意软件检索到磁盘（MalwareBazaar 返回的 zip 密码为 `infected`）。它需要设置 `acknowledge_malware_download=true`，并保存至隔离目录，且绝对不会执行任何内容。仅可在隔离环境中处理下载的产物。 - **不受信任的内容。** 沙箱报告中的每个字符串都是受攻击者控制的，可能包含提示词注入文本；服务器严格将其作为数据传递。 - **提供商服务条款。** 你必须遵守每个后端的 ToS（例如 Hybrid Analysis 的审核/条款、abuse.ch 仅限确认恶意软件的政策、VirusTotal 的非商业公共 API 条款）。结果由其提供商授权；严格保持 BYOK 方式使用。 - **无担保。** 按“原样”提供（参见 [LICENSE](LICENSE)）；作者不对滥用行为承担责任。 如需报告安全问题，请参阅 [URITY.md](SECURITY.md)。 ## 开发说明 ``` uv sync --extra dev uv run pytest # 156 tests, fully offline (respx-mocked) uv run ruff check . # lint uv run ruff format . # format ``` 测试从不进行真实的网络调用 —— 所有沙箱/情报的 HTTP 均被 `respx` 拦截。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 贡献与政策 - [CONTRIBUTING.md](CONTRIBUTING.md) — 开发设置、测试、代码风格、PR 预期 - [SECURITY.md](SECURITY.md) — 负责任的披露 + 恶意软件处理政策 - [CHANGELOG.md](CHANGELOG.md) — 发布历史（维护更新日志） - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — 贡献者公约 ## 许可证 [MIT](LICENSE) © Mahipal 威胁情报和沙箱数据分别由 Hybrid Analysis、Recorded Future (tria.ge)、ANY.RUN、abuse.ch (MalwareBazaar / ThreatFox / URLhaus / Feodo Tracker)、URLScan.io 和 VirusTotal 根据其各自条款提供。MITRE ATT&CK® 是 The MITRE Corporation 的注册商标。

标签：Claude, CVE检测, DAST, MCP, Python, 威胁情报, 开发者工具, 恶意软件分析, 无后门, 沙箱, 逆向工具