convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
Sbharadwaj05

Wazuh MCP Server

Sbharadwaj05/wazuh-mcp-server

Automação de operações de segurança Wazuh via Claude com 28 ferramentas nativas

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-server

1 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

Estrelas
13
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 3 dias
Versão
—
Issues abertas
2
Contribuidores
1

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, soc with hierarchical access
  • Dependabot + pip-audit + CodeQL — Automated dependency scanning on every push + weekly schedule
  • Non-root Docker — Production container runs as unprivileged wazuhmcp user
  • TLS everywhere — WAZUH_INSECURE=false in production, Wazuh API + Indexer both over HTTPS
  • Prometheus metrics — 7 metrics exposed on :9090/metrics for 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

WorkflowExample PromptTools 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)

ToolDescriptionData Source
wazuh_list_alertsQuery alerts by severity, agent, rule ID, MITRE, searchWazuh Indexer
wazuh_get_alertFetch single alert by ID with full contextWazuh Indexer
wazuh_alert_summaryAggregated: severity distribution, top rules/IPs, MITRE coverageWazuh Indexer

🔍 Threat Hunting (4)

ToolDescriptionData Source
wazuh_search_eventsSubmit raw events for Wazuh parsing/analysisWazuh API
wazuh_query_fimFile Integrity Monitoring — file changes, additions, deletionsWazuh API
wazuh_query_vulnerabilitiesCVE inventory per agent, filterable by severityWazuh Indexer
wazuh_search_mitreMITRE ATT&CK techniques, tactics, mitigations, groupsWazuh API

📋 Compliance (3)

ToolDescriptionData Source
wazuh_sca_statusSCA policy scores per agent (CIS, PCI DSS, NIST, GDPR)Wazuh API
wazuh_sca_checksPer-check pass/fail detail with rationales and remediationWazuh API
wazuh_compliance_reportFleet-wide compliance aggregation across all agentsWazuh API

🖥️ Agents & Groups (6)

ToolDescriptionData Source
wazuh_list_agentsList agents with status, OS, version, search, paginationWazuh API
wazuh_get_agentDeep-dive on single agent: config, modules, groupsWazuh API
wazuh_agent_healthFleet health: status counts, OS breakdown, stale agentsWazuh API
wazuh_list_groupsList agent groups with counts and checksumsWazuh API
wazuh_get_groupGroup details, configuration, member countsWazuh API
wazuh_group_agentsAll agents in a specific groupWazuh API

📚 CDB Lists (2)

ToolDescriptionData Source
wazuh_list_cdb_listsList CDB threat-intel files (IP blocklists, IOC databases)Wazuh API
wazuh_get_cdb_listRead contents of a CDB list fileWazuh API

⚙️ Manager & Cluster (5)

ToolDescriptionData Source
wazuh_manager_statsDaemon statistics (EPS, queues, processed events)Wazuh API
wazuh_manager_logsManager log retrieval with category and search filtersWazuh API
wazuh_cluster_statusCluster health: enabled/running stateWazuh API
wazuh_cluster_node_statsPer-node daemon stats (falls back to manager stats for single-node)Wazuh API
wazuh_rules_infoSearch rules by framework/MITRE (falls back to indexer on 4.14.x bug)Wazuh API / Indexer

📊 Security Analysis (3)

ToolDescriptionData Source
wazuh_rules_coverage_mapMITRE/NIST/PCI/GDPR/HIPAA coverage matrix vs your rulesWazuh Indexer
wazuh_vulnerability_heatmapRisk-scored CVE heatmap across all agentsWazuh Indexer
wazuh_incident_timelineAuto-generated chronological attack timeline from an alertWazuh Indexer

⚠️ Incident Response (2)

ToolDescriptionData Source
wazuh_run_active_responseTrigger firewall-drop, host-deny, restart-wazuh (with confirmation gate)Wazuh API
wazuh_agent_commandExecute 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)

MetricTypeDescription
wazuh_mcp_tool_calls_totalCounterTool invocations by name + status (success/error)
wazuh_mcp_tool_duration_secondsHistogramP50/P95/P99 latency per tool
wazuh_mcp_rate_limits_totalCounterRate-limit rejections per tool
wazuh_mcp_api_upGaugeWazuh API connectivity (1=up, 0=down)
wazuh_mcp_audit_entries_totalCounterDestructive actions logged
wazuh_mcp_active_requestsGaugeIn-flight tool calls
wazuh_mcp_tool_errors_totalCounterErrors 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:

RoleAccessTools
viewerRead-onlyAlerts, agents, compliance, rules
analyst+ InvestigationAll viewer + hunting, MITRE, CDB lists, analysis
admin+ AdministrationAll 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
  • /alerts returning 404 (indexer setup)
  • /rules returning 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

Ver o original no GitHub

Bom para

Relacionados