Wazuh MCP Server

---

概述

• 55 个工具，分属 8 个工具集：告警、Agent、漏洞、威胁分析、合规（PCI-DSS、HIPAA、SOX、GDPR、NIST、ISO 27001:2022）、管理器／集群健康状况，以及支持验证和回滚的主动响应。另有 5 个引导式提示词、6 个资源和 3 个资源模板。
• 默认只读。 14 个会更改状态的工具需要 wazuh:write 范围，绝不会隐式授予该范围。
• MCP 传输： /mcp 上的 Streamable HTTP。提供协议修订版本 2026-07-28（无状态请求），并支持 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05 版本的 initialize 握手。旧版 HTTP+SSE 端点 /sse 返回 410 Gone。
• 身份验证： 使用 API 密钥签发的 Bearer 令牌；OAuth 2.0（授权码 + PKCE），支持使用 API 密钥登录，或通过 OpenID Connect 提供方（Entra ID、Google Workspace、Okta、Keycloak）登录；本地开发也可不启用身份验证。
• 部署： Docker Compose 或已发布的多架构镜像；可选 Redis，用于多实例会话；可选多集群路由。
• 本地模型： vLLM + Open WebUI 技术栈（compose.local-llm.yml），并为小型模型提供工具集筛选。唯一会调用 Wazuh 部署之外服务的工具是可选的 search_external_context（You.com），可单独禁用。

支持的 Wazuh 版本：4.8.0 至 4.14.7。告警、漏洞和基于告警的合规工具需要 Wazuh Indexer。请参阅 WAZUH_COMPATIBILITY.md。

快速开始

需要安装 Docker（含 Compose v2），并拥有 Wazuh Manager API 用户。

git clone https://github.com/gensecaihq/Wazuh-MCP-Server.git
cd Wazuh-MCP-Server
cp .env.example .env

在 .env 中设置 Wazuh 连接信息：

WAZUH_HOST=your-wazuh-manager
WAZUH_USER=your-api-user
WAZUH_PASS=your-api-password

# Needed for alert, vulnerability and alert-backed compliance tools
WAZUH_INDEXER_HOST=your-wazuh-indexer
WAZUH_INDEXER_USER=your-indexer-user
WAZUH_INDEXER_PASS=your-indexer-password

系统会验证 Manager 的 TLS 证书。标准 Wazuh 安装使用的自签名 API 证书无法通过验证，因此请为你的主机重新签发证书并设置 WAZUH_CA_BUNDLE；或者，首次测试时添加 WAZUH_ALLOW_SELF_SIGNED=true（不进行验证即可连接；启动时会记录日志）。详情：Manager TLS。

生成签名密钥和 API 密钥。compose.yml 会以 ENVIRONMENT=production 运行服务，如果缺少 AUTH_SECRET_KEY，服务将拒绝启动：

echo "AUTH_SECRET_KEY=$(openssl rand -hex 32)" >> .env
echo "MCP_API_KEY=wazuh_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')" >> .env

启动服务并检查：

docker compose up -d
curl http://localhost:3000/health     # liveness
curl http://localhost:3000/ready      # checks Manager/Indexer reachability

使用 API 密钥换取 bearer 令牌（有效期为 TOKEN_LIFETIME_HOURS，默认为 24）：

curl -s -X POST http://localhost:3000/auth/token -H 'Content-Type: application/json' \
  -d "{\"api_key\": \"$(grep ^MCP_API_KEY= .env | cut -d= -f2)\"}"

该密钥为只读密钥。若要启用主动响应工具，请在 .env 中添加 MCP_API_KEY_SCOPES="wazuh:read wazuh:write"，使用 docker compose up -d 重建容器（restart 会保留旧环境变量），然后签发新令牌。

Compose 仅在 127.0.0.1 上发布端口。服务使用普通 HTTP；对外开放前，请在其前方部署一个终止 TLS 的反向代理（设置 MCP_BIND 可更改主机绑定地址）。

python3 deploy.py（Windows 上使用 deploy.bat）会执行相同的步骤，并在缺少 AUTH_SECRET_KEY 和 MCP_API_KEY 时生成它们。

预构建镜像

多架构镜像（amd64、arm64）已发布到 GitHub Container Registry，无需登录即可拉取：

docker pull ghcr.io/gensecaihq/wazuh-mcp-server:latest   # tracks main
docker pull ghcr.io/gensecaihq/wazuh-mcp-server:5.0.0    # latest tagged release

latest 基于 main 构建，可能包含 更新日志中 Unreleased 下列出的更改。发布镜像的标签为 5.0.0、5.0 和 v5.0.0（4.3.0 及更早版本没有 v 前缀标签）。从 4.x 升级：请先阅读 UPGRADING.md。

docker run -d --name wazuh-mcp-server --env-file .env -e MCP_HOST=0.0.0.0 -e ENVIRONMENT=production \
  -p 127.0.0.1:3000:3000 ghcr.io/gensecaihq/wazuh-mcp-server:latest

容器内必须设置 MCP_HOST=0.0.0.0，因为 .env.example 为裸机安装设置了 MCP_HOST=127.0.0.1。-e 的优先级高于 --env-file，因此即使你的 .env 设置了其他值，ENVIRONMENT=production 仍会生效。

---

连接客户端

所有客户端均使用 Streamable HTTP 端点 https://<your-host>/mcp。

客户端	认证模式	认证方式
Claude 自定义连接器（claude.ai、Claude Desktop）	oauth	使用 PKCE 的 OAuth 授权码流程。服务预先注册了一个公共客户端 claude-desktop，用于 Claude 的回调 URL。用户可在服务的 /oauth/authorize 页面使用 wazuh_ API 密钥登录（授权范围不会超过该密钥的范围）；若设置了 OAUTH_IDP_ISSUER，也可在你的 OpenID Connect 提供方登录。
Open WebUI、LibreChat、脚本及其他 MCP 客户端	bearer（默认）	使用来自 POST /auth/token 的令牌，通过 Authorization: Bearer <token> 进行认证。

在 OAuth 模式下，将 OAUTH_ISSUER_URL 设置为服务的公开 HTTPS URL（否则会根据每个请求推导；在代理后方时，该地址可能不是公开 URL）。除非设置 OAUTH_ENABLE_DCR=true，否则动态客户端注册（/oauth/register）处于关闭状态，且不能与 OAUTH_IDP_ISSUER 同时使用。

指南：Claude 集成 · 本地大模型

---

本地大模型

服务不会调用模型，只会执行工具。若要让 SIEM 数据保留在本地环境中，可将其与本地模型搭配使用：

cat >> .env <<EOF
VLLM_API_KEY=$(openssl rand -hex 32)
WEBUI_SECRET_KEY=$(openssl rand -hex 32)
EOF
docker compose -f compose.yml -f compose.local-llm.yml up -d

这会添加 vLLM（默认模型为 Qwen3.6-35B-A3B FP8，单张 NVIDIA GPU 约需 42 GB 显存；不会在主机端口上发布）和 Open WebUI，后者运行在 127.0.0.1:8080。在 Open WebUI 的管理员设置中，添加一个 MCP（Streamable HTTP）工具服务，地址为 http://wazuh-main-server:3000/mcp，并提供 bearer 令牌。

对于较小的模型，可通过 WAZUH_TOOLSETS / WAZUH_DISABLED_TOOLS 减少开放的工具数量，并在部署前使用 evals/tool_selection.py 检查工具选择（针对任意 OpenAI 兼容端点运行 25 个 SOC 场景，其中包括两个提示词注入场景；不会执行任何工具）。模型配置、Ollama 和 LiteLLM 的相关内容请参阅本地大模型指南。

---

工具

共有 55 个工具，按工具集分组，可通过 WAZUH_TOOLSETS（逗号分隔；默认全部启用）启用。R = wazuh:read，W = wazuh:write。

工具集	数量	工具
alerts	5 R	get_wazuh_alerts、get_wazuh_alert_summary、get_alerts_aggregated、analyze_alert_patterns、search_security_events
agents	6 R	get_wazuh_agents、get_wazuh_running_agents、check_agent_health、get_agent_processes、get_agent_ports、get_agent_configuration
vulnerabilities	3 R	get_wazuh_vulnerabilities、get_wazuh_critical_vulnerabilities、get_wazuh_vulnerability_summary
analysis	5 R	analyze_security_threat、check_ioc_reputation、perform_risk_assessment、get_top_security_threats、generate_security_report
web_search	1 R	search_external_context — You.com 网页搜索；除非设置了 YDC_API_KEY，否则会返回“未启用”结果
compliance	6 R	run_compliance_check（PCI-DSS、HIPAA、SOX、GDPR、NIST、ISO27001）、get_iso27001_dashboard、get_iso27001_control_detail、get_iso27001_gap_analysis、get_iso27001_alerts、get_sca_policy_checks
system	10 R	get_wazuh_statistics、get_wazuh_weekly_stats、get_wazuh_cluster_health、get_wazuh_cluster_nodes、get_wazuh_rules_summary、get_wazuh_remoted_stats、get_wazuh_log_collector_stats、search_wazuh_manager_logs、get_wazuh_manager_error_logs、validate_wazuh_connection
response — 隔离	9 W	wazuh_block_ip、wazuh_isolate_host、wazuh_kill_process、wazuh_disable_user、wazuh_quarantine_file、wazuh_firewall_drop、wazuh_host_deny、wazuh_active_response、wazuh_restart
response — 回滚	5 W	wazuh_unisolate_host、wazuh_enable_user、wazuh_restore_file、wazuh_firewall_allow、wazuh_host_allow
response — 验证	5 R	wazuh_check_blocked_ip、wazuh_check_agent_isolation、wazuh_check_process、wazuh_check_user_status、wazuh_check_file_quarantine

• 总计：41 个只读工具、14 个写入工具。不含 wazuh:write 的令牌在 tools/list 中看不到写入工具。
• 在多集群模式下，会增加第 56 个工具 list_wazuh_clusters（system，只读），且每个工具都接受可选的 cluster_id。
• WAZUH_DISABLED_TOOLS 可隐藏单个工具。隐藏的工具会从 tools/list 中移除，并且在调用 tools/call 时会被拒绝；未知的工具集或工具名称会导致服务器在启动时停止。
• 每个工具都带有根据其作用范围生成的 MCP 注释：只读工具为 readOnlyHint: true；隔离工具为 destructiveHint: true；回滚工具为 destructiveHint: false；只有 search_external_context 的 openWorldHint: true。
• 输入架构是封闭的（additionalProperties: false）；未声明的参数会被拒绝。
• 时间戳筛选条件接受 ISO 8601 或 OpenSearch 日期数学表达式（now-24h）。
• 提示词：security_investigation、threat_hunt、compliance_audit、vulnerability_assessment、iso27001_assessment。

各工具参数：API 文档。

主动响应行为

• 结果会报告 execution_status: "dispatched"：这表示 Wazuh 确认命令已发送给 Agent，而非确认命令已执行。请使用对应的 wazuh_check_* 工具确认效果。
• 封禁会永久生效，直到解除。对于通过 API 触发的命令，Wazuh 会忽略超时，因此会拒绝正数的 duration。
• wazuh_firewall_allow 和 wazuh_host_allow 需要由操作员部署撤销命令（WAZUH_AR_FIREWALL_UNDO_COMMAND、WAZUH_AR_HOSTDENY_UNDO_COMMAND）；若未部署，则会拒绝执行。

---

安全模型

控制措施	行为
权限范围（RBAC）	每个工具都需要 wazuh:read 或 wazuh:write。不含权限范围声明的令牌为只读。除非 MCP_API_KEY_SCOPES 包含 wazuh:write，否则 MCP_API_KEY 为只读。使用 AUTH_MODE=none 时，除非设置 AUTHLESS_ALLOW_WRITE=true，否则会禁用写入工具。
Bearer 令牌	JWT 使用 AUTH_SECRET_KEY 签名，必须包含 exp，并绑定到签发它们所用的 API 密钥：撤销或轮换密钥会使其令牌失效。刷新令牌不能用作访问令牌。
OAuth	授权码流程强制使用 S256 PKCE，授权码仅可使用一次，并支持刷新令牌轮换、重放检测和撤销。用户可使用 wazuh_ API 密钥登录（授权范围受限于该密钥的权限范围，且密钥撤销后其令牌也会失效），也可通过 OpenID Connect 提供商登录（验证 ID 令牌签名、颁发者、受众、有效期和 nonce；支持租户、域名和用户允许列表，以及组到权限范围的映射），因此权限范围、速率限制和审计记录均按用户区分。
操作防护措施	IP 封禁工具会拒绝环回地址、Manager 的地址（当 WAZUH_HOST 为 IP 时）以及 WAZUH_PROTECTED_IPS 中的所有地址；通用主动响应工具不会执行 IP 封禁、隔离、终止进程或禁用账户。针对 Agent 000（Manager）的操作和重启需要 WAZUH_ALLOW_MANAGER_AR=true；全群集封禁需要 WAZUH_ALLOW_FLEET_AR=true；隔离操作会拒绝系统目录和 Agent 目录。在生产环境中，写入工具需要设置 confirm=true（WAZUH_REQUIRE_ACTION_CONFIRMATION）。
Wazuh TLS	默认情况下，会根据系统证书库或 WAZUH_CA_BUNDLE 验证 Manager 和 Indexer 证书。禁用 Manager 验证（WAZUH_ALLOW_SELF_SIGNED=true）会在启动时记录日志，在生产环境中则会记为错误。
审计日志	每次通过权限范围和确认检查的写入工具调用，都会在执行前后记录日志（logger wazuh_mcp_server.audit），包含主体、会话、参数和结果。
脱敏	所有响应格式的工具输出和服务器日志中，凭据和令牌都会经过脱敏。
输入验证	对 Agent ID、IP、路径和命令名称进行类型验证；Indexer 查询使用 Query DSL 构建，而非通过字符串插值生成。
速率限制	滑动窗口，默认每 60 s 允许 100 个请求（RATE_LIMIT_REQUESTS、RATE_LIMIT_WINDOW）：/mcp 和 / 按主体和客户端 IP 限制；其他端点按客户端 IP 限制，探测端点（/health、/ready、/metrics 及其 /healthz、/readyz、/live、/livez 别名）除外。身份验证失败的请求按客户端 IP 限制速率。通过代理运行时，请设置 TRUSTED_PROXIES。
资源限制	Wazuh 调用设有熔断器：连续失败 5 次后打开，60 s 后重试。超大的工具结果会被截断并附注说明（MAX_TOOL_RESPONSE_CHARS）。get_wazuh_alerts 和 search_security_events 的 limit 上限为 MAX_ALERTS_PER_QUERY（默认值为 1000）。内存会话存储的上限为 MAX_SESSIONS（1000）和 MAX_SESSIONS_PER_PRINCIPAL（100），存储的客户端元数据会被截断。
容器	以 UID 1000 运行；compose.yml 设置只读根文件系统、cap_drop: ALL 和 no-new-privileges。运行时镜像不包含 pip。

没有内置的 TLS 监听器；请在反向代理或负载均衡器处终止 TLS。请按照 SECURITY.md 中的说明报告漏洞。

---

配置

所有设置均为环境变量（通常通过 .env 设置）。大多数部署常用的变量：

变量	默认值	用途
WAZUH_HOST、WAZUH_USER、WAZUH_PASS	—	管理器 API 连接（必需）
WAZUH_PORT	55000	管理器 API 端口
WAZUH_CA_BUNDLE	—	用于验证管理器和索引器、替代系统证书库的 CA PEM；参见 管理器 TLS
WAZUH_ALLOW_SELF_SIGNED	false	设为 true 时连接管理器而不验证证书（启动时会记录）
WAZUH_INDEXER_HOST、WAZUH_INDEXER_USER、WAZUH_INDEXER_PASS	—	索引器连接；主机前缀为 http:// 时使用纯 HTTP
WAZUH_INDEXER_PORT	9200	索引器端口
ENVIRONMENT	development	production 要求使用强 AUTH_SECRET_KEY（除非 AUTH_MODE=none）
AUTH_MODE	bearer	bearer、oauth 或 none
AUTH_SECRET_KEY	非生产环境下每个进程生成一个	令牌签名密钥；所有实例都使用相同的值
MCP_API_KEY / API_KEYS	未设置时每个进程生成一个（仅在开发环境中打印）	单个 wazuh_ 密钥，或包含哈希密钥及各自作用域的 JSON 列表
MCP_API_KEY_SCOPES	wazuh:read	MCP_API_KEY 的空格分隔作用域
OAUTH_ISSUER_URL	根据请求派生	服务器的公开 HTTPS URL，用于 AUTH_MODE=oauth
OAUTH_IDP_ISSUER	—	用于 OAuth 登录的 OpenID Connect 提供方（需设置 OAUTH_IDP_CLIENT_ID）；未设置时使用 API 密钥登录
WAZUH_REQUIRE_ACTION_CONFIRMATION	生产环境为 true，否则为 false	写入工具要求 confirm=true
MCP_HOST、MCP_PORT	127.0.0.1（Docker 镜像中为 0.0.0.0）、3000	绑定地址和端口
ALLOWED_ORIGINS	https://claude.ai,http://localhost:3000	CORS 允许列表（完全匹配）
WAZUH_TOOLSETS、WAZUH_DISABLED_TOOLS	全部启用	限制公开的工具
REDIS_URL	—	多实例部署的共享会话存储
WAZUH_CLUSTERS_FILE	./config/clusters.json	多集群拓扑；未设置时使用单集群模式
RESPONSE_FORMAT	json	gcf 会以紧凑的 GCF 格式编码警报、事件和漏洞集合（无损；编码器不可用时回退到 JSON）
YDC_API_KEY	—	启用 search_external_context

完整参考，包括 OAuth TTL、速率限制、会话和主动响应设置： 配置指南。多集群设置： 多集群指南 和 config/clusters.json.example。

从源代码运行

python -m venv .venv && source .venv/bin/activate
pip install -e ".[redis,gcf]"      # extras are optional
set -a; . ./.env; set +a           # the server reads the environment, not .env
python -m wazuh_mcp_server

需要 Python 3.11 或更高版本。

---

HTTP 端点

端点	方法	描述
/mcp	POST、GET、DELETE	MCP Streamable HTTP
/	POST、GET	与 /mcp 相同的处理程序
/sse	GET、POST	返回 410 Gone；请使用 /mcp
/health	GET	存活检查；不检查依赖项
/ready	GET	就绪检查；管理器、索引器或内存余量检查失败时返回 503
/metrics	GET	Prometheus 指标
/auth/token	POST	将 API 密钥兑换为 bearer JWT
/.well-known/oauth-authorization-server	GET	OAuth 元数据（RFC 8414），仅限 AUTH_MODE=oauth
/.well-known/oauth-protected-resource	GET	受保护资源元数据（RFC 9728），仅限 AUTH_MODE=oauth
/oauth/authorize、/oauth/token、/oauth/revoke、/oauth/register、/oauth/callback	GET/POST	OAuth 端点，仅限 AUTH_MODE=oauth（/oauth/register 要求 OAUTH_ENABLE_DCR=true 且未设置 OAUTH_IDP_ISSUER；/oauth/callback 是 OpenID Connect 重定向 URI，需要设置 OAUTH_IDP_ISSUER）
/docs、/redoc、/openapi.json	GET	OpenAPI 文档

---

项目布局

src/wazuh_mcp_server/
├── server.py          # FastAPI app, MCP protocol handling, CORS/Origin checks, tool definitions and dispatch
├── toolsets.py        # Toolset membership, WAZUH_TOOLSETS resolution, tool annotations
├── auth.py            # API keys and bearer JWTs
├── oauth.py           # OAuth 2.0 authorization server (PKCE, API-key sign-in)
├── oidc.py            # OpenID Connect sign-in at an external identity provider
├── config.py          # Environment configuration and startup validation
├── security.py        # Rate limiting, request and input validation, log redaction
├── clusters.py        # Multi-cluster registry and Cross-Cluster Search routing
├── session_store.py   # In-memory and Redis session storage
├── resilience.py      # Circuit breakers, retries, graceful shutdown
├── monitoring.py      # Prometheus metrics, structured logging
├── gcf_format.py      # Optional GCF response encoding
└── api/
    ├── wazuh_client.py    # Wazuh Manager REST API client
    └── wazuh_indexer.py   # Wazuh Indexer (OpenSearch) client

---

文档

文档	内容
配置指南	所有环境变量、身份验证模式、RBAC
Claude 集成	连接 Claude 自定义连接器
本地大模型指南	vLLM、Open WebUI、Ollama、LiteLLM、工具选择评估
多集群	命名集群和跨集群搜索
运维	部署、监控、维护
高级功能	多实例部署、精简输出
故障排除	常见问题及解决方法
API 参考	各工具的参数
安全强化	安全强化指南
MCP 合规性	协议符合性说明
Wazuh 兼容性	支持的 Wazuh 版本
升级 · 更新日志 · 安全政策	发行说明和政策

相关项目：Wazuh Autopilot 基于此服务构建自动化 SOC 工作流。

---

贡献

请参阅 CONTRIBUTING.md。Bug、功能请求和问题请提交至 Issues，安全报告请通过私密的安全公告提交。

---

许可证

MIT

---

致谢

感谢所有贡献代码、评审、Bug 报告和设计反馈的朋友。另请参阅 ACKNOWLEDGMENTS.md。

代码与拉取请求

• @andrzej-piotrowski-pl — ISO 27001:2022 合规工具：附录 A 控制项映射、域评分、差距分析（#74）
• @blackwell-systems — 为记录工具提供可选的 GCF 响应编码（#102、#104）
• @lucascruzb — 通过滚动汇总整个周期的告警，是 get_alerts_aggregated 的基础（#79）
• @kanylbullen — 紧凑输出模式，以实现高效的 Token 响应（#65）
• @mouse-value-add — 可选的 You.com 网络搜索上下文（#85）
• @DrRSatzteil — 修复 tools/list 分页问题（#70）
• @SiM22 — 支持 MCP 2025-06-18，以兼容 Windsurf（#66）
• @aiunmukto — .env.example（#12）、早期 CI 工作流和 Glama 注册目录条目
• @Karibusan — 依赖项修复（#38）
• @lwsinclair — MseeP.ai 条目（#9）
• @markeclaudio — OpenID Connect 登录（#123）、主动响应防护措施（#124、#125）、会话存储限制（#126）、默认启用 Manager TLS 验证（#127）
• @MilkyWay88 和 @taylorwalton — 早期关于配置、日志记录和打包的拉取请求

Bug 报告和讨论 @cbassonbgroup, @cybersentinel-06, @daod-arshad, @mamema, @marcolinux46, @matveevandrey, @punkpeye, @tonyliu9189, @Uberkarhu, @bl4ck5w4n07, @gnix45, @hackdefendr, @melmasry1987, @Vasanth120v, @wqfh

基于并协同工作的项目

• Wazuh — 开源安全平台
• Model Context Protocol — 本服务实现的协议
• vLLM、Ollama 和 Open WebUI — 本地模型服务与聊天，用于本地大模型技术栈

---

贡献者

贡献者

Avatar	Username	Contributions
	@alokemajumder	💻 Code, 🐛 Issues, 🔀 PRs, 💬 Discussions
	@Karibusan	💻 Code, 🐛 Issues, 🔀 PRs
	@gensecai-dev	💻 Code, 🔀 PRs, 💬 Discussions
	@aiunmukto	💻 Code, 🔀 PRs
	@andrzej-piotrowski-pl	💻 Code, 🔀 PRs
	@blackwell-systems	💻 Code, 🔀 PRs
	@kanylbullen	💻 Code, 🔀 PRs
	@lucascruzb	💻 Code, 🔀 PRs
	@lwsinclair	💻 Code, 🔀 PRs
	@mouse-value-add	💻 Code, 🔀 PRs
	@SiM22	💻 Code, 🔀 PRs
	@DrRSatzteil	🔀 PRs
	@MilkyWay88	🔀 PRs
	@taylorwalton	🔀 PRs
	@cbassonbgroup	🐛 Issues
	@cybersentinel-06	🐛 Issues
	@daod-arshad	🐛 Issues
	@mamema	🐛 Issues
	@marcolinux46	🐛 Issues
	@matveevandrey	🐛 Issues
	@punkpeye	🐛 Issues
	@tonyliu9189	🐛 Issues
	@Uberkarhu	🐛 Issues
	@bl4ck5w4n07	💬 Discussions
	@gnix45	💬 Discussions
	@hackdefendr	💬 Discussions
	@melmasry1987	💬 Discussions
	@Vasanth120v	💬 Discussions
	@wqfh	💬 Discussions

Legend: 💻 Code · 🐛 Issues · 🔀 Pull Requests · 💬 Discussions

Auto-updated by GitHub Actions