内容
<p align="center">
<img src="docs/assets/wazuh-mcp-banner.jpg" alt="wazuh-mcp banner">
</p>
<h1 align="center">wazuh-mcp</h1>
<p align="center">
<strong>一个允许AI客户端查询Wazuh SIEM/XDR的MCP服务器：警报、代理、漏洞、规则等，均为只读。</strong>
</p>
<p align="center">
<img src="https://img.shields.io/npm/v/wazuh-mcp?style=for-the-badge&logo=npm&logoColor=white&label=npm" alt="npm version">
<img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/wazuh-mcp/ci.yml?branch=main&style=for-the-badge&label=CI&logo=githubactions&logoColor=white" alt="CI status">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License">
<img src="https://img.shields.io/badge/MCP-server-7c3aed?style=for-the-badge" alt="MCP server">
<img src="https://img.shields.io/badge/Wazuh-SIEM%2FXDR-3385ff?style=for-the-badge" alt="Wazuh SIEM/XDR">
<img src="https://img.shields.io/badge/MITRE_ATT%26CK-mapped-0f766e?style=for-the-badge" alt="MITRE ATT&CK mapped">
</p>
<p align="center">
<strong>官方网站：</strong> <a href="https://lidless.dev/wazuh-mcp">lidless.dev/wazuh-mcp</a>
</p>
wazuh-mcp 是 [Model Context Protocol](https://modelcontextprotocol.io/) （MCP）服务器，适用于 [Wazuh](https://wazuh.com/) SIEM/XDR平台。它将Wazuh管理器和Wazuh索引器暴露为MCP工具，允许Claude、Claude Code或任何兼容MCP的客户端以纯语言查询警报、排查代理和提取漏洞库存。该服务器设计为只读且优先考虑安全性：默认启用TLS验证，除非您选择，否则隐藏敏感字段（代理IP、完整日志、文件哈希、命令行），并且将攻击者控制的SIEM文本包裹在不受信任的数据标记中，以防止调用模型的提示注入。
## 它能做什么
wazuh-mcp 将Wazuh SIEM/XDR部署转换为一组MCP工具，AI代理可以调用这些工具。指向MCP客户端的服务器，给予Wazuh管理器和（可选）Wazuh索引器的凭证，模型可以列出活动和断开连接的代理，检索和全文搜索安全警报，提取按CVE或严重程度分类的漏洞库存，检查检测规则和解码器，审查SCA（安全配置评估）结果，遍历系统库存（操作系统、软件包、进程、端口、网络、热补丁），读取文件完整性监控和rootcheck发现，获取管理器日志和配置，并运行连接诊断。它附带了28种工具、3种资源和3种引导提示，适用于stdio。服务器只从Wazuh读取：它执行的唯一写入是针对管理器的JWT身份验证和针对索引器的 `_search` 查询。
## 快速入门
使用 `npx` 直接从npm运行，无需克隆或构建：
```json
{
"mcpServers": {
"wazuh": {
"command": "npx",
"args": ["-y", "wazuh-mcp"],
"env": {
"WAZUH_URL": "https://your-wazuh-manager:55000",
"WAZUH_USERNAME": "wazuh-wui",
"WAZUH_PASSWORD": "your-password",
"WAZUH_INDEXER_URL": "https://your-wazuh-indexer:9200",
"WAZUH_INDEXER_USERNAME": "admin",
"WAZUH_INDEXER_PASSWORD": "your-indexer-password"
}
}
}
}
```
将其放入MCP客户端的服务器配置中（请参阅[用法](#usage)以获取每个客户端的确切文件），重启客户端，并询问类似 *"列出活动Wazuh代理"* 或 *"搜索过去24小时内 brute force 警报"*。索引器设置是可选的：如果没有这些设置，代理、规则、解码器和版本工具仍然有效，而警报和漏洞工具返回配置消息而不是失败。
更喜欢全局安装？
```bash
npm install -g wazuh-mcp
# 然后使用 "command": "wazuh-mcp" 代替上面的npx调用
```
## 功能
- **28种MCP工具** - 代理、警报、漏洞、规则、解码器、SCA、syscollector、FIM、rootcheck、组、管理器和诊断
- **3种MCP资源** - 代理、最近警报和规则摘要的预建视图
- **3种MCP提示** - 警报调查、代理健康检查和安全概述
- **设计为只读** - 唯一写入是JWT身份验证和索引器搜索；没有工具会更改Wazuh状态
- **默认安全** - 默认启用TLS验证，隐藏敏感字段，除非选择，否则不受信任的SIEM内容被限制
- **JWT身份验证** - 过期时自动令牌管理与刷新
- **完全合规映射** - PCI-DSS，GDPR，HIPAA，NIST 800-53，MITRE ATT&CK
- **分页** - 所有列表端点支持limit/offset分页
- **类型安全** - 具有严格模式和Zod模式验证的完整TypeScript
## 先决条件
- Node.js 20+
<!-- content-guard: allow port-reference -->
- 一个运行中的Wazuh管理器，启用API访问（默认端口55000）
- Wazuh API凭证（用户名/密码）
- （可选）Wazuh索引器（OpenSearch）访问，用于警报查询
## 安装
上面的快速入门使用 `npx` 运行已发布的npm包，这是推荐的方法。要从源代码工作：
```bash
git clone https://github.com/lidless-labs/wazuh-mcp.git
cd wazuh-mcp
npm install
npm run build
```
## 配置
设置以下环境变量：
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `WAZUH_URL` | 是 | - | Wazuh API URL（例如，`https://192.0.2.2:55000`） |
| `WAZUH_USERNAME` | 是 | - | API用户名 |
| `WAZUH_PASSWORD` | 是 | - | API密码 |
| `WAZUH_VERIFY_SSL` | 否 | `true` | 默认验证SSL证书。设置为 `false`（也接受 `0`/`no`/`off`）以禁用对受信任的自签名实验室环境的验证。 |
| `WAZUH_TIMEOUT` | 否 | `30` | 请求超时（秒）。必须为正整数。 |
| `WAZUH_ALLOW_SENSITIVE_CONFIG` | 否 | `false` | `get_manager_config`的服务器端门控。当未设置/`false`时，即使工具的`include_sensitive_config`参数为`true`，敏感配置值也会始终被删减。设置为`true`（也接受`1`/`yes`/`on`）以允许在显式请求时取消删减。 |
| `WAZUH_MCP_MAX_RESPONSE_BYTES` | 否 | `250000` | MCP工具响应大小上限，超过时返回带有元数据的截断预览。 |
还支持替代变量名称 `WAZUH_BASE_URL` 和 `WAZUH_USER`。
### Wazuh索引器（OpenSearch）- 警报和漏洞所需
Wazuh 4.x 将警报和漏洞库存存储在Wazuh索引器（OpenSearch）中，而不是REST API中。要启用警报工具（`get_alerts`、`get_alert`、`search_alerts`）、漏洞工具（`list_vulnerabilities`、`search_vulnerabilities`）和 `wazuh://alerts/recent` 资源，请配置索引器连接：
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `WAZUH_INDEXER_URL` | 否 | - | Wazuh索引器URL（例如，`https://192.0.2.2:9200`） |
| `WAZUH_INDEXER_USERNAME` | 否 | `admin` | 索引器用户名 |
| `WAZUH_INDEXER_PASSWORD` | 是，当设置了`WAZUH_INDEXER_URL` | - | 索引器密码。如果设置了`WAZUH_INDEXER_URL`，则服务器在启动时快速失败。 |
| `WAZUH_INDEXER_VERIFY_SSL` | 否 | `true` | 默认验证SSL证书。设置为 `false`（也接受 `0`/`no`/`off`）以禁用对受信任的自签名实验室环境的验证。 |
| `WAZUH_INDEXER_TIMEOUT` | 否 | `30` | 索引器请求超时（秒）。必须为正整数。 |
如果未设置 `WAZUH_INDEXER_URL`，则警报和漏洞工具将返回有用的配置消息。所有其他工具（代理、规则、解码器、版本）在没有索引器的情况下仍然有效。
默认启用SSL证书验证（默认安全）。当显式将任一SSL验证设置设为 `false` 时，服务器在启动时打印一条警告消息到stderr。仅为已配置的Wazuh客户端禁用TLS验证。
### 敏感输出默认值
多个工具默认返回最小化输出，以避免暴露原始日志、IP、命令行、哈希或原始事件有效载荷，除非请求：
| 工具 | 默认隐藏 | 选择加入字段 |
| --- | --- | --- |
| `list_agents`、`get_agent`、`get_group_agents` | 代理IP详细信息 | `include_ip: true` |
| `get_alerts`、`search_alerts` | `full_log` | `include_full_log: true` |
| `get_alert` | `full_log`、原始 `data` | `include_full_log: true`、`include_raw_data: true` |
| `list_vulnerabilities`、`search_vulnerabilities` | 漏洞描述 | `include_description: true` |
| `get_agent_processes` | 进程命令行和参数 | `include_command: true` |
| `get_fim_files` | MD5和SHA-256哈希 | `include_hashes: true` |
| `get_manager_logs` | 完整日志描述 | `include_description: true` |
| `get_manager_config` | 类似机密的配置值 | `include_sensitive_config: true`（仅在服务器端标志`WAZUH_ALLOW_SENSITIVE_CONFIG`启用时受尊敬；否则始终删减） |
### 不受信任的SIEM内容
警报和日志字段源自受监控的终端：任何可以写入监控主机日志行的人（失败的SSH登录、Web请求路径、syslog消息）都控制着`full_log`、警报`rule_description`、原始事件`data`和管理器日志描述中的文本。为了防止调用代理的提示注入，服务器用`<untrusted_siem_data>...</untrusted_siem_data>`标记包装这些值，在受影响的响应中包含`output.untrusted_data_note`警告，并在工具描述中说明内容是受攻击者影响的数据，而不是指令。
### 输入验证
在向Wazuh发送请求之前验证工具输入。分页是有限的，搜索文本长度有限，每个工具的排序字段是枚举的，基于路径的标识符（如代理ID、警报ID、组ID和SCA策略ID）拒绝不支持的字符。
分页工具响应包含具有 `total`、`limit`、`offset` 和 `has_more` 字段的 `pagination` 对象，同时保留现有的顶级 `total`、`limit` 和 `offset` 字段。
工具响应由 `WAZUH_MCP_MAX_RESPONSE_BYTES` 限制。超大响应返回具有字节数和预览的有效JSON。
暂时管理器 `GET` 请求和索引器搜索/就绪请求在出现 `429`、`502`、`503`、`504` 和常见的瞬时网络重置或超时错误时，会进行简短重试。
## 用法
顶部的快速入门 `mcpServers` 块适用于大多数客户端。下面是每个客户端的确切文件位置或CLI命令。
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"wazuh": {
"command": "npx",
"args": ["-y", "wazuh-mcp"],
"env": {
"WAZUH_URL": "https://your-wazuh-manager:55000",
"WAZUH_USERNAME": "wazuh-wui",
"WAZUH_PASSWORD": "your-password",
"WAZUH_INDEXER_URL": "https://your-wazuh-indexer:9200",
"WAZUH_INDEXER_USERNAME": "admin",
"WAZUH_INDEXER_PASSWORD": "your-indexer-password"
}
}
}
}
```
### Claude Code
```bash
claude mcp add wazuh \
--env WAZUH_URL=https://your-wazuh-manager:55000 \
--env WAZUH_USERNAME=wazuh-wui \
--env WAZUH_PASSWORD=your-password \
--env WAZUH_INDEXER_URL=https://your-wazuh-indexer:9200 \
--env WAZUH_INDEXER_USERNAME=admin \
--env WAZUH_INDEXER_PASSWORD=your-indexer-password \
-- npx -y wazuh-mcp
```
添加 `--scope user` 以使其在任何目录中都可用，而不仅仅是当前项目。
### Codex CLI
[Codex CLI](https://github.com/openai/codex) 通过 `codex mcp add` 注册MCP服务器：
```bash
codex mcp add wazuh \
--env WAZUH_URL=https://your-wazuh-manager:55000 \
--env WAZUH_USERNAME=wazuh-wui \
--env WAZUH_PASSWORD=your-password \
--env WAZUH_INDEXER_URL=https://your-wazuh-indexer:9200 \
--env WAZUH_INDEXER_USERNAME=admin \
--env WAZUH_INDEXER_PASSWORD=your-indexer-password \
-- npx -y wazuh-mcp
```
Codex将条目写入 `~/.codex/config.toml` 下的 `[mcp_servers.wazuh]`。通过 `codex mcp list` 验证。
### OpenClaw
使用npm包：
```bash
openclaw mcp set wazuh '{
"command": "npx",
"args": ["-y", "wazuh-mcp"],
"env": {
"WAZUH_URL": "https://your-wazuh-manager:55000",
"WAZUH_USERNAME": "wazuh-wui",
"WAZUH_PASSWORD": "your-password",
"WAZUH_INDEXER_URL": "https://your-wazuh-indexer:9200",
"WAZUH_INDEXER_USERNAME": "admin",
"WAZUH_INDEXER_PASSWORD": "your-indexer-password"
}
}'
```
或者，当运行源代码检出时，将 `command`/`args` 指向已构建的 `dist/index.js`：
```bash
openclaw mcp set wazuh '{
"command": "node",
"args": ["/absolute/path/to/wazuh-mcp/dist/index.js"],
"env": {
"WAZUH_URL": "https://your-wazuh-manager:55000",
"WAZUH_USERNAME": "wazuh-wui",
"WAZUH_PASSWORD": "your-password",
"WAZUH_INDEXER_URL": "https://your-wazuh-indexer:9200",
"WAZUH_INDEXER_USERNAME": "admin",
"WAZUH_INDEXER_PASSWORD": "your-indexer-password"
}
}'
```
然后重启网关以应用新的服务器：
```bash
systemctl --user restart openclaw-gateway
openclaw mcp list # 确认 "wazuh" 已注册
```
### Hermes 代理
[Hermes 代理](https://github.com/NousResearch/hermes-agent) 从 `~/.hermes/config.yaml` 读取MCP配置，在 `mcp_servers` 键下添加条目：
```yaml
mcp_servers:
wazuh:
command: "npx"
args: ["-y", "wazuh-mcp"]
env:
WAZUH_URL: "https://your-wazuh-manager:55000"
WAZUH_USERNAME: "wazuh-wui"
WAZUH_PASSWORD: "your-password"
WAZUH_INDEXER_URL: "https://your-wazuh-indexer:9200"
WAZUH_INDEXER_USERNAME: "admin"
WAZUH_INDEXER_PASSWORD: "your-indexer-password"
```
然后在Hermes会话中使用 `/reload-mcp` 重新加载MCP。
### 独立
```bash
export WAZUH_URL=https://your-wazuh-manager:55000
export WAZUH_USERNAME=wazuh-wui
export WAZUH_PASSWORD=your-password
npx -y wazuh-mcp
```
### 开发
```bash
npm run dev # 监视模式，带tsx
npm run lint # 类型检查
npm test # 运行测试
```
## MCP 工具
所有28种工具均为只读。
### 代理工具
| 工具 | 描述 |
| --- | --- |
| `list_agents` | 列出所有代理，可选状态过滤（活动、断开、未连接、待处理） |
| `get_agent` | 获取特定代理的详细信息 |
| `get_agent_stats` | 获取CPU、内存和磁盘统计信息 |
### 警报工具
| 工具 | 描述 |
| --- | --- |
| `get_alerts` | 检索最近的警报，可按时间范围、级别、代理、规则和文本搜索进行筛选 |
| `get_alert` | 通过ID检索单个警报 |
| `search_alerts` | 对警报进行全文搜索，可选时间范围筛选 |
### 漏洞工具
| 工具 | 描述 |
| --- | --- |
| `list_vulnerabilities` | 列出漏洞库存，可选CVE、代理、严重程度和软件包筛选 |
| `search_vulnerabilities` | 按CVE、软件包、代理或描述搜索漏洞库存 |
### 规则工具
| 工具 | 描述 |
| --- | --- |
| `list_rules` | 列出检测规则，支持按级别和组筛选 |
| `get_rule` | 获取完整规则详情，包括合规映射 |
| `search_rules` | 按描述文本搜索规则 |
### SCA 工具（安全配置评估）
| 工具 | 描述 |
| --- | --- |
| `get_sca_policies` | 列出代理的SCA策略和分数（CIS基准等） |
| `get_sca_checks` | 获取单个检查结果，并附带补救步骤和合规映射 |
### Syscollector 工具（系统库存）
| 工具 | 描述 |
| --- | --- |
| `get_agent_os` | 获取OS信息（名称、版本、架构、主机名） |
| `get_agent_packages` | 列出已安装的软件包及其版本 |
| `get_agent_processes` | 列出正在运行的进程及其PID和命令行 |
| `get_agent_ports` | 列出开放的网络端口及其关联的进程 |
| `get_agent_network` | 列出网络接口和IP地址 |
| `get_agent_hotfixes` | 列出已安装的Windows热补丁/补丁 |
### FIM 和 Rootcheck 工具
| 工具 | 描述 |
| --- | --- |
| `get_fim_files` | 获取文件完整性监控结果（文件、注册表键、哈希） |
| `get_rootcheck` | 获取rootkit检测扫描结果 |
### 管理器工具
| 工具 | 描述 |
| --- | --- |
| `get_manager_logs` | 获取Wazuh管理器日志，按级别和模块筛选 |
| `get_manager_config` | 获取活动管理器配置，按章节获取，默认隐藏机密值 |
### 组工具
| 工具 | 描述 |
| --- | --- |
| `list_groups` | 列出所有代理组 |
| `get_group_agents` | 列出特定组中的代理 |
### 其他工具
| 工具 | 描述 |
| --- | --- |
| `list_decoders` | 列出日志解码器，可按名称筛选 |
| `get_wazuh_version` | 获取Wazuh管理器版本和API信息 |
| `diagnose_wazuh_connection` | 检查净化配置、URL/TLS设置、管理器身份验证/版本和索引器就绪状态 |
## MCP 资源
| 资源URI | 描述 |
| --- | --- |
| `wazuh://agents` | 所有注册代理及其状态 |
| `wazuh://alerts/recent` | 最近25条安全警报 |
| `wazuh://rules/summary` | 按严重性排序的检测规则 |
## MCP 提示
| 提示 | 描述 |
| --- | --- |
| `investigate-alert` | 逐步警报调查，附带MITRE映射和补救 |
| `agent-health-check` | 全面的代理健康评估（状态、资源、警报） |
| `security-overview` | 完整的环境安全摘要，附带合规覆盖 |
## 示例
### 列出活跃代理
```
使用 list_agents 且状态为 "active" 来查看所有已连接的代理。
```
### 调查暴力破解尝试
```
搜索包含 "brute force" 的警报，并调查排名最高的警报，
包括 MITRE ATT&CK 技术和缓解措施。
```
### 检查代理健康状况
```
对代理 001 运行健康检查 - 检查其连接状态、
资源使用情况和最近的任何关键警报。
```
### 查找高严重性规则
```
列出所有级别为 12 或更高的规则，以查看关键检测规则
及其合规框架映射。
```
## 为什么不使用 Wazuh 仪表盘或原始 API？
- **Wazuh 仪表盘** 是为人工通过类似 Kibana 的视图点击而设计的。 它非常适合 SOC 分析师在屏幕前使用，但 AI 代理无法驱动它，而且它不能将自然语言问题转换为正确的安全管理和索引查询。 wazuh-mcp 为模型提供了键入的工具。
- **原始 Wazuh REST API + 索引器 `_search`** 可以直接调用，但随后每个代理都必须学习 JWT 身份验证、安全管理器与索引器的区别（Wazuh 4.x 中的警报和漏洞存在于索引器中）、分页形状以及哪些字段是敏感的。 wazuh-mcp 封装了所有这些，验证输入，限制响应大小，并清理错误，以免凭证泄露回模型。
- **通用 "运行任何 HTTP 请求" 工具** 从技术上讲可以访问 Wazuh，但它会将您的凭证交给模型，没有输入验证，没有只读保证，也没有 IP、哈希或完整日志的编辑。 该服务器默认情况下是只读的，并尽量减少敏感输出。
- **编写自己的 Wazuh MCP 代理** 是合理的，如果您想 fork 它，这里的源代码是 MIT 许可的。 这个代理已经处理了身份验证刷新、索引器回退消息、非受信任内容分隔、瞬时错误重试和 28 个已审查的工具。
## wazuh-mcp 不是什么
- **不是写入路径。** 没有工具会修改 Wazuh 状态。 它无法重启代理、编辑规则、确认警报或更改配置。 唯一写入的是 JWT 身份验证和索引器 `_search` 查询。
- **不是 Wazuh 仪表盘或 SIEM 的替代品。** 它是为 AI 客户端提供的查询接口，而不是分析师 UI、数据存储或警报引擎。
- **不是托管服务。** 它作为客户端旁边的 stdio MCP 服务器本地运行。 您的 Wazuh 凭证保留在您的机器上和客户端的配置文件中。
- **不能保证防止提示词注入。** 它分隔受攻击者影响的 SIEM 内容并警告模型，这降低了风险但不能消除风险。 将工具输出视为数据而非指令。
- **不能绕过 Wazuh 访问控制。** 它使用您提供的凭证，并且只能看到该帐户可以查看的内容。
## 文档和链接
- **网站：** [lidless.dev/wazuh-mcp](https://lidless.dev/wazuh-mcp)
- **npm：** [`wazuh-mcp`](https://www.npmjs.com/package/wazuh-mcp)
- **问题：** [github.com/lidless-labs/wazuh-mcp/issues](https://github.com/lidless-labs/wazuh-mcp/issues)
- **变更日志：** [CHANGELOG.md](CHANGELOG.md)
- **安全策略：** [SECURITY.md](SECURITY.md)
- **贡献：** [CONTRIBUTING.md](CONTRIBUTING.md)
## 测试
```bash
npm test # 运行所有测试
npm run typecheck # 类型检查 TypeScript
npm audit --omit=dev # 审核生产依赖项
npm run pack:check # 验证包内容
npm run test:watch # 监视模式
```
测试使用模拟的 Wazuh API 响应 - 不需要实时 Wazuh 实例。
## 项目结构
```
wazuh-mcp/
├── src/
│ ├── index.ts # MCP 服务器入口点
│ ├── config.ts # 环境配置
│ ├── client.ts # Wazuh REST API 客户端（JWT 身份验证）
│ ├── indexer-client.ts # Wazuh 索引器（OpenSearch）客户端
│ ├── types.ts # TypeScript 类型定义
│ ├── resources.ts # MCP 资源处理程序
│ ├── prompts.ts # MCP 提示模板
│ └── tools/
│ ├── agents.ts # 代理管理工具
│ ├── alerts.ts # 警报查询工具
│ ├── rules.ts # 规则查询工具
│ ├── decoders.ts # 解码器列表工具
│ ├── version.ts # 版本信息工具
│ ├── sca.ts # 安全配置评估
│ ├── syscollector.ts # 系统库存（操作系统、包、端口等）
│ ├── syscheck.ts # 文件完整性监控
│ ├── rootcheck.ts # 木马检测
│ ├── manager.ts # 安全管理器日志和配置
│ └── groups.ts # 代理组管理
├── tests/
│ ├── client.test.ts # API 客户端单元测试
│ └── tools.test.ts # 工具处理程序单元测试
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── vitest.config.ts
```
## 许可证
MIT. 请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器