Threatzonemcp

🚀 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 <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（推薦）
     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"
      }
    }
  }
}

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 中，嘗試詢問：

"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 返回的數字狀態碼錶示提交的當前狀態：

威脅級別值

分析結果包含一個威脅級別，指示發現的嚴重程度：

錯誤處理

服務器包括全面的錯誤處理，用於處理以下情況：

• 身份驗證失敗（401）
• 無效請求（400/422）
• 未找到錯誤（404）
• 速率限制
• 網絡問題

📄 許可證

本項目採用 GPL v3 許可證。詳情請參閱 LICENSE。

貢獻

1. 分叉倉庫。
2. 創建功能分支。
3. 進行更改。
4. 添加測試。
5. 提交拉取請求。

支持

如有問題和疑問，請參考：

• GitHub Issues
• Threat.Zone 文檔
• 郵箱：info@malwation.com