金大哥 - threatzonemcp MCP 详情

article

README

🚀 Threat.Zone MCP 服务器

Threat.Zone MCP 服务器是基于 FastMCP 构建的模型上下文协议（MCP）服务器，用于连接 Threat.Zone API。它能让大语言模型（LLMs）通过标准化的 MCP 工具调用 Threat.Zone 的恶意软件分析能力。

🚀 快速开始

安装

使用 pip

pip install threatzone-mcp

使用 uv（推荐）

uv add threatzone-mcp

开发环境安装

git clone https://github.com/threat-zone/threatzonemcp.git
cd threatzonemcp
uv sync --dev

配置

你可以通过设置环境变量来配置 Threat.Zone API 凭证：

export THREATZONE_API_KEY="your_api_key_here"
# 可选：适用于私有租户或本地部署
export THREATZONE_API_URL="https://your-tenant.threat.zone"

或者创建一个 .env 文件：

THREATZONE_API_KEY=your_api_key_here
# 可选：自定义 API URL（默认为 https://app.threat.zone）
THREATZONE_API_URL=https://your-tenant.threat.zone

支持的部署方式有：

公共云：https://app.threat.zone（默认）
私有租户：https://your-tenant.threat.zone
本地部署：https://your-server.company.com

连接到 Claude Desktop

前提条件

安装 Claude Desktop - 从 Claude Desktop 下载。
安装 UV - brew install uv 或者 curl -LsSf https://astral.sh/uv/install.sh | sh。
获取 Threat.Zone API 密钥 - 从 Threat.Zone 设置获取。

设置步骤

准备 MCP 服务器

# 克隆并设置项目
git clone <your-repo-url>
cd threatzonemcp

# 使用 UV 安装
uv venv
uv pip install -e .

# 测试服务器是否正常工作
THREATZONE_API_KEY=your_key uv run threatzone-mcp
# 应该无错误启动

配置 Claude Desktop
- 选项 A：使用 UV（推荐）
  1. 找到 Claude Desktop 配置目录：
    - macOS：~/Library/Application Support/Claude/
    - Windows：%APPDATA%\Claude\
    - Linux：~/.config/Claude/
  2. 创建或编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "threatzone": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/your/threatzonemcp",
        "threatzone-mcp"
      ],
      "env": {
        "THREATZONE_API_KEY": "your_actual_api_key_here",
        "THREATZONE_API_URL": "https://your-tenant.threat.zone"
      }
    }
  }
}

- **选项 B：直接使用 Python**

{
  "mcpServers": {
    "threatzone": {
      "command": "python",
      "args": [
        "-m",
        "threatzone_mcp.server"
      ],
      "cwd": "/full/path/to/your/threatzonemcp",
      "env": {
        "THREATZONE_API_KEY": "your_actual_api_key_here",
        "PYTHONPATH": "/full/path/to/your/threatzonemcp/src"
      }
    }
  }
}

- **选项 C：直接使用虚拟环境**

{
  "mcpServers": {
    "threatzone": {
      "command": "/full/path/to/your/threatzonemcp/.venv/bin/python",
      "args": [
        "-m",
        "threatzone_mcp.server"
      ],
      "cwd": "/full/path/to/your/threatzonemcp",
      "env": {
        "THREATZONE_API_KEY": "your_actual_api_key_here",
        "PYTHONPATH": "/full/path/to/your/threatzonemcp/src"
      }
    }
  }
}

重要配置说明
- 替换占位符：
  - 将 /full/path/to/your/threatzonemcp 替换为实际的完整路径。
  - 将 your_actual_api_key_here 替换为你的 Threat.Zone API 密钥。
- 获取完整路径：

cd threatzonemcp
pwd  # 这将显示完整路径

- **验证 API 密钥**：通过以下命令测试 API 密钥是否有效：

# 公共云（默认）
curl -H "Authorization: Bearer your_api_key" https://app.threat.zone/public-api/me

# 私有租户或本地部署
curl -H "Authorization: Bearer your_api_key" https://your-tenant.threat.zone/public-api/me

- **API URL 配置（可选）**：
    - **公共云**：无需设置 `THREATZONE_API_URL`（使用默认值）。
    - **私有租户**：设置 `THREATZONE_API_URL=https://your-tenant.threat.zone`。
    - **本地部署**：设置 `THREATZONE_API_URL=https://your-server.company.com`。

4. 重启 Claude Desktop 保存配置后： - 完全退出 Claude Desktop。 - 重新启动 Claude Desktop。 - 在新聊天中查找 🔌 图标 以确认 MCP 服务器已连接。 5. 测试连接 在 Claude Desktop 中，尝试询问：

"Can you get my Threat.Zone user information?" 或者 "What are the available threat levels in Threat.Zone?" Claude 应该能够使用 MCP 工具与 Threat.Zone API 进行交互。

✨ 主要特性

文件分析：提交文件进行恶意软件分析，包括沙箱执行、静态分析和 CDR（内容解除武装和重建）。
URL 分析：分析 URL 中的威胁和恶意内容。
提交管理：检索详细的分析结果、指标、IoC 和 YARA 规则。
网络分析：访问 DNS 查询、HTTP/TCP/UDP 请求和网络威胁。
报告生成：下载清理后的文件和 HTML 报告。
用户管理：获取用户信息和提交限制。

💻 使用示例

基础用法

# 使用安装的脚本
threatzone-mcp

# 或者直接使用 Python
python -m threatzone_mcp.server

高级用法

高级沙箱分析

scan_file_sandbox 工具支持全面的配置选项，用于详细的恶意软件分析：

# 简单分析
await client.call_tool("scan_file_sandbox_simple", {
    "file_path": "/path/to/file.exe"
})

# 高级分析
await client.call_tool("scan_file_sandbox", {
    "file_path": "/path/to/file.exe",
    "environment": "w11_x64",
    "timeout": 300,
    "internet_connection": True,
    "https_inspection": True,
    "raw_logs": True,
    "modules": ["csi", "cdr"]
})

检查提交状态

# 获取原始状态
submission = await client.call_tool("get_submission", {"uuid": "submission_id"})
print(f"Status code: {submission['status']}")

# 获取解释后的状态
summary = await client.call_tool("get_submission_status_summary", {"uuid": "submission_id"})
print(f"Status: {summary['status_description']}")
print(f"Threat Level: {summary['threat_level_description']}")

监控分析进度

import asyncio

async def wait_for_analysis(uuid):
    while True:
        summary = await client.call_tool("get_submission_status_summary", {"uuid": uuid})
        status = summary.get('status')
        
        if status == 5:  # 完成
            print(f"Analysis complete! Threat level: {summary['threat_level_description']}")
            break
        elif status == 2:  # 失败
            print("Analysis failed")
            break
        else:
            print(f"Status: {summary['status_description']}")
            await asyncio.sleep(10)  # 每 10 秒检查一次

📚 详细文档

可用工具

常量与辅助函数

get_metafields() - 获取高级配置可用的元字段。
get_levels() - 获取威胁级别。
get_statuses() - 获取提交状态。
get_sample_metafield() - 获取沙箱分析的示例配置。
interpret_status(status_value) - 将数字状态转换为可读描述。
interpret_threat_level(level_value) - 将数字威胁级别转换为描述。
get_submission_status_summary(uuid) - 获取带有解释状态和威胁级别的提交信息。
get_server_config() - 获取当前服务器配置和连接状态。

用户信息

get_user_info() - 获取当前用户信息和限制。

扫描

scan_url(url, is_public=False) - 分析 URL。
scan_file_sandbox(file_path, ...) - 提交文件进行高级沙箱分析，支持完整配置。
scan_file_sandbox_simple(file_path, is_public=False, entrypoint=None, password=None) - 提交文件进行默认设置的沙箱分析。
scan_file_static(file_path, is_public=False, entrypoint=None, password=None) - 提交文件进行静态分析。
scan_file_cdr(file_path, is_public=False, entrypoint=None, password=None) - 提交文件进行 CDR 处理。

提交检索

get_submission(uuid) - 获取提交详细信息。
get_submission_indicators(uuid) - 获取提交指标。
get_submission_iocs(uuid) - 获取攻击指标。
get_submission_yara_rules(uuid) - 获取匹配的 YARA 规则。
get_submission_varist_results(uuid) - 获取 Varist 混合分析结果。
get_submission_artifacts(uuid) - 获取分析工件。
get_submission_config_extractor(uuid) - 获取提取的配置。

网络分析

get_submission_dns(uuid) - 获取 DNS 查询。
get_submission_http(uuid) - 获取 HTTP 请求。
get_submission_tcp(uuid) - 获取 TCP 请求。
get_submission_udp(uuid) - 获取 UDP 请求。
get_submission_network_threats(uuid) - 获取网络威胁。

用户提交

get_my_submissions(page=1, jump=10) - 获取用户的提交。
get_public_submissions(page=1, jump=10) - 获取公共提交。
search_by_hash(hash, page=1, jump=10) - 通过哈希搜索提交。

下载

download_sanitized_file(uuid) - 下载 CDR 清理后的文件。
download_html_report(uuid) - 下载 HTML 分析报告。

高级沙箱分析配置

环境选项

Windows：w7_x64, w10_x64, w11_x64
macOS：macos
Android：android
Linux：linux

分析配置

超时时间：60、120、180、240 或 300 秒。
工作路径：desktop, root, %AppData%, windows, temp。
鼠标模拟：启用/禁用用户交互模拟。
互联网连接：允许/阻止网络访问。
HTTPS 检查：监控加密流量。
原始日志：包含详细的执行日志。
快照：在执行期间捕获 VM 状态。
睡眠逃避检测：检测反分析技术。
智能跟踪：高级行为分析。
转储收集器：收集内存转储。

🔧 技术细节

结果解读

提交状态值

API 返回的数字状态码表示提交的当前状态： | 值 | 状态 | 描述 | |-------|--------|-------------| | 1 | File received | 文件已上传并排队等待分析 | | 2 | Submission failed | 分析因错误或超时失败 | | 3 | Submission running | 分析正在进行中 | | 4 | Submission VM ready | 虚拟机已准备好并开始分析 | | 5 | Submission finished | 分析已成功完成 |

威胁级别值

分析结果包含一个威胁级别，指示发现的严重程度： | 值 | 级别 | 描述 | |-------|-------|-------------| | 0 | Unknown | 无法确定威胁级别 | | 1 | Informative | 文件看起来无害，但有一些值得注意的行为 | | 2 | Suspicious | 文件表现出潜在的恶意特征 | | 3 | Malicious | 文件被确认为恶意软件或高度危险 |

错误处理

服务器包括全面的错误处理，用于处理以下情况：

身份验证失败（401）
无效请求（400/422）
未找到错误（404）
速率限制
网络问题

📄 许可证

本项目采用 GPL v3 许可证。详情请参阅 LICENSE。

贡献

分叉仓库。
创建功能分支。
进行更改。
添加测试。
提交拉取请求。

支持

如有问题和疑问，请参考：

GitHub Issues
Threat.Zone 文档
邮箱：info@malwation.com