Submit
threat-zone

Threat.Zone MCP Server

Community threat-zone
Updated

MCP Server for Threat.Zone Holistic Malware Analysis Platform

████████╗██╗  ██╗██████╗ ███████╗ █████╗ ████████╗   ███████╗ ██████╗ ███╗   ██╗███████╗███╗   ███╗ ██████╗██████╗ 
╚══██╔══╝██║  ██║██╔══██╗██╔════╝██╔══██╗╚══██╔══╝   ╚══███╔╝██╔═══██╗████╗  ██║██╔════╝████╗ ████║██╔════╝██╔══██╗
   ██║   ███████║██████╔╝█████╗  ███████║   ██║        ███╔╝ ██║   ██║██╔██╗ ██║█████╗  ██╔████╔██║██║     ██████╔╝
   ██║   ██╔══██║██╔══██╗██╔══╝  ██╔══██║   ██║       ███╔╝  ██║   ██║██║╚██╗██║██╔══╝  ██║╚██╔╝██║██║     ██╔═══╝ 
   ██║   ██║  ██║██║  ██║███████╗██║  ██║   ██║   ██╗███████╗╚██████╔╝██║ ╚████║███████╗██║ ╚═╝ ██║╚██████╗██║     
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝   ╚═╝   ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝╚═╝     ╚═╝ ╚═════╝╚═╝

Threat.Zone MCP Server

A Model Context Protocol (MCP) server for the Threat.Zone API, built with FastMCP. This server provides LLMs with access to Threat.Zone's malware analysis capabilities through standardized MCP tools.

Features

  • File Analysis: Submit files for malware analysis including sandbox execution, static analysis, and CDR (Content Disarm and Reconstruction)
  • URL Analysis: Analyze URLs for threats and malicious content
  • Submission Management: Retrieve detailed analysis results, indicators, IoCs, and YARA rules
  • Network Analysis: Access DNS queries, HTTP/TCP/UDP requests, and network threats
  • Report Generation: Download sanitized files and HTML reports
  • User Management: Get user information and submission limits

Installation

Using pip

pip install threatzone-mcp

Using uv (recommended)

uv add threatzone-mcp

Development Installation

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

Configuration

Set your Threat.Zone API credentials as environment variables:

export THREATZONE_API_KEY="your_api_key_here"
# Optional: For private tenants or on-premise deployments
export THREATZONE_API_URL="https://your-tenant.threat.zone"

Or create a .env file:

THREATZONE_API_KEY=your_api_key_here
# Optional: Custom API URL (defaults to https://app.threat.zone)
THREATZONE_API_URL=https://your-tenant.threat.zone

Supported Deployments

  • Public Cloud: https://app.threat.zone (default)
  • Private Tenant: https://your-tenant.threat.zone
  • On-Premise: https://your-server.company.com

Connecting Threat.Zone MCP Server to Claude Desktop

Prerequisites

  1. Claude Desktop installed - Download from Claude Desktop
  2. UV installed - brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
  3. Threat.Zone API Key - Get from Threat.Zone Settings

Setup Steps

1. Prepare the MCP Server

# Clone and setup the project
git clone <your-repo-url>
cd threatzonemcp

# Install with UV
uv venv
uv pip install -e .

# Test the server works
THREATZONE_API_KEY=your_key uv run threatzone-mcp
# Should start without errors

2. Configure Claude Desktop

Option A: Using UV (Recommended)

  1. Find your Claude Desktop config directory:

    • macOS: ~/Library/Application Support/Claude/
    • Windows: %APPDATA%\Claude\
    • Linux: ~/.config/Claude/

  2. Create or edit 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"
       }
    }
  }
}
Option B: Using Python directly
{
  "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"
      }
    }
  }
}
Option C: Using virtual environment directly
{
  "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. Important Configuration Notes

  1. Replace placeholders:

    • Replace /full/path/to/your/threatzonemcp with the actual full path
    • Replace your_actual_api_key_here with your Threat.Zone API key

  2. Get the full path:

cd threatzonemcp
pwd  # This shows the full path
  1. Verify API key: Make sure your API key is valid by testing:
# For public cloud (default)
curl -H "Authorization: Bearer your_api_key" https://app.threat.zone/public-api/me

# For private tenant or on-premise
curl -H "Authorization: Bearer your_api_key" https://your-tenant.threat.zone/public-api/me
  1. API URL Configuration (Optional):
    • Public Cloud: No need to set THREATZONE_API_URL (uses default)
    • Private Tenant: Set THREATZONE_API_URL=https://your-tenant.threat.zone
    • On-Premise: Set THREATZONE_API_URL=https://your-server.company.com

4. Restart Claude Desktop

After saving the configuration:

  1. Quit Claude Desktop completely
  2. Restart Claude Desktop
  3. Look for the 🔌 icon in a new chat to confirm MCP servers are connected

5. Test the Connection

In Claude Desktop, try asking:

"Can you get my Threat.Zone user information?"

or

"What are the available threat levels in Threat.Zone?"

Claude should be able to use the MCP tools to interact with the Threat.Zone API.

Troubleshooting

Common Issues

  1. "Server not found" error:

    • Check the full path is correct
    • Verify UV is installed and in PATH
    • Test the command manually: uv run --directory /path/to/threatzonemcp threatzone-mcp

  2. "API key required" error:

    • Verify the API key is set correctly in the env section
    • Test the API key works with curl

  3. "Permission denied" error:

    • Make sure the script is executable
    • Check file permissions

  4. Python import errors:

    • Verify the virtual environment is properly set up
    • Check PYTHONPATH includes the src directory

Available Tools

Once connected, Claude will have access to these Threat.Zone tools:

Analysis Tools

  • URL Analysis: scan_url - Analyze URLs for threats
  • File Analysis:
    • scan_file_sandbox - Advanced sandbox analysis with full configuration
    • scan_file_sandbox_simple - Simple sandbox analysis with defaults
    • scan_file_static - Static file analysis
    • scan_file_cdr - Content Disarm and Reconstruction

Results & Monitoring

  • Submission Details: get_submission, get_submission_status_summary
  • Threat Intelligence: get_submission_indicators, get_submission_iocs
  • Detection Rules: get_submission_yara_rules, get_submission_varist_results
  • Network Activity: get_submission_dns, get_submission_http, get_submission_tcp, get_submission_udp, get_submission_network_threats
  • Artifacts: get_submission_artifacts, get_submission_config_extractor

Helper Functions

  • Status Interpretation: interpret_status, interpret_threat_level
  • Constants: get_metafields, get_levels, get_statuses, get_sample_metafield

User Management

  • Account Info: get_user_info
  • Submission History: get_my_submissions, get_public_submissions
  • Search: search_by_hash

Downloads

  • Files: download_sanitized_file (CDR-cleaned files)
  • Reports: download_html_report (detailed analysis reports)

Example Claude Conversations

Once connected, you can ask Claude things like:

"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 will use the appropriate MCP tools to interact with Threat.Zone and provide comprehensive malware analysis insights!

Usage

Running the Server

# Using the installed script
threatzone-mcp

# Or directly with Python
python -m threatzone_mcp.server

Available Tools

The server provides the following MCP tools:

Constants & Helpers
  • get_metafields() - Get available metafields for advanced configuration
  • get_levels() - Get threat levels
  • get_statuses() - Get submission statuses
  • get_sample_metafield() - Get sample configuration for sandbox analysis
  • interpret_status(status_value) - Convert numeric status to human-readable description
  • interpret_threat_level(level_value) - Convert numeric threat level to description
  • get_submission_status_summary(uuid) - Get submission with interpreted status and threat level
  • get_server_config() - Get current server configuration and connection status
User Information
  • get_user_info() - Get current user information and limits
Scanning
  • scan_url(url, is_public=False) - Analyze a URL
  • scan_file_sandbox(file_path, ...) - Submit file for advanced sandbox analysis with full configuration
  • scan_file_sandbox_simple(file_path, is_public=False, entrypoint=None, password=None) - Submit file for sandbox analysis with default settings
  • scan_file_static(file_path, is_public=False, entrypoint=None, password=None) - Submit file for static analysis
  • scan_file_cdr(file_path, is_public=False, entrypoint=None, password=None) - Submit file for CDR processing
Submission Retrieval
  • get_submission(uuid) - Get submission details
  • get_submission_indicators(uuid) - Get submission indicators
  • get_submission_iocs(uuid) - Get Indicators of Compromise
  • get_submission_yara_rules(uuid) - Get matched YARA rules
  • get_submission_varist_results(uuid) - Get Varist Hybrid Analyzer results
  • get_submission_artifacts(uuid) - Get analysis artifacts
  • get_submission_config_extractor(uuid) - Get extracted configurations
Network Analysis
  • get_submission_dns(uuid) - Get DNS queries
  • get_submission_http(uuid) - Get HTTP requests
  • get_submission_tcp(uuid) - Get TCP requests
  • get_submission_udp(uuid) - Get UDP requests
  • get_submission_network_threats(uuid) - Get network threats
User Submissions
  • get_my_submissions(page=1, jump=10) - Get user's submissions
  • get_public_submissions(page=1, jump=10) - Get public submissions
  • search_by_hash(hash, page=1, jump=10) - Search submissions by hash
Downloads
  • download_sanitized_file(uuid) - Download CDR-sanitized file
  • download_html_report(uuid) - Download HTML analysis report

Advanced Sandbox Analysis

The scan_file_sandbox tool supports comprehensive configuration options for detailed malware analysis:

Environment Options

  • Windows: w7_x64, w10_x64, w11_x64
  • macOS: macos
  • Android: android
  • Linux: linux

Analysis Configuration

  • Timeout: 60, 120, 180, 240, or 300 seconds
  • Work Path: desktop, root, %AppData%, windows, temp
  • Mouse Simulation: Enable/disable user interaction simulation
  • Internet Connection: Allow/block network access
  • HTTPS Inspection: Monitor encrypted traffic
  • Raw Logs: Include detailed execution logs
  • Snapshots: Capture VM state during execution
  • Sleep Evasion: Detect anti-analysis techniques
  • Smart Tracing: Advanced behavioral analysis
  • Dump Collector: Collect memory dumps

Usage Examples

Simple Analysis:

# Use default settings
await client.call_tool("scan_file_sandbox_simple", {
    "file_path": "/path/to/file.exe"
})

Advanced Analysis:

# Full configuration control
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"]
})

See examples/advanced_sandbox_example.py for detailed usage examples.

Understanding Results

Submission Status Values

The API returns numeric status codes that indicate the current state of your submission:

Value Status Description
1 File received File has been uploaded and queued for analysis
2 Submission failed Analysis failed due to error or timeout
3 Submission running Analysis is currently in progress
4 Submission VM ready Virtual machine is prepared and starting analysis
5 Submission finished Analysis completed successfully

Threat Level Values

Analysis results include a threat level indicating the severity of findings:

Value Level Description
0 Unknown Unable to determine threat level
1 Informative File appears benign with some notable behaviors
2 Suspicious File exhibits potentially malicious characteristics
3 Malicious File confirmed as malware or highly dangerous

Usage Examples

Check submission status:

# Get raw status
submission = await client.call_tool("get_submission", {"uuid": "submission_id"})
print(f"Status code: {submission['status']}")

# Get interpreted 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']}")

Monitor analysis progress:

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 Reference

All tools follow the Threat.Zone API specification. For detailed parameter descriptions and response formats, refer to the Threat.Zone API documentation.

Error Handling

The server includes comprehensive error handling for:

  • Authentication failures (401)
  • Invalid requests (400/422)
  • Not found errors (404)
  • Rate limiting
  • Network issues

License

GPL v3 License. See LICENSE for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Support

For issues and questions:

MCP Server · Populars

MCP Server · New