npm package: @modular-intelligence/threat-intel
Description: MCP server for threat intelligence lookups (VirusTotal, Shodan, AbuseIPDB, OTX)
Latest version: 1.0.2

# 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:**
```typescript
{
  hash: string  // MD5 (32 chars), SHA1 (40 chars), or SHA256 (64 chars) hex string
}
```

**Example Request:**
```json
{
  "hash": "9f101483662fc071b7c920b122df1735"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  url: string  // HTTP or HTTPS URL
}
```

**Example Request:**
```json
{
  "url": "https://example.com/malware.exe"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  domain: string  // Valid domain name (e.g., example.com)
}
```

**Example Request:**
```json
{
  "domain": "malicious-site.com"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  ip: string  // Valid IPv4 address
}
```

**Example Request:**
```json
{
  "ip": "192.0.2.1"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  ip: string  // Valid IPv4 address
}
```

**Example Request:**
```json
{
  "ip": "192.0.2.1"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  query: string        // Shodan search query (e.g., 'apache country:US')
  max_results: number  // Maximum results to return (1-100, default: 10)
}
```

**Example Request:**
```json
{
  "query": "apache country:US",
  "max_results": 5
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  ip: string              // Valid IPv4 address
  max_age_days: number    // Maximum age of reports in days (1-365, default: 90)
}
```

**Example Request:**
```json
{
  "ip": "192.0.2.1",
  "max_age_days": 30
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  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:**
```json
{
  "indicator": "192.0.2.1",
  "type": "IPv4"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  url: string              // HTTP or HTTPS URL to scan
  visibility: string       // Visibility level: 'public' or 'private' (default: 'public')
}
```

**Example Request:**
```json
{
  "url": "https://example.com",
  "visibility": "public"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  uuid: string  // UUID from a previous urlscan_submit request
}
```

**Example Request:**
```json
{
  "uuid": "12345678-1234-1234-1234-123456789012"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  hash: string  // MD5 (32 chars), SHA1 (40 chars), or SHA256 (64 chars) hex string
}
```

**Example Request:**
```json
{
  "hash": "e2d27b3b7ecd0b35e6c13f7d9f5f8c1a"
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  tag: string      // Tag or malware family name to search
  limit: number    // Maximum results to return (1-100, default: 25)
}
```

**Example Request:**
```json
{
  "tag": "emotet",
  "limit": 10
}
```

**Example Output:**
```json
{
  "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:

```bash
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

1. Clone or download this repository:
```bash
git clone <repo-url>
cd threat-intel
```

2. Install dependencies:
```bash
bun install
```

3. Build the project:
```bash
bun run build
```

4. Set environment variables:
```bash
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"
```

5. Run the server:
```bash
bun run start
```

The server will start listening on stdio transport.

## Usage

### Running the Server

Start the server with Bun:

```bash
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`:

```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):

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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