Comprehensive Wazuh Architecture: High-Level Overview and Codebase Deep Dive

Table of Contents#

Introduction#

This document provides a comprehensive overview of the Wazuh security platform (v4.11.2), including its high-level architecture, component relationships, data flows, codebase organization, and security considerations. Wazuh is an open-source security monitoring solution that provides threat detection, integrity monitoring, incident response, and compliance capabilities.

System Architecture#

The Wazuh security monitoring platform consists of several interconnected components that work together to provide comprehensive security monitoring capabilities:

1
graph TB
2
    subgraph "Endpoints"
3
        A1[Wazuh Agent<br/>Linux/Windows/macOS]
4
        A2[Wazuh Agent<br/>Containers]
5
        A3[Wazuh Agent<br/>Cloud Instances]
6
    end
7

8
    subgraph "Central Components"
9
        LB[Load Balancer<br/>Optional]
10

11
        subgraph "Wazuh Manager"
12
            LC[Log Collector]
13
            CF[Core Framework]
14
            RD[Rules & Decoders]
15
            API[RESTful API]
16
            FB[Filebeat Integration]
17

18
            subgraph "Wodles"
19
                W1[Syscheck]
20
                W2[Vulnerability<br/>Detector]
21
                W3[CIS-CAT]
22
                W4[Command<br/>Execution]
23
                W5[osquery]
24
            end
25
        end
26
    end
27

28
    subgraph "Storage & Visualization"
29
        ES[Elasticsearch/<br/>OpenSearch]
30
        WD[Wazuh Dashboard]
31
    end
32

33
    A1 -->|TLS| LB
34
    A2 -->|TLS| LB
35
    A3 -->|TLS| LB
36
    LB --> LC
37

38
    LC --> CF
39
    CF --> RD
40
    CF --> W1
41
    CF --> W2
42
    CF --> W3
43
    CF --> W4
44
    CF --> W5
45

46
    RD --> API
47
    API --> WD
48
    FB --> ES
49
    WD --> ES
50

51
    style A1 fill:#e1f5fe
52
    style A2 fill:#e1f5fe
53
    style A3 fill:#e1f5fe
54
    style CF fill:#fff9c4
55
    style ES fill:#f3e5f5
56
    style WD fill:#e8f5e9

Component Descriptions#

External Components#

Wazuh Agent#

Purpose: Lightweight security monitor deployed on endpoints (servers, workstations, containers)
Functions:
- Collects system logs, application logs, and security events
- Performs file integrity monitoring and security configuration assessment
- Executes active response actions
- Communicates with the Wazuh Manager using an encrypted channel (TLS)

Load Balancer (Optional)#

Purpose: Distributes agent connections across multiple Wazuh Managers
Benefits: Provides high availability and scalability for large-scale deployments
Implementation: Typically uses HAProxy, Nginx, or cloud-based load balancers

Wazuh Dashboard#

Purpose: Web-based user interface for visualization and management
Features:
- Real-time alert visualization
- Compliance dashboards
- Agent management interface
- Rule and decoder configuration
Technology: Built on OpenSearch Dashboards or modified Kibana

Indexer/Storage#

Purpose: Elasticsearch or OpenSearch for storing and indexing security events
Capabilities:
- Fast search across large volumes of security data
- Historical analysis and trending
- Data retention policies
- Integration with visualization tools

Central Components (Wazuh Manager)#

Log Collector#

Function: Receives and decodes logs from agents
Processing: Initial parsing and normalization of events
Output: Prepares events for processing by the core framework

Core Framework#

Role: Central event processing engine
Features:
- Event pipeline management
- Module coordination
- Common utilities and libraries
- Memory and resource management

Rules & Decoders#

Decoders: Extract relevant fields from raw logs
Rules: Match patterns to identify security events
Format: XML-based configuration files
Customization: Supports custom rules for specific security use cases

Dynamic Modules (“Wodles”)#

Specialized security modules that extend functionality:

Syscheck: File integrity monitoring (FIM)
Vulnerability Detector: CVE scanning and vulnerability assessment
CIS-CAT: Compliance assessment against CIS benchmarks
Command Execution: Active response and remediation actions
osquery: Advanced endpoint queries using Facebook’s osquery

RESTful API#

Purpose: Provides programmatic access to the Wazuh Manager
Functions:
- Agent management (registration, status, configuration)
- Rule and decoder management
- Alert queries and statistics
- System configuration
Security: Token-based authentication, HTTPS encryption

Filebeat Integration#

Purpose: Forwards alerts to the indexer (Elasticsearch/OpenSearch)
Features:
- Reliable delivery with acknowledgments
- Data buffering during indexer outages
- Lightweight resource usage

Security Data Flow#

The security data flow in Wazuh follows this sequence:

1
sequenceDiagram
2
    participant Agent as Wazuh Agent
3
    participant Manager as Wazuh Manager
4
    participant Indexer as Elasticsearch/OpenSearch
5
    participant Dashboard as Wazuh Dashboard
6
    participant Admin as Administrator
7

8
    Agent->>Agent: Collect logs & events
9
    Agent->>Manager: Send encrypted data (TLS)
10
    Manager->>Manager: Decode & analyze events
11
    Manager->>Manager: Apply rules & generate alerts
12
    Manager->>Indexer: Forward alerts via Filebeat
13
    Indexer->>Indexer: Index and store data
14
    Admin->>Dashboard: Access web interface
15
    Dashboard->>Indexer: Query security data
16
    Indexer->>Dashboard: Return results
17
    Dashboard->>Admin: Display visualizations
18
    Admin->>Dashboard: Update configurations
19
    Dashboard->>Manager: Apply changes via API
20
    Manager->>Agent: Push new configurations

Data Collection: Agents collect logs and security events from endpoints
Secure Transport: Data is sent to the Manager using TLS encryption
Event Processing: The Manager processes events through its analysis pipeline
Alert Generation: Matching events trigger alerts based on rule definitions
Data Indexing: Alerts and events are stored in Elasticsearch/OpenSearch
Visualization: The Dashboard queries and displays security information
Management: Configuration changes flow from Dashboard through API to Agents

Deployment Models#

Small Deployment#

For small environments (< 50 agents):

Single Wazuh Manager server
Elasticsearch/OpenSearch on the same server
Wazuh Dashboard co-located
Suitable for testing and small production environments

Distributed Deployment#

For large environments (> 100 agents):

Multiple Wazuh Managers in cluster mode
Dedicated Elasticsearch/OpenSearch cluster
Load balancer for agent connections
Separate Dashboard servers
High availability configuration

Wazuh Codebase Architecture#

Codebase Organization#

The Wazuh codebase is organized into several major directories:

1
wazuh/
2
├── src/                    # Core C codebase
3
│   ├── analysisd/         # Event analysis daemon
4
│   ├── remoted/           # Remote daemon (agent communication)
5
│   ├── syscheckd/         # File integrity monitoring
6
│   ├── wazuh_modules/     # Wazuh modules framework
7
│   ├── shared/            # Common libraries
8
│   ├── headers/           # Shared header files
9
│   ├── monitord/          # Monitoring daemon
10
│   └── os_*/              # OS-specific libraries
11
├── framework/             # Python framework
12
│   ├── core/              # Core Python libraries
13
│   ├── wazuh/             # Main Wazuh Python package
14
│   └── scripts/           # Utility scripts
15
├── api/                   # RESTful API
16
│   ├── framework/         # API framework code
17
│   └── scripts/           # API scripts
18
├── ruleset/               # Rules and decoders
19
│   ├── rules/             # XML rule definitions
20
│   ├── decoders/          # XML decoder definitions
21
│   └── lists/             # CDB list files
22
├── wodles/                # Wazuh modules
23
│   ├── aws/               # AWS integration
24
│   ├── azure/             # Azure integration
25
│   ├── gcp/               # GCP integration
26
│   ├── docker/            # Docker monitoring
27
│   └── oscap/             # OpenSCAP integration
28
├── integrations/          # External integrations
29
│   ├── virustotal/        # VirusTotal integration
30
│   ├── pagerduty/         # PagerDuty integration
31
│   └── slack/             # Slack notifications
32
└── tests/                 # Test suite

Manager Component Architecture#

1
graph TB
2
    subgraph "Wazuh Manager Codebase"
3
        subgraph "Core Daemons (C)"
4
            AD[analysisd<br/>Event Analysis]
5
            RD[remoted<br/>Agent Communication]
6
            SD[syscheckd<br/>FIM]
7
            MD[monitord<br/>System Monitor]
8
        end
9

10
        subgraph "Shared Libraries"
11
            SL[shared/<br/>Common Functions]
12
            OS[os_*/<br/>OS Abstractions]
13
            HD[headers/<br/>Definitions]
14
        end
15

16
        subgraph "Modules Framework"
17
            WM[wazuh_modules/<br/>Module Core]
18
            WD[wodles/<br/>Module Implementations]
19
        end
20

21
        subgraph "Management Layer (Python)"
22
            FW[framework/<br/>Python Core]
23
            AP[api/<br/>RESTful API]
24
            SC[scripts/<br/>Utilities]
25
        end
26

27
        subgraph "Configuration"
28
            RL[ruleset/<br/>Rules & Decoders]
29
            CF[etc/<br/>Config Files]
30
        end
31
    end
32

33
    AD --> SL
34
    RD --> SL
35
    SD --> SL
36
    MD --> SL
37

38
    WM --> WD
39
    WM --> SL
40

41
    FW --> AD
42
    FW --> RD
43
    AP --> FW
44

45
    AD --> RL
46

47
    style AD fill:#ffebee
48
    style RD fill:#e3f2fd
49
    style SD fill:#f3e5f5
50
    style FW fill:#fff9c4
51
    style AP fill:#e8f5e9

Event Processing Workflow#

1
flowchart LR
2
    subgraph "Event Processing Pipeline"
3
        A[Log Reception<br/>remoted] --> B[Decoding<br/>analysisd/decoders]
4
        B --> C[Pre-decoding<br/>analysisd/cleanevent]
5
        C --> D[Rule Matching<br/>analysisd/rules]
6
        D --> E[Alert Generation<br/>analysisd/alerts]
7
        E --> F[Output<br/>Filebeat/API]
8

9
        D --> G[Correlation<br/>analysisd/accumulate]
10
        G --> E
11

12
        D --> H[Active Response<br/>analysisd/active-response]
13
    end
14

15
    style A fill:#e3f2fd
16
    style D fill:#ffebee
17
    style E fill:#e8f5e9

Core Components Detailed#

Analysisd (Event Analysis Engine)#

Key source files:

analysisd/analysisd.c - Main daemon initialization
analysisd/decoder.c - Log message decoding logic
analysisd/rules.c - Rule matching engine
analysisd/eventinfo.c - Event information structure
analysisd/accumulate.c - Event correlation
analysisd/alerts.c - Alert generation and formatting
analysisd/lists.c - CDB list handling

Remoted (Agent Communication)#

Key source files:

remoted/remoted.c - Main daemon initialization
remoted/manager.c - Agent management
remoted/secure.c - Secure communication
remoted/sendmsg.c - Message sending to agents
remoted/netbuffer.c - Network buffer management

Wazuh Modules Framework#

Key source files:

wazuh_modules/wmodules.c - Main module initialization
wazuh_modules/wm_control.c - Module control interface
wazuh_modules/wm_threadpool.c - Thread pool implementation
Individual modules in wodles/ directory

Security Considerations#

Authentication & Authorization#

Agent Authentication: TLS client certificates for agent-manager authentication
User Authentication: Strong authentication for dashboard users
API Security: Token-based authentication with role-based access control
Key Management: Secure storage and rotation of authentication keys

Encryption#

Transport Security: TLS 1.2+ for all communications
Certificate Management: Proper certificate rotation and validation
Data at Rest: Encryption for sensitive data in the indexer
Key Storage: Hardware security modules (HSM) for production environments

Integrity Verification#

Binary Integrity: Verify agent binary signatures
Configuration Signing: Digital signatures for configurations
Rule Updates: Checksums for ruleset updates
Secure Boot: Where supported by the platform

Network Security#

Network Segmentation: Separate management and monitoring networks
Firewall Rules: Restrict communication to necessary ports
VPN Integration: Support for remote agents over VPN
Traffic Analysis: Monitor for anomalous communication patterns

Regular Updates#

Component Updates: Keep all components current
Security Patches: Apply patches within defined SLAs
Rule Updates: Regular updates to detection rules
Threat Intelligence: Integration with threat feeds

Integration Points#

Wazuh provides several integration points for extending its capabilities:

RESTful API#

Custom management tools and automation
Integration with ticketing systems
Automated response workflows
Custom dashboards and reporting

Custom Rules and Decoders#

Organization-specific detection logic
Proprietary log format parsing
Business logic security rules
Compliance-specific checks

Alert Integration#

SIEM platforms
SOAR (Security Orchestration, Automation, and Response)
Ticketing systems (ServiceNow, Jira)
Communication platforms (Slack, Teams)

Custom Modules (Wodles)#

Cloud provider integrations
Custom vulnerability scanners
Specialized compliance checks
Third-party security tools

Performance Optimization#

Manager Optimization#

Rule Optimization: Organize rules by frequency and complexity
Decoder Efficiency: Use parent-child decoder relationships
Memory Management: Configure appropriate memory limits
Thread Tuning: Adjust worker threads based on load

Storage Optimization#

Index Management: Implement index lifecycle policies
Data Retention: Define retention based on compliance needs
Shard Strategy: Optimize shard count and size
Query Performance: Use appropriate field mappings

Network Optimization#

Compression: Enable compression for agent communication
Batch Processing: Configure appropriate batch sizes
Connection Pooling: Optimize connection pool settings
Geographic Distribution: Deploy regional managers

Troubleshooting Guide#

Common Issues#

Agent Connection Problems#

Verify network connectivity
Check firewall rules
Validate certificates
Review agent logs

High Resource Usage#

Check rule complexity
Review decoder efficiency
Analyze event volumes
Optimize configurations

Alert Delays#

Monitor queue sizes
Check processing backlogs
Verify indexer performance
Review rule priorities

Diagnostic Tools#

wazuh-control: Service management
agent_control: Agent status and management
wazuh-logtest: Rule and decoder testing
cluster_control: Cluster status monitoring

Best Practices#

Deployment#

Start with a pilot deployment
Document your architecture
Implement proper change management
Plan for growth and scalability

Configuration#

Use configuration management tools
Version control for rules and decoders
Test changes in non-production first
Document custom configurations

Monitoring#

Monitor Wazuh component health
Track resource utilization trends
Set up alerting for critical issues
Regular performance reviews

Security#

Regular security assessments
Penetration testing
Compliance audits
Incident response procedures

Conclusion#

Wazuh provides a comprehensive security monitoring solution with a modular, scalable architecture. Its design supports everything from small single-server deployments to large distributed clusters. The codebase is well-organized with clear separation between core components, modules, and management layers.

By understanding both the high-level architecture and the underlying codebase structure, organizations can effectively deploy, customize, and maintain Wazuh as a core component of their security strategy. The platform’s extensibility through APIs, custom rules, and modules makes it adaptable to various security requirements and environments.

This architecture overview is based on Wazuh v4.11.2. For the most current information and detailed implementation guides, please refer to the official Wazuh documentation.