@modular-intelligence/threat-intel

v1.0.2

Published

3 days ago

MCP server for threat intelligence lookups (VirusTotal, Shodan, AbuseIPDB, OTX)

0High
0Medium
0Low

Threat Intelligence MCP Server

A comprehensive threat intelligence lookup service that integrates with multiple industry-leading threat intelligence APIs. This MCP (Model Context Protocol) server enables Claude to query threat intelligence data including file reputation, URL safety checks, domain analysis, IP intelligence, open port scanning, and malware database lookups.

Overview

This server provides access to six major threat intelligence platforms through a unified interface:

VirusTotal - File hash, URL, domain, and IP reputation analysis
Shodan - Internet-connected device discovery and vulnerability assessment
AbuseIPDB - IP address abuse reporting and reputation scoring
AlienVault OTX - Open Threat Exchange indicator analysis and correlation
urlscan.io - URL and website scanning with comprehensive security analysis
MalwareBazaar - Malware sample repository and hash lookups

Perfect for security research, incident response, malware analysis, and vulnerability assessments.

Tools

| Tool | API | Description | |------|-----|-------------| | vt_hash_lookup | VirusTotal | Query file hash reputation (MD5/SHA1/SHA256) | | vt_url_lookup | VirusTotal | Check URL reputation and categorization | | vt_domain_lookup | VirusTotal | Domain analysis with DNS records and WHOIS | | vt_ip_lookup | VirusTotal | IP address reputation and ASN information | | shodan_host | Shodan | Detailed host information including open ports and services | | shodan_search | Shodan | Search for internet-connected devices matching a query | | abuseipdb_check | AbuseIPDB | IP abuse score and reporting history | | otx_indicator | AlienVault OTX | Threat indicator correlation and pulse data | | urlscan_submit | urlscan.io | Submit URL for scanning and analysis | | urlscan_result | urlscan.io | Retrieve scan results by UUID | | malwarebazaar_hash | MalwareBazaar | Look up malware sample by hash | | malwarebazaar_search | MalwareBazaar | Search by malware tag or family name |

VirusTotal Hash Lookup

Query VirusTotal for file hash reputation using MD5, SHA1, or SHA256 hashes.

Input Parameters:

{
  hash: string  // MD5 (32 chars), SHA1 (40 chars), or SHA256 (64 chars) hex string
}

Example Request:

{
  "hash": "9f101483662fc071b7c920b122df1735"
}

Example Output:

{
  "hash": "9f101483662fc071b7c920b122df1735",
  "found": true,
  "hash_type": "MD5",
  "detection_ratio": "45/71",
  "positives": 45,
  "total": 71,
  "scan_date": "2024-01-15T10:30:45.000Z",
  "file_type": "Win32 EXE",
  "file_size": 524288,
  "sha256": "5d41402abc4b2a76b9719d911017c592",
  "sha1": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
  "md5": "9f101483662fc071b7c920b122df1735",
  "tags": ["trojan", "malware", "executable"],
  "detections": [
    {
      "engine": "Avast",
      "result": "Win32:Malware-gen"
    },
    {
      "engine": "McAfee",
      "result": "Trojan.Generic.eb!c"
    }
  ]
}

VirusTotal URL Lookup

Check URL reputation and categorization on VirusTotal.

Input Parameters:

{
  url: string  // HTTP or HTTPS URL
}

Example Request:

{
  "url": "https://example.com/malware.exe"
}

Example Output:

{
  "url": "https://example.com/malware.exe",
  "found": true,
  "positives": 12,
  "total": 89,
  "scan_date": "2024-01-15T09:20:30.000Z",
  "categories": {
    "Phishing": 1,
    "Malware": 1,
    "Suspicious": 2
  },
  "reputation": -15,
  "detections": [
    {
      "engine": "Phishtank",
      "result": "phishing"
    },
    {
      "engine": "Kaspersky",
      "result": "malware"
    }
  ]
}

VirusTotal Domain Lookup

Retrieve comprehensive domain intelligence including DNS records and WHOIS information.

Input Parameters:

{
  domain: string  // Valid domain name (e.g., example.com)
}

Example Request:

{
  "domain": "malicious-site.com"
}

Example Output:

{
  "domain": "malicious-site.com",
  "found": true,
  "categories": {
    "phishing": "Phishing",
    "malware": "Malware Distribution"
  },
  "last_analysis_stats": {
    "malicious": 3,
    "suspicious": 2,
    "harmless": 45,
    "undetected": 50
  },
  "reputation": -25,
  "registrar": "GoDaddy.com",
  "creation_date": "2020-03-15T00:00:00.000Z",
  "last_dns_records": [
    {
      "type": "A",
      "value": "192.0.2.1",
      "ttl": 3600
    },
    {
      "type": "MX",
      "value": "mail.example.com",
      "ttl": 3600
    }
  ],
  "whois": "Domain Name: MALICIOUS-SITE.COM\nRegistrant Name: John Doe\n...",
  "tags": ["phishing", "malware", "c2"]
}

VirusTotal IP Lookup

Get IP address reputation, geolocation, ASN information, and analysis statistics.

Input Parameters:

{
  ip: string  // Valid IPv4 address
}

Example Request:

{
  "ip": "192.0.2.1"
}

Example Output:

{
  "ip": "192.0.2.1",
  "country": "CN",
  "as_owner": "China Unicom",
  "asn": 9808,
  "network": "192.0.2.0/24",
  "last_analysis_stats": {
    "malicious": 2,
    "suspicious": 1,
    "harmless": 60,
    "undetected": 37
  },
  "reputation": -10,
  "whois": "inetnum: 192.0.2.0 - 192.0.2.255\nnetname: EXAMPLE-NET\n...",
  "tags": ["c2", "botnet"]
}

Shodan Host Lookup

Query Shodan for detailed information about a specific host including open ports, services, and vulnerabilities.

Input Parameters:

{
  ip: string  // Valid IPv4 address
}

Example Request:

{
  "ip": "192.0.2.1"
}

Example Output:

{
  "ip": "192.0.2.1",
  "found": true,
  "hostnames": ["router.example.com", "gateway.local"],
  "country": "United States",
  "city": "San Francisco",
  "org": "Example ISP",
  "isp": "Example Internet",
  "asn": "AS12345",
  "os": "Linux 2.6.x",
  "ports": [22, 80, 443, 8080],
  "vulns": ["CVE-2021-1234", "CVE-2020-5678"],
  "services": [
    {
      "port": 22,
      "protocol": "tcp",
      "service": "ssh",
      "banner": "SSH-2.0-OpenSSH_7.4",
      "product": "OpenSSH",
      "version": "7.4"
    },
    {
      "port": 80,
      "protocol": "tcp",
      "service": "http",
      "banner": "HTTP/1.1 200 OK\\r\\nServer: Apache/2.4.6\\r\\n",
      "product": "Apache httpd",
      "version": "2.4.6"
    }
  ],
  "last_update": "2024-01-15T10:00:00.000Z"
}

Shodan Search

Search for internet-connected devices matching a specific query.

Input Parameters:

{
  query: string        // Shodan search query (e.g., 'apache country:US')
  max_results: number  // Maximum results to return (1-100, default: 10)
}

Example Request:

{
  "query": "apache country:US",
  "max_results": 5
}

Example Output:

{
  "total": 2847362,
  "query": "apache country:US",
  "matches": [
    {
      "ip": "192.0.2.1",
      "port": 80,
      "org": "Example Corp",
      "hostnames": ["web1.example.com"],
      "product": "Apache httpd",
      "version": "2.4.41",
      "os": "Linux",
      "banner": "HTTP/1.1 200 OK\\r\\nServer: Apache/2.4.41 (Ubuntu)\\r\\n"
    },
    {
      "ip": "192.0.2.2",
      "port": 8080,
      "org": "Another Corp",
      "hostnames": ["app-server.another.com"],
      "product": "Apache httpd",
      "version": "2.4.48",
      "os": "Ubuntu 20.04",
      "banner": "HTTP/1.1 301 Moved Permanently\\r\\nLocation: https://..."
    }
  ]
}

AbuseIPDB Check

Query AbuseIPDB for IP reputation including abuse scores, report history, and ISP information.

Input Parameters:

{
  ip: string              // Valid IPv4 address
  max_age_days: number    // Maximum age of reports in days (1-365, default: 90)
}

Example Request:

{
  "ip": "192.0.2.1",
  "max_age_days": 30
}

Example Output:

{
  "ip": "192.0.2.1",
  "is_public": true,
  "abuse_confidence_score": 75,
  "country_code": "RU",
  "isp": "Example ISP",
  "domain": "example.ru",
  "total_reports": 42,
  "num_distinct_users": 18,
  "last_reported_at": "2024-01-14T15:30:00.000Z",
  "is_tor": false,
  "is_whitelisted": false,
  "usage_type": "Data Center",
  "hostnames": ["bot.example.ru", "c2.example.ru"]
}

AlienVault OTX Indicator Lookup

Query AlienVault OTX for threat indicator analysis and correlation with known malicious activity pulses.

Input Parameters:

{
  indicator: string  // The indicator value (IP, domain, hash, URL)
  type: string      // Indicator type: IPv4, IPv6, domain, hostname, url, FileHash-MD5, FileHash-SHA1, FileHash-SHA256
}

Example Request:

{
  "indicator": "192.0.2.1",
  "type": "IPv4"
}

Example Output:

{
  "indicator": "192.0.2.1",
  "type": "IPv4",
  "found": true,
  "pulse_count": 5,
  "pulses": [
    {
      "id": "63d5e7f3c8e7e4f7c8e7e4f7",
      "name": "Mirai Botnet C&C",
      "description": "Command and control server for Mirai botnet variant",
      "created": "2024-01-10T12:00:00.000Z",
      "tags": ["malware", "botnet", "mirai", "iot"]
    },
    {
      "id": "63d5e7f4c8e7e4f7c8e7e4f8",
      "name": "Brute Force Attacks",
      "description": "SSH brute force attack campaign",
      "created": "2024-01-12T08:30:00.000Z",
      "tags": ["attack", "brute-force", "ssh"]
    }
  ],
  "reputation": -3,
  "country": "China",
  "validation": [
    {
      "source": "shodan",
      "message": "SSH service detected on port 22"
    }
  ]
}

urlscan Submit

Submit a URL to urlscan.io for scanning and security analysis. The scan will analyze the page for malicious content, phishing, and other security threats.

Input Parameters:

{
  url: string              // HTTP or HTTPS URL to scan
  visibility: string       // Visibility level: 'public' or 'private' (default: 'public')
}

Example Request:

{
  "url": "https://example.com",
  "visibility": "public"
}

Example Output:

{
  "message": "Scan submitted successfully",
  "uuid": "12345678-1234-1234-1234-123456789012",
  "result_url": "https://urlscan.io/result/12345678-1234-1234-1234-123456789012/",
  "api_url": "https://urlscan.io/api/v1/result/12345678-1234-1234-1234-123456789012/",
  "visibility": "public",
  "note": "Use urlscan_result with the UUID to retrieve results after scan completes (usually 10-30 seconds)"
}

urlscan Result

Retrieve scan results from urlscan.io using a scan UUID. Results include security verdicts, page information, detected resources, and a screenshot.

Input Parameters:

{
  uuid: string  // UUID from a previous urlscan_submit request
}

Example Request:

{
  "uuid": "12345678-1234-1234-1234-123456789012"
}

Example Output:

{
  "uuid": "12345678-1234-1234-1234-123456789012",
  "status": "complete",
  "task_url": "https://urlscan.io/result/12345678-1234-1234-1234-123456789012/",
  "page": {
    "url": "https://example.com",
    "domain": "example.com",
    "ip": "192.0.2.1",
    "country": "US",
    "server": "nginx",
    "title": "Example Domain",
    "status_code": 200
  },
  "verdicts": {
    "overall": {
      "score": 0,
      "categories": [],
      "tags": []
    },
    "urlscan": {
      "score": 0,
      "categories": [],
      "tags": []
    },
    "community": {
      "score": 0,
      "categories": [],
      "tags": []
    }
  },
  "stats": {
    "requests": 45,
    "data_length": 2048000,
    "encoded_data_length": 1024000,
    "unique_ips": 8,
    "unique_countries": 2
  },
  "lists": {
    "ips": ["192.0.2.1", "192.0.2.2"],
    "domains": ["example.com", "cdn.example.com"],
    "urls": ["https://example.com", "https://example.com/page"],
    "certificates": ["CN=example.com"]
  },
  "screenshot_url": "https://urlscan.io/screenshots/12345678-1234-1234-1234-123456789012.png"
}

MalwareBazaar Hash Lookup

Look up a malware sample by its hash on MalwareBazaar (abuse.ch). Supports MD5, SHA1, or SHA256 hashes.

Input Parameters:

{
  hash: string  // MD5 (32 chars), SHA1 (40 chars), or SHA256 (64 chars) hex string
}

Example Request:

{
  "hash": "e2d27b3b7ecd0b35e6c13f7d9f5f8c1a"
}

Example Output:

{
  "hash": "e2d27b3b7ecd0b35e6c13f7d9f5f8c1a",
  "found": true,
  "sha256": "5d41402abc4b2a76b9719d911017c592e2d27b3b7ecd0b35e6c13f7d9f5f8c1a",
  "sha1": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
  "md5": "e2d27b3b7ecd0b35e6c13f7d9f5f8c1a",
  "file_type": "PE32 executable",
  "file_type_mime": "application/x-dosexec",
  "file_size": 524288,
  "signature": "Emotet",
  "first_seen": "2023-06-15T08:30:00.000Z",
  "last_seen": "2024-01-10T15:45:00.000Z",
  "reporter": "MalwareBazaar Community",
  "tags": ["emotet", "trojan", "banking-malware"],
  "delivery_method": "email",
  "intelligence": {
    "downloads": 247,
    "uploads": 89,
    "mail_intelligence": {
      "detected": true,
      "count": 156
    }
  }
}

MalwareBazaar Search

Search MalwareBazaar for malware samples by tag or malware family name. Useful for finding samples related to a specific malware family.

Input Parameters:

{
  tag: string      // Tag or malware family name to search
  limit: number    // Maximum results to return (1-100, default: 25)
}

Example Request:

{
  "tag": "emotet",
  "limit": 10
}

Example Output:

{
  "tag": "emotet",
  "found": true,
  "total_results": 10,
  "results": [
    {
      "sha256": "5d41402abc4b2a76b9719d911017c592e2d27b3b7ecd0b35e6c13f7d9f5f8c1a",
      "file_type": "PE32 executable",
      "file_size": 524288,
      "signature": "Emotet.A",
      "first_seen": "2023-06-15T08:30:00.000Z",
      "tags": ["emotet", "banking-trojan"],
      "reporter": "abuse.ch"
    },
    {
      "sha256": "7a5f8e2c1b9d4e3a6c2f5d8b1e4a7c3f9d2e5a8b1c4f7e0a3d6b9c2e5f8a1b",
      "file_type": "PE32 executable",
      "file_size": 456789,
      "signature": "Emotet.B",
      "first_seen": "2023-07-20T12:15:00.000Z",
      "tags": ["emotet", "banking-trojan"],
      "reporter": "abuse.ch"
    }
  ]
}

Configuration

Environment Variables

This server requires API keys from threat intelligence services. Set these environment variables before running:

export VIRUSTOTAL_API_KEY="your-virustotal-api-key"
export SHODAN_API_KEY="your-shodan-api-key"
export ABUSEIPDB_API_KEY="your-abuseipdb-api-key"
export OTX_API_KEY="your-otx-api-key"
export URLSCAN_API_KEY="your-urlscan-api-key"

Note: URLSCAN_API_KEY is required for urlscan_submit. The urlscan_result tool does not require an API key.

Getting API Keys

VirusTotal

Sign up at https://www.virustotal.com/gui/home/upload
Create account and navigate to Settings -> API key
Free tier provides 500 lookups per day
Rate limit: 4 requests per minute (free tier)
Documentation: https://developers.virustotal.com/v3.0/reference

Shodan

Register at https://www.shodan.io
Access API key from Account -> API Key page
Free tier provides limited search results
Rate limit: 1 request per second (free tier)
Documentation: https://developer.shodan.io/api

AbuseIPDB

Sign up at https://www.abuseipdb.com/register
Navigate to Account -> API Key
Free tier provides 1,000 checks per day
Rate limit: 10 requests per day (free tier), 15 requests per minute (paid)
Documentation: https://www.abuseipdb.com/api

AlienVault OTX

Create account at https://otx.alienvault.com/
Go to Settings to generate API key
Free tier provides unlimited queries
Rate limit: 20 requests per minute (free tier)
Documentation: https://otx.alienvault.com/api

urlscan.io

Sign up at https://urlscan.io/
Navigate to Settings to find your API key
Free tier provides 100 scans per day
Rate limit: 60 scans per minute (free tier)
Documentation: https://urlscan.io/docs/

MalwareBazaar

No API key required for basic queries
Access at https://www.malwarebazaar.org/
Free tier provides unlimited lookups
Rate limit: Reasonable limits for public API
Documentation: https://www.malwarebazaar.org/api/

Rate Limits Summary

| Service | Free Tier | Rate Limit | |---------|-----------|-----------| | VirusTotal | 500/day | 4 req/min | | Shodan | Limited | 1 req/sec | | AbuseIPDB | 1,000/day | 10 req/day (free) / 15 req/min (paid) | | OTX | Unlimited | 20 req/min | | urlscan.io | 100/day | 60 scans/min | | MalwareBazaar | Unlimited | Reasonable limits |

Installation

Prerequisites

Bun runtime (version 1.x or later)
Node.js 18+ (alternative runtime)
Valid API keys for at least one threat intelligence service

Steps

Clone or download this repository:

git clone <repo-url>
cd threat-intel

Install dependencies:

bun install

Build the project:

bun run build

Set environment variables:

export VIRUSTOTAL_API_KEY="your-key"
export SHODAN_API_KEY="your-key"
export ABUSEIPDB_API_KEY="your-key"
export OTX_API_KEY="your-key"
export URLSCAN_API_KEY="your-key"

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": {
    "threat-intel": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/threat-intel/src/index.ts"
      ],
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key",
        "SHODAN_API_KEY": "your-shodan-api-key",
        "ABUSEIPDB_API_KEY": "your-abuseipdb-api-key",
        "OTX_API_KEY": "your-otx-api-key",
        "URLSCAN_API_KEY": "your-urlscan-api-key"
      }
    }
  }
}

Claude Code MCP Settings

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

{
  "servers": {
    "threat-intel": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/threat-intel/src/index.ts"],
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key",
        "SHODAN_API_KEY": "your-shodan-api-key",
        "ABUSEIPDB_API_KEY": "your-abuseipdb-api-key",
        "OTX_API_KEY": "your-otx-api-key",
        "URLSCAN_API_KEY": "your-urlscan-api-key"
      }
    }
  }
}

Example Usage in Claude

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

Request: "Check the reputation of the domain malicious-site.com on VirusTotal"

Claude will call:

{
  "tool": "vt_domain_lookup",
  "input": {
    "domain": "malicious-site.com"
  }
}

Request: "Search Shodan for Apache servers in the United States and return the top 5 results"

Claude will call:

{
  "tool": "shodan_search",
  "input": {
    "query": "apache country:US",
    "max_results": 5
  }
}

Request: "Check if 192.0.2.1 has been reported as malicious on AbuseIPDB"

Claude will call:

{
  "tool": "abuseipdb_check",
  "input": {
    "ip": "192.0.2.1",
    "max_age_days": 90
  }
}

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

Domain Validation

Requires valid domain name format (RFC-compliant)
Maximum length: 253 characters
Validates character set (alphanumeric, dots, hyphens)
Rejects local/private domains

IP Address Validation

Only IPv4 addresses supported
Validates octet range (0-255)
Proper dotted-decimal format required
Rejects private IP addresses (10.x.x.x, 192.168.x.x, 127.x.x.x, 172.16-31.x.x)

URL Validation

Requires properly formatted URLs
Only HTTP and HTTPS protocols allowed
Validates against Node.js URL parser
Rejects non-web protocols (ftp, file, etc.)

Shodan Query Validation

Maximum query length: 500 characters
Blocks shell injection characters: ;, &, |, backticks, $, (), {}
Prevents command injection via query parameters
Validates against malicious operator chaining

What Gets Blocked

The server rejects:

Invalid hash formats (non-hex, wrong length)
Malformed domains and non-domain strings
Private/RFC-1918 IP addresses
Non-HTTP/HTTPS URLs
Queries containing shell metacharacters
Missing or invalid API keys
Oversized inputs

Error Handling

Invalid inputs return descriptive error messages
API errors are caught and reported with status codes
Missing API keys trigger helpful configuration messages
Network timeouts are handled gracefully

License

MIT License - see LICENSE file for details

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Threat Intelligence MCP Server

Overview

Tools

VirusTotal Hash Lookup

VirusTotal URL Lookup

VirusTotal Domain Lookup

VirusTotal IP Lookup

Shodan Host Lookup

Shodan Search

AbuseIPDB Check

AlienVault OTX Indicator Lookup

urlscan Submit

urlscan Result

MalwareBazaar Hash Lookup

MalwareBazaar Search

Configuration

Environment Variables

Getting API Keys

Rate Limits Summary

Installation

Prerequisites

Steps

Usage

Running the Server

Claude Desktop Configuration

Claude Code MCP Settings

Example Usage in Claude

Security

Input Validation

What Gets Blocked

Error Handling

License