npm package: @modular-intelligence/suricata
Description: MCP server wrapping Suricata for network IDS analysis of PCAP files
Latest version: 1.0.2

# 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)
   ```bash
   # macOS
   brew install suricata

   # Ubuntu/Debian
   apt-get install suricata

   # RHEL/CentOS
   yum install suricata
   ```

2. **Bun runtime** (for running the MCP server)
   ```bash
   curl -fsSL https://bun.sh/install | bash
   ```

3. **Emerging Threats Open Rules** (recommended)
   ```bash
   # macOS
   suricata-update

   # Linux
   sudo suricata-update
   ```

### Verify Installation

```bash
suricata --version
suricata --list-app-layer-protos
```

## Installation

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

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

### Cline VSCode Extension

In Cline MCP Settings:

```json
{
  "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:**
```json
{
  "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:**
```typescript
{
  "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:**
```json
{
  "valid": true,
  "errors": [],
  "warnings": [
    "Warning: Rule uses deprecated fast_pattern syntax"
  ]
}
```

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

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

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

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

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

```bash
# Verify installation
which suricata

# Check PATH
echo $PATH

# Install if missing (macOS)
brew install suricata
```

### Rules not loading

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

```typescript
{
  "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

```bash
bun run build
```

### Run locally

```bash
bun run start
```

### Test with MCP Inspector

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

## Resources

- [Suricata Documentation](https://suricata.readthedocs.io/)
- [Emerging Threats Rules](https://rules.emergingthreats.net/)
- [Suricata Rule Format](https://suricata.readthedocs.io/en/latest/rules/index.html)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## 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