# Wazuh SIEM Integration Guide

SoulEyez integrates with Wazuh SIEM to provide comprehensive security monitoring capabilities:
- **Detection Validation** - Correlate attacks with SIEM alerts to identify detection gaps
- **Vulnerability Management** - Sync and track CVEs from Wazuh's vulnerability scanner
- **Gap Analysis** - Compare passive Wazuh detection vs active scan findings

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Configuration](#configuration)
4. [Detection Validation](#detection-validation)
5. [Wazuh Vulnerabilities](#wazuh-vulnerabilities)
6. [Gap Analysis](#gap-analysis)
7. [Host Mapping](#host-mapping)
8. [Attack Signatures](#attack-signatures)
9. [Agent Configuration](#agent-configuration)
10. [Troubleshooting](#troubleshooting)
11. [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

---

## Wazuh Vulnerabilities

Wazuh includes a **Vulnerability Detection** module that continuously scans agents for known CVEs. SoulEyez syncs this data to provide a unified view of passive vulnerabilities alongside your active scan findings.

### How It Works

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Wazuh Agent   │     │  Wazuh Manager  │     │    SoulEyez     │
│  scans packages │────▶│  correlates to  │────▶│   syncs CVEs    │
│  on endpoint    │     │  CVE databases  │     │   to database   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

Wazuh's vulnerability scanner:
- Inventories installed packages on each agent
- Correlates with NVD, Red Hat, Ubuntu, Debian CVE feeds
- Updates automatically as new CVEs are published
- Provides CVSS scores and severity ratings

### Accessing Wazuh Vulnerabilities

From **Mission Control** → **Wazuh Integration** → **Wazuh Vulnerabilities**

Or directly from Attack Surface view:
- Select a host → View Host Detail → **[w] View all Wazuh vulns**

### Syncing Vulnerabilities

Before viewing vulnerabilities, sync data from Wazuh:

1. Go to **Wazuh Vulnerabilities** menu
2. Select **[s] Sync from Wazuh**
3. Wait for sync to complete

```
┌─────────────────────────────────────────────────────────────────┐
│ Sync Complete                                                    │
├─────────────────────────────────────────────────────────────────┤
│   Total fetched:     847 vulnerabilities                        │
│   New:               215                                        │
│   Updated:           632                                        │
│   Mapped hosts:      5                                          │
│   Unmapped agents:   0                                          │
│   Duration:          12.3 seconds                               │
└─────────────────────────────────────────────────────────────────┘
```

The sync operation:
- Fetches all vulnerabilities from Wazuh Indexer (`wazuh-states-vulnerabilities-*` index)
- Retrieves agent IP addresses from the Manager API
- Stores CVE data with package info, severity, and CVSS scores
- Auto-maps Wazuh agents to SoulEyez hosts by IP address

### Viewing Vulnerabilities

**All Vulnerabilities View:**
```
┌─────────────────────────────────────────────────────────────────┐
│ Wazuh Vulnerabilities - All (847 total)                         │
├─────────────────────────────────────────────────────────────────┤
│   CVE ID            Agent         Package           Severity    │
│   ───────────────── ───────────── ───────────────── ─────────── │
│   CVE-2024-38428    yoda          wget 1.21.3       Critical    │
│   CVE-2023-52425    soul          expat 2.5.0       High        │
│   CVE-2024-2961     mama          glibc 2.35        High        │
│   CVE-2023-4911     soul          glibc 2.35        High        │
│   CVE-2024-6387     yoda          openssh 8.9p1     High        │
│   ...                                                           │
├─────────────────────────────────────────────────────────────────┤
│   n/p: Next/Previous page | [f] Filter | [i] Interactive        │
│   [c] Critical only | [h] High+ | [b] Back                      │
└─────────────────────────────────────────────────────────────────┘
```

**Filtering Options:**
- **By Severity**: Critical only, High and above, or all
- **By Agent**: View vulnerabilities for specific Wazuh agent
- **By CVE**: Search for specific CVE ID
- **By Package**: Filter by affected package name

**Vulnerability Detail View:**
```
┌─────────────────────────────────────────────────────────────────┐
│ CVE-2024-6387 - regreSSHion                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Severity:        High                                         │
│   CVSS Score:      8.1 (v3.1)                                   │
│   Package:         openssh-server 8.9p1                         │
│   Agent:           yoda (10.0.0.50)                             │
│   Detected:        2024-07-01 14:23:00                          │
│   Published:       2024-07-01                                   │
│                                                                 │
│   Description:                                                  │
│   Race condition in sshd signal handler allows unauthenticated  │
│   remote code execution on glibc-based Linux systems.           │
│                                                                 │
│   References:                                                   │
│   • https://nvd.nist.gov/vuln/detail/CVE-2024-6387              │
│   • https://www.qualys.com/2024/07/01/cve-2024-6387/regresshion │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Wazuh Vulns in Host Detail

When viewing a host in Attack Surface, Wazuh vulnerabilities appear automatically:

```
┌─────────────────────────────────────────────────────────────────┐
│ Host Detail: 10.0.0.50 (yoda)                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ WAZUH VULNERABILITIES                                           │
│ ─────────────────────────────────────────────────────────────── │
│   3 Critical | 12 High | 28 Medium | 45 Low                     │
│                                                                 │
│   Top Critical:                                                 │
│   • CVE-2024-38428 - wget: mishandled semicolons (CVSS 9.1)     │
│   • CVE-2024-6387 - openssh: regreSSHion RCE (CVSS 8.1)         │
│   • CVE-2023-4911 - glibc: Looney Tunables (CVSS 7.8)           │
│                                                                 │
│   [w] View all Wazuh vulns                                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Wazuh Indexer Requirements

For vulnerability sync to work, your Wazuh Indexer must have:
- Vulnerability Detection enabled on the Manager
- The `wazuh-states-vulnerabilities-*` index populated
- Indexer credentials configured in SoulEyez

Test indexer access from **Wazuh Integration** → **Test Vulnerability Index**.

---

## Gap Analysis

Gap Analysis compares vulnerabilities found by **Wazuh passive scanning** against those discovered during **active penetration testing**. This reveals critical gaps where one method found vulnerabilities the other missed.

### Why Gap Analysis Matters

| Scenario | Implication |
|----------|-------------|
| **Wazuh found it, scan didn't** | Passive detection works, but pentest missed it (scope issue?) |
| **Scan found it, Wazuh didn't** | Active testing revealed what passive monitoring missed (detection gap!) |
| **Both found it** | Confirmed vulnerability - high confidence |
| **Neither found it** | Unknown vulnerabilities may exist |

### Running Gap Analysis

1. Go to **Mission Control** → **Wazuh Integration** → **Gap Analysis**
2. Or from **Wazuh Vulnerabilities** menu → **Gap Analysis**

The analysis automatically:
- Matches Wazuh CVEs to scan findings by CVE ID
- Groups vulnerabilities by host (using IP mapping)
- Categorizes into Wazuh-only, Scan-only, and Confirmed

### Gap Analysis Views

**Summary Dashboard:**
```
┌─────────────────────────────────────────────────────────────────┐
│ Gap Analysis Summary                                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Wazuh Only:      124 CVEs  ████████████                       │
│   Scan Only:        38 CVEs  ████                               │
│   Confirmed:        67 CVEs  ███████                            │
│                                                                 │
│   Detection Coverage:                                           │
│   ████████████████░░░░  76%  (of scan findings in Wazuh)        │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│   [1] Wazuh Only    [2] Scan Only    [3] Confirmed              │
│   [4] Actionable Gaps (prioritized)                             │
└─────────────────────────────────────────────────────────────────┘
```

**Wazuh Only View:**

Vulnerabilities Wazuh detected but active scans missed:
```
┌─────────────────────────────────────────────────────────────────┐
│ Wazuh Only - 124 vulnerabilities                                │
├─────────────────────────────────────────────────────────────────┤
│   CVE ID            Host          Package           Severity    │
│   ───────────────── ───────────── ───────────────── ─────────── │
│   CVE-2024-38428    10.0.0.50     wget 1.21.3       Critical    │
│   CVE-2023-52425    10.0.0.51     expat 2.5.0       High        │
│   ...                                                           │
└─────────────────────────────────────────────────────────────────┘
```

These may indicate:
- Scan scope was too narrow
- Scan tools don't check certain package vulns
- Wazuh has broader coverage (good!)

**Scan Only View:**

Vulnerabilities active scans found but Wazuh missed:
```
┌─────────────────────────────────────────────────────────────────┐
│ Scan Only - 38 vulnerabilities                                  │
├─────────────────────────────────────────────────────────────────┤
│   CVE ID            Host          Tool              Severity    │
│   ───────────────── ───────────── ───────────────── ─────────── │
│   CVE-2024-1234     10.0.0.50     nuclei            High        │
│   CVE-2023-5678     10.0.0.51     nmap              Medium      │
│   ...                                                           │
└─────────────────────────────────────────────────────────────────┘
```

**These are detection gaps!** Wazuh should have found these. Investigate:
- Is vulnerability detection enabled for those agents?
- Are the packages being inventoried?
- Is the Wazuh CVE feed up to date?

**Confirmed View:**

Vulnerabilities found by both methods - high confidence:
```
┌─────────────────────────────────────────────────────────────────┐
│ Confirmed - 67 vulnerabilities                                  │
├─────────────────────────────────────────────────────────────────┤
│   CVE ID            Host          Wazuh Pkg     Scan Tool       │
│   ───────────────── ───────────── ───────────── ─────────────── │
│   CVE-2024-6387     10.0.0.50     openssh 8.9   nuclei          │
│   CVE-2023-4911     10.0.0.51     glibc 2.35    nmap            │
│   ...                                                           │
└─────────────────────────────────────────────────────────────────┘
```

**Actionable Gaps View:**

Prioritized list of gaps requiring attention:
```
┌─────────────────────────────────────────────────────────────────┐
│ Actionable Gaps - Prioritized                                   │
├─────────────────────────────────────────────────────────────────┤
│ CRITICAL - Scan found, Wazuh missed:                            │
│   • CVE-2024-1234 on 10.0.0.50 - Detection gap!                 │
│                                                                 │
│ HIGH - Wazuh found, scan missed (verify scope):                 │
│   • CVE-2024-38428 on 10.0.0.50 - wget vulnerability            │
│   • CVE-2023-52425 on 10.0.0.51 - expat vulnerability           │
│                                                                 │
│ RECOMMENDATIONS:                                                │
│   1. Verify Wazuh vuln detection is enabled on all agents       │
│   2. Expand scan scope to cover more package-level vulns        │
│   3. Update Wazuh CVE feeds if outdated                         │
└─────────────────────────────────────────────────────────────────┘
```

### Interactive Mode

Press **[i]** in any gap view to enter interactive selection mode:
- Navigate with arrow keys
- Press Enter to view details
- Quick filtering and sorting

---

## Host Mapping

For Gap Analysis to work accurately, Wazuh agents must be mapped to SoulEyez hosts. This allows correlation of vulnerabilities between the two systems.

### How Mapping Works

SoulEyez maps Wazuh agents to hosts by **IP address**:
- Wazuh agent IP (from agent registration)
- SoulEyez host IP (from target scope)

```
Wazuh Agent: "yoda" (10.0.0.50) ──────▶ SoulEyez Host: 10.0.0.50
Wazuh Agent: "mama" (10.0.0.51) ──────▶ SoulEyez Host: 10.0.0.51
Wazuh Agent: "soul" (10.0.0.52) ──────▶ SoulEyez Host: 10.0.0.52
```

### Auto-Mapping

During vulnerability sync, SoulEyez automatically:
1. Fetches agent list from Wazuh (with IPs)
2. Matches agent IPs to host IPs in scope
3. Links vulnerabilities to the correct hosts

### Viewing Mapping Status

After sync, the status shows:
```
Mapped hosts:     5
Unmapped agents:  2  ← These need manual attention
```

### Manual Mapping

If agents have different IPs than scope hosts (e.g., NAT, multiple interfaces):

1. Go to **Wazuh Integration** → **Host Mapping**
2. View unmapped agents
3. Manually map agent to host

```
┌─────────────────────────────────────────────────────────────────┐
│ Unmapped Wazuh Agents                                           │
├─────────────────────────────────────────────────────────────────┤
│   Agent Name    Agent IP        Status                          │
│   ───────────── ─────────────── ────────────────────────────── │
│   web-server    192.168.1.100   Not in scope (private IP)       │
│   db-server     192.168.1.101   Not in scope (private IP)       │
├─────────────────────────────────────────────────────────────────┤
│   Select agent to map to scope host...                          │
└─────────────────────────────────────────────────────────────────┘
```

### Troubleshooting Mapping

**Agent IPs showing as None:**
- Wazuh vulnerability index may not include agent IPs
- SoulEyez syncs agent IPs from the Manager API separately
- Re-run sync to fetch agent IPs

**Agents not mapping:**
- Verify agent IP matches a host in your engagement scope
- Check if agent is using a different interface IP
- Use manual mapping for complex network setups

---

## 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
```

### Vulnerability Sync Issues

**Error: "Vulnerability index not accessible"**
```
Cause: Indexer credentials wrong or vuln detection not enabled
Fix:
  1. Verify Indexer URL and credentials in Wazuh config
  2. Test: curl -k -u admin:pass https://INDEXER:9200/wazuh-states-vulnerabilities-*/_count
  3. Check Wazuh Manager has vulnerability-detection enabled
```

**Problem: Agent IPs showing as None**
```
Cause: Vulnerability index doesn't include agent IP field
Fix:
  1. SoulEyez fetches IPs from /agents endpoint separately
  2. Ensure agents are registered with correct IPs
  3. Re-run sync to update agent IP lookup
```

**Problem: No vulnerabilities synced**
```
Cause: Vulnerability detection not running or empty index
Fix:
  1. Check index exists: GET /wazuh-states-vulnerabilities-*/_count
  2. Verify vuln detection is enabled in ossec.conf
  3. Wait for vulnerability scan cycle to complete (first run may take time)
```

### Gap Analysis Issues

**Problem: No gaps showing despite having data**
```
Cause: Host mapping not established
Fix:
  1. Run vulnerability sync first
  2. Check if agents mapped to hosts (Wazuh Integration → Host Mapping)
  3. Manually map agents if IPs don't match scope hosts
```

**Problem: Few "Confirmed" vulnerabilities**
```
Cause: CVE IDs don't match between Wazuh and scan tools
Fix:
  1. Verify scan tools are identifying CVEs (not just generic vulns)
  2. Check CVE ID format consistency (CVE-YYYY-NNNNN)
  3. Some tools report different CVE formats - manual review may be needed
```

---

## 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
5. **Sync Wazuh vulnerabilities** to establish baseline
6. **Verify host mapping** - ensure agents map to scope hosts

### 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
4. **Re-sync vulnerabilities** periodically to catch new CVEs
5. **Run Gap Analysis** after major scan phases

### After the Engagement

1. **Generate detection coverage report** for client
2. **Highlight detection gaps** with recommendations
3. **Include rule tuning suggestions** based on gaps
4. **Run final Gap Analysis** - compare all Wazuh vs scan findings
5. **Document host mapping** for future engagements

### 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 |
| Host Mapping | Map Wazuh agents to scope hosts |
| Wazuh Vulnerabilities | Sync and view CVEs from Wazuh |
| Gap Analysis | Compare Wazuh vs scan findings |

### API Endpoints Used

| Endpoint | Purpose |
|----------|---------|
| `POST /security/user/authenticate` | Get JWT token |
| `GET /manager/info` | Test connection |
| `GET /agents` | List monitored agents (with IPs) |
| `GET /rules` | Query rule definitions |
| `GET /rules/files/{filename}` | Get rule XML source |
| `POST /wazuh-alerts-*/_search` | Query alerts (Indexer) |
| `POST /wazuh-states-vulnerabilities-*/_search` | Query vulnerabilities (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
