Wazuh Mcp Server

🛡️ Wazuh MCP Server

Servidor MCP (Model Context Protocol) para Wazuh SIEM/XDR — integración directa con Hermes Agent.

Servidor MCP de alto rendimiento que expone 101 herramientas y 11 prompts guiados para interactuar con la API del Wazuh Manager y el Indexer de OpenSearch. Diseñado para despliegue en producción sobre un VPS Contabo, permitiendo que Hermes Agent (o Claude Desktop y cualquier cliente MCP) consulte agentes, vulnerabilidades, alertas, reglas, SCA, hardware y salud del cluster, y además realice threat hunting, análisis de incidentes, informes de compliance, enriquecimiento con threat intelligence e integraciones con Jira/TheHive/Slack, directamente desde Wazuh.

• 17 tools núcleo (server.py) — probadas en producción, cliente thread-safe con pool de conexiones, JWT auto-refresh y autenticación por certificados.
• 84 tools extendidas + 11 prompts (wazuh_tools/) — portadas de adi5353/wazuh-mcp (Apache-2.0) y adaptadas a la infraestructura de este proyecto. Carga tolerante a fallos: si un módulo extendido fallara, las 17 tools núcleo siguen operativas.

---

🏗️ Arquitectura

┌─────────────────┐     MCP (Streamable HTTP)     ┌──────────────────┐
│  Hermes Agent   │ ◄──────────────────────────► │  Wazuh MCP Server │
│  (Cliente MCP)  │        Puerto 8090            │  (FastMCP)        │
└─────────────────┘                               └────────┬─────────┘
                                                            │
                                          ┌─────────────────┼─────────────────┐
                                          │                 │                  │
                                    ┌─────▼─────┐   ┌──────▼──────┐   ┌──────▼──────┐
                                    │  Wazuh    │   │  OpenSearch │   │  Syscollector│
                                    │  Manager  │   │  Indexer    │   │  (agentes)  │
                                    │  API      │   │  (alertas,  │   │             │
                                    │  :55000   │   │   vulns)    │   │             │
                                    └───────────┘   │  :9200      │   └─────────────┘
                                                    └─────────────┘

Componentes principales

| Archivo | Descripción | |---------|-------------| | server.py | Servidor MCP principal (v2.0). Usa FastMCP + httpx con pool de conexiones, timeouts diferenciados, token JWT con refresh automático y cliente thread-safe. | | mcp_wazuh.py | Implementación legacy/alternativa del cliente Wazuh MCP (compatible con mcporter). | | direct_api.py | API HTTP directa sin dependencia MCP — endpoints REST simples para integración con n8n. | | http_wrapper.py | Wrapper HTTP que expone herramientas MCP como endpoints REST (usa mcporter internamente). | | Dockerfile | Imagen Python 3.12-slim con dependencias versionadas (fastmcp, httpx, uvicorn). | | docker-compose.yml | Despliegue production-ready con límites de memoria, healthcheck, montaje de certificados y reinicio automático. |

Stack tecnológico

• Python 3.12 + FastMCP 2.7.0 — servidor MCP con transporte HTTP
• httpx 0.28.1 — cliente HTTP asíncrono con pool de conexiones
• uvicorn — servidor ASGI para el transporte HTTP
• Docker — contenedorizado para despliegue consistente

---

🔧 Herramientas MCP disponibles

Agentes

| Herramienta | Descripción | |-------------|-------------| | list_agents | Lista todos los agentes con estado, versión, SO, IP y grupos | | get_agent_info | Información detallada de un agente específico | | get_agents_summary | Resumen con estadísticas de todos los agentes (activos, desconectados, por SO) | | get_agent_groups | Grupos a los que pertenece un agente | | restart_agent | Reinicia un agente específico |

Vulnerabilidades (Indexer)

| Herramienta | Descripción | |-------------|-------------| | get_agent_vulnerabilities | Vulnerabilidades de un agente con filtro por severidad | | get_vulnerability_summary | Resumen de CVEs únicos con desglose por severidad (usa collapse + aggregations) |

Reglas

| Herramienta | Descripción | |-------------|-------------| | list_rules | Lista reglas con filtro por estado y grupo | | get_rules_groups | Lista todos los grupos de reglas disponibles |

Alertas (Indexer)

| Herramienta | Descripción | |-------------|-------------| | search_alerts | Búsqueda de alertas con query string, filtro por agente |

Syscollector / SCA

| Herramienta | Descripción | |-------------|-------------| | get_agent_sca | Resultados del Security Configuration Assessment (SCA) | | get_agent_netaddr | Interfaces de red del agente | | get_agent_hardware | Información de hardware (CPU, RAM, placa base) | | get_agent_ports | Puertos en escucha del agente (desde el Indexer) |

Infraestructura

| Herramienta | Descripción | |-------------|-------------| | get_manager_stats | Estadísticas del Wazuh Manager | | get_cluster_nodes | Nodos del cluster Wazuh | | get_indexer_health | Salud del cluster OpenSearch (status, nodos, shards) |

---

🚀 Herramientas extendidas (84 tools en 21 dominios)

Portadas de adi5353/wazuh-mcp y adaptadas al cliente de este proyecto (ver [wazuh_tools/NOTICE.md](wazuhtools/NOTICE.md)):

| Dominio | Tools destacadas | |---------|------------------| | Alertas avanzadas | alert_summary, alert_timeline, search_by_mitre, search_by_source_ip, search_authentication_failures, get_alert_by_id | | Threat Hunting | hunt_lateral_movement, hunt_persistence_mechanisms, hunt_data_exfiltration | | Incidentes | incident_timeline, blast_radius_analysis, create_incident_report, tag_alert, bulk_suppress_rule | | Vulnerabilidades | vulnerability_summary (flota), search_cve, prioritize_patches, get_agent_vulnerabilities_detailed | | FIM | get_recent_fim_changes, search_fim_alerts, fim_summary, critical_file_changes | | Compliance | compliance_summary y generate_compliance_report (PCI-DSS, HIPAA, GDPR, NIST 800-53, TSC) | | SCA | get_sca_failed_checks, sca_alerts_summary, fleet_sca_weakest_agents | | Inventario de flota | fleet_find_package, fleet_find_process, fleet_find_listening_port, get_agent_login_history, get_agent_packages, get_agent_processes | | Reglas y decoders | search_rules, get_rule_details, test_log_against_rules, test_rule_coverage, list_decoders, get_custom_rules | | CDB Lists | list_cdb_lists, add_to_cdb_list, remove_from_cdb_list, preview_cdb_list_impact | | Active Response | get_active_responses, run_active_response, correlate_alert_with_response, active_response_effectiveness | | MITRE ATT&CK | mitre_coverage_analysis, get_mitre_gaps | | Threat Intel | enrich_ip (VirusTotal + AbuseIPDB), enrich_file_hash, enrich_ip_geo (GeoIP gratuito) | | Supresión de ruido | list_suppressed_rules, noise_score_rule, expire_suppression | | Reporting | generate_weekly_summary, generate_shift_handover, compare_alert_volume, detect_rule_anomalies | | Integraciones | create_jira_ticket, create_thehive_case, update_ticket_status | | Notificaciones | send_alert_to_slack, send_critical_alert_notify, email_compliance_report | | Onboarding | generate_enrollment_command, list_never_connected_agents, agent_onboarding_checklist | | Archive | search_archive_logs, search_archive_logs_by_agent (forense) | | Cluster | get_cluster_health, check_event_queue_health | | Agentes/Grupos | run_active_response, list_groups, get_group_agents, add_agent_to_group |

Las integraciones externas (Jira, TheHive, Slack, SMTP, VirusTotal, AbuseIPDB) degradan con elegancia: si no configuras sus credenciales, las demás tools funcionan con normalidad.

🔐 Operaciones de escritura deshabilitadas por defecto

Las tools extendidas destructivas (run_active_response, add_to_cdb_list, tag_alert, bulk_suppress_rule, add_agent_to_group, expire_suppression, remove_from_cdb_list) requieren WAZUH_ALLOW_WRITES=true. Además, varias soportan dry_run=True (por defecto) para previsualizar el impacto sin aplicar cambios. La tool núcleo restart_agent no se ve afectada por este flag (mantiene su comportamiento original).

💬 Prompts MCP (workflows guiados)

| Prompt | Uso | |--------|-----| | investigate_brute_force | Investigación completa de fuerza bruta en 6 pasos | | weekly_soc_briefing | Briefing ejecutivo semanal del SOC | | triage_alert | Triaje estructurado de una alerta (TP/FP + severidad) | | cve_emergency_response | Respuesta de emergencia a un CVE | | morning_briefing | Briefing de inicio de turno | | incident_triage_full | Triaje completo de incidente por agente o IP | | threat_hunt_session | Sesión de threat hunt (lateral + persistencia + exfiltración) | | end_of_shift_handover | Informe de relevo de turno | | daily_security_report | Reporte diario técnico — métricas de alertas, amenazas activas, salud de infraestructura, vulnerabilidades y acciones prioritarias (12 tools orquestadas) | | weekly_security_report | Reporte semanal táctico — tendencias, threat hunting, MITRE ATT&CK, gestión de vulnerabilidades, compliance y plan de acción (17 tools orquestadas) | | monthly_ciso_report | Reporte mensual ejecutivo CISO — scorecard de postura, paisaje de amenazas, riesgos, compliance multi-framework, KPIs y recomendaciones estratégicas (25 tools orquestadas) |

---

📋 Variables de entorno

Copia .env.example a .env y configura los valores:

| Variable | Requerida | Default | Descripción | |----------|-----------|---------|-------------| | WAZUH_URL | ✅ | https://localhost:55000 | URL base de la API del Wazuh Manager | | WAZUH_USER | ✅ | — | Usuario con acceso a la API de Wazuh | | WAZUH_PASS | ✅ | — | Contraseña del usuario de la API | | INDEXER_URL | ✅ | https://localhost:9200 | URL base del Indexer de OpenSearch | | INDEXER_USER | ⚠️ | — | Usuario del Indexer (si no usas certificados) | | INDEXER_PASS | ⚠️ | — | Contraseña del Indexer (si no usas certificados) | | INDEXER_CERT | ⚠️ | — | Ruta al certificado cliente (alternativa a user/pass) | | INDEXER_KEY | ⚠️ | — | Ruta a la clave privada del certificado | | INDEXER_CA | ❌ | — | Ruta al CA bundle (opcional) | | VERIFY_SSL | ❌ | false | Verificar certificados SSL (true/false) | | INDEXER_TIMEOUT | ❌ | 30.0 | Timeout para consultas al Indexer (segundos) | | WAZUH_API_TIMEOUT | ❌ | 15.0 | Timeout para consultas a la API de Wazuh | | MAX_CONNECTIONS | ❌ | 20 | Conexiones máximas en el pool HTTP | | MAX_KEEPALIVE | ❌ | 10 | Conexiones keep-alive máximas | | WAZUH_HTTP_PORT | ❌ | 8090 | Puerto HTTP del servidor MCP | | WAZUH_ALLOW_WRITES | ❌ | false | Habilita las tools extendidas de escritura (active response, CDB, tagging) | | WAZUH_MAX_RESULTS_GLOBAL | ❌ | 500 | Límite global de resultados en las tools extendidas | | WAZUH_TS_FIELD | ❌ | timestamp | Campo de tiempo de los documentos de alertas (timestamp o @timestamp) | | VIRUSTOTAL_API_KEY | ❌ | — | Enriquecimiento de IPs/hashes con VirusTotal | | ABUSEIPDB_API_KEY | ❌ | — | Scoring de IPs con AbuseIPDB | | JIRA_URL / JIRA_USER / JIRA_API_TOKEN / JIRA_PROJECT_KEY | ❌ | — | Creación de tickets en Jira | | THEHIVE_URL / THEHIVE_API_KEY | ❌ | — | Creación de casos en TheHive | | SLACK_WEBHOOK_URL o SLACK_BOT_TOKEN | ❌ | — | Notificaciones a Slack | | SMTP_HOST / SMTP_USER / SMTP_PASS / REPORT_EMAIL_TO | ❌ | — | Envío de informes por email |

> ⚠️ INDEXERUSER/INDEXERPASS o INDEXERCERT/INDEXERKEY — al menos un par es obligatorio para conectarse al Indexer. > > Ver .env.example para la lista completa comentada (patrones de índice, canales de Slack, password de enrolamiento, etc.).

---

🐳 Despliegue con Docker Compose

Requisitos previos

1. Certificados del Wazuh Indexer en el host:

• /etc/wazuh-indexer/certs/admin.pem — certificado de administrador
• /etc/wazuh-indexer/certs/admin-key.pem — clave privada
• /etc/wazuh-indexer/certs/root-ca.pem — CA raíz

1. Archivo .env con las credenciales configuradas.

Despliegue

# 1. Clonar el repositorio
git clone  wazuh-mcp
cd wazuh-mcp

# 2. Crear .env desde el ejemplo
cp .env.example .env
# Editar .env con tus credenciales reales
nano .env

# 3. Construir y levantar
docker compose up -d --build

# 4. Verificar que está corriendo
docker compose ps
docker compose logs -f

Healthcheck

El contenedor incluye un healthcheck funcional que verifica que el endpoint MCP responde correctamente:

# Verificar estado del healthcheck
docker inspect wazuh-mcp --format='{{.State.Health.Status}}'

# Probar manualmente
curl -X POST http://localhost:8090/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Configuración de certificados

Si tu Wazuh Indexer está en el mismo host que el contenedor, los certificados se montan como volúmenes de solo lectura:

volumes:
  - /etc/wazuh-indexer/certs/admin.pem:/certs/admin.pem:ro
  - /etc/wazuh-indexer/certs/admin-key.pem:/certs/admin-key.pem:ro
  - /etc/wazuh-indexer/certs/root-ca.pem:/certs/root-ca.pem:ro

Luego en tu .env:

INDEXER_CERT=/certs/admin.pem
INDEXER_KEY=/certs/admin-key.pem
INDEXER_CA=/certs/root-ca.pem
# INDEXER_USER=   ← dejar vacío si usas certificados
# INDEXER_PASS=   ← dejar vacío si usas certificados

Si el Indexer está en otro servidor, copia los certificados al host Docker y ajusta las rutas de los volúmenes.

---

🔌 Conexión con Hermes Agent Gateway

Configuración del perfil

En tu perfil de Hermes Agent, añade el servidor MCP al archivo de configuración:

{
  "mcpServers": {
    "wazuh-siem": {
      "type": "streamable-http",
      "url": "http://:8090/mcp"
    }
  }
}

Probar la conexión

Una vez configurado, Hermes Agent podrá invocar cualquiera de las herramientas MCP. Ejemplos de prompts:

• "Muéstrame todos los agentes de Wazuh"
• "¿Cuántas vulnerabilidades críticas tiene el agente 001?"
• "Busca alertas de rootkit en las últimas 24 horas"
• "¿Cuál es el estado de salud del cluster OpenSearch?"
• "Dame el resumen de todos los agentes"

---

🛠️ Desarrollo local

# Instalar dependencias
pip install -r requirements.txt

# Ejecutar en modo HTTP (recomendado)
python server.py http 8090 127.0.0.1

# Ejecutar en modo stdio
python server.py stdio

---

📁 Estructura del proyecto

wazuh-mcp/
├── server.py              # Servidor MCP principal (17 tools núcleo + registro de extendidas)
├── wazuh_tools/           # 84 tools extendidas en 21 dominios + 11 prompts MCP
│   ├── __init__.py        #   Orquestador: register_all() con proxy de prefijos/colisiones
│   ├── compat.py          #   Clientes async con pool, JWT auto-refresh y certificados
│   ├── helpers.py         #   trim_alert, trim_vuln, time_window...
│   ├── prompts.py         #   11 prompts de workflows guiados
│   ├── alerts.py, fim.py, threat_hunting.py, incidents.py, ...  (21 módulos)
│   ├── LICENSE            #   Apache-2.0 del proyecto original
│   └── NOTICE.md          #   Atribución y lista de adaptaciones
├── mcp_wazuh.py           # Cliente MCP alternativo (compatible mcporter)
├── direct_api.py          # API HTTP directa para n8n
├── http_wrapper.py        # Wrapper HTTP para herramientas MCP
├── Dockerfile             # Imagen Docker
├── docker-compose.yml     # Despliegue con Docker Compose
├── requirem

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [luislopezsanchez](https://github.com/luislopezsanchez)
- **Source:** [luislopezsanchez/wazuh-mcp-server](https://github.com/luislopezsanchez/wazuh-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.