Suricata MCP Server

A Model Context Protocol (MCP) server that provides network intrusion detection and PCAP analysis using Suricata IDS.

Overview

This MCP server wraps the Suricata IDS command-line tool to provide comprehensive network traffic analysis, threat detection, and security monitoring capabilities. It operates strictly in offline analysis mode, analyzing PCAP files without live network capture.

Prerequisites

Required Software

1. Suricata IDS (version 6.0 or higher recommended)

   # macOS
   brew install suricata
   
   # Ubuntu/Debian
   apt-get install suricata
   
   # RHEL/CentOS
   yum install suricata

2. Bun runtime (for running the MCP server)

   curl -fsSL https://bun.sh/install | bash

3. Emerging Threats Open Rules (recommended)

   # macOS
   suricata-update
   
   # Linux
   sudo suricata-update

Verify Installation

suricata --version
suricata --list-app-layer-protos

Installation

cd suricata
bun install
bun run build

Configuration

Add to your MCP settings configuration file:

Claude Desktop

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "suricata": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/suricata/src/index.ts"]
    }
  }
}

Cline VSCode Extension

In Cline MCP Settings:

{
  "suricata": {
    "command": "bun",
    "args": ["run", "/absolute/path/to/suricata/src/index.ts"]
  }
}

Security Model

Offline Analysis Only

This server is designed for offline PCAP analysis only. Live network capture is explicitly blocked for security:

• Blocked flags: -i, --af-packet, --pcap, --netmap, -D, --daemon
• Only reads from existing PCAP files
• Cannot access live network interfaces

File Validation

• PCAP paths: Must be absolute, no path traversal, .pcap or .pcapng extension only
• Max PCAP size: 2GB to prevent memory exhaustion
• Rule files: Must be absolute paths with .rules extension
• Rule content: Max 100KB, must contain valid Suricata rule keywords

Sandboxed Execution

• Temporary directories created under /tmp/mcp-suricata/
• Automatic cleanup after analysis
• Extracted files stored in isolated temporary locations
• 50MB output buffer limit
• Configurable timeouts (30-600 seconds)

Available Tools

1. suricata_analyze_pcap

Analyze a PCAP file for security threats and suspicious patterns.

Parameters:

• pcap_path (string, required): Absolute path to PCAP file
• rule_path (string, optional): Path to custom Suricata rules file
• timeout (number, optional): Analysis timeout in seconds (default: 300)

Returns:

{
  "pcap": "/path/to/capture.pcap",
  "alerts": [
    {
      "timestamp": "2024-01-15T10:30:45.123456+0000",
      "signature": "ET MALWARE Suspicious DNS Query",
      "severity": 1,
      "src_ip": "192.168.1.100",
      "src_port": 54321,
      "dest_ip": "8.8.8.8",
      "dest_port": 53,
      "protocol": "UDP",
      "action": "alert",
      "category": "Malware"
    }
  ],
  "alert_count": 42,
  "flow_count": 156
}

Example:

{
  "pcap_path": "/tmp/suspicious_traffic.pcap",
  "rule_path": "/etc/suricata/rules/custom.rules",
  "timeout": 300
}

2. suricata_rule_validate

Validate Suricata rule syntax without running analysis.

Parameters:

• rule_content (string, required): Rule content to validate (max 100KB)

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [
    "Warning: Rule uses deprecated fast_pattern syntax"
  ]
}

Example:

{
  "rule_content": "alert tcp any any -> any 80 (msg:\"HTTP GET Request\"; flow:established,to_server; content:\"GET\"; http_method; sid:1000001; rev:1;)"
}

3. suricata_extract_files

Extract files from network traffic (HTTP, FTP, SMTP attachments, etc.).

Parameters:

• pcap_path (string, required): Absolute path to PCAP file
• timeout (number, optional): Extraction timeout in seconds (default: 300)

Returns:

{
  "files": [
    {
      "filename": "document.pdf",
      "size": 245760,
      "magic": "PDF document, version 1.4",
      "md5": "5d41402abc4b2a76b9719d911017c592",
      "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
      "stored_path": "/tmp/mcp-suricata/filestore/2c26b46..."
    }
  ],
  "total": 12,
  "note": "Files are stored in sandboxed temporary directory and will be cleaned up"
}

4. suricata_list_rules

List and filter available Suricata rules.

Parameters:

• rule_path (string, optional): Path to rules directory or file (default: /etc/suricata/rules)
• category (string, optional): Filter by rule classification/category

Returns:

{
  "rules": [
    {
      "sid": 2100498,
      "msg": "GPL ATTACK_RESPONSE id check returned root",
      "classtype": "bad-unknown",
      "severity": 2,
      "protocol": "tcp",
      "direction": "->"
    }
  ],
  "total": 1543,
  "by_category": {
    "trojan-activity": 423,
    "bad-unknown": 234,
    "attempted-admin": 156
  }
}

5. suricata_flow_analyze

Analyze network flows for traffic patterns and behavior.

Parameters:

• pcap_path (string, required): Absolute path to PCAP file
• timeout (number, optional): Analysis timeout in seconds (default: 300)

Returns:

{
  "flows": [
    {
      "timestamp": "2024-01-15T10:30:45.123456+0000",
      "src_ip": "192.168.1.100",
      "src_port": 54321,
      "dest_ip": "93.184.216.34",
      "dest_port": 443,
      "protocol": "TCP",
      "app_protocol": "tls",
      "bytes_toserver": 1024,
      "bytes_toclient": 8192,
      "duration": 45.2,
      "state": "closed"
    }
  ],
  "total_flows": 156,
  "by_protocol": {
    "tls": 89,
    "http": 34,
    "dns": 23,
    "ssh": 10
  }
}

6. suricata_dns_log

Extract and analyze DNS queries for suspicious domains.

Parameters:

• pcap_path (string, required): Absolute path to PCAP file
• timeout (number, optional): Analysis timeout in seconds (default: 300)

Returns:

{
  "queries": [
    {
      "timestamp": "2024-01-15T10:30:45.123456+0000",
      "src_ip": "192.168.1.100",
      "dest_ip": "8.8.8.8",
      "query": "example.com",
      "type": "A",
      "answer": "93.184.216.34",
      "rcode": "NOERROR"
    }
  ],
  "unique_domains": 87,
  "total_queries": 234,
  "suspicious": [
    "a1b2c3d4e5f6g7h8.tk",
    "random-domain-12345.ml"
  ]
}

Suspicious Domain Detection:

• Free TLDs: .tk, .ml, .ga, .cf, .gq
• Long numeric sequences (10+ digits)
• Long hexadecimal strings (32+ chars) - DGA indicators
• Tor .onion domains

7. suricata_stats

Get comprehensive traffic statistics from PCAP analysis.

Parameters:

• pcap_path (string, required): Absolute path to PCAP file
• timeout (number, optional): Analysis timeout in seconds (default: 300)

Returns:

{
  "capture": {
    "packets": 15234,
    "bytes": 12456789,
    "invalid": 3
  },
  "decoder": {
    "ipv4": 14890,
    "ipv6": 344,
    "tcp": 12345,
    "udp": 2567,
    "icmp": 322
  },
  "detect": {
    "alerts": 42,
    "rules_loaded": 31543
  },
  "flow": {
    "tcp": 456,
    "udp": 234,
    "icmp": 12
  },
  "app_layer": {
    "http": 234,
    "tls": 189,
    "dns": 123,
    "smtp": 45,
    "ssh": 23
  }
}

Common Workflows

Threat Hunting

# 1. Analyze PCAP for threats
suricata_analyze_pcap {
  "pcap_path": "/tmp/network_capture.pcap"
}

# 2. If alerts found, get DNS queries
suricata_dns_log {
  "pcap_path": "/tmp/network_capture.pcap"
}

# 3. Analyze flows for C2 patterns
suricata_flow_analyze {
  "pcap_path": "/tmp/network_capture.pcap"
}

Malware Analysis

# 1. Extract files from traffic
suricata_extract_files {
  "pcap_path": "/tmp/malware_traffic.pcap"
}

# 2. Analyze with custom malware rules
suricata_analyze_pcap {
  "pcap_path": "/tmp/malware_traffic.pcap",
  "rule_path": "/etc/suricata/rules/malware.rules"
}

Rule Development

# 1. Validate new rule syntax
suricata_rule_validate {
  "rule_content": "alert http any any -> any any (msg:\"Test\"; sid:1;)"
}

# 2. Test against sample traffic
suricata_analyze_pcap {
  "pcap_path": "/tmp/test_traffic.pcap",
  "rule_path": "/tmp/new_rules.rules"
}

Traffic Profiling

# 1. Get overall statistics
suricata_stats {
  "pcap_path": "/tmp/baseline_traffic.pcap"
}

# 2. Analyze flow patterns
suricata_flow_analyze {
  "pcap_path": "/tmp/baseline_traffic.pcap"
}

# 3. Profile DNS usage
suricata_dns_log {
  "pcap_path": "/tmp/baseline_traffic.pcap"
}

Error Handling

The server provides detailed error messages for common issues:

• Suricata not installed: Install Suricata CLI tool
• File not found: Check PCAP path exists and is accessible
• Path traversal: Use absolute paths only
• File too large: Maximum 2GB PCAP size
• Timeout: Increase timeout parameter or reduce PCAP size
• Invalid syntax: Check rule syntax with suricata_rule_validate

Performance Considerations

• Large PCAPs: Files over 500MB may take several minutes to analyze
• Memory usage: Suricata can use 500MB-2GB RAM depending on ruleset size
• Timeouts: Default 120s for most operations, 300s for full analysis
• Parallel analysis: Run multiple tools sequentially, not in parallel

Limitations

• Offline only: No live capture support
• No packet injection: Read-only PCAP analysis
• No network access: Cannot fetch remote rules or update signatures
• Single PCAP: One file per analysis (no PCAP merging)
• Linux/macOS only: Windows support requires WSL

Troubleshooting

Suricata command not found

# Verify installation
which suricata

# Check PATH
echo $PATH

# Install if missing (macOS)
brew install suricata

Rules not loading

# Update rule database
sudo suricata-update

# Verify rules directory
ls -la /var/lib/suricata/rules/
ls -la /etc/suricata/rules/

# Check Suricata config
suricata --dump-config

Analysis timeout

Increase timeout for large files:

{
  "pcap_path": "/tmp/large_capture.pcap",
  "timeout": 600  // 10 minutes
}

Memory errors

• Reduce PCAP size (split with editcap or tcpdump)
• Disable unused rule categories
• Use BPF filters to pre-filter PCAP

Development

Build

bun run build

Run locally

bun run start

Test with MCP Inspector

npx @modelcontextprotocol/inspector bun run src/index.ts

Resources

• Suricata Documentation
• Emerging Threats Rules
• Suricata Rule Format
• Model Context Protocol

License

MIT

Contributing

Contributions welcome! Please ensure:

• All Zod schemas have .describe() annotations
• Security validations are maintained
• Offline-only operation is preserved
• Error messages are clear and actionable