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

Using uv (recommended)

Development Installation

Configuration

Set your Threat.Zone API credentials as environment variables:

Or create a .env file:

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

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:

Option B: Using Python directly

Option C: Using virtual environment directly

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:

3. Verify API key: Make sure your API key is valid by testing:

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

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:

Advanced Analysis:

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:

Threat Level Values

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

Usage Examples

Check submission status:

Monitor analysis progress:

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:

• GitHub Issues
• Threat.Zone Documentation
• Email: info@malwation.com