内容
<p align="center">
<img src="docs/assets/suricata-mcp-banner.jpg" alt="Watercolor EVE alert triage desk for suricata-mcp" width="100%" />
</p>
<h1 align="center">suricata-mcp</h1>
<p align="center">
<strong>一个MCP服务器，允许AI客户端读取和分诊Suricata IDS/IPS和Zeek NSM遥测数据，从而在自然语言中进行警报调查，而不是通过grep EVE JSON。</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/suricata-mcp"><img src="https://img.shields.io/npm/v/suricata-mcp?style=for-the-badge&logo=npm&color=cb3837" alt="npm版本" /></a>
<a href="https://github.com/lidless-labs/suricata-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/suricata-mcp/ci.yml?branch=main&style=for-the-badge&label=CI&logo=github" alt="CI状态" /></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-server-6f42c1?style=for-the-badge" alt="模型上下文协议服务器" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow?style=for-the-badge" alt="MIT许可证" /></a>
</p>
<p align="center">
<a href="https://lidless.dev/suricata-mcp"><strong>网站和文档 -> lidless.dev/suricata-mcp</strong></a>
</p>
suricata-mcp是一个模型上下文协议（MCP）服务器，用于网络安全监控：它将Suricata IDS/IPS警报和Zeek NSM日志作为结构化工具暴露给AI客户端。 **为什么：** SOC分析师通常通过手动在 `eve.json`、流量记录、DNS/HTTP/TLS事务和Zeek日志之间进行跳转来追踪单个警报，这在压力下很慢且容易出错。 **它与众不同之处：** 与其使用仪表板或一次性日志运输工具，它为模型提供了查询、聚合、关联和威胁狩猎工具，这些工具在本地日志文件上运行，具有跨Suricata和Zeek的关联以及针对C2信标、DGA、数据泄露和横向移动的内置分析，因此分析师可以用普通语言提问，模型进行跳转。
## 它做什么
suricata-mcp是 **Suricata** IDS/IPS和 **Zeek** 网络安全监控的MCP服务器。它直接从磁盘读取Suricata **EVE JSON** 警报、流量和协议记录（DNS、HTTP、TLS/JA3/JA4、SSH、fileinfo、异常）和Zeek TSV日志，然后将它们作为MCP工具暴露给AI客户端，以进行查询、聚合、时间线、主机和警报调查以及跨传感器关联。在原始遥测数据之上，它提供入侵检测分析、C2信标检测、DGA域名检测、数据泄露检测和横向移动检测，以及Suricata规则管理和可选的MISP和TheHive威胁情报集成。服务器 **默认只读**：所有分析工具开箱即用，少数更改实时IDS或外壳的工具在您明确选择加入之前保持禁用。它通过stdio使用MCP，因此它可以与Claude Desktop、Claude Code、Codex CLI、OpenClaw、Hermes或任何MCP-capable代理一起使用。
## 为什么不直接查询日志？
- **`jq` / `grep` 超过 `eve.json`.** 适用于单个字段的一个文件。它不关联Suricata警报与Zeek的 `conn` / `dns` / `http` / `ssl` 记录的相同IP对和时间窗口，它不计算信标间隔或DNS熵，也不为LLM提供键控工具表面。 suricata-mcp执行所有这些操作，并流式传输大型、gzip旋转的日志而不加载它们。
- **完整的SIEM（Splunk、Elastic、Wazuh）。** SIEM是长期保留、仪表板和多源警报的合适场所。 suricata-mcp不是SIEM，也不是试图成为SIEM。它是一种本地、无基础设施的方式，让代理在传感器上已有Suricata和Zeek日志上进行推理，无需提供索引，也无需运行服务。
- **通用日志尾随MCP服务器。** 那些流式传输原始行。 suricata-mcp了解EVE JSON和Zeek TSV模式，因此它按SID、签名、JA3/JA4、MIME类型和CIDR过滤，聚合顶部谈话者和协议分布，并返回结构化结果，代理可以对其采取行动，而不是文本块。
- **编写自己的MCP包装器。** 你可以，但你会重新实现流式EVE/Zeek解析器、CIDR感知过滤、分析、双重突变保护和重定向拒绝威胁情报客户端。 这项工作已经完成并在此处测试。
## suricata-mcp 不是什么
- **不是数据包捕获或IDS引擎。** 它不嗅探流量或运行检测。 Suricata（和可选的Zeek）生成日志；这个服务器读取它们。
- **不是SIEM、日志存储或仪表板。** 没有保留，没有UI，没有索引。 它分析已经存在于磁盘上的日志。
- **不是热衷于写入。** 默认情况下，它不能修改您的规则集、重新加载引擎或重放PCAP。 变异工具需要操作员环境选择加入 **和** 每个调用的 `confirm: true`。
- **不是托管服务。** 它在本地stdio上运行，针对您自己的文件。 除非您配置了可选的明确MISP/TheHive调用，否则不会将任何内容发送到任何地方。
## 功能
- **41种工具** 用于全面网络安全分析
- **5种资源** 用于快速参考数据
- **5种提示** 用于有指导的调查工作流程
- **Suricata EVE JSON** 警报查询、流量分析、协议检查、规则管理
- **Zeek TSV日志** 连接分析、DNS/HTTP/TLS/SSH/文件检查
- **跨关联** Suricata警报和Zeek网络元数据之间
- **威胁情报** 与MISP IOC查找和TheHive案例/警报创建集成
- **PCAP管理** 列出和重放PCAP文件，通过Suricata或Zeek
- **高级分析** DGA检测、C2信标检测、数据泄露检测、横向移动检测
- **规则管理** 创建、启用/禁用和重载自定义Suricata规则
- 流式解析器用于大文件、CIDR感知过滤、gzip存档支持
## 快速入门
将suricata-mcp添加到任何MCP客户端，使用已发布的npm包。无需克隆或构建：
```json
{
"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"
}
}
}
}
```
这就是整个安装过程。服务器以只读方式启动，针对您指向的日志；以下所有内容都是配置详细信息和每个客户端的连接。
## 先决条件
- Node.js 20+
- 产生EVE JSON日志的Suricata传感器
- （可选）带有TSV日志输出的Zeek NSM
- （可选）用于威胁情报的MISP和/或TheHive实例
## 安装
大多数客户端可以直接使用已发布的包运行 `npx -y suricata-mcp`（参见 [快速入门](#快速入门)）。要从源代码开始：
```bash
git clone https://github.com/lidless-labs/suricata-mcp.git
cd suricata-mcp
npm install
npm run build
```
## 配置
设置环境变量以指向您的NIDS安装：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `SURICATA_EVE_LOG` | `/var/log/suricata/eve.json` | 主要EVE JSON日志的路径 |
| `SURICATA_EVE_ARCHIVE` | `/var/log/suricata/` | 旋转/存档日志的目录 |
| `SURICATA_RULES_DIR` | _（无）_ | Suricata规则目录 |
| `SURICATA_MAX_RESULTS` | `1000` | 每个查询的最大结果数 |
| `SURICATA_UNIX_SOCKET` | _（无）_ | 实时命令的Unix套接字路径 |
| `ZEEK_LOGS_DIR` | _（无）_ | Zeek日志目录（启用Zeek工具） |
| `PCAP_DIR` | _（无）_ | PCAP投递目录（启用PCAP工具） |
| `MISP_URL` | _（无）_ | MISP实例URL |
| `MISP_API_KEY` | _（无）_ | MISP API密钥 |
| `THEHIVE_URL` | _（无）_ | TheHive实例URL |
| `THEHIVE_API_KEY` | _（无）_ | TheHive API密钥 |
| `SURICATA_ALLOW_MUTATION` | _（关闭）_ | 设置为 `1` 以启用变异工具（规则写入、规则集重载、PCAP重放）。默认关闭。 |
### 变异工具（需选择加入）
默认情况下，服务器是只读的：每个分析/查询工具都有效，但更改实时IDS或外壳的工具被禁用。要启用它们，您必须：
1. 在服务器环境中设置 `SURICATA_ALLOW_MUTATION=1` （操作员选择加入），并且
2. 在工具调用本身上传递 `confirm: true` （每次调用选择加入）。
必须满足这两个条件；否则，工具返回错误而不执行操作。已门控的工具是：
- `suricata_create_rule` - 追加到 `local.rules`。此外，还强制执行本地SID范围（`sid >= 1000000`）并拒绝与已加载的规则集冲突的SID。
- `suricata_reload_rules_docker` - 在Docker上运行 `suricata-update` + `SIGUSR2`。
- `pcap_replay_suricata` / `pcap_replay_zeek` - 通过引擎重放PCAP。文件名进行basename清理，如果以 `-` 开头则拒绝（选项注入），并发重放次数上限。
威胁情报HTTP调用（MISP/TheHive）使用 `redirect: "manual"`，因此来自受损或配置错误的端点的3xx被拒绝，而不是用附加的API密钥重定向。
## 用法
### 克劳德桌面
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"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"
}
}
}
}
```
如果您从源代码安装，请将 `"command"` 设置为 `"suricata-mcp"`（全局npm安装）或 `"command"` 设置为 `"node"`，并将 `"args"` 设置为 `[ "/absolute/path/to/suricata-mcp/dist/index.js"]`。
### 克劳德代码
```bash
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
```
添加 `--scope user` 以使其在任何目录中都可用，而不仅仅是当前项目。
### 开放利爪
如果您从源代码检出运行而不是npm安装的二进制文件，请将 `command` / `args` 指向编译的 `dist/index.js`:
```bash
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"
}
}'
```
或使用已发布的包：
```bash
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"
}
}'
```
然后重启OpenClaw网关以获取新的服务器：
```bash
systemctl --user restart openclaw-gateway
openclaw mcp list # 确认“suricata”已注册
```
### 海尔墨斯代理
[Hermes Agent](https://github.com/NousResearch/hermes-agent) 从 `~/.hermes/config.yaml` 下的 `mcp_servers` 键读取MCP配置。添加一个条目：
```yaml
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"
```
或在从源代码检出运行而非发布的包时：
```yaml
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"
```
然后在赫尔墨斯会话内重新加载MCP：
```
/reload-mcp
```
### 代码克斯CLI
[Codex CLI](https://github.com/openai/codex) 通过 `codex mcp add` 注册MCP服务器：
```bash
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
```
或在从源代码检出时：
```bash
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 将条目写入 `~/.codex/config.toml` 下的 `[mcp_servers.suricata]`。使用以下命令进行验证：
```bash
codex mcp list
```
### 独立
```bash
SURICATA_EVE_LOG=/var/log/suricata/eve.json \
ZEEK_LOGS_DIR=/opt/zeek/logs \
node dist/index.js
```
### 开发
```bash
npm run dev # 监视模式，带tsx
npm run build # 生产构建
npm test # 运行测试套件（158个测试）
npm run lint # 类型检查
```
## 工具
### Suricata 警报分析（4种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_query_alerts` | 按SID、签名、类别、严重性、IP、端口、协议、操作、时间范围搜索警报 |
| `suricata_alert_summary` | 按签名、类别、严重性、源或目标分组的聚合警报统计信息 |
| `suricata_top_alerts` | 按频率和严重性显示的热门警报，带有唯一源/目标计数 |
| `suricata_alert_timeline` | 带有严重性分解的时间桶警报计数 |
### Suricata 流量分析（2种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_query_flows` | 按IP、端口、协议、应用协议、字节、持续时间、状态搜索流量 |
| `suricata_flow_summary` | 流量统计：顶级谈话者、协议分布、带宽统计 |
### Suricata 协议分析（6种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_query_dns` | 按名称、源IP、记录类型、响应代码搜索DNS查询 |
| `suricata_query_http` | 按主机名、URL、方法、状态、用户代理搜索HTTP事务 |
| `suricata_query_tls` | 按SNI、JA3/JA4、证书主题/颁发者搜索TLS连接 |
| `suricata_query_ssh` | 按客户端/服务器软件版本搜索SSH连接 |
| `suricata_query_fileinfo` | 按文件名、魔术类型、哈希、大小搜索提取的文件 |
| `suricata_query_anomalies` | 按类型、源/目标IP搜索协议异常 |
### Suricata 规则管理（5种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_search_rules` | 按SID、消息、分类、引用、内容搜索规则文件 |
| `suricata_rule_stats` | 规则集统计：总数、启用的/禁用的、按操作、按分类 |
| `suricata_create_rule` | 将自定义规则写入local.rules |
| `suricata_toggle_rule` | 按SID启用或禁用规则 |
| `suricata_reload_rules_docker` | 通过Docker重载规则（suricata-update + SIGUSR2） |
### Suricata 引擎和实时命令（3种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_engine_stats` | 捕获、解码器、检测和流量统计 |
| `suricata_reload_rules` | 通过Unix套接字实时重载规则 |
| `suricata_iface_stat` | 通过Unix套接字获取接口捕获统计 |
### Suricata 调查（2种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_investigate_host` | 跨所有事件类型进行完整的主机调查 |
| `suricata_investigate_alert` | 深入警报调查，关联流量和协议数据 |
### 高级分析（4种工具）
| 工具 | 描述 |
| --- | --- |
| `suricata_beaconing_detection` | 通过连接间隔分析检测C2信标，带有抖动和置信度评分 |
| `suricata_dga_detection` | 使用香农熵分析检测DGA域名 |
| `suricata_exfiltration_detection` | 检测具有异常高出站数据传输的主机 |
| `suricata_lateral_movement_detection` | 检测在不常见端口上的内部到内部扫描 |
### Zeek NSM 分析（8种工具）
| 工具 | 描述 |
| --- | --- |
| `zeek_query_connections` | 按IP、端口、协议、服务、持续时间、字节、状态搜索conn.log |
| `zeek_query_dns` | 按查询名称、类型、rcode搜索dns.log |
| `zeek_query_http` | 按主机、URI、方法、状态、用户代理搜索http.log |
| `zeek_query_ssl` | 按服务器名称、TLS版本搜索ssl.log |
| `zeek_query_files` | 按文件名、MIME类型、哈希搜索files.log |
| `zeek_query_ssh` | 按客户端、服务器、身份验证成功搜索ssh.log |
| `zeek_query_weird` | 在weird.log中搜索协议异常 |
| `zeek_connection_summary` | 流量统计：顶级谈话者、协议和服务分布、带宽统计 |
### 跨关联（1种工具）
| 工具 | 描述 |
| --- | --- |
| `correlate_alert_with_zeek` | 按IP对和时间窗口关联Suricata警报与Zeek conn/dns/http/ssl日志 |
### PCAP 管理（3种工具）
| 工具 | 描述 |
| --- | --- |
| `pcap_list` | 列出可用的PCAP文件 |
| `pcap_replay_suricata` | 通过Suricata重放PCAP |
| `pcap_replay_zeek` | 通过Zeek重放PCAP |
### 威胁情报（3种工具）
| 工具 | 描述 |
| --- | --- |
| `misp_search_ioc` | 在MISP中搜索IOC（IP、域名、哈希） |
| `thehive_create_case` | 从调查结果中创建TheHive案例 |
| `thehive_create_alert` | 将Suricata警报推送到TheHive进行分诊 |
## 资源
| URI | 描述 |
| --- | --- |
| `suricata://event-types` | 所有EVE事件类型及其字段描述 |
| `suricata://stats/current` | 最新引擎性能统计 |
| `suricata://rules/summary` | 规则集摘要 |
| `suricata://config` | 当前服务器配置（已净化） |
| `zeek://log-types` | 可用的Zeek日志类型及其字段描述 |
## 提示
| 提示 | 描述 |
|--------|-------------|
| `investigate-alert` | 有导向的警报调查工作流程 |
| `hunt-for-threats` | 主动威胁狩猎方法论 |
| `incident-response` | 完整的事件响应工作流程，包含Suricata + Zeek + TheHive |
| `network-baseline` | 网络基线报告生成 |
| `daily-alert-report` | 每日警报摘要报告模板 |
## 架构
```
suricata-mcp/
src/
index.ts # MCP服务器入口，工具注册
config.ts # 环境配置（Suricata，Zeek，PCAP，MISP，TheHive）
types.ts # EVE JSON类型定义
parser/
eve.ts # 流式EVE JSON解析器（支持.gz）
rules.ts # Suricata规则文件解析器
zeek.ts # Zeek TSV日志解析器，带头部处理
query/
engine.ts # EVE文件查询引擎
filters.ts # CIDR，通配符，时间范围，IP匹配
aggregation.ts # 统计聚合，top-N，数值统计
timeline.ts # 时间分桶事件聚合
tools/
alerts.ts # Suricata警报分析
flows.ts # Suricata流量分析
dns.ts # Suricata DNS工具
http.ts # Suricata HTTP工具
tls.ts # Suricata TLS/JA3/JA4工具
files.ts # Suricata文件提取工具
ssh.ts # Suricata SSH工具
anomalies.ts # Suricata异常工具
rules.ts # 规则管理（搜索，统计，创建，切换，重新加载）
stats.ts # 引擎统计工具
investigation.ts # 跨类型调查
zeek.ts # Zeek日志查询工具（conn，dns，http，ssl，files，ssh，weird）
pcap.ts # PCAP列表和重放工具
threatintel.ts # MISP搜索 + TheHive案例/警报创建
correlation.ts # Suricata-Zeek跨关联
analytics/
beaconing.ts # C2信标检测
dns_entropy.ts # 通过香农熵进行DGA检测
exfiltration.ts # 数据泄露检测
lateral.ts # 横向移动检测 + RFC1918辅助
ja3.ts # 已知JA3指纹数据库
socket/
client.ts # 用于实时Suricata命令的Unix套接字
resources.ts # MCP资源
prompts.ts # MCP提示
tests/
parser.test.ts # 解析器单元测试
query.test.ts # 过滤器和聚合测试
tools.test.ts # 工具处理集成测试
zeek.test.ts # Zeek解析器和工具测试
analytics.test.ts # 高级分析测试
correlation.test.ts # 跨关联测试
test-data/
eve.json # 示例Suricata EVE JSON数据
sample.rules # 示例Suricata规则
conn.log # 示例Zeek conn.log
dns.log # 示例Zeek dns.log
http.log # 示例Zeek http.log
ssl.log # 示例Zeek ssl.log
files.log # 示例Zeek files.log
ssh.log # 示例Zeek ssh.log
weird.log # 示例Zeek weird.log
scripts/
generate-eve.ts # 模拟EVE数据生成器
```
## 测试
```bash
npm test # 运行所有158个测试
npm run test:watch # 监视模式
```
## 贡献
欢迎提出问题和拉取请求。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献流程，并在报告漏洞前阅读 [SECURITY.md](SECURITY.md)。通过参与，您同意遵守 [Code of Conduct](CODE_OF_CONDUCT.md)。
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器