suricata-mcp

<p align="center"> <img src="docs/assets/suricata-mcp-social-preview.jpg" alt="suricata-mcp banner" width="900"> </p> <p align="center"> <a href="https://lidless.dev"><img src="docs/assets/marks/suricata-mcp-circle.png" width="48" alt="Lidless Labs"></a> </p> <h1 align="center">suricata-mcp</h1> <p align="center"> <strong>An MCP server that lets an AI client read and triage Suricata IDS/IPS and Zeek NSM telemetry, so alert investigation happens in natural language instead of grep over EVE JSON.</strong> </p> <p align="center"> <a href="https://lidless.dev/suricata-mcp"><strong>Website &amp; docs -&gt; lidless.dev/suricata-mcp</strong></a> </p> <p align="center"> <img src="https://shieldcn.dev/github/ci/lidless-labs/suricata-mcp.svg?branch=main&workflow=ci.yml" alt="CI status"> <img src="https://shieldcn.dev/npm/suricata-mcp.svg" alt="npm version"> <img src="https://shieldcn.dev/badge/MCP-server-8A2BE2.svg" alt="MCP server"> <img src="https://shieldcn.dev/badge/license-MIT-green.svg" alt="MIT license"> </p>

suricata-mcp is a Model Context Protocol (MCP) server for network security monitoring: it exposes Suricata IDS/IPS alerts and Zeek NSM logs to an AI client as structured tools. Why: a SOC analyst chasing a single alert normally pivots by hand across eve.json, flow records, DNS/HTTP/TLS transactions, and the Zeek logs next to them, which is slow and easy to get wrong under pressure. How it differs: instead of a dashboard or a one-shot log shipper, it gives the model query, aggregation, correlation, and threat-hunting tools that run locally against your own log files, with cross-correlation between Suricata and Zeek and built-in analytics for C2 beaconing, DGA, exfiltration, and lateral movement, so the analyst asks questions in plain language and the model does the pivoting.

What it does

suricata-mcp is an MCP server for Suricata IDS/IPS and Zeek network-security monitoring. It reads Suricata EVE JSON alerts, flows, and protocol records (DNS, HTTP, TLS/JA3/JA4, SSH, fileinfo, anomalies) and Zeek TSV logs straight off disk, then exposes them to an AI client as MCP tools for querying, aggregation, timelines, host and alert investigation, and cross-sensor correlation. On top of the raw telemetry it ships intrusion-detection analytics, C2 beaconing detection, DGA domain detection via Shannon entropy, data-exfiltration detection, and lateral-movement detection, plus Suricata rule management and optional threat-intel pivots into MISP and TheHive. The server is read-only by default: every analysis tool works out of the box, and the handful of tools that change a live IDS or shell out stay disabled until you explicitly opt in. It speaks MCP over stdio, so it drops into Claude Desktop, Claude Code, Codex CLI, OpenClaw, Hermes, or any MCP-capable agent.

Installation

Most clients can run the published package directly with npx -y suricata-mcp (see Quickstart). To work from source instead:

git clone https://github.com/lidless-labs/suricata-mcp.git
cd suricata-mcp
npm install
npm run build

Quickstart

Add suricata-mcp to any MCP client with the published npm package. No clone or build required:

{
  "mcpServers": {
    "suricata": {
      "command": "npx",
      "args": ["-y", "suricata-mcp"],
      "env": {
        "SURICATA_EVE_LOG": "/var/log/suricata/eve.json",
        "SURICATA_RULES_DIR": "/etc/suricata/rules",
        "ZEEK_LOGS_DIR": "/opt/zeek/logs"
      }
    }
  }
}

That is the entire install. The server starts read-only against the logs you point it at; everything below is configuration detail and per-client wiring.

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "suricata": {
      "command": "npx",
      "args": ["-y", "suricata-mcp"],
      "env": {
        "SURICATA_EVE_LOG": "/opt/nids/suricata/logs/eve.json",
        "SURICATA_RULES_DIR": "/opt/nids/suricata/rules",
        "ZEEK_LOGS_DIR": "/opt/nids/zeek/logs",
        "PCAP_DIR": "/opt/nids/pcaps",
        "MISP_URL": "https://misp.local",
        "MISP_API_KEY": "your-key",
        "THEHIVE_URL": "http://thehive.local:9000",
        "THEHIVE_API_KEY": "your-key"
      }
    }
  }
}

If you installed from source, set "command": "suricata-mcp" (global npm install) or "command": "node" with "args": ["/absolute/path/to/suricata-mcp/dist/index.js"].

Claude Code

claude mcp add suricata \
  --env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \
  --env SURICATA_RULES_DIR=/opt/nids/suricata/rules \
  --env ZEEK_LOGS_DIR=/opt/nids/zeek/logs \
  -- npx -y suricata-mcp

Add --scope user to make it available from any directory instead of only the current project.

OpenClaw

If you're running from a source checkout instead of the npm-installed binary, point command/args at the built dist/index.js:

openclaw mcp set suricata '{
  "command": "node",
  "args": ["/absolute/path/to/suricata-mcp/dist/index.js"],
  "env": {
    "SURICATA_EVE_LOG": "/opt/nids/suricata/logs/eve.json",
    "SURICATA_RULES_DIR": "/opt/nids/suricata/rules",
    "ZEEK_LOGS_DIR": "/opt/nids/zeek/logs"
  }
}'

Or, with the published package:

openclaw mcp set suricata '{
  "command": "npx",
  "args": ["-y", "suricata-mcp"],
  "env": {
    "SURICATA_EVE_LOG": "/opt/nids/suricata/logs/eve.json",
    "SURICATA_RULES_DIR": "/opt/nids/suricata/rules",
    "ZEEK_LOGS_DIR": "/opt/nids/zeek/logs"
  }
}'

Then restart the OpenClaw gateway so the new server is picked up:

systemctl --user restart openclaw-gateway
openclaw mcp list   # confirm "suricata" is registered

Hermes Agent

Hermes Agent reads MCP config from ~/.hermes/config.yaml under the mcp_servers key. Add an entry:

mcp_servers:
  suricata:
    command: "npx"
    args: ["-y", "suricata-mcp"]
    env:
      SURICATA_EVE_LOG: "/opt/nids/suricata/logs/eve.json"
      SURICATA_RULES_DIR: "/opt/nids/suricata/rules"
      ZEEK_LOGS_DIR: "/opt/nids/zeek/logs"

Or, when running from a source checkout instead of the published package:

mcp_servers:
  suricata:
    command: "node"
    args: ["/absolute/path/to/suricata-mcp/dist/index.js"]
    env:
      SURICATA_EVE_LOG: "/opt/nids/suricata/logs/eve.json"
      SURICATA_RULES_DIR: "/opt/nids/suricata/rules"
      ZEEK_LOGS_DIR: "/opt/nids/zeek/logs"

Then reload MCP from inside a Hermes session:

/reload-mcp

Codex CLI

Codex CLI registers MCP servers via codex mcp add:

codex mcp add suricata \
  --env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \
  --env SURICATA_RULES_DIR=/opt/nids/suricata/rules \
  --env ZEEK_LOGS_DIR=/opt/nids/zeek/logs \
  -- npx -y suricata-mcp

Or, when running from a source checkout:

codex mcp add suricata \
  --env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \
  --env SURICATA_RULES_DIR=/opt/nids/suricata/rules \
  --env ZEEK_LOGS_DIR=/opt/nids/zeek/logs \
  -- node /absolute/path/to/suricata-mcp/dist/index.js

Codex writes the entry to ~/.codex/config.toml under [mcp_servers.suricata]. Verify with:

codex mcp list

Standalone

SURICATA_EVE_LOG=/var/log/suricata/eve.json \
ZEEK_LOGS_DIR=/opt/zeek/logs \
node dist/index.js

Development

npm run dev          # Watch mode with tsx
npm run build        # Production build
npm test             # Run test suite (158 tests)
npm run lint         # Type-check

Tools

Suricata Alert Analysis (4 tools)

| Tool | Description | |------|-------------| | suricata_query_alerts | Search alerts by SID, signature, category, severity, IP, port, protocol, action, time range | | suricata_alert_summary | Aggregated alert statistics grouped by signature, category, severity, source, or destination | | suricata_top_alerts | Top alerts by frequency and severity with unique source/destination counts | | suricata_alert_timeline | Time-bucketed alert counts with severity breakdown |

Suricata Flow Analysis (2 tools)

| Tool | Description | |------|-------------| | suricata_query_flows | Search flows by IP, port, protocol, app protocol, bytes, duration, state | | suricata_flow_summary | Top talkers, protocol distribution, bandwidth stats |

Suricata Protocol Analysis (6 tools)

| Tool | Description | |------|-------------| | suricata_query_dns | Search DNS queries by name, source IP, record type, response code | | suricata_query_http | Search HTTP transactions by hostname, URL, method, status, user-agent | | suricata_query_tls | Search TLS connections by SNI, JA3/JA4, certificate subject/issuer | | suricata_query_ssh | Search SSH connections by client/server software version | | suricata_query_fileinfo | Search extracted files by name, magic type, hash, size | | suricata_query_anomalies | Search protocol anomalies by type, source/destination IP |

Suricata Rule Management (5 tools)

| Tool | Description | |------|-------------| | suricata_search_rules | Search rule files by SID, message, classtype, reference, content | | suricata_rule_stats | Rule set statistics: total, enabled/disabled, by action, by classtype | | suricata_create_rule | Write a custom rule to local.rules | | suricata_toggle_rule | Enable or disable a rule by SID | | suricata_reload_rules_docker | Reload rules via Docker (suricata-update + SIGUSR2) |

Suricata Engine & Live Commands (3 tools)

| Tool | Description | |------|-------------| | suricata_engine_stats | Capture, decoder, detect, and flow statistics | | suricata_reload_rules | Live rule reload via Unix socket | | suricata_iface_stat | Interface capture statistics via Unix socket |

Suricata Investigation (2 tools)

| Tool | Description | |------|-------------| | suricata_investigate_host | Full host investigation across all event types | | suricata_investigate_alert | Deep alert investigation with correlated flow and protocol data |

Advanced Analytics (4 tools)

| Tool | Description | |------|-------------| | suricata_beaconing_detection | Detect C2 beaconing via connection interval analysis with jitter and confidence scoring | | suricata_dga_detection | Detect DGA domains using Shannon entropy analysis on DNS queries | | suricata_exfiltration_detection | Detect hosts with abnormally high outbound data transfer | | suricata_lateral_movement_detection | Detect internal-to-internal scanning on unusual ports |

Zeek NSM Analysis (8 tools)

| Tool | Description | |------|-------------| | zeek_query_connections | Search conn.log by IP, port, protocol, service, duration, bytes, state | | zeek_query_dns | Search dns.log by query name, type, rcode | | zeek_query_http | Search http.log by host, URI, method, status, user-agent | | zeek_query_ssl | Search ssl.log by server name, TLS version | | zeek_query_files | Search files.log by filename, MIME type, hash | | zeek_query_ssh | Search ssh.log by client, server, auth success | | zeek_query_weird | Search weird.log for protocol anomalies | | zeek_connection_summary | Top talkers, protocol and service distribution, bandwidth stats |

Cross-Correlation (1 tool)

| Tool | Description | |------|-------------| | correlate_alert_with_zeek | Cross-correlate Suricata alerts with Zeek conn/dns/http/ssl logs by IP pair and time window |

PCAP Management (3 tools)

| Tool | Description | |------|-------------| | pcap_list | List available PCAP files | | pcap_replay_suricata | Replay a PCAP through Suricata | | pcap_replay_zeek | Replay a PCAP through Zeek |

Threat Intelligence (3 tools)

| Tool | Description | |------|-------------| | misp_search_ioc | Search MISP for IOCs (IP, domain, hash)