Offers sandbox analysis capabilities for Android environments, enabling malware analysis on Android systems.
Provides sandbox analysis in Linux environments for analyzing potentially malicious files and their behavior.
Enables sandbox analysis in macOS environments to detect and analyze threats targeting Apple operating systems.
Uses Python for implementation and provides Python-based installation methods for the 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
Claude Desktop installed - Download from Claude Desktop
UV installed -
brew install uv
orcurl -LsSf https://astral.sh/uv/install.sh | sh
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)
Find your Claude Desktop config directory:
macOS:
~/Library/Application Support/Claude/
Windows:
%APPDATA%\Claude\
Linux:
~/.config/Claude/
Create or edit :
Option B: Using Python directly
Option C: Using virtual environment directly
3. Important Configuration Notes
Replace placeholders:
Replace
/full/path/to/your/threatzonemcp
with the actual full pathReplace
your_actual_api_key_here
with your Threat.Zone API key
Get the full path:
Verify API key: Make sure your API key is valid by testing:
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:
Quit Claude Desktop completely
Restart Claude Desktop
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
"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
"API key required" error:
Verify the API key is set correctly in the env section
Test the API key works with curl
"Permission denied" error:
Make sure the script is executable
Check file permissions
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 threatsFile Analysis:
scan_file_sandbox
- Advanced sandbox analysis with full configurationscan_file_sandbox_simple
- Simple sandbox analysis with defaultsscan_file_static
- Static file analysisscan_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 configurationget_levels()
- Get threat levelsget_statuses()
- Get submission statusesget_sample_metafield()
- Get sample configuration for sandbox analysisinterpret_status(status_value)
- Convert numeric status to human-readable descriptioninterpret_threat_level(level_value)
- Convert numeric threat level to descriptionget_submission_status_summary(uuid)
- Get submission with interpreted status and threat levelget_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 URLscan_file_sandbox(file_path, ...)
- Submit file for advanced sandbox analysis with full configurationscan_file_sandbox_simple(file_path, is_public=False, entrypoint=None, password=None)
- Submit file for sandbox analysis with default settingsscan_file_static(file_path, is_public=False, entrypoint=None, password=None)
- Submit file for static analysisscan_file_cdr(file_path, is_public=False, entrypoint=None, password=None)
- Submit file for CDR processing
Submission Retrieval
get_submission(uuid)
- Get submission detailsget_submission_indicators(uuid)
- Get submission indicatorsget_submission_iocs(uuid)
- Get Indicators of Compromiseget_submission_yara_rules(uuid)
- Get matched YARA rulesget_submission_varist_results(uuid)
- Get Varist Hybrid Analyzer resultsget_submission_artifacts(uuid)
- Get analysis artifactsget_submission_config_extractor(uuid)
- Get extracted configurations
Network Analysis
get_submission_dns(uuid)
- Get DNS queriesget_submission_http(uuid)
- Get HTTP requestsget_submission_tcp(uuid)
- Get TCP requestsget_submission_udp(uuid)
- Get UDP requestsget_submission_network_threats(uuid)
- Get network threats
User Submissions
get_my_submissions(page=1, jump=10)
- Get user's submissionsget_public_submissions(page=1, jump=10)
- Get public submissionssearch_by_hash(hash, page=1, jump=10)
- Search submissions by hash
Downloads
download_sanitized_file(uuid)
- Download CDR-sanitized filedownload_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:
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:
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
Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request
Support
For issues and questions:
Tools
Provides LLMs with access to Threat.Zone's malware analysis capabilities through standardized MCP tools, allowing for file and URL analysis, sandbox execution, and threat intelligence retrieval.
Related MCP Servers
- -securityAlicense-qualityAn MCP server that provides tools to load and fetch documentation from any llms.txt source, giving users full control over context retrieval for LLMs in IDE agents and applications.Last updated -752MIT License
- -securityFlicense-qualityAn MCP server that integrates various penetration testing tools, enabling security professionals to perform reconnaissance, vulnerability scanning, and API testing through natural language commands in compatible LLM clients like Claude Desktop.Last updated -4
- AsecurityFlicenseAqualityA specialized MCP server for Claude Desktop that allows executing terminal commands for malware analysis with support for common analysis tools like file, strings, hexdump, objdump, and xxd.Last updated -72
- -securityAlicense-qualityConnects local LLMs to external tools (calculator, knowledge base) via MCP protocol, enabling automatic tool detection and execution to enhance query responses.Last updated -MIT License