Malware Sandbox MCP Server

A comprehensive malware analysis service that integrates with multiple industry-leading sandbox and threat analysis platforms. This MCP (Model Context Protocol) server enables Claude to submit files and URLs for dynamic malware analysis, search malware databases, and retrieve detailed threat intelligence data.

Overview

This server provides access to two major malware analysis platforms through a unified interface:

• Hybrid Analysis - Dynamic file and URL analysis with threat scoring, behavioral analysis, and network monitoring
• MalwareBazaar - Malware sample database with threat intelligence, tags, and family classification

Perfect for malware analysis, incident response, threat intelligence research, and security investigations.

Tools

| Tool | API | Description | |------|-----|-------------| | sandbox_submit_file | Hybrid Analysis | Submit file hash for existing analysis lookup | | sandbox_submit_url | Hybrid Analysis | Submit URL for quick dynamic analysis | | sandbox_get_report | Hybrid Analysis | Retrieve detailed sandbox analysis report with verdict and threat score | | sandbox_search | MalwareBazaar | Search malware database by hash, tag, or family name | | sandbox_network_activity | Hybrid Analysis | Extract network activity from analysis including DNS and HTTP requests | | sandbox_dropped_files | Hybrid Analysis | Get list of files dropped during sandbox analysis |

Hybrid Analysis Submit File

Submit a file hash to retrieve existing sandbox analysis results from Hybrid Analysis.

Input Parameters:

{
  hash: string             // File hash (MD5, SHA1, or SHA256)
  environment?: string     // Sandbox environment (default: windows-10-64)
                          // Options: windows-7-32, windows-7-64, windows-10-64, linux-64
}

Example Request:

{
  "hash": "9f101483662fc071b7c920b122df1735"
}

Example Output:

{
  "verdict": "malicious",
  "threat_score": 98,
  "threat_level": "critical",
  "av_detect": 52,
  "vx_family": "Trojan.Win32.Generic",
  "tags": ["trojan", "malware", "executable"],
  "signatures": [
    {
      "name": "Suspicious process creation",
      "description": "Process creates child process with suspicious characteristics"
    },
    {
      "name": "Registry modification",
      "description": "Registry key modified for persistence"
    }
  ],
  "domains": ["malicious-c2.com", "exfil-server.net"],
  "hosts": ["192.0.2.45", "192.0.2.89"],
  "classification_tags": ["packer", "antivirus-evasion"]
}

Hybrid Analysis Submit URL

Submit a URL for quick dynamic analysis in the Hybrid Analysis sandbox.

Input Parameters:

{
  url: string              // HTTP or HTTPS URL (must be publicly accessible)
  environment?: string     // Sandbox environment (default: windows-10-64)
                          // Options: windows-7-32, windows-7-64, windows-10-64, linux-64
}

Example Request:

{
  "url": "https://example.com/suspicious-file.exe",
  "environment": "windows-10-64"
}

Example Output:

{
  "job_id": "635f2a8c9e7d4e8f9g0h1i2j3k4l5m6n",
  "scan_id": "sandbox-scan-12345",
  "submitted_url": "https://example.com/suspicious-file.exe",
  "environment": "windows-10-64",
  "status": "in_progress",
  "submission_time": "2024-01-15T14:30:00.000Z",
  "estimated_completion": "2024-01-15T14:45:00.000Z"
}

Hybrid Analysis Get Report

Retrieve a detailed analysis report by report ID or file hash from Hybrid Analysis.

Input Parameters:

{
  id: string  // Sandbox report ID or file hash
}

Example Request:

{
  "id": "635f2a8c9e7d4e8f9g0h1i2j3k4l5m6n"
}

Example Output:

{
  "verdict": "malicious",
  "threat_score": 87,
  "threat_level": "high",
  "av_detect": 45,
  "vx_family": "Win32.Trojan.Emotet",
  "tags": ["trojan", "banking-malware", "spambot"],
  "signatures": [
    {
      "name": "Command and control communication",
      "description": "Connects to known command and control server"
    },
    {
      "name": "Information stealing",
      "description": "Attempts to steal credentials and banking information"
    },
    {
      "name": "Lateral movement",
      "description": "Moves laterally through network"
    }
  ],
  "domains": ["c2-server.xyz", "exfil.attacker.com"],
  "hosts": ["192.0.2.105", "192.0.2.156"],
  "compromised_hosts": ["internal-pc.local"],
  "classification_tags": ["worm", "info-stealer"]
}

MalwareBazaar Search

Search MalwareBazaar database for malware samples by hash, tag, or malware family.

Input Parameters:

{
  query: string           // Search term (hash, tag, or malware family name)
  search_type?: string    // Type of search (default: hash)
                         // Options: hash, tag, family
}

Example Request:

{
  "query": "emotet",
  "search_type": "family"
}

Example Output:

{
  "query_status": "ok",
  "query": "emotet",
  "search_type": "family",
  "result_count": 2847,
  "data": [
    {
      "sha256": "5d41402abc4b2a76b9719d911017c592",
      "sha1": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
      "md5": "9f101483662fc071b7c920b122df1735",
      "file_name": "emotet-variant-1.exe",
      "file_size": 524288,
      "file_type": "PE32 executable",
      "malware_family": "emotet",
      "tags": ["trojan", "banking-malware", "spambot"],
      "first_submission": "2024-01-10T08:00:00.000Z",
      "last_submission": "2024-01-15T16:30:00.000Z",
      "downloads": 3421
    },
    {
      "sha256": "7a92c45f3d8e1b6a9f2c3d4e5f6g7h8i",
      "sha1": "bcd5c61ddcc5e8a2dabede0f3b482cd9aea9434d",
      "md5": "2g201483662fc071b7c920b122df1735",
      "file_name": "emotet-loader.bin",
      "file_size": 327680,
      "file_type": "PE32 executable",
      "malware_family": "emotet",
      "tags": ["downloader", "loader"],
      "first_submission": "2024-01-12T10:15:00.000Z",
      "last_submission": "2024-01-14T22:45:00.000Z",
      "downloads": 1856
    }
  ]
}

Hybrid Analysis Network Activity

Extract network activity data from a sandbox analysis report including DNS lookups, HTTP requests, and contacted hosts.

Input Parameters:

{
  id: string  // Sandbox report ID
}

Example Request:

{
  "id": "635f2a8c9e7d4e8f9g0h1i2j3k4l5m6n"
}

Example Output:

{
  "dns_lookups": [
    {
      "query": "malicious-c2.com",
      "response": "192.0.2.45",
      "type": "A",
      "timestamp": "2024-01-15T14:32:15.000Z"
    },
    {
      "query": "exfil-server.net",
      "response": "203.0.113.89",
      "type": "A",
      "timestamp": "2024-01-15T14:32:45.000Z"
    }
  ],
  "http_requests": [
    {
      "method": "POST",
      "uri": "http://malicious-c2.com/api/checkin",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "timestamp": "2024-01-15T14:33:00.000Z"
    },
    {
      "method": "GET",
      "uri": "http://exfil-server.net/collect?id=12345",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "timestamp": "2024-01-15T14:33:30.000Z"
    }
  ],
  "contacted_ips": ["192.0.2.45", "203.0.113.89", "198.51.100.200"],
  "contacted_hosts": ["malicious-c2.com", "exfil-server.net"],
  "contacted_domains": ["malicious-c2.com", "exfil-server.net"],
  "compromised_hosts": ["infected-pc.local"]
}

Hybrid Analysis Dropped Files

Get list of files created or modified during sandbox analysis execution.

Input Parameters:

{
  id: string  // Sandbox report ID
}

Example Request:

{
  "id": "635f2a8c9e7d4e8f9g0h1i2j3k4l5m6n"
}

Example Output:

{
  "dropped_files": [
    {
      "name": "svchost.exe",
      "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "type": "PE32 executable",
      "size": 262144,
      "path": "C:\\Windows\\System32\\svchost.exe",
      "threat_level": "high"
    },
    {
      "name": "config.dat",
      "hash": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
      "type": "Data file",
      "size": 8192,
      "path": "C:\\Users\\Admin\\AppData\\Local\\config.dat",
      "threat_level": "medium"
    },
    {
      "name": "persistence.vbs",
      "hash": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
      "type": "VBScript",
      "size": 4096,
      "path": "C:\\Users\\Admin\\AppData\\Roaming\\Microsoft\\Windows\\Start Menu\\Startup\\persistence.vbs",
      "threat_level": "critical"
    }
  ]
}

Configuration

Environment Variables

This server requires an API key from Hybrid Analysis. MalwareBazaar does not require authentication. Set these environment variables before running:

export HYBRID_ANALYSIS_API_KEY="your-hybrid-analysis-api-key"

Getting API Keys

Hybrid Analysis

• Sign up at https://www.hybrid-analysis.com/signup
• Navigate to API Keys section in account settings
• Free tier provides limited submissions per day
• Rate limit: Varies by account tier
• Documentation: https://www.hybrid-analysis.com/docs/api/v2

MalwareBazaar

• No API key required for basic searches
• Public API available at https://mb-api.abuse.ch/
• Free tier provides unlimited queries
• Rate limit: Reasonable rate limiting enforced
• Documentation: https://bazaar.abuse.ch/api/

Rate Limits Summary

| Service | Free Tier | Rate Limit | |---------|-----------|-----------| | Hybrid Analysis | Limited | Varies by tier | | MalwareBazaar | Unlimited | Reasonable rate limiting |

Installation

Prerequisites

• Bun runtime (version 1.x or later)
• Node.js 18+ (alternative runtime)
• Valid API key for Hybrid Analysis (optional for MalwareBazaar-only usage)

Steps

1. Clone or download this repository:

git clone <repo-url>
cd malware-sandbox

2. Install dependencies:

bun install

3. Build the project:

bun run build

4. Set environment variables:

export HYBRID_ANALYSIS_API_KEY="your-api-key"

5. Run the server:

bun run start

The server will start listening on stdio transport.

Usage

Running the Server

Start the server with Bun:

bun run src/index.ts

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "malware-sandbox": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/malware-sandbox/src/index.ts"
      ],
      "env": {
        "HYBRID_ANALYSIS_API_KEY": "your-hybrid-analysis-api-key"
      }
    }
  }
}

Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in .mcp.json or via settings UI):

{
  "servers": {
    "malware-sandbox": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/malware-sandbox/src/index.ts"],
      "env": {
        "HYBRID_ANALYSIS_API_KEY": "your-hybrid-analysis-api-key"
      }
    }
  }
}

Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

Request: "Analyze the hash 9f101483662fc071b7c920b122df1735 for malware"

Claude will call:

{
  "tool": "sandbox_submit_file",
  "input": {
    "hash": "9f101483662fc071b7c920b122df1735"
  }
}

Request: "Check the URL https://example.com/suspicious-file.exe for threats in the sandbox"

Claude will call:

{
  "tool": "sandbox_submit_url",
  "input": {
    "url": "https://example.com/suspicious-file.exe"
  }
}

Request: "Search for emotet malware samples in MalwareBazaar and show me the family"

Claude will call:

{
  "tool": "sandbox_search",
  "input": {
    "query": "emotet",
    "search_type": "family"
  }
}

Request: "Show me the network activity from report 635f2a8c9e7d4e8f9g0h1i2j3k4l5m6n"

Claude will call:

{
  "tool": "sandbox_network_activity",
  "input": {
    "id": "635f2a8c9e7d4e8f9g0h1i2j3k4l5m6n"
  }
}

Security

This server implements comprehensive input validation and security measures to prevent injection attacks and misuse:

Input Validation

Hash Validation

• Accepts MD5 (32 hex chars), SHA1 (40 hex chars), SHA256 (64 hex chars)
• Validates hexadecimal character set
• Rejects hashes outside valid length ranges (32-64 characters)

URL Validation

• Requires properly formatted HTTP or HTTPS URLs
• Validates URLs against Node.js URL parser
• Blocks private/local IP addresses including:
  • 10.0.0.0/8 (private networks)
  • 172.16.0.0/12 (private networks)
  • 192.168.0.0/16 (private networks)
  • 127.0.0.0/8 (loopback)
  • 0.0.0.0/8 (current network)
  • ::1 (IPv6 loopback)
  • fd*/fe80* (IPv6 local)
• Rejects non-HTTP/HTTPS protocols (ftp, file, etc.)

Report ID Validation

• Alphanumeric characters, hyphens, and underscores only
• Maximum length: 100 characters
• Prevents injection of special characters

Search Query Validation

• Maximum length: 500 characters
• Accepts hashes, malware family names, and tags
• Input is passed directly to MalwareBazaar API

What Gets Blocked

The server rejects:

• Invalid hash formats (non-hex characters, wrong length)
• URLs pointing to private/local IP addresses
• Non-HTTP/HTTPS URLs
• Malformed or oversized report IDs
• Missing Hybrid Analysis API key (for restricted endpoints)
• Oversized search queries (>500 characters)

Error Handling

• Invalid inputs return descriptive error messages
• API errors are caught and reported with status codes
• Missing API keys trigger helpful configuration messages
• Rate limit responses (429) are handled gracefully
• Network timeouts are handled with appropriate error messages

License

ISC License - see LICENSE file for details