Architecture

The Wazuh Server API is a layered system where an HTTP server delegates to a Python framework, which in turn communicates with internal daemons and databases through Unix sockets.

System Architecture Overview

graph TD
    A["Client (curl / SDK / Dashboard)"] --> B["Wazuh Server API (REST, JWT, RBAC)"]
    B --> C["Wazuh Python Framework"]
    C --> D["Core Logic Layer"]
    
    D --> E["Unix sockets (daemons)"]
    D --> F["Wazuh Database (WDB)"]
    D --> G["Configuration files"]
    D --> H["Internal queues"]

    style A fill:#f9f,stroke:#333,stroke-width:2px,color:#fff
    style B fill:#bbf,stroke:#333,stroke-width:2px,color:#fff
    style C fill:#baf,stroke:#333,stroke-width:2px,color:#fff
    style D fill:#1ad,stroke:#333,stroke-width:2px,color:#fff
    style E fill:#666,stroke:#333,color:#fff
    style F fill:#666,stroke:#333,color:#fff
    style G fill:#666,stroke:#333,color:#fff
    style H fill:#666,stroke:#333,color:#fff

Directory Structure

API Interface Layer

wazuh/framework/wazuh/

This layer:

• Exposes API-facing functions
• Validates input
• Enforces RBAC
• Formats responses

It must not contain business logic.

Core Logic Layer

wazuh/framework/wazuh/core/

This layer contains all real logic. It is API-agnostic and can be reused internally.

API Server Layer

wazuh/api/api/

This layer implements the HTTP server that exposes the REST API.

Controllers

Each controller wraps framework calls in the DAPI (Distributed API) layer to transparently route requests across cluster nodes.

RBAC Sub-module

wazuh/framework/wazuh/rbac/

Cluster Sub-module

wazuh/framework/wazuh/core/cluster/

Indexer Sub-module

wazuh/framework/wazuh/core/indexer/

Execution Flow

Example: GET /agents?status=active

1. HTTP request reaches the Server API (Starlette/Connexion)
2. Middlewares process the request (security headers, rate limiting, access logging)
3. JWT token is validated via authentication.py
4. Input parameters are validated via validator.py (regex-based)
5. Request is routed to the controller (agent_controller.py)
6. Controller wraps the call in the DAPI layer for cluster routing
7. DAPI determines the target node (local_master, local_any, etc.)
8. Framework function (wazuh/agent.py) is invoked
9. RBAC permissions are checked via expose_resources decorator
10. Core logic (core/agent.py) is executed
11. Data is fetched from:
    • WDB (via Unix socket or HTTP)
    • Manager daemon (via Unix socket)
    • Filesystem
12. Result is wrapped in AffectedItemsWazuhResult or WazuhResult
13. Result is serialized to JSON and returned

Distributed API (DAPI)

In cluster deployments, not all requests can be handled by the node receiving them.

The DAPI layer (core/cluster/dapi/) transparently routes requests:

graph LR
    A["Client"] --> B["API Node"]
    B --> C{"DAPI"}
    C -->|local_master| D["Master Node"]
    C -->|local_any| E["Current Node"]
    C -->|distributed| F["Worker Node(s)"]

Result Model

All framework functions return standardized result objects defined in core/results.py:

Results support:

• Merge operations (| operator) for combining results across cluster nodes
• Iteration, length, and containment checks
• Pagination metadata

Socket Communication Protocol

The framework communicates with Wazuh daemons via Unix domain sockets using a length-prefixed protocol.

Protocol Details

• Messages use a 4-byte little-endian header indicating the payload length
• The same framing is used for both sending and receiving
• WazuhAsyncSocket (in core/wdb.py) handles async socket connections

Key Socket Paths

Logging Architecture

Custom Log Rotation (core/wlogging.py)

• The CustomFileRotatingHandler class extends Python's logging to:
  • Rotate log files when they reach a size threshold
  • Compress rotated files with gzip
  • Set file permissions to 0o640
  • Store rotated logs in a dedicated directory

API Access Logging (api/alogging.py)

• Every API request generates an access log entry
• Passwords and sensitive data are sanitized from query strings and request bodies before logging