Suricata MCP Server

A Go-based Model Context Protocol (MCP) server that enables LLM clients to autonomously use Suricata for network traffic analysis.

Overview

Suricata MCP exposes Suricata's network security monitoring capabilities through standardized MCP tools and prompts, allowing Claude and other LLM clients to perform deep network traffic analysis on PCAP files — including alert triage, EVE JSON parsing, threat indicator extraction, and honeypot pattern detection.

Features

Tools (14 MCP Tools)

Suricata Operations:

• get_suricata_version — Get installed Suricata version
• get_suricata_help — Get Suricata CLI help output
• get_alerts_from_pcap_file — Process PCAP and return alerts (fast.log, EVE JSON, or both)
• get_stats_from_pcap_file — Process PCAP and return statistics from stats.log

EVE JSON Analysis:

• analyze_eve_json — Parse and filter EVE JSON with preset patterns (alerts, protocols, flows, DNS, TLS, anomalies)
• get_threat_indicators — Extract IOCs (IPs, domains, certificates, file hashes) for threat intelligence
• detect_honeypot_patterns — Detect attack patterns (C2 beaconing, exploitation, lateral movement, exfiltration, scanning)
• get_protocol_summary — Statistical summaries of protocols, flows, and traffic patterns
• correlate_flow_events — Reconstruct complete attack timeline by flow_id
• stream_eve_json — Memory-efficient streaming analysis for large EVE JSON files

Discovery & Validation:

• get_supported_protocols — List all application-layer protocols Suricata can parse
• get_suricata_keywords — List/search rule keywords for signature writing
• validate_suricata_config — Test Suricata configuration for errors
• analyze_file_hashes — Extract and analyze file hashes from EVE JSON fileinfo records

Prompts (4 Workflow Prompts)

• pcap-analysis-workflow — Step-by-step guidance for analyzing PCAP files
• ioc-extraction-workflow — Extract and enrich indicators of compromise for threat intelligence
• honeypot-pcap-analysis — Specialized workflow for analyzing honeypot sensor captures
• threat-hunting-workflow — Advanced proactive threat hunting in network traffic

Resources (1 MCP Resource)

• suricata://cli-reference — Complete Suricata command-line options reference

Platform Support

• Linux: /usr/bin/suricata
• macOS (Homebrew): /usr/local/bin/suricata or /opt/homebrew/bin/suricata
• Windows: C:\Program Files\Suricata\suricata.exe

Configuration via Environment Variables

Variable	Type	Default	Description
SURICATA_DIR	string	Platform-specific	Directory containing Suricata executable
SURICATA_EXE	string	suricata	Suricata executable filename
SURICATA_TIMEOUT	int	300	Command timeout in seconds

Installation

Prerequisites

• Go 1.23 or later
• Suricata installed on your system

From Source

git clone https://github.com/greyNoise-intelligence/suricata-mcp.git
cd suricata-mcp

# Build the binary
go build -o suricata-mcp .

# Or use just
just build

Using go install

go install github.com/greyNoise-intelligence/suricata-mcp@latest

Configuration

The server detects Suricata automatically based on your platform. If Suricata is installed in a non-standard location, set the SURICATA_DIR environment variable:

export SURICATA_DIR=/usr/local/bin

EVE JSON Analysis

Suricata MCP includes comprehensive EVE JSON (Extensible Event Format) analysis capabilities for advanced network traffic investigation.

What is EVE JSON?

EVE JSON is Suricata's structured event output format that provides detailed information about:

• Alerts and signatures
• Network flows (bytes, packets, timestamps)
• DNS queries and responses
• TLS/SSL certificates and handshakes
• HTTP requests and responses
• File transfers and hashes
• SMB, SSH, SMTP, and other protocol events

Analysis Capabilities

Pattern Detection:

• Automated detection of C2 beaconing (DNS NXDOMAIN, low TTL, self-signed certs)
• Exploitation attempts (SMB anomalies, old TLS, DCERPC)
• Lateral movement (SMB to multiple hosts)
• Data exfiltration (large flows, DNS tunneling)
• Scanning activity (port/host scanning patterns)

IOC Extraction:

• IP addresses with direction, alert count, protocols
• Domains with NXDOMAIN detection, low TTL flagging
• TLS certificates (self-signed, subject/issuer analysis)
• File hashes from captured files

Statistical Analysis:

• Protocol distribution and traffic volume
• Top talkers and destinations
• Port usage analysis
• Time-series traffic patterns

Usage

MCP Server Mode (stdio)

./suricata-mcp

Version

./suricata-mcp version

Claude Desktop Integration

Add the server to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "suricata": {
      "command": "/path/to/suricata-mcp",
      "env": {
        "SURICATA_DIR": "/usr/local/bin"
      }
    }
  }
}

Cursor Integration

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "suricata": {
      "command": "/path/to/suricata-mcp",
      "env": {
        "SURICATA_DIR": "/usr/local/bin"
      }
    }
  }
}

Examples

Basic PCAP Analysis

User: Analyze this PCAP file for threats
Claude: I'll analyze the PCAP file using Suricata.

[Claude uses get_suricata_version to verify installation]
[Claude uses get_alerts_from_pcap_file with output_format="eve_json"]
[Claude uses analyze_eve_json to examine alerts and protocols]

Here's what I found:
- 3 high-severity alerts detected
- SQL injection attempt from 192.168.1.100
- Malware C2 callback to suspicious domain
- Port scanning activity detected

Threat Intelligence Extraction

User: Extract IOCs from this honeypot capture for threat intel
Claude: I'll extract indicators of compromise from the EVE JSON.

[Claude uses get_alerts_from_pcap_file with output_format="eve_json"]
[Claude uses get_threat_indicators with indicator_types=["ips", "domains", "certificates"]]

Extracted IOCs:
- 5 malicious IPs (high confidence)
- 12 suspicious domains (8 with NXDOMAIN)
- 3 self-signed certificates
- Ready for enrichment with GreyNoise, VirusTotal, etc.

Honeypot Pattern Detection

User: What attack patterns are in this honeypot PCAP?
Claude: I'll analyze the honeypot data for attack patterns.

[Claude uses detect_honeypot_patterns with patterns=["all"]]

Detected patterns:
- C2 Beaconing (confidence: 0.85)
  - 15 DNS NXDOMAIN responses
  - 8 low TTL queries
  - 2 self-signed certificates
- Exploitation (confidence: 0.70)
  - SMB anomalies detected
  - Old TLS version usage

Flow Correlation

User: Show me everything related to flow ID 1038930578016525
Claude: I'll correlate all events for that flow.

[Claude uses correlate_flow_events with flow_id=1038930578016525]

Timeline for flow 1038930578016525:
1. DNS query for malicious.example.com
2. TLS handshake (self-signed certificate)
3. HTTP POST with suspicious payload
4. Alert triggered: Malware callback detected
5. Large data transfer (potential exfiltration)

Using Workflow Prompts

User: /prompt honeypot-pcap-analysis pcap_path="/data/honeypot.pcap"
Claude: Here's the honeypot analysis workflow:
1. Process PCAP with EVE JSON output...
2. Detect attack patterns automatically...
3. Extract threat indicators...
4. Investigate high-confidence detections...
5. Enrich IOCs with threat intelligence...
6. Recommend defensive actions...

Development

Building

# Build for current platform
just build

# Build with version info
just build-release 0.1.0

# Cross-compile for all platforms
just build-all

Testing

# Run unit tests
just test

# Run tests with coverage
just test-coverage

# Run integration tests (requires Suricata installed)
go test -v -tags=integration -timeout 30s

# Test with MCP Inspector
just inspect

Test Coverage:

• Unit tests: 40+ tests across 5 packages
  • Analyzer package: EVE JSON parsing, filtering, time handling
  • Config, executor, server packages: Core functionality
• Integration tests: Real PCAP file processing with Suricata
• Coverage: 60–100% across packages

Code Quality

just fmt      # Format code
just lint     # Run linter
just tidy     # Tidy dependencies

Architecture

suricata-mcp/
├── internal/
│   ├── analyzer/       # EVE JSON parsing and analysis
│   │   ├── eve.go      # EVE event structures and parsing
│   │   ├── time.go     # Custom timestamp handling
│   │   ├── filters.go  # Event filtering and aggregation
│   │   ├── ioc.go      # IOC extraction logic
│   │   ├── honeypot.go # Attack pattern detection
│   │   └── stats.go    # Statistical analysis
│   ├── config/         # Configuration management
│   ├── executor/       # Suricata command execution
│   └── server/         # MCP server implementation
│       ├── server.go   # Server setup and registration
│       ├── tools.go    # Tool handler implementations
│       ├── prompts.go  # Prompt handler implementations
│       └── resources.go # Resource handler implementations
├── docs/               # Design documents
├── pcaps/              # Sample PCAP files for testing
├── main.go             # Entry point
└── version.go          # Version information

Key Design Decisions

• No External Dependencies beyond mcp-go — uses Go's encoding/json for EVE JSON parsing
• Streaming Support — memory-efficient processing of large EVE JSON files via channels
• Custom Time Handling — microsecond-precision timestamp parsing for accurate timeline reconstruction
• Pointer-Based Optional Fields — clear distinction between absent and zero-value event fields

License

MIT License — see LICENSE for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure just test and just lint pass
5. Open a pull request

Acknowledgments

• Built with mcp-go
• Powered by Suricata from the Open Information Security Foundation
• Follows the Model Context Protocol specification