lidless-labs/zeek-mcp
GitHub: lidless-labs/zeek-mcp
为 Zeek 和 Suricata 提供基于 MCP 协议的智能日志查询与分析服务，使 LLM 能够直接对网络安全监控数据进行跨日志调查与威胁检测。
Stars: 0 | Forks: 0
zeek-mcp
一个用于 [Zeek](https://zeek.org/) 和 [Suricata](https://suricata.io/) 的 MCP (Model Context Protocol) 服务器，提供对网络安全监控数据的智能日志解析、查询和分析。使 LLM 能够查询连接日志、DNS 活动、HTTP 请求、SSL 证书、文件提取、安全通知、IDS 告警，并在两个传感器的发现结果之间进行交叉引用。
## 功能
- **25 个工具**，用于查询和分析 Zeek + Suricata 日志
- **2 个资源**，用于日志类型元数据和传感器统计信息
- **4 个提示词**，用于引导调查工作流
- **双格式支持** - JSON 和 TSV（Zeek 原生的制表符分隔格式）
- **Suricata 集成** - 查询 eve.json 告警，与 Zeek 交叉关联，引擎统计信息
- **CIDR 匹配** - 按 IP 范围过滤 (10.0.0.0/8, 192.168.1.0/24)
- **IPv6 支持** - 完整的 IPv6 CIDR 匹配
- **通配符匹配** - 使用模式搜索域名和 URI (*.evil.com)
- **Beaconing 检测** - 带有抖动评分的统计型 C2 beacon 分析
- **异常检测** - 端口扫描、数据外泄和异常端口检测
- **DNS 隧道检测** - 带有编码检测的 Shannon 熵分析
- **DHCP 资产映射** - MAC 到 IP/主机名的设备清单
- **压缩日志支持** - 读取 .gz 归档日志
- **基于日期的轮转** - 按日期浏览 Zeek 的归档日志目录
## 前置条件
- Node.js 20+
- 生成日志的 Zeek 传感器（JSON 或 TSV 格式）
- Suricata（可选，用于 IDS 告警关联）
## 安装说明
```
git clone https://github.com/solomonneas/zeek-mcp.git
cd zeek-mcp
npm install
npm run build
```
## 配置
### Zeek
| Variable | Default | Description |
|----------|---------|-------------|
| `ZEEK_LOG_DIR` | `/opt/zeek/logs/current` | 当前 Zeek 日志的路径 |
| `ZEEK_LOG_ARCHIVE` | `/opt/zeek/logs` | 归档/轮转日志的路径 |
| `ZEEK_LOG_FORMAT` | `json` | 日志格式：`json` 或 `tsv` |
| `ZEEK_MAX_RESULTS` | `1000` | 每次查询的最大结果数 |
### Suricata
| Variable | Default | Description |
|----------|---------|-------------|
| `SURICATA_EVE_LOG` | `/opt/nids/suricata/logs/eve.json` | Suricata eve.json 的路径 |
| `SURICATA_FAST_LOG` | `/opt/nids/suricata/logs/fast.log` | Suricata fast.log 的路径 |
| `SURICATA_RULES_DIR` | `/opt/nids/suricata/rules` | Suricata 规则目录的路径 |
### PCAP 分析
| Variable | Default | Description |
|----------|---------|-------------|
| `PCAP_DIR` | `/opt/nids/pcaps` | PCAP 文件的目录。`pcap_analyze` 将所有文件名（相对和绝对）限制在此目录中；解析到此目录之外的任何内容都将被拒绝。 |
| `ZEEK_BINARY` | `/usr/local/zeek/bin/zeek` | Zeek 二进制文件的路径。 |
| `ZEEK_CONTAINER` | `zeek` | 用于运行 Zeek 的 Docker 容器。设置为空则直接在主机上运行 Zeek。 |
| `PCAP_OUTPUT_DIR` | `/tmp/zeek-pcap-analysis` | 生成日志的工作目录。 |
### MISP
| Variable | Default | Description |
|----------|---------|-------------|
| `MISP_URL` | `https://localhost` | MISP 的基础 URL。 |
| `MISP_API_KEY` | (无) | MISP API 密钥。MISP 工具必需。 |
| `MISP_VERIFY_SSL` | `true` | 设置为 `false` 可仅针对 MISP 请求禁用 TLS 证书验证（对于自签名的 MISP 证书很有用）。通过专用的分发器限定于 MISP 连接；它不会影响任何其他连接或设置全局 TLS 选项。 |
### TheHive
| Variable | Default | Description |
|----------|---------|-------------|
| `THEHIVE_URL` | `http://localhost:9000` | TheHive 的基础 URL。 |
| `THEHIVE_API_KEY` | (无) | TheHive API 密钥。TheHive 工具必需。 |
| `THEHIVE_VERIFY_SSL` | `true` | 设置为 `false` 可仅针对 TheHive 请求禁用 TLS 证书验证（对于自签名证书很有用）。限定于 TheHive 连接；它不会影响任何其他连接或设置全局 TLS 选项。 |
## 使用说明
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows)：
```
{
"mcpServers": {
"zeek": {
"command": "zeek-mcp",
"env": {
"ZEEK_LOG_DIR": "/opt/nids/zeek/logs",
"ZEEK_LOG_FORMAT": "tsv",
"SURICATA_EVE_LOG": "/opt/nids/suricata/logs/eve.json"
}
}
}
}
```
### Claude Code
```
claude mcp add zeek \
--env ZEEK_LOG_DIR=/opt/nids/zeek/logs \
--env ZEEK_LOG_FORMAT=tsv \
--env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \
-- zeek-mcp
```
添加 `--scope user` 可使其在任何目录下可用，而不仅仅是当前项目。
### OpenClaw
如果您是从源代码检出版本运行，而不是通过 npm 安装的二进制文件，请将 `command`/`args` 指向已构建的 `dist/index.js`：
```
openclaw mcp set zeek '{
"command": "node",
"args": ["/absolute/path/to/zeek-mcp/dist/index.js"],
"env": {
"ZEEK_LOG_DIR": "/opt/nids/zeek/logs",
"ZEEK_LOG_FORMAT": "tsv",
"SURICATA_EVE_LOG": "/opt/nids/suricata/logs/eve.json"
}
}'
```
或者，使用全局 npm 安装：
```
openclaw mcp set zeek '{
"command": "zeek-mcp",
"env": {
"ZEEK_LOG_DIR": "/opt/nids/zeek/logs",
"ZEEK_LOG_FORMAT": "tsv",
"SURICATA_EVE_LOG": "/opt/nids/suricata/logs/eve.json"
}
}'
```
然后重启 OpenClaw 网关以便加载新服务器：
```
systemctl --user restart openclaw-gateway
openclaw mcp list # confirm "zeek" is registered
```
### Hermes Agent
[Hermes Agent](https://github.com/NousResearch/hermes-agent) 从 `mcp_servers` 键下的 `~/.hermes/config.yaml` 中读取 MCP 配置。添加一个条目：
```
mcp_servers:
zeek:
command: "zeek-mcp"
env:
ZEEK_LOG_DIR: "/opt/nids/zeek/logs"
ZEEK_LOG_FORMAT: "tsv"
SURICATA_EVE_LOG: "/opt/nids/suricata/logs/eve.json"
```
或者，当从源代码检出版本而不是全局 npm 安装运行时：
```
mcp_servers:
zeek:
command: "node"
args: ["/absolute/path/to/zeek-mcp/dist/index.js"]
env:
ZEEK_LOG_DIR: "/opt/nids/zeek/logs"
ZEEK_LOG_FORMAT: "tsv"
SURICATA_EVE_LOG: "/opt/nids/suricata/logs/eve.json"
```
然后在 Hermes 会话中重新加载 MCP：
```
/reload-mcp
```
### Codex CLI
[Codex CLI](https://github.com/openai/codex) 通过 `codex mcp add` 注册 MCP 服务器：
```
codex mcp add zeek \
--env ZEEK_LOG_DIR=/opt/nids/zeek/logs \
--env ZEEK_LOG_FORMAT=tsv \
--env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \
-- zeek-mcp
```
或者，当从源代码检出版本运行时：
```
codex mcp add zeek \
--env ZEEK_LOG_DIR=/opt/nids/zeek/logs \
--env ZEEK_LOG_FORMAT=tsv \
--env SURICATA_EVE_LOG=/opt/nids/suricata/logs/eve.json \
-- node /absolute/path/to/zeek-mcp/dist/index.js
```
Codex 将条目写入 `[mcp_servers.zeek` 下的 `~/.codex/config.toml` 中。验证方式如下：
```
codex mcp list
```
### 独立运行
```
ZEEK_LOG_DIR=/opt/nids/zeek/logs ZEEK_LOG_FORMAT=tsv node dist/index.js
```
### 开发
```
ZEEK_LOG_DIR=./test-data npm run dev
```
## 工具
### 连接分析
| Tool | Description |
|------|-------------|
| `zeek_query_connections` | 使用灵活的过滤器（CIDR、协议、持续时间、字节）搜索连接日志 |
| `zeek_connection_summary` | 统计摘要：顶级通信者、服务、字节、连接数 |
| `zeek_long_connections` | 查找长连接（潜在的 C2 beacon、隧道） |
### DNS 分析
| Tool | Description |
|------|-------------|
| `zeek_query_dns` | 使用域名通配符和响应代码过滤搜索 DNS 查询 |
| `zeek_dns_summary` | 顶级域名、NXDOMAIN 计数（DGA 检测）、查询类型分布 |
| `zeek_dns_tunneling_check` | 通过熵分析和编码检测识别 DNS 隧道 |
### HTTP 分析
| Tool | Description |
|------|-------------|
| `zeek_query_http` | 按主机、URI、方法、User Agent、状态码搜索 HTTP 请求 |
| `zeek_suspicious_http` | 查找可疑的 HTTP：向 IP 发送的 POST、异常的 agent、大体积 body、URL 中的 base64 |
### SSL/TLS 分析
| Tool | Description |
|------|-------------|
| `zeek_query_ssl` | 按 SNI、版本、验证状态、证书字段搜索 SSL/TLS |
| `zeek_expired_certs` | 查找过期、自签名或无效的证书 |
### 文件分析
| Tool | Description |
|------|-------------|
| `zeek_query_files` | 按 MIME 类型、哈希、文件名、大小搜索提取的文件 |
| `zeek_executable_downloads` | 查找网络上的可执行文件传输（PE、ELF、脚本） |
### 安全通知
| Tool | Description |
|------|-------------|
| `zeek_query_notices` | 搜索 Zeek 安全通知（端口扫描、无效证书、自定义告警） |
### SSH 分析
| Tool | Description |
|------|-------------|
| `zeek_query_ssh` | 按认证状态、方向、客户端/服务器搜索 SSH 连接 |
| `zeek_ssh_bruteforce` | 检测超过失败阈值的 SSH 暴力破解尝试 |
### DHCP 与资产发现
| Tool | Description |
|------|-------------|
| `zeek_query_dhcp` | 搜索 DHCP 日志以获取租约分配和设备发现信息 |
| `zeek_dhcp_asset_map` | 为网络清单构建 MAC 到 IP/主机名的资产映射 |
### 跨日志调查
| Tool | Description |
|------|-------------|
| `zeek_investigate_host` | 跨所有日志类型对主机进行全面调查 |
| `zeek_investigate_uid` | 跨所有日志类型追踪连接 UID |
### 软件发现
| Tool | Description |
|------|-------------|
| `zeek_software_inventory` | 列出网络上检测到的软件和版本 |
### 分析
| Tool | Description |
|------|-------------|
| `zeek_detect_beaconing` | 通过分析连接间隔的规律性和抖动来检测 C2 beaconing |
| `zeek_detect_anomalies` | 统计异常检测：端口扫描、数据外泄、异常端口 |
### Suricata IDS
| Tool | Description |
|------|-------------|
| `suricata_query_alerts` | 按签名、严重性、IP、协议、时间搜索 Suricata 告警 |
| `suricata_alert_summary` | 高级别告警摘要：顶级签名、类别、IP、严重性分布 |
| `suricata_correlate_zeek` | 将 Suricata 告警与 Zeek 日志进行交叉引用以获取完整上下文 |
| `suricata_eve_stats` | Suricata 引擎统计信息：数据包、流、检测性能 |
### 传感器管理
| Tool | Description |
|------|-------------|
| `nids_sensor_status` | 实时传感器状态：日志清单、大小、新鲜度、健康检查 |
## 资源
| Resource | URI | Description |
|----------|-----|-------------|
| Log Types | `zeek://log-types` | 包含字段描述的所有 Zeek 日志类型 |
| Stats | `zeek://stats` | 传感器统计信息和可用的日志类型 |
## 提示词
| Prompt | Description |
|--------|-------------|
| `triage-alert` | 通过与 Zeek 日志进行交叉引用来对 Suricata 告警进行分类 |
| `investigate-host` | 跨所有日志的引导式主机调查工作流 |
| `hunt-for-c2` | 针对 C2 通信模式的威胁狩猎 |
| `network-baseline` | 生成网络活动基线 |
## 支持的日志类型
conn, dns, http, ssl, files, notice, weird, x509, smtp, ssh, dpd, software, dhcp, ntp, ocsp, websocket
## 测试
```
npm test
```
110 个测试，涵盖解析器（JSON + TSV）、查询引擎、CIDR/通配符过滤器、分析（熵、beaconing、异常检测）、Suricata eve.json 解析、DHCP 日志解析和传感器状态。
### 生成测试数据
```
npm run generate-logs
npx tsx scripts/generate-zeek-logs.ts --output=/tmp/zeek-logs --format=json
```
## 项目结构
```
zeek-mcp/
src/
index.ts # MCP server entry point
config.ts # Environment config + validation
types.ts # Zeek log type definitions (16 log types)
resources.ts # MCP resources
prompts.ts # MCP prompts (4 workflows)
parser/
index.ts # Format-agnostic parser + log resolution
json.ts # JSON log parser
tsv.ts # TSV log parser with header detection
query/
engine.ts # Query engine with filtering/sorting
filters.ts # CIDR match (v4+v6), wildcard, range operators
aggregation.ts # Statistical aggregation functions
tools/
connections.ts # Connection analysis tools
dns.ts # DNS analysis tools
http.ts # HTTP analysis tools
ssl.ts # SSL/TLS analysis tools
files.ts # File analysis tools
notices.ts # Security notice tools
ssh.ts # SSH analysis tools
investigation.ts # Cross-log investigation tools
software.ts # Software/asset discovery
dhcp.ts # DHCP log tools + asset mapping
beaconing.ts # Beaconing detection tool
anomaly.ts # Anomaly detection tool
suricata.ts # Suricata eve.json tools
sensor.ts # Sensor status + health checks
analytics/
entropy.ts # Shannon entropy calculation
beaconing.ts # Beacon detection algorithms
anomaly.ts # Statistical anomaly detection
tests/
parser.test.ts # Parser unit tests (JSON + TSV)
query.test.ts # Query engine + filter tests
analytics.test.ts # Entropy, beaconing, anomaly tests
tools.test.ts # Integration tests with sample data
suricata.test.ts # Suricata eve.json parsing tests
dhcp.test.ts # DHCP log parsing + asset map tests
beaconing-tools.test.ts # Beaconing + anomaly detection tests
sensor.test.ts # Sensor status tests
test-data/ # Sample Zeek + Suricata logs
scripts/
generate-zeek-logs.ts # Mock data generator
```
## 许可证
MIT
标签：IP 地址批量处理, MCP, Metaprompt, MITM代理, Rootkit, Suricata, TypeScript, Zeek, 安全插件, 暗色界面, 现代安全运营, 网络安全, 自动化攻击, 隐私保护