Threat.Zone MCP Server

``` ████████╗██╗ ██╗██████╗ ███████╗ █████╗ ████████╗ ███████╗ ██████╗ ███╗ ██╗███████╗███╗ ███╗ ██████╗██████╗ ╚══██╔══╝██║ ██║██╔══██╗██╔════╝██╔══██╗╚══██╔══╝ ╚══███╔╝██╔═══██╗████╗ ██║██╔════╝████╗ ████║██╔════╝██╔══██╗ ██║ ███████║██████╔╝█████╗ ███████║ ██║ ███╔╝ ██║ ██║██╔██╗ ██║█████╗ ██╔████╔██║██║ ██████╔╝ ██║ ██╔══██║██╔══██╗██╔══╝ ██╔══██║ ██║ ███╔╝ ██║ ██║██║╚██╗██║██╔══╝ ██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║ ██║██║ ██║███████╗██║ ██║ ██║ ██╗███████╗╚██████╔╝██║ ╚████║███████╗██║ ╚═╝ ██║╚██████╗██║ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝╚═╝ ╚═╝ ╚═════╝╚═╝ ``` # 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 ```bash pip install threatzone-mcp ``` ### Using uv (recommended) ```bash uv add threatzone-mcp ``` ### Development Installation ```bash git clone https://github.com/threat-zone/threatzonemcp.git cd threatzonemcp uv sync --dev ``` ## Configuration Set your Threat.Zone API credentials as environment variables: ```bash 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: ```env 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](https://claude.ai/download) 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](https://app.threat.zone/settings/api-key) ## Setup Steps ### 1. Prepare the MCP Server ```bash # 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`**: ```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 ```json { "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 ```json { "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**: ```bash cd threatzonemcp pwd # This shows the full path ``` 3. **Verify API key**: Make sure your API key is valid by testing: ```bash # 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 ``` 4. **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 ```bash # 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**: ```python # Use default settings await client.call_tool("scan_file_sandbox_simple", { "file_path": "/path/to/file.exe" }) ``` **Advanced Analysis**: ```python # 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**: ```python # 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**: ```python 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](https://app.threat.zone/public-api/docs). ## 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](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: - [GitHub Issues](https://github.com/threat-zone/threatzonemcp/issues) - [Threat.Zone Documentation](https://threat.zone/docs) - Email: info@malwation.com