Threatzonemcp

Threatzonemcp

安全 Python

🚀 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

前提条件

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

设置步骤

  1. 准备 MCP 服务器
# 克隆并设置项目
git clone 
cd threatzonemcp

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

# 测试服务器是否正常工作
THREATZONE_API_KEY=your_key uv run threatzone-mcp
# 应该无错误启动
  1. 配置 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"
}
}
}
}
  1. 重要配置说明
    • 替换占位符：
      • 将 /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`。
  1. 重启 Claude Desktop 保存配置后：
    • 完全退出 Claude Desktop。
    • 重新启动 Claude Desktop。
    • 在新聊天中查找 🔌 图标 以确认 MCP 服务器已连接。
  2. 测试连接 在 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。

贡献

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

支持

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

默认排序 时间排序

0 个评论

« 上一篇
Eventwhisper
下一篇 »
Cursor Mcp Trivy
  • 0 关注
  • 0 收藏，16 浏览
  • system 提出于 2025-09-29 21:39

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »