# 🔐 Wazuh SIEM × Claude Desktop — Conversational SOC via MCP

A complete walkthrough of my hands-on cybersecurity project integrating a SIEM with an AI assistant to enable natural-language security operations.

---

## 🎯 Project Overview

This project demonstrates how AI can augment SOC operations by connecting **Wazuh SIEM** to **Claude Desktop** through the **MCP (Model Context Protocol)**, allowing a security analyst to query the SIEM in natural language and receive instant, structured analysis — without manually navigating dashboards.

Slack enrichment is handled both **automatically** (Wazuh native integration, level 7+ alerts) and **on-demand** (via Claude Desktop conversation).

**What I accomplished:**

- ✅ Deployed Wazuh Manager + Indexer on Ubuntu Server VM
- ✅ Connected Windows and Kali Linux agents to the Wazuh Manager
- ✅ Built a Python MCP server exposing 5 tools to Claude Desktop
- ✅ Enabled natural-language querying of alerts, agents, and vulnerabilities
- ✅ Configured automatic Slack notifications for critical alerts (level 7+)
- ✅ Added on-demand AI-enriched Slack reporting from Claude Desktop

---

## 🏗️ Architecture

```
[Physical Machine — Windows 10 — Claude Desktop]
        │
        │ stdio (local subprocess)
        ▼
  wazuh_mcp_server.py  ←── Python MCP Server
        │
        ├── HTTPS :55000 → Wazuh Manager API
        ├── HTTPS :9200  → Wazuh Indexer (OpenSearch)
        └── HTTPS        → Slack Webhook
        │
        ▼
[VM Ubuntu Server — Wazuh Manager + Indexer]
        ▲
        │ Logs / Heartbeat (port 1514)
        ├── [VM Windows — Wazuh Agent]
        └── [VM Kali    — Wazuh Agent]
```

---

## 🛠️ Technical Implementation

### Environment Setup

```
Host OS       : Windows 10 (Claude Desktop + Python MCP Server)
VM 1          : Ubuntu Server — Wazuh Manager 4.11.2 + Wazuh Indexer
VM 2          : Windows 10   — Wazuh Agent
VM 3          : Kali Linux   — Wazuh Agent / Attack simulation
Hypervisor    : VMware
```

### MCP Server — 5 Tools Built

| Tool | Description |
|------|-------------|
| `get_critical_alerts` | Fetch alerts filtered by severity and time range |
| `get_agents_status` | List all agents with status, IP, OS, version |
| `get_vulnerabilities` | CVEs detected per agent, filtered by severity |
| `generate_security_report` | Aggregate alerts + agents + vulns into a full report |
| `send_to_slack` | Post AI-enriched analysis to the SOC Slack channel |

### Natural Language Queries (Examples)

```
"Show me critical alerts from the last 24 hours"
"Which agents have unpatched critical vulnerabilities?"
"Generate a security report with recommendations"
"Send the critical alerts to Slack with an analysis"
```

### Slack Integration

**Automatic** — via Wazuh native integration in `ossec.conf` :
```xml
<integration>
  <name>custom-slack</name>
  <hook_url>https://hooks.slack.com/services/XXX/YYY/ZZZ</hook_url>
  <level>7</level>
  <alert_format>json</alert_format>
</integration>
```

**On-demand** — via `send_to_slack` MCP tool called by Claude Desktop,
posting an AI-generated summary with alert details, severity color coding,
and timestamp directly to the SOC channel.

### Claude Desktop Configuration

```json
{
  "mcpServers": {
    "wazuh": {
      "command": "python",
      "args": ["C:\\wazuh-mcp\\wazuh_mcp_server.py"]
    }
  }
}
```

### Network Ports Required

```bash
sudo ufw allow 55000/tcp   # Wazuh Manager API
sudo ufw allow 9200/tcp    # Wazuh Indexer (OpenSearch)
sudo ufw allow 1514/tcp    # Agent communication
```

---

## 📊 Results & Findings

### What Worked Well

- ✅ Full natural-language SIEM querying in seconds
- ✅ Real-time alert detection (SSH sudo usage, PAM sessions, brute-force attempts)
- ✅ AI-generated security reports with structured recommendations
- ✅ Dual Slack enrichment — automatic + on-demand from Claude Desktop
- ✅ Multi-agent visibility (Ubuntu Manager, Windows agent, Kali agent)

### Key Lessons

- MCP bridges the gap between complex security tools and conversational AI
- Separating authentication systems (Wazuh API vs Indexer) is critical to avoid errors
- AI enrichment reduces the time an analyst spends interpreting raw log data
- Natural-language interfaces lower the barrier to entry for SOC operations

---

## 🔒 Security Notes

- API account used with **read-only scope** (principle of least privilege)
- Secrets managed via `.env` file — never committed to version control
- `WAZUH_VERIFY_SSL=true` recommended in production with valid certificates
- Indexer port 9200 should be restricted to trusted IPs only in production

---

## 🛠️ Skills Demonstrated

**Technical Skills**
- SIEM deployment and configuration (Wazuh)
- Python async development (httpx, MCP SDK)
- REST API integration (JWT authentication, OpenSearch queries)
- Multi-VM network configuration (VMware, bridged networking)
- AI tool integration (Claude Desktop, MCP protocol)
- Slack API (Incoming Webhooks, Block Kit formatting)

**Security Skills**
- Alert triage and severity classification
- Vulnerability management workflow
- SOC operations and incident analysis
- Security report generation

---

## ⚙️ Installation

### Prerequisites
- Python 3.10+
- Wazuh Manager + Indexer (Ubuntu Server)
- Claude Desktop
- Slack Incoming Webhook URL

### Setup

```powershell
git clone https://github.com/cisse-lalya/wazuh-mcp-soc.git
cd wazuh-mcp-soc
pip install -r requirements.txt
copy .env.example .env
notepad .env   # Fill in your Wazuh + Slack credentials
```

### `.env` Configuration

```env
WAZUH_API_URL=https://<WAZUH_VM_IP>:55000
WAZUH_API_USER=wazuh
WAZUH_API_PASSWORD=your_password

WAZUH_INDEXER_URL=https://<WAZUH_VM_IP>:9200
WAZUH_INDEXER_USER=admin
WAZUH_INDEXER_PASSWORD=your_password

WAZUH_VERIFY_SSL=false
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
```

### Test Connection

```powershell
python -c "from dotenv import load_dotenv; load_dotenv(); import asyncio; from wazuh_client import WazuhClient; c=WazuhClient(); print(asyncio.run(c.get_agents_status()))"
```

---

## 🧰 Tech Stack

`Wazuh 4.11.2` · `OpenSearch` · `Claude Desktop` · `MCP Protocol` · `Python 3.13` · `httpx` · `Slack Webhooks` · `VMware` · `Ubuntu Server` · `Windows 10` · `Kali Linux`

---

## 👤 About Me

Cybersecurity student and Junior SOC Analyst, passionate about bridging network operations and security through automation and AI-driven tooling. This project reflects my approach to security: building practical, integrated solutions rather than studying tools in isolation.

**Connect with me:**
- GitHub: [@cisse-lalya](https://github.com/cisse-lalya)
- LinkedIn: [linkedin.com/in/ndeyelalyacisse](https://www.linkedin.com/in/ndeyelalyacisse)