威胁区域mcp

Name: 威胁区域mcp
Author: threat-zone

作者：threat-zone14 星标更新：2025-07-09

安装使用来源：spider==github.com

项目介绍

Threat.Zone MCP 服务器

这是一个用于 Threat.Zone API 的模型上下文协议（MCP）服务器，使用 FastMCP 构建。此服务器通过标准化的 MCP 工具为大型语言模型提供访问 Threat.Zone 马尔软件分析功能的能力。

功能

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

安装

使用 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

将 Threat.Zone MCP 服务器连接到 Claude Desktop

前提条件

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

设置步骤

1. 准备 MCP 服务器

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

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

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

2. 配置 Claude Desktop

选项 A：使用 UV（推荐）

找到您的 Claude Desktop 配置目录：
- macOS：~/Library/Application Support/Claude/
- Windows：%APPDATA%\Claude\
- Linux：~/.config/Claude/
创建或编辑 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"
      }
    }
  }
}

3. 重要配置说明

替换占位符：
- 替换 /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 中，尝试询问：

"你能获取我的 Threat.Zone 用户信息吗？"

或

"Threat.Zone 中有哪些可用的威胁级别？"

Claude 应该能够使用 MCP 工具与 Threat.Zone API 进行交互。

故障排除

常见问题

“未找到服务器” 错误：
- 检查完整路径是否正确
- 确认 UV 已安装并在 PATH 中
- 手动测试命令：uv run --directory /path/to/threatzonemcp threatzone-mcp
“需要 API 密钥” 错误：
- 确认 API 密钥在 env 部分设置正确
- 使用 curl 测试 API 密钥是否有效
“权限被拒绝” 错误：
- 确保脚本具有可执行权限
- 检查文件权限
Python 导入错误：
- 确认虚拟环境已正确设置
- 检查 PYTHONPATH 包含 src 目录

可用工具

一旦连接，Claude 将可以访问这些 Threat.Zone 工具：

分析工具

URL 分析：scan_url - 分析 URL 中的威胁
文件分析：
- scan_file_sandbox - 具有完整配置的高级沙箱分析
- scan_file_sandbox_simple - 使用默认设置的简单沙箱分析
- scan_file_static - 静态文件分析
- scan_file_cdr - 内容解除武装与重建

结果与监控

提交详情：get_submission，get_submission_status_summary
威胁情报：get_submission_indicators，get_submission_iocs
检测规则：get_submission_yara_rules，get_submission_varist_results
网络活动：get_submission_dns，get_submission_http，get_submission_tcp，get_submission_udp，get_submission_network_threats
工件：get_submission_artifacts，get_submission_config_extractor

辅助函数

状态解释：interpret_status，interpret_threat_level
常量：get_metafields，get_levels，get_statuses，get_sample_metafield

用户管理

账户信息：get_user_info
提交历史：get_my_submissions，get_public_submissions
搜索：search_by_hash

下载

文件：download_sanitized_file（CDR 清理过的文件）
报告：download_html_report（详细分析报告）

示例 Claude 对话

一旦连接，您可以向 Claude 提问如下内容：

"使用 Windows 11 环境和启用互联网访问来分析这个可疑的 PDF 文件"

"检查我最近提交的状态，并显示任何发现恶意软件的"

"提交 UUID abc-123 的网络连接和 DNS 查询是什么？"

"下载我最新提交的分析报告"

"监控提交进度，在分析完成后通知我"

Claude 将使用适当的 MCP 工具与 Threat.Zone 互动，并提供全面的马尔软件分析见解！

使用

运行服务器

# 使用已安装的脚本
threatzone-mcp

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

可用工具

服务器提供了以下 MCP 工具：

常量与辅助

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 分析报告

高级沙箱分析

scan_file_sandbox 工具支持详尽的配置选项，用于详细的马尔软件分析：

环境选项

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

分析配置

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

使用示例

简单分析：

# 使用默认设置
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"]
})

参见 examples/advanced_sandbox_example.py 以获取详细的使用示例。

理解结果

提交状态值

API 返回数字状态码，指示您的提交当前状态：

值	状态	描述
1	文件接收	文件已上传并排队等待分析
2	提交失败	分析因错误或超时而失败
3	提交运行中	分析正在进行中
4	虚拟机准备就绪	虚拟机已准备好并开始分析
5	提交完成	分析成功完成

威胁级别值

分析结果包括一个威胁级别，表示发现的严重程度：

值	级别	描述
0	未知	无法确定威胁级别
1	信息性	文件看似良性但有一些值得注意的行为
2	可疑	文件表现出潜在的恶意特征
3	恶意	文件确认为马尔软件或高度危险

使用示例

检查提交状态：

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

# 获取解释状态
summary = await client.call_tool("get_submission_status_summary", {"uuid": "submission_id"})
print(f"状态：{summary['status_description']}")
print(f"威胁级别：{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"分析完成！威胁级别：{summary['threat_level_description']}")
            break
        elif status == 2:  # 失败
            print("分析失败")
            break
        else:
            print(f"状态：{summary['status_description']}")
            await asyncio.sleep(10)  # 再次检查前等待 10 秒

API 参考

所有工具遵循 Threat.Zone API 规范。有关详细参数描述和响应格式，请参考 Threat.Zone API 文档。

错误处理

服务器包括全面的错误处理，针对：

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

许可

GPL v3 许可。详情见 LICENSE。

贡献

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

支持

对于问题和疑问：