# Wazuh SIEM Integration Guide

SoulEyez integrates with Wazuh SIEM to provide **Detection Validation** - automatically correlating your penetration test attacks with security alerts to identify detection gaps in your client's security monitoring infrastructure.

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Configuration](#configuration)
4. [Detection Validation](#detection-validation)
5. [Attack Signatures](#attack-signatures)
6. [Agent Configuration](#agent-configuration)
7. [Troubleshooting](#troubleshooting)
8. [Best Practices](#best-practices)

---

## Overview

### What is Detection Validation?

Detection Validation answers the critical question: **"Did the target's security monitoring detect our attack?"**

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   SoulEyez      │     │     Wazuh       │     │    Report       │
│   runs attack   │────▶│   checks for    │────▶│  "SQLi attack   │
│   (SQLi, nmap)  │     │   alerts        │     │   NOT detected" │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

### Key Benefits

- **Automated Correlation**: Automatically match attacks to SIEM alerts
- **Detection Gap Analysis**: Identify what attacks went undetected
- **Coverage Metrics**: Quantify detection coverage (e.g., "67% of attacks detected")
- **Actionable Recommendations**: Suggest missing rules and tuning improvements
- **Professional Reports**: Include detection analysis in client deliverables

### Wazuh Architecture

SoulEyez connects to two Wazuh components:

| Component | Port | Purpose |
|-----------|------|---------|
| **Wazuh Manager API** | 55000 | Authentication, rule queries, agent info |
| **Wazuh Indexer** | 9200 | Alert queries (Elasticsearch-compatible) |

---

## Prerequisites

### Wazuh Requirements

- **Wazuh 4.x** (4.5+ recommended)
- Manager API enabled and accessible
- Indexer (OpenSearch/Elasticsearch) accessible
- API user with appropriate permissions

### Network Requirements

From the SoulEyez host, you need access to:
- `https://<wazuh-manager>:55000` (Manager API)
- `https://<wazuh-manager>:9200` (Indexer API)

### Required Wazuh API Permissions

Create a dedicated API user with these permissions:
- `agents:read` - Query agent information
- `manager:read` - Get manager info and status
- `rules:read` - Read rule definitions
- `alerts:read` - Query alerts (via Indexer)

```bash
# Create API user via Wazuh CLI (on Wazuh Manager)
/var/ossec/bin/wazuh-api-users add souleyez -p 'YourSecurePassword'
```

---

## Configuration

### Initial Setup

1. Navigate to **Mission Control** → **Wazuh Integration** (shortcut: `w`)
2. Select **Configure Wazuh Connection**
3. Enter your Wazuh details:

```
┌─────────────────────────────────────────────────────────────────┐
│ Wazuh SIEM Configuration                                       │
├─────────────────────────────────────────────────────────────────┤
│ Manager API URL:     https://10.0.0.111:55000                   │
│ API Username:        souleyez                                   │
│ API Password:        ••••••••••                                 │
│ Verify SSL:          No (self-signed certs)                     │
│                                                                 │
│ Indexer URL:         https://10.0.0.111:9200  (auto-derived)    │
│ Indexer Username:    admin                                      │
│ Indexer Password:    ••••••••••                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Connection Test

After configuration, test the connection:

```
┌─────────────────────────────────────────────────────────────────┐
│ ✓ Connection Successful                                         │
│                                                                 │
│   Wazuh Version:  4.7.2                                         │
│   Hostname:       wazuh-manager                                 │
│   Cluster:        Disabled                                      │
│   Agents:         5 registered                                  │
└─────────────────────────────────────────────────────────────────┘
```

### Credential Storage

Wazuh credentials are encrypted using the same vault system as other credentials:
- Encrypted with AES-256-GCM
- Protected by your master password
- Stored per-engagement (different clients can have different Wazuh instances)

---

## Detection Validation

### Running Validation

After completing attacks, validate detections:

1. Go to **Mission Control** → **Wazuh Integration**
2. Select **Validate Detections**
3. Choose scope:
   - **Single Job**: Validate a specific attack
   - **Entire Engagement**: Validate all completed attacks

### Understanding Results

Each attack receives a detection status:

| Status | Meaning |
|--------|---------|
| **Detected** | Wazuh generated alerts for this attack |
| **Not Detected** | No matching alerts found - detection gap! |
| **Partial** | Some expected alerts found, but not all |
| **Offline** | Tool runs locally (e.g., hashcat) - no network detection expected |
| **Unknown** | Job failed or Wazuh not configured |

### Coverage Summary

```
┌─────────────────────────────────────────────────────────────────┐
│ Detection Coverage Summary                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ████████████░░░░░░  67%  Detection Rate                       │
│                                                                 │
│   Total Attacks:     18                                         │
│   Detected:          12  ████████████                           │
│   Not Detected:       4  ████  ← GAPS                           │
│   Offline:            2  ██                                     │
│                                                                 │
│ Detection Gaps:                                                 │
│   • sqlmap → 10.0.0.50:443 - No web attack rules triggered      │
│   • gobuster → 10.0.0.50:80 - Directory scan not detected       │
│   • hydra → 10.0.0.50:22 - Brute force not blocked              │
│   • nmap → 10.0.0.50 - Port scan went unnoticed                 │
└─────────────────────────────────────────────────────────────────┘
```

### Viewing Alert Details

For detected attacks, you can drill down to see:
- Matched Wazuh rule IDs
- Alert timestamps
- Rule descriptions and severity
- Actual rule XML definitions

---

## Attack Signatures

SoulEyez maps each attack tool to expected Wazuh detection rules.

### Supported Tools

| Tool | Category | Expected Wazuh Rules |
|------|----------|---------------------|
| **nmap** | Reconnaissance | 5700, 5701, 5702, 5710 |
| **hydra** | Credential Access | 5551, 5710, 5712, 5720, 5763-5765 |
| **medusa** | Credential Access | 5551, 5710, 5712, 5720 |
| **sqlmap** | Web Attack | 31101, 31103-31106, 31151-31153 |
| **gobuster** | Web Attack | 31100, 31101, 31120-31122 |
| **ffuf** | Web Attack | 31100, 31101, 31120-31122 |
| **nikto** | Web Attack | 31100, 31101, 31151-31154 |
| **crackmapexec** | Lateral Movement | 18104-18106, 5710, 5720 |
| **metasploit** | Exploitation | 87700-87702, 5710, 31101 |
| **hashcat** | Credential Access | *Offline - no detection expected* |
| **john** | Credential Access | *Offline - no detection expected* |

### Detection Windows

Each attack type has a configurable detection window:
- **Port scans (nmap)**: 5 minutes after attack
- **Brute force (hydra)**: 10 minutes after attack
- **Web attacks (sqlmap)**: 5 minutes after attack
- **Exploitation (metasploit)**: 10 minutes after attack

### Viewing Attack Signatures

From **Wazuh Integration** menu:
1. Select **View Attack Signatures**
2. Browse tool categories
3. Select a tool to see expected rules
4. Drill into specific rules to view:
   - Rule ID, level, and description
   - Rule XML source code
   - Detection patterns

---

## Agent Configuration

For optimal detection, Wazuh agents on target systems should be properly configured.

### Linux Agent Configuration

Key settings for Linux endpoints:

```xml
<agent_config os="Linux">
    <!-- Real-time monitoring with whodata (requires auditd) -->
    <syscheck>
        <directories whodata="yes" check_all="yes" report_changes="yes">/home</directories>
        <directories whodata="yes" check_all="yes" report_changes="yes">/etc</directories>
        <directories realtime="yes">/tmp</directories>
    </syscheck>

    <!-- Authentication logs -->
    <localfile>
        <log_format>syslog</log_format>
        <location>/var/log/auth.log</location>
    </localfile>

    <!-- Suricata IDS (if installed) -->
    <localfile>
        <log_format>json</log_format>
        <location>/var/log/suricata/eve.json</location>
    </localfile>
</agent_config>
```

**Requirements for whodata:**
```bash
sudo apt install auditd
sudo systemctl enable auditd
```

### macOS Agent Configuration

Key settings for macOS endpoints:

```xml
<agent_config os="Darwin">
    <!-- Real-time monitoring (FSEvents) -->
    <syscheck>
        <directories check_all="yes" realtime="yes">/Applications</directories>
        <directories check_all="yes" realtime="yes">/Users/*/Downloads</directories>
        <!-- Persistence locations -->
        <directories check_all="yes">/Library/LaunchAgents</directories>
        <directories check_all="yes">/Library/LaunchDaemons</directories>
    </syscheck>

    <!-- macOS Unified Logging -->
    <localfile>
        <log_format>full_command</log_format>
        <command>log show --predicate 'subsystem == "com.apple.securityd"' --style syslog --last 5m</command>
        <alias>macOS Security Events</alias>
        <frequency>300</frequency>
    </localfile>
</agent_config>
```

### Windows Agent Configuration

Key settings for Windows endpoints:

```xml
<agent_config os="Windows">
    <!-- File integrity with whodata (requires audit policy) -->
    <syscheck>
        <directories whodata="yes">C:\Users\*\Downloads</directories>
        <directories whodata="yes">%PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\Startup</directories>

        <!-- Registry monitoring for persistence -->
        <windows_registry arch="both">HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run</windows_registry>
        <windows_registry arch="both">HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run</windows_registry>
    </syscheck>

    <!-- Windows Event Logs -->
    <localfile>
        <location>Security</location>
        <log_format>eventchannel</log_format>
    </localfile>

    <localfile>
        <location>Microsoft-Windows-PowerShell/Operational</location>
        <log_format>eventchannel</log_format>
    </localfile>

    <localfile>
        <location>Microsoft-Windows-Sysmon/Operational</location>
        <log_format>eventchannel</log_format>
    </localfile>
</agent_config>
```

**Requirements for whodata:**
```cmd
auditpol /set /subcategory:"Object Access" /success:enable /failure:enable
```

### Wazuh Manager Configuration

Ensure the manager has these features enabled:

```xml
<ossec_config>
    <!-- Vulnerability detection -->
    <vulnerability-detection>
        <enabled>yes</enabled>
        <index-status>yes</index-status>
        <feed-update-interval>60m</feed-update-interval>
    </vulnerability-detection>

    <!-- Indexer connection -->
    <indexer>
        <enabled>yes</enabled>
        <hosts>
            <host>https://10.0.0.111:9200</host>
        </hosts>
    </indexer>

    <!-- Active responses (optional) -->
    <active-response>
        <command>firewall-drop</command>
        <location>local</location>
        <rules_id>5710</rules_id>
        <timeout>600</timeout>
    </active-response>
</ossec_config>
```

---

## Troubleshooting

### Connection Issues

**Error: "Connection failed"**
```
Cause: Cannot reach Wazuh Manager API
Fix:
  1. Verify network connectivity: curl -k https://10.0.0.111:55000
  2. Check firewall rules allow port 55000
  3. Ensure Wazuh API is running: systemctl status wazuh-api
```

**Error: "Auth failed: 401 Unauthorized"**
```
Cause: Invalid credentials or vault locked
Fix:
  1. Verify credentials are correct
  2. Unlock vault: Settings → Security → Unlock Vault
  3. Re-enter Wazuh credentials
```

**Error: "SSL certificate verify failed"**
```
Cause: Self-signed certificate
Fix: Set "Verify SSL" to No in configuration
```

### Detection Issues

**Problem: Attacks show "Not Detected" but alerts exist**
```
Possible causes:
  1. Time sync issue - Wazuh and attack host clocks differ
  2. Wrong agent IP - Alerts logged under different IP
  3. Detection window too short - Increase window in attack signatures

Fix:
  1. Sync time: sudo ntpdate pool.ntp.org
  2. Verify attack source IP matches agent IP in alerts
  3. Manually search Wazuh for alerts in wider time range
```

**Problem: No alerts in Wazuh at all**
```
Possible causes:
  1. Wazuh rules not enabled for attack type
  2. Agent not forwarding logs
  3. Indexer not receiving data

Fix:
  1. Enable relevant rule groups in Wazuh
  2. Check agent status: /var/ossec/bin/agent_control -l
  3. Verify indexer: curl -k https://10.0.0.111:9200/_cat/indices
```

### Vault/Encryption Issues

**Error: "Failed to decrypt Wazuh credentials"**
```
Cause: Vault is locked or master password changed
Fix:
  1. Unlock vault with current master password
  2. If password changed, re-configure Wazuh credentials
```

---

## Best Practices

### Before the Engagement

1. **Configure Wazuh connection** in SoulEyez before starting attacks
2. **Test the connection** to ensure API access works
3. **Verify agent deployment** on target systems
4. **Sync time** between attack host and Wazuh/targets

### During the Engagement

1. **Run attacks from consistent IP** so Wazuh can correlate
2. **Document attack times** for manual verification
3. **Periodically validate detections** to catch issues early

### After the Engagement

1. **Generate detection coverage report** for client
2. **Highlight detection gaps** with recommendations
3. **Include rule tuning suggestions** based on gaps

### Recommended Wazuh Rules

Ensure these rule groups are enabled for comprehensive detection:

| Rule Group | Purpose | Rules |
|------------|---------|-------|
| sshd_rules | SSH brute force | 5700-5765 |
| web_rules | Web attacks | 31100-31199 |
| apache_rules | Apache attacks | 30100-30399 |
| nginx_rules | Nginx attacks | 31300-31399 |
| syslog_rules | System events | 1000-1999 |
| ids_rules | IDS/Suricata | 86000-86999 |
| attack_rules | Generic attacks | 87700-87799 |

### Detection Gap Recommendations

When attacks go undetected, consider:

1. **Enable missing rule groups** - Many rules disabled by default
2. **Lower thresholds** - E.g., detect after 3 failed logins instead of 10
3. **Add custom rules** - Create rules for specific attack patterns
4. **Deploy Suricata/Snort** - Network-level IDS complements host-based
5. **Enable PowerShell logging** - Critical for Windows attacks
6. **Install Sysmon** - Enhanced Windows event logging

---

## Quick Reference

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `w` | Open Wazuh Integration menu (from Mission Control) |

### Menu Options

| Option | Description |
|--------|-------------|
| Configure Connection | Set up Wazuh API credentials |
| Test Connection | Verify connectivity |
| Validate Detections | Correlate attacks with alerts |
| View Attack Signatures | Browse expected detection rules |
| Detection Coverage | View engagement-wide statistics |

### API Endpoints Used

| Endpoint | Purpose |
|----------|---------|
| `POST /security/user/authenticate` | Get JWT token |
| `GET /manager/info` | Test connection |
| `GET /agents` | List monitored agents |
| `GET /rules` | Query rule definitions |
| `GET /rules/files/{filename}` | Get rule XML source |
| `POST /wazuh-alerts-*/_search` | Query alerts (Indexer) |

---

## Support

For issues with Wazuh integration:
1. Check this guide's [Troubleshooting](#troubleshooting) section
2. Review Wazuh logs: `/var/ossec/logs/ossec.log`
3. Report bugs: https://github.com/anthropics/claude-code/issues
