Suricata和Zeek安全监控MCP服务器

suricata-mcp

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.

Website & docs -> lidless.dev/suricata-mcp

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)

Suricata Flow Analysis (2 tools)

Suricata Protocol Analysis (6 tools)

Suricata Rule Management (5 tools)

Suricata Engine & Live Commands (3 tools)

Suricata Investigation (2 tools)

Advanced Analytics (4 tools)

Zeek NSM Analysis (8 tools)

Cross-Correlation (1 tool)

PCAP Management (3 tools)

Threat Intelligence (3 tools)

Configuration

Set environment variables to point at your NIDS installation:

Mutating tools (opt-in)

By default the server is read-only: every analysis/query tool works, but the tools that change a live IDS or shell out are disabled. To enable them you must:

1. Set SURICATA_ALLOW_MUTATION=1 in the server environment (operator opt-in), and
2. Pass confirm: true on the tool call itself (per-invocation opt-in).

Both guards must be satisfied; otherwise the tool returns an error without acting. The gated tools are:

• suricata_create_rule - appends to local.rules. Additionally enforces a local SID range (sid >= 1000000) and rejects SIDs that collide with the loaded ruleset. Rule text must be a single line with no newline or carriage return characters.
• suricata_toggle_rule - enables or disables a rule by SID in local.rules.
• suricata_reload_rules - reloads rules through the Unix socket.
• thehive_create_case / thehive_create_alert - creates a case or alert in TheHive.
• suricata_reload_rules_docker - runs suricata-update + SIGUSR2 against the live container.
• pcap_replay_suricata / pcap_replay_zeek - replay a PCAP through the engine. Filenames must be a bare name of letters, digits, ., -, and _ (anything else is rejected), are rejected if they begin with - (option-injection), and concurrent replays are capped. Docker is invoked with argv arrays, never a shell.

Threat-intel HTTP calls (MISP/TheHive) use redirect: "manual", so a 3xx from a compromised or misconfigured endpoint is refused rather than followed with the API key attached.

Features

• 41 tools for comprehensive network security analysis
• 5 resources for quick reference data
• 5 prompts for guided investigation workflows
• Suricata EVE JSON alert querying, flow analysis, protocol inspection, rule management
• Zeek TSV logs connection analysis, DNS/HTTP/TLS/SSH/file inspection
• Cross-correlation between Suricata alerts and Zeek network metadata
• Threat intel integration with MISP IOC lookup and TheHive case/alert creation
• PCAP management list and replay PCAPs through Suricata or Zeek
• Advanced analytics DGA detection, C2 beaconing, data exfiltration, lateral movement
• Rule management create, enable/disable, and reload custom Suricata rules
• Streaming parsers for large files, CIDR-aware filtering, gzip archive support

Prerequisites

• Node.js 20+
• Suricata sensor producing EVE JSON logs
• (Optional) Zeek NSM with TSV log output
• (Optional) MISP and/or TheHive instances for threat intel

Resources

Prompts

Architecture

suricata-mcp/
  src/
    index.ts              # MCP server entry, tool registration
    config.ts             # Environment config (Suricata, Zeek, PCAP, MISP, TheHive)
    types.ts              # EVE JSON type definitions
    parser/
      eve.ts              # Streaming EVE JSON parser (supports .gz)
      rules.ts            # Suricata rule file parser
      zeek.ts             # Zeek TSV log parser with header handling
    query/
      engine.ts           # Query engine for EVE files
      filters.ts          # CIDR, wildcard, time range, IP matching
      aggregation.ts      # Statistical aggregation, top-N, numeric stats
      timeline.ts         # Time-bucketed event aggregation
    tools/
      alerts.ts           # Suricata alert analysis
      flows.ts            # Suricata flow analysis
      dns.ts              # Suricata DNS tools
      http.ts             # Suricata HTTP tools
      tls.ts              # Suricata TLS/JA3/JA4 tools
      files.ts            # Suricata file extraction tools
      ssh.ts              # Suricata SSH tools
      anomalies.ts        # Suricata anomaly tools
      rules.ts            # Rule management (search, stats, create, toggle, reload)
      stats.ts            # Engine stats tools
      investigation.ts    # Cross-type investigation
      zeek.ts             # Zeek log query tools (conn, dns, http, ssl, files, ssh, weird)
      pcap.ts             # PCAP list and replay tools
      threatintel.ts      # MISP search + TheHive case/alert creation
      correlation.ts      # Suricata-Zeek cross-correlation
    analytics/
      beaconing.ts        # C2 beacon detection
      dns_entropy.ts      # DGA detection via Shannon entropy
      exfiltration.ts     # Data exfiltration detection
      lateral.ts          # Lateral movement detection + RFC1918 helpers
      ja3.ts              # Known JA3 fingerprint database
    socket/
      client.ts           # Unix socket for live Suricata commands
    resources.ts          # MCP resources
    prompts.ts            # MCP prompts
  tests/
    parser.test.ts        # Parser unit tests
    query.test.ts         # Filter and aggregation tests
    tools.test.ts         # Tool handler integration tests
    zeek.test.ts          # Zeek parser and tool tests
    analytics.test.ts     # Advanced analytics tests
    correlation.test.ts   # Cross-correlation tests
  test-data/
    eve.json              # Sample Suricata EVE JSON data
    sample.rules          # Sample Suricata rules
    conn.log              # Sample Zeek conn.log
    dns.log               # Sample Zeek dns.log
    http.log              # Sample Zeek http.log
    ssl.log               # Sample Zeek ssl.log
    files.log             # Sample Zeek files.log
    ssh.log               # Sample Zeek ssh.log
    weird.log             # Sample Zeek weird.log
  scripts/
    generate-eve.ts       # Mock EVE data generator

Why not query the logs directly?

• jq / grep over eve.json. Fine for one field on one file. It does not cross-correlate a Suricata alert with the Zeek conn/dns/http/ssl records for the same IP pair and time window, it does not compute beaconing intervals or DNS entropy, and it does not hand an LLM a typed tool surface. suricata-mcp does all of that and streams large, gzip-rotated logs without loading them whole.
• A full SIEM (Splunk, Elastic, Wazuh). A SIEM is the right home for long-term retention, dashboards, and multi-source alerting. suricata-mcp is not a SIEM and is not trying to be one. It is a local, zero-infrastructure way to let an agent reason over the Suricata and Zeek logs already on a sensor, with no index to feed and no service to run.
• A generic log-tailing MCP server. Those stream raw lines. suricata-mcp understands EVE JSON and Zeek TSV schemas, so it filters by SID, signature, JA3/JA4, MIME type, and CIDR, aggregates top talkers and protocol distributions, and returns structured results an agent can act on instead of text blobs.
• Writing your own MCP wrapper. You could, but you would re-implement streaming EVE/Zeek parsers, CIDR-aware filtering, the analytics, the dual mutation guard, and the redirect-refusing threat-intel client. That work is already done and tested here.

What suricata-mcp is not

• Not a packet capture or IDS engine. It does not sniff traffic or run detection. Suricata (and optionally Zeek) produce the logs; this server reads them.
• Not a SIEM, log store, or dashboard. No retention, no UI, no indexing. It analyzes the logs that already exist on disk.
• Not write-happy. By default it cannot modify your ruleset, reload the engine, or replay a PCAP. Mutating tools require both an operator environment opt-in and a per-call confirm: true.
• Not a hosted service. It runs locally over stdio against your own files. Nothing is sent anywhere except the optional, explicit MISP/TheHive calls you configure.

Testing

npm test             # Run all 158 tests
npm run test:watch   # Watch mode

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md for the contribution path and SECURITY.md before reporting a vulnerability. By participating you agree to the Code of Conduct.

License

MIT

Part of Lidless Labs · the eye does not close

_{Security / SOC: soc-stack · wazuh-mcp · misp-mcp · thehive-mcp · cortex-mcp · mitre-mcp · zeek-mcp · hotwash}

_{All tools · Lidless Labs on GitHub}