Threatzonemcp

🚀 Threat.Zone MCP Server

このThreat.Zone API用のModel Context Protocol (MCP) サーバーは、FastMCPを使用して構築されています。このサーバーは、標準化されたMCPツールを通じて、LLMにThreat.Zoneのマルウェア分析機能へのアクセスを提供します。

✨ 主な機能

• ファイル分析：サンドボックス実行、静的分析、CDR (Content Disarm and Reconstruction) を含むマルウェア分析のためにファイルを送信します。
• URL分析：URLの脅威と悪意のあるコンテンツを分析します。
• 提出管理：詳細な分析結果、指標、IoC、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 Serverを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 Settings から取得します。

セットアップ手順

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. 重要な設定メモ

1. プレースホルダーを置き換える：

   • /full/path/to/your/threatzonemcp を実際の完全パスに置き換えます。
   • your_actual_api_key_here をThreat.Zone APIキーに置き換えます。

2. 完全パスを取得する：

cd threatzonemcp
pwd  # これで完全パスが表示されます

3. 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

4. API URLの設定 (オプション)：
   • パブリッククラウド：THREATZONE_API_URL を設定する必要はありません (デフォルトを使用します)。
   • プライベートテナント：THREATZONE_API_URL=https://your-tenant.threat.zone を設定します。
   • オンプレミス：THREATZONE_API_URL=https://your-server.company.com を設定します。

4. Claude Desktopを再起動する

設定を保存した後：

1. Claude Desktopを完全に終了します。
2. Claude Desktopを再起動します。
3. 新しいチャットで🔌アイコンを探して、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とやり取りできるはずです。

トラブルシューティング

一般的な問題

1. "Server not found"エラー：

   • 完全パスが正しいことを確認します。
   • UVがインストールされており、PATHに含まれていることを確認します。
   • コマンドを手動でテストします：uv run --directory /path/to/threatzonemcp threatzone-mcp

2. "API key required"エラー：

   • APIキーがenvセクションで正しく設定されていることを確認します。
   • APIキーがcurlで正常に動作することをテストします。

3. "Permission denied"エラー：

   • スクリプトが実行可能であることを確認します。
   • ファイルのパーミッションを確認します。

4. Pythonインポートエラー：

   • 仮想環境が正しく設定されていることを確認します。
   • PYTHONPATHにsrcディレクトリが含まれていることを確認します。

利用可能なツール

接続後、Claudeは次のThreat.Zoneツールにアクセスできます。

分析ツール

• URL分析：scan_url - URLの脅威を分析します。
• ファイル分析：
  • scan_file_sandbox - 完全な設定での高度なサンドボックス分析。
  • scan_file_sandbox_simple - デフォルト設定での簡単なサンドボックス分析。
  • scan_file_static - 静的ファイル分析。
  • scan_file_cdr - Content Disarm and Reconstruction。

結果と監視

• 提出詳細：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に次のような質問をすることができます。

"Analyze this suspicious PDF file with Windows 11 environment and internet access enabled"

"Check the status of my recent submissions and show me any that found malware"

"What are the network connections and DNS queries from submission UUID abc-123?"

"Download the analysis report for my latest submission"

"Monitor submission progress and notify me when analysis is complete"

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) - 指標の妥協 (IoC) を取得します。
• get_submission_yara_rules(uuid) - 一致したYARAルールを取得します。
• get_submission_varist_results(uuid) - Varist Hybrid Analyzerの結果を取得します。
• 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検査：暗号化されたトラフィックを監視します。
• 生ログ：詳細な実行ログを含めます。
• スナップショット：実行中にVMの状態をキャプチャします。
• スリープ回避：反分析技術を検出します。
• スマートトレーシング：高度な動作分析を行います。
• ダンプ収集器：メモリダンプを収集します。

使用例

基本的な使用法

# デフォルト設定を使用する
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は、提出の現在の状態を示す数値ステータスコードを返します。

脅威レベル値

分析結果には、発見された脅威の深刻度を示す脅威レベルが含まれています。

使用例

提出ステータスを確認する

# 生のステータスを取得する
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:  # Finished
            print(f"Analysis complete! Threat level: {summary['threat_level_description']}")
            break
        elif status == 2:  # Failed
            print("Analysis failed")
            break
        else:
            print(f"Status: {summary['status_description']}")
            await asyncio.sleep(10)  # Wait 10 seconds before checking again

APIリファレンス

すべてのツールはThreat.Zone API仕様に従っています。詳細なパラメータの説明とレスポンス形式については、Threat.Zone APIドキュメント を参照してください。

エラーハンドリング

サーバーには、次のような包括的なエラーハンドリングが含まれています。

• 認証失敗 (401)
• 無効なリクエスト (400/422)
• 見つからないエラー (404)
• レート制限
• ネットワーク問題

📄 ライセンス

GPL v3ライセンスです。詳細は LICENSE を参照してください。

コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. テストを追加します。
5. プルリクエストを送信します。

サポート

問題や質問については、以下を参照してください。

• GitHub Issues
• Threat.Zone Documentation
• メール：info@malwation.com