# 🔐 SB SIEM MCP
**28 个 MCP 工具。9 个领域。已在 Wazuh 4.14.5 实时实例上测试。为 Wazuh SIEM/XDR 提供 AI 驱动的安全运营。**
只需一个提示词。您的 AI 助手就能查询 7,514 条告警，检查 5,038 条 FIM 记录，扫描 12 个 CVE，交叉比对 750 个 MITRE 技术，审计 CIS 合规性，并触发事件响应 —— 所有这些都通过您的 Wazuh 基础设施完成。
## 工作原理（30 秒）
您已经在某处运行了 Wazuh。MCP 服务器是一个**本地进程**，由您的 AI 客户端作为子进程启动 —— 就像语言服务器或 linter 一样。
```
Your Machine Your Wazuh Server
┌────────────────────┐ ┌──────────────────┐
│ Zed / Claude │ │ │
│ │ │ │ Wazuh API │
│ ▼ │ │ :55000 │
│ python -m │───────HTTPS──────▶│ │
│ wazuh_mcp.server │ │ Wazuh Indexer │
│ (child process) │───────HTTPS──────▶│ :9200 │
└────────────────────┘ └──────────────────┘
```
**无需 Docker。无需容器。无需安装代理。** 只需将其指向您现有的 Wazuh，即可开始用自然语言提问。
## 🛡️ 安全特性（纵深防御）
- [x] **输入验证** — 阻止 Shell 元字符，对 agent ID、IP、CVE、MITRE ID 使用正则表达式
- [x] **速率限制** — 令牌桶算法：读操作工具 30次/60秒，破坏性操作工具 5次/120秒
- [x] **输出清理** — 从绑定至 LLM 的数据中脱敏 AWS 密钥、JWT token、SSH 密钥、API 密钥、密码
- [x] **审计日志** — 为所有破坏性操作记录仅追加的 JSONL 审计轨迹
- [x] **确认门控** — 针对主动响应工具的两步 `confirm=True` + 过期 token 机制
- [x] **RBAC** — 4 个内置角色：`viewer`、`analyst`、`admin`、`soc`，具有层级访问权限
- [x] **Dependabot + pip-audit + CodeQL** — 每次 push 时进行自动依赖扫描 + 每周定期扫描
- [x] **非 root Docker** — 生产环境容器以非特权用户 `wazuhmcp` 运行
- [x] **TLS 支持** — 验证服务器证书，或在本地开发中通过 `WAZUH_INSECURE` 禁用
- [x] **Prometheus 指标** — 在 `:9090/metrics` 暴露 7 个指标用于 SOC 监控（延迟、错误、速率限制）
- [x] **OpenAPI 3.0 / Swagger UI** — 在 `/docs` 提供交互式 API 文档，原始规范位于 `/openapi.json`
## 📊 架构
```
┌──────────────────────────┐ ┌──────────────────────────┐
│ Your AI Client │ │ Wazuh Infrastructure │
│ (Zed / Claude / Cursor) │ │ │
│ │ │ │ Wazuh API :55000 │
│ ▼ │ │ ├─ Agents, Groups │
│ ┌──────────────────┐ │ │ ├─ SCA, FIM, MITRE │
│ │ MCP Server │────HTTPS────▶│ ├─ Manager, Cluster │
│ │ 28 tools │ │ │ └─ Active Response │
│ │ │ │ │ │
│ │ WazuhClient ────┼────HTTPS────▶│ Wazuh Indexer :9200 │
│ │ IndexerClient ───┤ │ │ ├─ Alerts (7,514+) │
│ │ RateLimiter │ │ │ ├─ Vulnerabilities │
│ │ Sanitizer │ │ │ └─ Events, Rules │
│ │ RBACEnforcer │ │ │ │
│ └──────────────────┘ │ └──────────────────────────┘
│ │ │
│ :9090/metrics │
│ :8000/docs │
└──────────────────────────┘
```
MCP 服务器与 Wazuh REST API（端口 55000，用于管理）**以及** Wazuh Indexer（端口 9200，用于告警/漏洞）进行通信。在 Wazuh 4.x/5.x 中，告警和漏洞仅在 indexer 中提供 —— 无法通过 REST API 访问。服务器的 `IndexerClient` 会透明地处理此问题。
## 📊 功能介绍
| 工作流 | 示例提示词 | 使用的工具 |
|----------|---------------|------------|
| **告警分类** | *"按严重程度和 MITRE 技术总结今天的告警"* | `list_alerts`, `alert_summary`, `get_alert` |
| **威胁狩猎** | *"在所有事件和 FIM 记录中搜索 IOC 10.0.0.50"* | `search_events`, `query_fim`, `search_mitre` |
| **合规审计** | *"显示所有未通过 CIS 基准检查的 agent"* | `sca_status`, `sca_checks`, `compliance_report` |
| **规则覆盖** | *"我的 NIST 800-53 检测覆盖率是多少？"* | `rules_coverage_map`, `rules_info` |
| **漏洞管理** | *"哪些系统存在未修补的关键 CVE？"* | `query_vulnerabilities`, `vulnerability_heatmap` |
| **事件时间线** | *"重建告警 #45821 前后发生的事情"* | `incident_timeline`, `search_events`, `query_fim` |
| **资产管理** | *"列出已断开连接的 agent 及其所属组"* | `list_agents`, `get_agent`, `agent_health`, `list_groups` |
| **威胁情报** | *"显示 CDB 黑名单以及 T1059 的 MITRE 技术"* | `list_cdb_lists`, `get_cdb_list`, `search_mitre` |
| **事件响应** ⚠️ | *"在所有 Web 服务器上封禁 IP 203.0.113.55"* | `run_active_response` （需确认） |
## 📦 安装说明
### pip（来自 PyPI —— 即将推出）
```
pip install sb-siem-mcp
```
### 从源码安装
```
git clone https://github.com/Sbharadwaj05/sb-siem-mcp.git
cd sb-siem-mcp
pip install -e ".[dev]"
```
### Docker（一键演示 —— 启动 Wazuh + MCP 用于测试）
```
git clone https://github.com/Sbharadwaj05/sb-siem-mcp.git
cd sb-siem-mcp
docker compose up -d
# Wazuh Dashboard: https://localhost:443
# Swagger UI: http://localhost:8000/docs
# Prometheus Metrics: http://localhost:9090/metrics
```
### 配置
创建一个 `.env` 文件：
```
# 必需
WAZUH_API_URL=https://your-wazuh-manager:55000
WAZUH_USERNAME=wazuh-wui
WAZUH_PASSWORD=your-api-password
# 警报、漏洞、规则所需（Wazuh 4.x/5.x）
WAZUH_INDEXER_URL=https://your-wazuh-manager:9200
WAZUH_INDEXER_USER=admin
WAZUH_INDEXER_PASS=your-indexer-password
# 可选
WAZUH_INSECURE=true # Skip TLS verification (dev only)
WAZUH_RBAC_ROLE=analyst # Restrict tools by role
WAZUH_RATE_LIMIT_TOKENS=30 # Rate limit burst
WAZUH_RATE_LIMIT_PERIOD=60 # Rate limit window
```
### Claude Desktop / Zed / Cursor
```
{
"mcpServers": {
"wazuh": {
"command": "python",
"args": ["-m", "wazuh_mcp.server"],
"cwd": "/path/to/sb-siem-mcp/src",
"env": {
"WAZUH_API_URL": "https://192.168.56.102:55000",
"WAZUH_USERNAME": "wazuh-wui",
"WAZUH_PASSWORD": "your-api-password",
"WAZUH_INSECURE": "true",
"WAZUH_INDEXER_PASS": "your-indexer-password"
}
}
}
}
```
## 🔧 完整工具参考（28 个工具，9 个领域）
### 🔔 告警与分类 (3)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_list_alerts` | 按严重程度、agent、规则 ID、MITRE、搜索查询告警 | Wazuh Indexer |
| `wazuh_get_alert` | 通过 ID 获取单个告警及其完整上下文 | Wazuh Indexer |
| `wazuh_alert_summary` | 聚合：严重程度分布、热门规则/IP、MITRE 覆盖率 | Wazuh Indexer |
### 🔍 威胁狩猎 (4)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_search_events` | 提交原始事件供 Wazuh 解析/分析 | Wazuh API |
| `wazuh_query_fim` | 文件完整性监控 —— 文件更改、添加、删除 | Wazuh API |
| `wazuh_query_vulnerabilities` | 每个 agent 的 CVE 清单，可按严重程度过滤 | Wazuh Indexer |
| `wazuh_search_mitre` | MITRE ATT&CK 技术、战术、缓解措施、组织 | Wazuh API |
### 📋 合规性 (3)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_sca_status` | 每个 agent 的 SCA 策略评分（CIS、PCI DSS、NIST、GDPR） | Wazuh API |
| `wazuh_sca_checks` | 每项检查的通过/失败详情，包含理由和补救措施 | Wazuh API |
| `wazuh_compliance_report` | 跨所有 agent 的资产级合规性聚合 | Wazuh API |
### 🖥️ Agent 与组 (6)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_list_agents` | 列出 agent 的状态、OS、版本、搜索、分页信息 | Wazuh API |
| `wazuh_get_agent` | 深入了解单个 agent：配置、模块、组 | Wazuh API |
| `wazuh_agent_health` | 资产健康度：状态计数、OS 分布、僵尸 agent | Wazuh API |
| `wazuh_list_groups` | 列出 agent 组及其数量和校验和 | Wazuh API |
| `wazuh_get_group` | 组详情、配置、成员数量 | Wazuh API |
| `wazuh_group_agents` | 特定组中的所有 agent | Wazuh API |
### 📚 CDB 列表 (2)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_list_cdb_lists` | 列出 CDB 威胁情报文件（IP 黑名单、IOC 数据库） | Wazuh API |
| `wazuh_get_cdb_list` | 读取 CDB 列表文件的内容 | Wazuh API |
### ⚙️ 管理器与集群 (5)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_manager_stats` | 守护进程统计信息（EPS、队列、已处理事件） | Wazuh API |
| `wazuh_manager_logs` | 获取管理器日志，支持按类别和搜索过滤 | Wazuh API |
| `wazuh_cluster_status` | 集群健康度：启用/运行状态 | Wazuh API |
| `wazuh_cluster_node_stats` | 每个节点的守护进程统计信息（单节点下回退至管理器统计信息） | Wazuh API |
| `wazuh_rules_info` | 按框架/MITRE 搜索规则（在 4.14.x 版本 bug 下回退至 indexer） | Wazuh API / Indexer |
### 📊 安全分析 (3)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_rules_coverage_map` | 对照您的规则生成 MITRE/NIST/PCI/GDPR/HIPAA 覆盖率矩阵 | Wazuh Indexer |
| `wazuh_vulnerability_heatmap` | 跨所有 agent 的风险评分 CVE 热力图 | Wazuh Indexer |
| `wazuh_incident_timeline` | 从单条告警自动生成按时间顺序排列的攻击时间线 | Wazuh Indexer |
### ⚠️ 事件响应 (2)
| 工具 | 描述 | 数据源 |
|------|-------------|-------------|
| `wazuh_run_active_response` | 触发 firewall-drop、host-deny、restart-wazuh（带有确认门控） | Wazuh API |
| `wazuh_agent_command` | 在远程 agent 上执行命令（带有确认门控） | Wazuh API |
## 🖥️ 可观测性
### Prometheus 指标 (`:9090/metrics`)
| 指标 | 类型 | 描述 |
|--------|------|-------------|
| `wazuh_mcp_tool_calls_total` | Counter | 按名称 + 状态（成功/错误）统计的工具调用 |
| `wazuh_mcp_tool_duration_seconds` | Histogram | 每个工具的 P50/P95/P99 延迟 |
| `wazuh_mcp_rate_limits_total` | Counter | 每个工具的速率限制拒绝次数 |
| `wazuh_mcp_api_up` | Gauge | Wazuh API 连通性（1=正常，0=宕机） |
| `wazuh_mcp_audit_entries_total` | Counter | 记录的破坏性操作 |
| `wazuh_mcp_active_requests` | Gauge | 正在处理中的工具调用 |
| `wazuh_mcp_tool_errors_total` | Counter | 按工具 + 错误类型统计的错误数 |
### OpenAPI / Swagger (`:8000/docs`)
为所有 28 个工具提供交互式 API 文档。原始 OpenAPI 3.0 规范位于 `/openapi.json`。
### 审计日志 (`~/.wazuh-mcp/audit.jsonl`)
仅追加的 JSON Lines。每次破坏性操作对应一条记录。永不截断。线程安全。
## 🔐 RBAC
四个具有层级递增访问权限的内置角色：
| 角色 | 权限 | 工具 |
|------|--------|-------|
| `viewer` | 只读 | 告警、agent、合规性、规则 |
| `analyst` | + 调查 | 所有 viewer 权限 + 狩猎、MITRE、CDB 列表、分析 |
| `admin` | + 管理 | 所有 analyst 权限 + 管理器统计、日志、集群 |
| `soc` | + 响应 ⚠️ | 所有 admin 权限 + 主动响应、agent 命令 |
```
export WAZUH_RBAC_ROLE=analyst
# 或自定义 policy: WAZUH_RBAC_POLICY=/path/to/rbac.json
```
## 📁 项目结构
```
sb-siem-mcp/
├── src/wazuh_mcp/
│ ├── server.py # FastMCP entry point (stdio + SSE transport)
│ ├── client.py # Wazuh REST API client (JWT, Basic Auth, fallback)
│ ├── indexer.py # Wazuh Indexer / OpenSearch client (alerts, vulns)
│ ├── rbac.py # Role-Based Access Control (4 roles, custom policies)
│ ├── audit.py # Immutable audit logging (JSONL, append-only)
│ ├── sanitizer.py # Output sanitization (credential redaction)
│ ├── rate_limiter.py # Token-bucket per-tool rate limiting
│ ├── validators.py # Input validation (regex, shell metacharacter blocking)
│ ├── metrics.py # Prometheus metrics exporter (7 metrics)
│ ├── openapi.py # OpenAPI 3.0 spec + Swagger UI generator
│ ├── output.py # Token-efficient field selection (5 modes)
│ ├── utils.py # JSON formatters, pagination helpers
│ └── tools/ # 9 tool modules, 28 MCP tools
│ ├── alerts.py # 3 tools: list, get, summary
│ ├── hunting.py # 4 tools: events, fim, vulns, mitre
│ ├── compliance.py # 3 tools: sca status, checks, report
│ ├── agents.py # 3 tools: list, get, health
│ ├── groups.py # 3 tools: list, get, group agents
│ ├── lists.py # 2 tools: list cdb, get cdb
│ ├── manager.py # 5 tools: stats, logs, cluster, node, rules
│ ├── analysis.py # 3 tools: coverage, heatmap, timeline
│ └── response.py # 2 tools: active response, agent command (safety-gated)
├── tests/ # pytest-asyncio test suite (12 tests, all passing)
├── docs/ # SECURITY, DEVELOPMENT, ADVANCED_FEATURES, TROUBLESHOOTING
├── scripts/setup.sh # One-command Wazuh + MCP dev environment
├── docker-compose.yml # Wazuh 4.9 + MCP server + Prometheus
├── Dockerfile # Multi-stage production build (non-root)
├── openapi.json # Generated OpenAPI 3.0 specification (24 paths)
├── .github/workflows/ # CI (test matrix), Release, Security Scan
├── CHANGELOG.md
└── README.md
```
## 🚀 快速开始
```
# 1. Clone
git clone https://github.com/Sbharadwaj05/sb-siem-mcp.git
cd sb-siem-mcp
# 2. Configure
cp .env.example .env
# 使用你的 Wazuh API + Indexer credentials 编辑 .env
# 3. Install
pip install -e ".[dev]"
# 4. 验证连通性
python -c "
from wazuh_mcp.client import WazuhClient
import asyncio
async def t():
c = WazuhClient(insecure=True)
print('Agents:', (await c.list_agents(limit=1)).get('total_affected_items','?'))
print('Alerts:', (await c.list_alerts(limit=1)).get('total_affected_items','?'))
await c.close()
asyncio.run(t())
"
# 5. 连接到 AI client
# 将 claude_desktop_config.json.example 复制到你的 MCP config 中
```
## 🔒 生产环境加固
本项目出厂带有安全的默认设置，但为了方便本地测试，docker-compose 演示堆栈禁用了一些安全功能。**不要在生产环境中使用演示配置**，除非进行了以下更改：
### 1. 在各处启用 TLS
- 设置 `WAZUH_INSECURE=false` —— 现在 docker-compose 默认设置为 `false`。
- 重新启用 Wazuh Indexer 安全插件 —— 从 `wazuh.indexer` 服务中移除 `DISABLE_SECURITY_PLUGIN=true` 和 `plugins.security.disabled=true`。取而代之的是，生成正确的证书。
- 在 Wazuh Manager 上设置 `FILEBEAT_SSL_VERIFICATION_MODE=full`。
### 2. 限制 MCP Endpoint
MCP 服务器端口 8000 上暴露了一个 HTTP endpoint。**此 endpoint 没有内置的客户端身份验证。** 在生产环境中：
- 如果 AI 客户端在同一主机上运行，请绑定到 `127.0.0.1`，或者
- 将 MCP 服务器置于具有双向 TLS / API 密钥身份验证的反向代理之后，或者
- 使用网络级控制（防火墙规则、安全组）来限制访问。
### 3. 保护 Wazuh Indexer
Indexer（端口 9200）必须能从 MCP 服务器进行网络访问。
- 使用 TLS 和证书验证（`WAZUH_INSECURE=false`）。
- 将 Indexer 凭据存储在密钥管理器中（Docker secrets、Kubernetes secrets、HashiCorp Vault） —— 在生产环境中绝对不要以明文形式存放在 `.env` 文件中。
- 考虑在网络/防火墙层进行 IP 白名单过滤。
### 4. 加固审计日志
- 默认的审计日志位置是 `~/.wazuh-mcp/audit.jsonl`。在生产环境中，请设置 `WAZUH_AUDIT_LOG=/var/log/wazuh-mcp/audit.jsonl`（或主目录之外的另一个持久化卷）。
- 为了实现真正的不可变性，请将审计日志发送到外部 SIEM 或使用一次写入多次读取（WORM）文件系统。
### 5. RBAC：启用它
RBAC 默认是禁用的（`WAZUH_RBAC_ROLE` 未设置 → 所有工具均可用）。在生产环境中，请设置 `WAZUH_RBAC_ROLE=analyst`（或更严格的角色），并在您的 AI 客户端中配置相应的工具权限。
### 6. 版本兼容性
本服务器主要针对 Wazuh 4.x（已在 4.14.5 上测试）。Wazuh 5.x 用新的存储后端取代了 Indexer —— 本服务器需要进行更新才能与 5.x 兼容。部署前请检查您的 Wazuh 版本。
## 🔒 安全策略
请参阅 [docs/SECURITY.md](docs/SECURITY.md) 获取完整的纵深防御文档（6 层）、生产环境部署清单以及漏洞报告流程。
## 🛠️ 故障排除
请参阅 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) 获取以下问题的解决方案：
- Wazuh dashboard 版本不匹配
- `/alerts` 返回 404（indexer 设置）
- `/rules` 返回 500（Wazuh 4.14.x bug + indexer 回退）
- Indexer 401 身份验证
- Filebeat 连接问题
- MCP 服务器连通性
- 速率限制和确认门控行为
- 完整的网络架构图
## 📄 许可证
MIT © [Sbharadwaj05](https://github.com/Sbharadwaj05)
需要自定义检测规则、SIEM 调优或构建 MCP 服务器？请访问 Topmate：https://topmate.io/subhash_bharadwaj 或私信获取 Fiverr 交易链接。