# Wazuh MCP Server

A Python-based Model Context Protocol (MCP) server that exposes **Wazuh security alerts** and agent data to Claude Desktop and other AI assistants.

## What This Does

This server connects to your Wazuh manager and provides Claude with 4 security tools:

| Tool | Purpose | Example |
|------|---------|---------|
| **critical_alerts** | Get critical security events | "Show all critical alerts from today" |
| **investigate_host** | Deep dive into a specific system | "Investigate host web-server-01" |
| **brute_force_detection** | Find login attack attempts | "Which user failed authentication 20 times?" |
| **security_summary** | High-level overview | "Give me a security summary" |

## Quick Start (5 minutes)

### 1. Prerequisites

- **Python 3.8+**
- **Wazuh manager** running and accessible
- **Claude Desktop** installed
- Wazuh manager credentials (default: `wazuh/wazuh`)

### 2. Setup

```bash
# Clone or download this project
cd wazuh-mcp-server

# Run setup script
chmod +x setup.sh
./setup.sh

# Edit configuration
nano .env
# Update WAZUH_HOST to your Wazuh manager IP
```

### 3. Test Connection

```bash
# Activate environment
source venv/bin/activate

# Run connection test
python3 test_connection.py
```

You should see:
```
✓ Connected successfully!
✓ Found 5 agent(s)
✓ Found 23 alert(s)
✅ All tests passed!
```

### 4. Connect to Claude Desktop

Edit `~/.claude/claude_desktop_config.json`:

**macOS/Linux:**
```bash
nano ~/.claude/claude_desktop_config.json
```

**Windows:**
```
notepad %APPDATA%\Claude\claude_desktop_config.json
```

**Add this configuration:**

```json
{
  "mcpServers": {
    "wazuh": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/wazuh_mcp_server/server.py"],
      "env": {
        "WAZUH_HOST": "YOUR_WAZUH_IP",
        "WAZUH_USER": "wazuh",
        "WAZUH_PASS": "wazuh"
      }
    }
  }
}
```

**Get absolute paths:**

```bash
# Python path
which python3
# /Users/yourname/wazuh-mcp-server/venv/bin/python3

# Server path
pwd
# /Users/yourname/wazuh-mcp-server
```

### 5. Restart Claude Desktop

Close and reopen Claude Desktop. You should see "Wazuh Security Tools" in the Tools panel.

### 6. Try It Out

In Claude Desktop, try:

```
Show all critical alerts from the last 24 hours

Which hosts are experiencing high alert rates?

Investigate the database server

Detect any brute force attempts
```

## Project Structure

```
wazuh-mcp-server/
├── server.py                 # Main MCP server (FastMCP)
├── wazuh_client.py          # Wazuh API client
├── requirements.txt         # Python dependencies
├── .env.example            # Configuration template
├── setup.sh                # Automated setup script
├── test_connection.py      # Connection verification
└── README.md               # This file
```

## Configuration

Edit `.env` to customize:

```env
WAZUH_HOST=192.168.1.100    # Your Wazuh manager IP
WAZUH_USER=wazuh            # API username
WAZUH_PASS=wazuh            # API password
```

## Troubleshooting

### "Connection refused" or "Network error"

```bash
# Check Wazuh manager is running
ssh user@wazuh-ip
sudo systemctl status wazuh-manager

# Verify API port is open
curl -k https://YOUR_WAZUH_IP:55000/security/user/authenticate \
  -u wazuh:wazuh
```

### Claude Desktop doesn't show the tools

1. **Check config syntax:**
   ```bash
   python3 -c "import json; json.load(open(expanduser('~/.claude/claude_desktop_config.json')))"
   # Should return no errors
   ```

2. **Check absolute paths:**
   - Don't use `~/` or `.` in the config
   - Use full paths like `/Users/name/...`

3. **Check logs:**
   ```bash
   tail -f ~/Library/Logs/Claude/mcp-server.log  # macOS
   # or check Windows Event Viewer for Claude Desktop
   ```

4. **Restart Claude Desktop:**
   - Close completely
   - Reopen
   - Wait 5 seconds for MCP to connect

### "Authentication failed"

```bash
# Verify credentials by testing directly
curl -k https://WAZUH_IP:55000/security/user/authenticate \
  -u wazuh:wazuh -X GET

# If 401: wrong credentials
# If 404: endpoint doesn't exist (Wazuh version issue)
# If timeout: firewall blocking
```

## Advanced

### Custom Wazuh Queries

The `wazuh_client.py` supports arbitrary queries:

```python
from wazuh_client import WazuhClient

wazuh = WazuhClient("192.168.1.100")

# Search by rule group
alerts = wazuh.search_logs("rule.group=auth_failure")

# Search by agent
alerts = wazuh.search_logs("agent.name=web-server")

# Search by source IP
alerts = wazuh.search_logs("data.srcip=192.168.1.50")

# Search by user
alerts = wazuh.search_logs("data.user=root")
```

### Adding More Tools

Edit `server.py` and add a new `@app.tool()`:

```python
@app.tool()
async def my_new_tool(param1: str) -> str:
    """
    Tool description shown to Claude.
    
    Args:
        param1: Parameter description
    
    Returns:
        JSON string with results
    """
    # Your code here
    return json.dumps({"result": "..."})
```

### Production Considerations

- ✅ Use SSL certificates (not self-signed)
- ✅ Store credentials in HashiCorp Vault or AWS Secrets
- ✅ Rate limit MCP server to prevent abuse
- ✅ Enable audit logging on Wazuh API
- ✅ Create dedicated read-only API user
- ✅ Use network segmentation to isolate Wazuh

## Security Notes

⚠️ **For Development/Learning:**
- Default credentials are `wazuh/wazuh`
- SSL verification disabled (dev mode)
- Credentials in plaintext in `.env`

**For Production:**
- Change Wazuh credentials immediately
- Use proper SSL certificates
- Store credentials in secure vault
- Create read-only API user with minimal permissions
- Audit all API access
- Network firewall rules to restrict access

## API Reference

### WazuhClient Methods

```python
# Get alerts
wazuh.get_alerts(level=7, hours=24, limit=100, agent_id=None)

# Get all agents
wazuh.get_agents()

# Get agent details
wazuh.get_agent_details(agent_id="001")

# Search alerts
wazuh.search_logs(query="rule.id=100001", hours=24, limit=50)

# Get alert groups
wazuh.get_alert_groups(hours=24)
```

## Learning Resources

- [Wazuh Official Docs](https://documentation.wazuh.com/)
- [Wazuh API Reference](https://documentation.wazuh.com/current/api/index.html)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlouis/fastmcp)

## Support

For issues:
1. Run `test_connection.py` to diagnose
2. Check Wazuh logs: `tail -f /var/ossec/logs/ossec.log`
3. Review Claude Desktop logs
4. Verify network connectivity between your machine and Wazuh manager

## License

MIT

## Changelog

**v1.0.0** (2026-01-02)
- Initial release
- 4 core tools: critical_alerts, investigate_host, brute_force_detection, security_summary
- Full Wazuh API client
- Claude Desktop integration
- Comprehensive setup guide

---

**Built for learning and security automation** 🔍