🔐 SB SIEM MCP

Note: Independent, third-party project — not affiliated with or endorsed by Wazuh Inc. Actively developed and tested against live Wazuh instances; review and test before production deployment.

28 MCP tools. 9 domains. Tested on Wazuh 4.14.5 against live instances. AI-powered security operations for Wazuh SIEM/XDR.

<p align="center"> <a href="https://github.com/Sbharadwaj05/sb-siem-mcp/actions/workflows/ci.yml"><img src="https://github.com/Sbharadwaj05/sb-siem-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/Sbharadwaj05/sb-siem-mcp/actions/workflows/security-scan.yml"><img src="https://github.com/Sbharadwaj05/sb-siem-mcp/actions/workflows/security-scan.yml/badge.svg" alt="Security Scan"></a> <img src="https://img.shields.io/badge/tools-28%20%2F%2028%20operational-brightgreen" alt="28/28 tools"> <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue" alt="Python"> <a href="https://github.com/Sbharadwaj05/sb-siem-mcp/blob/master/LICENSE"><img src="https://img.shields.io/github/license/Sbharadwaj05/sb-siem-mcp" alt="License: MIT"></a> </p>

"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)

• [x] Input validation — Shell metacharacter blocking, regex for agent IDs, IPs, CVEs, MITRE IDs
• [x] Rate limiting — Token-bucket: 30/60s for read tools, 5/120s for destructive
• [x] Output sanitization — Redacts AWS keys, JWT tokens, SSH keys, API keys, passwords from LLM-bound data
• [x] Audit logging — Append-only JSONL trail for all destructive actions
• [x] Confirmation gate — Two-step confirm=True + expiring token for active response tools
• [x] RBAC — 4 built-in roles: viewer, analyst, admin, soc with hierarchical access
• [x] Dependabot + pip-audit + CodeQL — Automated dependency scanning on every push + weekly schedule
• [x] Non-root Docker — Production container runs as unprivileged wazuhmcp user
• [x] TLS support — Verify server certificates, or disable for local dev via WAZUH_INSECURE
• [x] Prometheus metrics — 7 metrics exposed on :9090/metrics for SOC monitoring (latency, errors, rate limits)
• [x] 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 sb-siem-mcp

From source

git clone https://github.com/Sbharadwaj05/sb-siem-mcp.git
cd sb-siem-mcp
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.

🔒 The MCP endpoint has no built-in client authentication. The demo server binds to localhost:8000 — keep it local. For remote access, place it behind a reverse proxy with auth. See Production Hardening below.

git clone https://github.com/Sbharadwaj05/sb-siem-mcp.git
cd sb-siem-mcp
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/sb-siem-mcp/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

sb-siem-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/sb-siem-mcp.git
cd sb-siem-mcp

# 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

---

🔒 Production Hardening

This project ships with safe defaults, but the docker-compose demo stack disables several security features for ease of local testing. Do not use the demo config in production without these changes:

1. Enable TLS Everywhere

• Set WAZUH_INSECURE=false — the docker-compose now defaults to false.
• Re-enable the Wazuh Indexer security plugin — remove DISABLE_SECURITY_PLUGIN=true and plugins.security.disabled=true from the wazuh.indexer service. Generate proper certificates instead.
• Set FILEBEAT_SSL_VERIFICATION_MODE=full on the Wazuh Manager.

2. Restrict the MCP Endpoint

The MCP server exposes an HTTP endpoint on port 8000. This endpoint has no built-in client authentication. In production:

• Bind to 127.0.0.1 if the AI client runs on the same host, OR
• Place the MCP server behind a reverse proxy with mutual TLS / API key auth, OR
• Use network-level controls (firewall rules, security groups) to restrict access.

3. Secure the Wazuh Indexer

The Indexer (port 9200) must be network-accessible from the MCP server.

• Use TLS with certificate verification (WAZUH_INSECURE=false).
• Store Indexer credentials in a secrets manager (Docker secrets, Kubernetes secrets, HashiCorp Vault) — never in plaintext .env files in production.
• Consider IP whitelisting at the network/firewall layer.

4. Harden the Audit Log

• The default audit log location is ~/.wazuh-mcp/audit.jsonl. In production, set WAZUH_AUDIT_LOG=/var/log/wazuh-mcp/audit.jsonl (or another persistent volume outside the home directory).
• For true immutability, ship audit logs to an external SIEM or use a write-once-read-many (WORM) filesystem.

5. RBAC: Enable It

RBAC is disabled by default (WAZUH_RBAC_ROLE is unset → all tools available). In production, set WAZUH_RBAC_ROLE=analyst (or stricter) and configure tool permissions in your AI client to match.

6. Version Compatibility

This server targets Wazuh 4.x (tested on 4.14.5). Wazuh 5.x replaces the Indexer with a new storage back-end — this server will require updates to work with 5.x. Check your Wazuh version before deploying.

🔒 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