Wazuh MCP Server
Sbharadwaj05/wazuh-mcp-server
Automação de operações de segurança Wazuh via Claude com 28 ferramentas nativas
Ver no GitHubMCP server que integra Wazuh SIEM/XDR com Claude e outras IA, oferecendo 28 ferramentas operacionais para consultas de segurança em linguagem natural. Conecta-se diretamente à API e Elasticsearch do Wazuh, sem Docker ou agentes adicionais, com suporte a 9 domínios de segurança incluindo alertas críticos, CVEs, MITRE ATT&CK e resposta a incidentes.
Instalação
npx convez-ai Sbharadwaj05/wazuh-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Investigação de alertas críticos e correlação com CVEs em linguagem natural
- Consultas cross-domain (MITRE ATT&CK, CIS compliance, FIM) através de um único prompt
- Automação de resposta a incidentes e triagem de alertas de segurança
- Auditoria de conformidade e análise de padrões de ataque com IA
Veredito

Ferramenta madura e bem-arquitetada para SOCs que usam Wazuh. Oferece segurança em profundidade (validação de entrada, rate limiting, auditoria, RBAC, sanitização de output), automação real de investigações e integração leve com Claude. Recomendado para equipes que precisam acelerar operações de segurança com IA, sem overhead de infraestrutura.
README
A tradução para o português deste README ainda está na fila.
🔐 Wazuh MCP Server
28 MCP tools. 9 domains. 100% operational on Wazuh 4.14.5. AI-powered security operations for Wazuh SIEM/XDR.
"Show me all critical alerts in the last 6 hours, cross-reference with MITRE ATT&CK, and check if any affected hosts have unpatched CVEs."
One prompt. Your AI assistant queries 7,514 alerts, checks 5,038 FIM records, scans 12 CVEs, cross-references 750 MITRE techniques, audits CIS compliance, and triggers incident response — all through your Wazuh infrastructure.
How It Works (30 seconds)
You already have Wazuh running somewhere. The MCP server is a local process that your AI client spawns as a child — just like a language server or linter.
Your Machine Your Wazuh Server
┌────────────────────┐ ┌──────────────────┐
│ Zed / Claude │ │ │
│ │ │ │ Wazuh API │
│ ▼ │ │ :55000 │
│ python -m │───────HTTPS──────▶│ │
│ wazuh_mcp.server │ │ Wazuh Indexer │
│ (child process) │───────HTTPS──────▶│ :9200 │
└────────────────────┘ └──────────────────┘
No Docker required. No containers. No agents to install. Just point it at your existing Wazuh and start asking questions in natural language.
🛡️ Security Features (Defense in Depth)
- Input validation — Shell metacharacter blocking, regex for agent IDs, IPs, CVEs, MITRE IDs
- Rate limiting — Token-bucket: 30/60s for read tools, 5/120s for destructive
- Output sanitization — Redacts AWS keys, JWT tokens, SSH keys, API keys, passwords from LLM-bound data
- Audit logging — Append-only JSONL trail for all destructive actions
- Confirmation gate — Two-step
confirm=True+ expiring token for active response tools - RBAC — 4 built-in roles:
viewer,analyst,admin,socwith hierarchical access - Dependabot + pip-audit + CodeQL — Automated dependency scanning on every push + weekly schedule
- Non-root Docker — Production container runs as unprivileged
wazuhmcpuser - TLS everywhere —
WAZUH_INSECURE=falsein production, Wazuh API + Indexer both over HTTPS - Prometheus metrics — 7 metrics exposed on
:9090/metricsfor SOC monitoring (latency, errors, rate limits) - OpenAPI 3.0 / Swagger UI — Interactive API docs at
/docs, raw spec at/openapi.json
📊 Architecture
┌──────────────────────────┐ ┌──────────────────────────┐
│ 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 │
└──────────────────────────┘
The MCP server talks to both the Wazuh REST API (port 55000, for management) and the Wazuh Indexer (port 9200, for alerts/vulnerabilities). In Wazuh 4.x/5.x, alerts and vulnerabilities are indexer-only — not available via the REST API. The server's IndexerClient handles this transparently.
📊 What This Does
| Workflow | Example Prompt | Tools Used |
|---|---|---|
| Alert Triage | "Summarize today's alerts by severity and MITRE technique" | list_alerts, alert_summary, get_alert |
| Threat Hunting | "Search for IOC 10.0.0.50 across all events and FIM records" | search_events, query_fim, search_mitre |
| Compliance Audit | "Show me all agents failing CIS benchmark checks" | sca_status, sca_checks, compliance_report |
| Rules Coverage | "What's my NIST 800-53 detection coverage?" | rules_coverage_map, rules_info |
| Vulnerability Mgmt | "Which systems have critical unpatched CVEs?" | query_vulnerabilities, vulnerability_heatmap |
| Incident Timeline | "Reconstruct what happened around alert #45821" | incident_timeline, search_events, query_fim |
| Fleet Management | "List disconnected agents and their groups" | list_agents, get_agent, agent_health, list_groups |
| Threat Intel | "Show me the CDB blocklists and MITRE techniques for T1059" | list_cdb_lists, get_cdb_list, search_mitre |
| Incident Response ⚠️ | "Block IP 203.0.113.55 on all web servers" | run_active_response (with confirmation) |
📦 Installation
pip (from PyPI — coming soon)
pip install wazuh-mcp-server
From source
git clone https://github.com/Sbharadwaj05/wazuh-mcp-server.git
cd wazuh-mcp-server
pip install -e ".[dev]"
Docker (one‑command demo — spins up Wazuh + MCP for testing)
⚠️ This bundles a full Wazuh stack for quick demos. In production, you already have Wazuh running — just use the pip install above and point to your existing Wazuh.
git clone https://github.com/Sbharadwaj05/wazuh-mcp-server.git
cd wazuh-mcp-server
docker compose up -d
# Wazuh Dashboard: https://localhost:443
# Swagger UI: http://localhost:8000/docs
# Prometheus Metrics: http://localhost:9090/metrics
Configuration
Create a .env file:
# Required
WAZUH_API_URL=https://your-wazuh-manager:55000
WAZUH_USERNAME=wazuh-wui
WAZUH_PASSWORD=your-api-password
# Required for alerts, vulnerabilities, rules (Wazuh 4.x/5.x)
WAZUH_INDEXER_URL=https://your-wazuh-manager:9200
WAZUH_INDEXER_USER=admin
WAZUH_INDEXER_PASS=your-indexer-password
# Optional
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
Important: The Wazuh Indexer (port 9200) must be accessible from the MCP server. By default it only listens on
localhost. See Troubleshooting for the one-line fix.
Claude Desktop / Zed / Cursor
{
"mcpServers": {
"wazuh": {
"command": "python",
"args": ["-m", "wazuh_mcp.server"],
"cwd": "/path/to/wazuh-mcp-server/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"
}
}
}
}
🔧 Complete Tool Reference (28 tools, 9 domains)
🔔 Alerts & Triage (3)
| Tool | Description | Data Source |
|---|---|---|
wazuh_list_alerts | Query alerts by severity, agent, rule ID, MITRE, search | Wazuh Indexer |
wazuh_get_alert | Fetch single alert by ID with full context | Wazuh Indexer |
wazuh_alert_summary | Aggregated: severity distribution, top rules/IPs, MITRE coverage | Wazuh Indexer |
🔍 Threat Hunting (4)
| Tool | Description | Data Source |
|---|---|---|
wazuh_search_events | Submit raw events for Wazuh parsing/analysis | Wazuh API |
wazuh_query_fim | File Integrity Monitoring — file changes, additions, deletions | Wazuh API |
wazuh_query_vulnerabilities | CVE inventory per agent, filterable by severity | Wazuh Indexer |
wazuh_search_mitre | MITRE ATT&CK techniques, tactics, mitigations, groups | Wazuh API |
📋 Compliance (3)
| Tool | Description | Data Source |
|---|---|---|
wazuh_sca_status | SCA policy scores per agent (CIS, PCI DSS, NIST, GDPR) | Wazuh API |
wazuh_sca_checks | Per-check pass/fail detail with rationales and remediation | Wazuh API |
wazuh_compliance_report | Fleet-wide compliance aggregation across all agents | Wazuh API |
🖥️ Agents & Groups (6)
| Tool | Description | Data Source |
|---|---|---|
wazuh_list_agents | List agents with status, OS, version, search, pagination | Wazuh API |
wazuh_get_agent | Deep-dive on single agent: config, modules, groups | Wazuh API |
wazuh_agent_health | Fleet health: status counts, OS breakdown, stale agents | Wazuh API |
wazuh_list_groups | List agent groups with counts and checksums | Wazuh API |
wazuh_get_group | Group details, configuration, member counts | Wazuh API |
wazuh_group_agents | All agents in a specific group | Wazuh API |
📚 CDB Lists (2)
| Tool | Description | Data Source |
|---|---|---|
wazuh_list_cdb_lists | List CDB threat-intel files (IP blocklists, IOC databases) | Wazuh API |
wazuh_get_cdb_list | Read contents of a CDB list file | Wazuh API |
⚙️ Manager & Cluster (5)
| Tool | Description | Data Source |
|---|---|---|
wazuh_manager_stats | Daemon statistics (EPS, queues, processed events) | Wazuh API |
wazuh_manager_logs | Manager log retrieval with category and search filters | Wazuh API |
wazuh_cluster_status | Cluster health: enabled/running state | Wazuh API |
wazuh_cluster_node_stats | Per-node daemon stats (falls back to manager stats for single-node) | Wazuh API |
wazuh_rules_info | Search rules by framework/MITRE (falls back to indexer on 4.14.x bug) | Wazuh API / Indexer |
📊 Security Analysis (3)
| Tool | Description | Data Source |
|---|---|---|
wazuh_rules_coverage_map | MITRE/NIST/PCI/GDPR/HIPAA coverage matrix vs your rules | Wazuh Indexer |
wazuh_vulnerability_heatmap | Risk-scored CVE heatmap across all agents | Wazuh Indexer |
wazuh_incident_timeline | Auto-generated chronological attack timeline from an alert | Wazuh Indexer |
⚠️ Incident Response (2)
| Tool | Description | Data Source |
|---|---|---|
wazuh_run_active_response | Trigger firewall-drop, host-deny, restart-wazuh (with confirmation gate) | Wazuh API |
wazuh_agent_command | Execute command on remote agent (with confirmation gate) | Wazuh API |
🔒 SAFETY: Destructive tools require two-step
confirm=True+ one-time expiring token. A misconfigured LLM cannot silently block IPs or quarantine hosts. All destructive actions are recorded in an append-only audit log.
🖥️ Observability
Prometheus Metrics (:9090/metrics)
| Metric | Type | Description |
|---|---|---|
wazuh_mcp_tool_calls_total | Counter | Tool invocations by name + status (success/error) |
wazuh_mcp_tool_duration_seconds | Histogram | P50/P95/P99 latency per tool |
wazuh_mcp_rate_limits_total | Counter | Rate-limit rejections per tool |
wazuh_mcp_api_up | Gauge | Wazuh API connectivity (1=up, 0=down) |
wazuh_mcp_audit_entries_total | Counter | Destructive actions logged |
wazuh_mcp_active_requests | Gauge | In-flight tool calls |
wazuh_mcp_tool_errors_total | Counter | Errors by tool + error type |
OpenAPI / Swagger (:8000/docs)
Interactive API docs for all 28 tools. Raw OpenAPI 3.0 spec at /openapi.json.
Audit Log (~/.wazuh-mcp/audit.jsonl)
Append-only JSON Lines. One entry per destructive action. Never truncated. Thread-safe.
🔐 RBAC
Four built-in roles with hierarchical, cumulative access:
| Role | Access | Tools |
|---|---|---|
viewer | Read-only | Alerts, agents, compliance, rules |
analyst | + Investigation | All viewer + hunting, MITRE, CDB lists, analysis |
admin | + Administration | All analyst + manager stats, logs, cluster |
soc | + Response ⚠️ | All admin + active response, agent commands |
export WAZUH_RBAC_ROLE=analyst
# Or custom policy: WAZUH_RBAC_POLICY=/path/to/rbac.json
📁 Project Structure
Wazuh-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
🚀 Quick Start
# 1. Clone
git clone https://github.com/Sbharadwaj05/wazuh-mcp-server.git
cd wazuh-mcp-server
# 2. Configure
cp .env.example .env
# Edit .env with your Wazuh API + Indexer credentials
# 3. Install
pip install -e ".[dev]"
# 4. Verify connectivity
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. Connect to AI client
# Copy claude_desktop_config.json.example into your MCP config
🔒 Security Policy
See docs/SECURITY.md for full defense-in-depth documentation (6 layers), production deployment checklist, and vulnerability reporting process.
🛠️ Troubleshooting
See docs/TROUBLESHOOTING.md for solutions to:
- Wazuh dashboard version mismatch
/alertsreturning 404 (indexer setup)/rulesreturning 500 (Wazuh 4.14.x bug + indexer fallback)- Indexer 401 authentication
- Filebeat connection issues
- MCP server connectivity
- Rate limiting and confirmation gate behavior
- Complete network architecture diagram
📄 License
MIT © Sbharadwaj05