{"id":49250478,"url":"https://github.com/solomonneas/zeek-mcp","last_synced_at":"2026-04-30T03:04:20.059Z","repository":{"id":337129270,"uuid":"1152358373","full_name":"solomonneas/zeek-mcp","owner":"solomonneas","description":"MCP server for Zeek network analysis framework — intelligent log parsing, querying, and security analysis","archived":false,"fork":false,"pushed_at":"2026-04-20T22:55:35.000Z","size":175,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T00:39:00.820Z","etag":null,"topics":["ai-agents","mcp","model-context-protocol","network-analysis","security","traffic-analysis","zeek"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solomonneas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"solomonneas","ko_fi":"solomonneas","buy_me_a_coffee":"solomonneas"}},"created_at":"2026-02-07T18:55:43.000Z","updated_at":"2026-04-20T22:58:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/solomonneas/zeek-mcp","commit_stats":null,"previous_names":["solomonneas/zeek-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/solomonneas/zeek-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fzeek-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fzeek-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fzeek-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fzeek-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solomonneas","download_url":"https://codeload.github.com/solomonneas/zeek-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fzeek-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32245156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","mcp","model-context-protocol","network-analysis","security","traffic-analysis","zeek"],"created_at":"2026-04-25T00:02:58.121Z","updated_at":"2026-04-30T03:04:20.053Z","avatar_url":"https://github.com/solomonneas.png","language":"TypeScript","funding_links":["https://github.com/sponsors/solomonneas","https://ko-fi.com/solomonneas","https://buymeacoffee.com/solomonneas"],"categories":[],"sub_categories":[],"readme":"# Zeek MCP Server\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green?logo=node.js)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-1.x-purple)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAn MCP (Model Context Protocol) server for [Zeek](https://zeek.org/) and [Suricata](https://suricata.io/), providing intelligent log parsing, querying, and analysis over network security monitoring data. Enables LLMs to query connection logs, DNS activity, HTTP requests, SSL certificates, file extractions, security notices, IDS alerts, and cross-reference findings between both sensors.\n\n## Features\n\n- **25 tools** for querying and analyzing Zeek + Suricata logs\n- **2 resources** for log type metadata and sensor stats\n- **4 prompts** for guided investigation workflows\n- **Dual format support** - JSON and TSV (Zeek's native tab-separated format)\n- **Suricata integration** - Query eve.json alerts, cross-correlate with Zeek, engine stats\n\u003c!-- content-guard: allow private-ipv4 --\u003e\n- **CIDR matching** - Filter by IP ranges (10.0.0.0/8, 192.168.1.0/24)\n- **IPv6 support** - Full IPv6 CIDR matching\n- **Wildcard matching** - Search domains and URIs with patterns (*.evil.com)\n- **Beaconing detection** - Statistical C2 beacon analysis with jitter scoring\n- **Anomaly detection** - Port scan, data exfiltration, and unusual port detection\n- **DNS tunneling detection** - Shannon entropy analysis with encoding detection\n- **DHCP asset mapping** - MAC-to-IP/hostname device inventory\n- **Compressed log support** - Reads .gz archived logs\n- **Date-based rotation** - Navigates Zeek's archived log directories by date\n\n## Prerequisites\n\n- Node.js 20+\n- Zeek sensor generating logs (JSON or TSV format)\n- Suricata (optional, for IDS alert correlation)\n\n## Installation\n\n```bash\ngit clone https://github.com/solomonneas/zeek-mcp.git\ncd zeek-mcp\nnpm install\nnpm run build\n```\n\n## Configuration\n\n### Zeek\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `ZEEK_LOG_DIR` | `/opt/zeek/logs/current` | Path to current Zeek logs |\n| `ZEEK_LOG_ARCHIVE` | `/opt/zeek/logs` | Path to archived/rotated logs |\n| `ZEEK_LOG_FORMAT` | `json` | Log format: `json` or `tsv` |\n| `ZEEK_MAX_RESULTS` | `1000` | Maximum results per query |\n\n### Suricata\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SURICATA_EVE_LOG` | `/opt/nids/suricata/logs/eve.json` | Path to Suricata eve.json |\n| `SURICATA_FAST_LOG` | `/opt/nids/suricata/logs/fast.log` | Path to Suricata fast.log |\n| `SURICATA_RULES_DIR` | `/opt/nids/suricata/rules` | Path to Suricata rules directory |\n\n## Usage\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"zeek\": {\n      \"command\": \"zeek-mcp\",\n      \"env\": {\n        \"ZEEK_LOG_DIR\": \"/opt/nids/zeek/logs\",\n        \"ZEEK_LOG_FORMAT\": \"tsv\",\n        \"SURICATA_EVE_LOG\": \"/opt/nids/suricata/logs/eve.json\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add zeek \\\n  --env ZEEK_LOG_DIR=/opt/nids/zeek/logs \\\n  --env ZEEK_LOG_FORMAT=tsv \\\n  --env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \\\n  -- zeek-mcp\n```\n\nAdd `--scope user` to make it available from any directory instead of only the current project.\n\n### OpenClaw\n\nIf you're running from a source checkout instead of the npm-installed binary, point `command`/`args` at the built `dist/index.js`:\n\n```bash\nopenclaw mcp set zeek '{\n  \"command\": \"node\",\n  \"args\": [\"/absolute/path/to/zeek-mcp/dist/index.js\"],\n  \"env\": {\n    \"ZEEK_LOG_DIR\": \"/opt/nids/zeek/logs\",\n    \"ZEEK_LOG_FORMAT\": \"tsv\",\n    \"SURICATA_EVE_LOG\": \"/opt/nids/suricata/logs/eve.json\"\n  }\n}'\n```\n\nOr, with the global npm install:\n\n```bash\nopenclaw mcp set zeek '{\n  \"command\": \"zeek-mcp\",\n  \"env\": {\n    \"ZEEK_LOG_DIR\": \"/opt/nids/zeek/logs\",\n    \"ZEEK_LOG_FORMAT\": \"tsv\",\n    \"SURICATA_EVE_LOG\": \"/opt/nids/suricata/logs/eve.json\"\n  }\n}'\n```\n\nThen restart the OpenClaw gateway so the new server is picked up:\n\n```bash\nsystemctl --user restart openclaw-gateway\nopenclaw mcp list   # confirm \"zeek\" is registered\n```\n\n### Hermes Agent\n\n[Hermes Agent](https://github.com/NousResearch/hermes-agent) reads MCP config from `~/.hermes/config.yaml` under the `mcp_servers` key. Add an entry:\n\n```yaml\nmcp_servers:\n  zeek:\n    command: \"zeek-mcp\"\n    env:\n      ZEEK_LOG_DIR: \"/opt/nids/zeek/logs\"\n      ZEEK_LOG_FORMAT: \"tsv\"\n      SURICATA_EVE_LOG: \"/opt/nids/suricata/logs/eve.json\"\n```\n\nOr, when running from a source checkout instead of the global npm install:\n\n```yaml\nmcp_servers:\n  zeek:\n    command: \"node\"\n    args: [\"/absolute/path/to/zeek-mcp/dist/index.js\"]\n    env:\n      ZEEK_LOG_DIR: \"/opt/nids/zeek/logs\"\n      ZEEK_LOG_FORMAT: \"tsv\"\n      SURICATA_EVE_LOG: \"/opt/nids/suricata/logs/eve.json\"\n```\n\nThen reload MCP from inside a Hermes session:\n\n```\n/reload-mcp\n```\n\n### Codex CLI\n\n[Codex CLI](https://github.com/openai/codex) registers MCP servers via `codex mcp add`:\n\n```bash\ncodex mcp add zeek \\\n  --env ZEEK_LOG_DIR=/opt/nids/zeek/logs \\\n  --env ZEEK_LOG_FORMAT=tsv \\\n  --env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \\\n  -- zeek-mcp\n```\n\nOr, when running from a source checkout:\n\n```bash\ncodex mcp add zeek \\\n  --env ZEEK_LOG_DIR=/opt/nids/zeek/logs \\\n  --env ZEEK_LOG_FORMAT=tsv \\\n  --env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \\\n  -- node /absolute/path/to/zeek-mcp/dist/index.js\n```\n\nCodex writes the entry to `~/.codex/config.toml` under `[mcp_servers.zeek]`. Verify with:\n\n```bash\ncodex mcp list\n```\n\n### Standalone\n\n```bash\nZEEK_LOG_DIR=/opt/nids/zeek/logs ZEEK_LOG_FORMAT=tsv node dist/index.js\n```\n\n### Development\n\n```bash\nZEEK_LOG_DIR=./test-data npm run dev\n```\n\n## Tools\n\n### Connection Analysis\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_connections` | Search connection logs with flexible filters (CIDR, protocol, duration, bytes) |\n| `zeek_connection_summary` | Statistical summary: top talkers, services, bytes, connection counts |\n| `zeek_long_connections` | Find long-lived connections (potential C2 beacons, tunnels) |\n\n### DNS Analysis\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_dns` | Search DNS queries with domain wildcards and response code filtering |\n| `zeek_dns_summary` | Top domains, NXDOMAIN counts (DGA detection), query type distribution |\n| `zeek_dns_tunneling_check` | Detect DNS tunneling via entropy analysis and encoding detection |\n\n### HTTP Analysis\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_http` | Search HTTP requests by host, URI, method, user agent, status code |\n| `zeek_suspicious_http` | Find suspicious HTTP: POSTs to IPs, unusual agents, large bodies, base64 in URLs |\n\n### SSL/TLS Analysis\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_ssl` | Search SSL/TLS by SNI, version, validation status, certificate fields |\n| `zeek_expired_certs` | Find expired, self-signed, or invalid certificates |\n\n### File Analysis\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_files` | Search file extractions by MIME type, hash, filename, size |\n| `zeek_executable_downloads` | Find executable transfers (PE, ELF, scripts) on the wire |\n\n### Security Notices\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_notices` | Search Zeek security notices (port scans, invalid certs, custom alerts) |\n\n### SSH Analysis\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_ssh` | Search SSH connections by auth status, direction, client/server |\n| `zeek_ssh_bruteforce` | Detect SSH brute force attempts exceeding a failure threshold |\n\n### DHCP \u0026 Asset Discovery\n\n| Tool | Description |\n|------|-------------|\n| `zeek_query_dhcp` | Search DHCP logs for lease assignments and device discovery |\n| `zeek_dhcp_asset_map` | Build MAC-to-IP/hostname asset map for network inventory |\n\n### Cross-Log Investigation\n\n| Tool | Description |\n|------|-------------|\n| `zeek_investigate_host` | Full host investigation across all log types |\n| `zeek_investigate_uid` | Follow a connection UID across all log types |\n\n### Software Discovery\n\n| Tool | Description |\n|------|-------------|\n| `zeek_software_inventory` | List detected software and versions on the network |\n\n### Analytics\n\n| Tool | Description |\n|------|-------------|\n| `zeek_detect_beaconing` | Detect C2 beaconing by analyzing connection interval regularity and jitter |\n| `zeek_detect_anomalies` | Statistical anomaly detection: port scans, data exfiltration, unusual ports |\n\n### Suricata IDS\n\n| Tool | Description |\n|------|-------------|\n| `suricata_query_alerts` | Search Suricata alerts by signature, severity, IP, protocol, time |\n| `suricata_alert_summary` | High-level alert summary: top signatures, categories, IPs, severity distribution |\n| `suricata_correlate_zeek` | Cross-reference Suricata alerts with Zeek logs for full context |\n| `suricata_eve_stats` | Suricata engine statistics: packets, flows, detection performance |\n\n### Sensor Management\n\n| Tool | Description |\n|------|-------------|\n| `nids_sensor_status` | Live sensor status: log inventory, sizes, freshness, health checks |\n\n## Resources\n\n| Resource | URI | Description |\n|----------|-----|-------------|\n| Log Types | `zeek://log-types` | All Zeek log types with field descriptions |\n| Stats | `zeek://stats` | Sensor statistics and available log types |\n\n## Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `triage-alert` | Triage a Suricata alert by cross-referencing with Zeek logs |\n| `investigate-host` | Guided host investigation workflow across all logs |\n| `hunt-for-c2` | Threat hunting for C2 communication patterns |\n| `network-baseline` | Generate a network activity baseline |\n\n## Supported Log Types\n\nconn, dns, http, ssl, files, notice, weird, x509, smtp, ssh, dpd, software, dhcp, ntp, ocsp, websocket\n\n## Testing\n\n```bash\nnpm test\n```\n\n110 tests covering parsers (JSON + TSV), query engine, CIDR/wildcard filters, analytics (entropy, beaconing, anomaly detection), Suricata eve.json parsing, DHCP log parsing, and sensor status.\n\n### Generate Test Data\n\n```bash\nnpm run generate-logs\nnpx tsx scripts/generate-zeek-logs.ts --output=/tmp/zeek-logs --format=json\n```\n\n## Project Structure\n\n```\nzeek-mcp/\n  src/\n    index.ts                 # MCP server entry point\n    config.ts                # Environment config + validation\n    types.ts                 # Zeek log type definitions (16 log types)\n    resources.ts             # MCP resources\n    prompts.ts               # MCP prompts (4 workflows)\n    parser/\n      index.ts               # Format-agnostic parser + log resolution\n      json.ts                # JSON log parser\n      tsv.ts                 # TSV log parser with header detection\n    query/\n      engine.ts              # Query engine with filtering/sorting\n      filters.ts             # CIDR match (v4+v6), wildcard, range operators\n      aggregation.ts         # Statistical aggregation functions\n    tools/\n      connections.ts         # Connection analysis tools\n      dns.ts                 # DNS analysis tools\n      http.ts                # HTTP analysis tools\n      ssl.ts                 # SSL/TLS analysis tools\n      files.ts               # File analysis tools\n      notices.ts             # Security notice tools\n      ssh.ts                 # SSH analysis tools\n      investigation.ts       # Cross-log investigation tools\n      software.ts            # Software/asset discovery\n      dhcp.ts                # DHCP log tools + asset mapping\n      beaconing.ts           # Beaconing detection tool\n      anomaly.ts             # Anomaly detection tool\n      suricata.ts            # Suricata eve.json tools\n      sensor.ts              # Sensor status + health checks\n    analytics/\n      entropy.ts             # Shannon entropy calculation\n      beaconing.ts           # Beacon detection algorithms\n      anomaly.ts             # Statistical anomaly detection\n  tests/\n    parser.test.ts           # Parser unit tests (JSON + TSV)\n    query.test.ts            # Query engine + filter tests\n    analytics.test.ts        # Entropy, beaconing, anomaly tests\n    tools.test.ts            # Integration tests with sample data\n    suricata.test.ts         # Suricata eve.json parsing tests\n    dhcp.test.ts             # DHCP log parsing + asset map tests\n    beaconing-tools.test.ts  # Beaconing + anomaly detection tests\n    sensor.test.ts           # Sensor status tests\n  test-data/                 # Sample Zeek + Suricata logs\n  scripts/\n    generate-zeek-logs.ts    # Mock data generator\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolomonneas%2Fzeek-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolomonneas%2Fzeek-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolomonneas%2Fzeek-mcp/lists"}