Wazuh MCP Server

The Wazuh MCP Server v4.3.0 provides 55 tools organized into functional categories to allow LLMs to interact with your SIEM. The tools are divided into:

• Alert Management: Query and analyze security alerts (e.g., get_wazuh_alerts, analyze_alert_patterns). Timestamps support ISO 8601 or relative math like now-24h.
• Agent Management: Monitor and manage Wazuh agents (e.g., get_wazuh_agents, get_agent_processes).
• Vulnerability Management: Identify security vulnerabilities (e.g., get_wazuh_vulnerabilities).
• Security Analysis: Threat intelligence and risk assessment (e.g., analyze_security_threat, check_ioc_reputation).
• Compliance & Reporting: Framework validation like PCI-DSS, HIPAA, and ISO 27001 (e.g., run_compliance_check, get_iso27001_dashboard).
• System Monitoring: Monitor Wazuh health and performance (e.g., get_wazuh_statistics, get_wazuh_cluster_health).
• Active Response: Execute actions on agents (e.g., wazuh_block_ip, wazuh_isolate_host, wazuh_kill_process).
• Verification: Confirm the status of active response actions (e.g., wazuh_check_blocked_ip).
• Rollback: Reverse active response actions (e.g., wazuh_unisolate_host, wazuh_restore_file).

The Wazuh MCP server implements several security layers to protect your SIEM data:

• RBAC (Role-Based Access Control): Uses per-tool scope enforcement. It is fail-closed; tokens without explicit scope claims default to read-only. To enable write capabilities, you must opt-in using MCP_API_KEY_SCOPES="wazuh:read wazuh:write". If AUTHLESS_ALLOW_WRITE is not set to true, authless mode is strictly read-only.
• Audit Logging: All destructive tool calls (e.g., wazuh_block_ip, wazuh_isolate_host) are logged with client ID, session, timestamp, and full arguments.
• Output Sanitization: Redacts credentials, tokens, and API keys from alert full_log fields before they reach the LLM.
• Input Validation: Validates all parameters using regex for agent IDs, ipaddress modules for IPs, and blocks shell metacharacters in active response tools.
• Rate Limiting: Implements a per-principal sliding window based on the authenticated client and trusted-proxy IP.
• Circuit Breakers: Automatically triggers a 60s fail-fast state upon Wazuh API failures to prevent cascading issues.
• Container Hardening: Runs as a non-root user with a read-only filesystem and CAP_DROP ALL privileges.

Multi-cluster mode allows you to manage multiple Wazuh deployments from a single MCP server instance. It is an opt-in feature triggered by the presence of a clusters configuration file.

Operational Modes

• Single-Cluster Mode (Default): If no clusters file is present, the server uses environment variables (e.g., WAZUH_HOST, WAZUH_INDEXER_HOST) to connect to one deployment. Tools do not accept a cluster_id argument.
• Multi-Cluster Mode: When a clusters file is provided via the WAZUH_CLUSTERS_FILE environment variable (defaults to ./config/clusters.json), each entry in the file becomes a named cluster.

Key Multi-Cluster Features

• Named Clusters: Every tool gains an optional cluster_id argument to route requests to a specific deployment.
• Discovery: A new tool, list_wazuh_clusters, becomes available to list all configured clusters.
• Health Reporting: The /health and /ready endpoints report the status of all configured clusters.
• Backward Compatibility: The cluster configured via environment variables remains reachable using the default ID, ensuring existing automation does not break.

If your Wazuh Indexers are managed by an OpenSearch Cross-Cluster Search coordinator, you can use the ccs_prefix field to qualify index queries.

Individual Cluster Prefix

Setting ccs_prefix to a value (e.g., eu) ensures that indexer queries are qualified against the remote cluster (e.g., eu:wazuh-alerts-*).

Fleet-wide Search (The 'all' Pseudo-Cluster)

You can create a special cluster entry with "ccs_prefix": "*". This acts as an all pseudo-cluster that searches every remote cluster known to the coordinator, allowing for aggregated fleet-wide alert and vulnerability reads.

// Configuration for a fleet-wide 'all' cluster
{
  "id": "all",
  "wazuh_host": "wazuh-eu.example.com",
  "wazuh_user": "${WAZUH_EU_USER}",
  "wazuh_pass": "${WAZUH_EU_PASS}",
  "indexer_host": "ccs-coordinator.example.com",
  "indexer_user": "${INDEXER_USER}",
  "indexer_pass": "${INDEXER_PASS}",
  "ccs_prefix": "*"
}

// Usage: Aggregating alerts across the entire fleet
{ "name": "get_alerts_aggregated", "arguments": { "cluster_id": "all", "timestamp_start": "now-24h" } }

The server supports three authentication modes via AUTH_MODE:

1. Bearer (bearer): Default mode. Uses an API key to exchange for a JWT/session-token.
2. OAuth (oauth): OAuth 2.0 with PKCE. Required for certain integrations like Claude Desktop.
3. Authless (none): No authentication. Read-only by default unless AUTHLESS_ALLOW_WRITE=true is set (development only).

Scopes and RBAC

Scopes are fail-closed. A token with no scope is read-only.

• wazuh:read: Access to 41 tools (alerts, agents, vulnerabilities, etc.).
• wazuh:write: Access to 14 tools (active response, rollback, etc.).

To grant write access to the primary API key, use: MCP_API_KEY_SCOPES="wazuh:read wazuh:write"

# Exchange an API key for a JWT in Bearer mode
curl -X POST https://your-server/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "wazuh_your-api-key"}'

The Wazuh MCP Server includes several production-grade reliability features that are automatically applied to all Wazuh API calls without requiring manual configuration:

• Circuit Breakers: Automatically opens after 5 consecutive failures to prevent cascading failures to the Wazuh API. It recovers automatically after 60 seconds.
• Retry Logic: Implements exponential backoff with jitter. It performs 3 retry attempts with 1-10 second delays. It only retries transient errors (5xx, connection errors) and ignores client errors (400, 401, 404).
• Graceful Shutdown: When the server terminates, it waits up to 30 seconds for active connections to complete and runs cleanup tasks to prevent data loss.
• Security & Monitoring Middleware: Automatically adds security headers (HSTS, CSP, XSS-Protection, etc.) and tracks request metrics (counts, duration, correlation IDs). Prometheus metrics are exposed at the /metrics endpoint.