# wazuh/wazuh-agent architecture

> Architecture diagram of the GitHub repository wazuh/wazuh-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wazuh/wazuh-agent
- Repository: https://github.com/wazuh/wazuh-agent

## Overview

##### Project Overview and Purpose
- That this is an “agent” deployed on monitored hosts. Its primary responsibility is collecting security and system data (logs, system events, file integrity changes, etc.) and then forwarding these to a centralized Wazuh Server for analysis.
- The agent integrates with third-party software (e.g., Boost libraries, OpenSSL, SQLite, and others) to support networking, configuration parsing, logging, and data storage.

##### Major Layers/Components
a. Core Agent Subsystem:
- • Communication: Located in src/agent/communicator and http_client directories, this module handles network connections and secure data transmission (using, for example, HTTP/HTTPS and JWT-cpp for token handling).
- • Configuration and Parsing: The configuration_parser component (found in src/agent/configuration_parser) reads and processes YAML or other configuration files. Additionally, common and command handling logic resides in src/agent/command_handler and src/agent/agent.
- • Command Processing and Execution: The command_handler and multitype_queue components control data flow, agent commands, and inter-module messaging.
- • Persistence and Data Storage: The agent persists data using SQLite (src/agent/persistence) for storing agent state, logs, or execution history in case processing needs to be resilient.

b. Module/Plugin Architecture:
- The project contains a “modules” directory with numerous submodules (active_response, aws, azure, docker, fim, logcollector, rootcheck, sca, etc.). These modules encapsulate specific functionalities:
– Active Response: Handles firewall modifications, account locking, etc. (src/modules/active_response).
– File Integrity Monitoring (FIM): Monitors file changes (src/modules/fim).
– Log Collector: Collects and processes logs from various sources (src/modules/logcollector).
– Cloud Modules (aws, azure, ms_graph, office365, gcp): Interface with cloud platforms for event ingestion.
– Additional modules like osquery, rootcheck, inventory, upgrade, etc.
- Each module follows a similar structure with specific source, include, test, and sometimes script directories, reflecting a plugin architecture. This supports extensibility and the ability to support different data sources and response types.

c. Build, Packaging, and CI/CD:
- The presence of CMakeLists.txt files across the agent and module directories implies a unified CMake-based build system.
- Dedicated packaging directories (packages/*) and continuous integration files (under .github/actions and .github/workflows) indicate automated build, package creation, and testing pipelines.
- Build Server/CI Pipeline (e.g., GitHub workflows for building packages, Docker images, and running tests)
- Package generation for different platforms (Debs, RPMs, Windows MSI, macOS)
- Integration with external code quality and test frameworks

##### Relationships and Interactions
- The Core Agent collects security events and system data → It processes these through various internal queues and modules.
- The communication subsystem encrypts and transmits collected data to the Wazuh Server.
- Command and configuration updates flow from the central server (or manager) back to the agent, triggering local actions.
- The modules act as plugins that can independently read, process, and react to specific events (active response execution, log parsing, integrity checks, etc.).

##### Architectural Patterns
- The codebase demonstrates a clear separation of concerns: core agent logic stands apart from modules (plugin design pattern) and from build/packaging/CI pipelines.
- Employ a layered architecture style that separates platform abstraction (pal and OS-specific implementations such as in src/agent/src/windows) from the business logic.
- The modular design further enables micro-functional units (each module can be thought of as a microservice in a distributed monitoring ecosystem) even though they compile into one agent binary.

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Core Agent Subsystem"
    A1["Communicator"]:::core
    A2["HTTP Client"]:::core
    B1["Configuration Parser"]:::core
    B2["Command Handler"]:::core
    B3["Multitype Queue"]:::core
    B4["Persistence"]:::core
    B5["Service"]:::core
    B6["Windows Implementation"]:::core
  end

  subgraph "Modules/Plugin Architecture"
    M1["Active Response"]:::modules
    M2["File Integrity Monitoring (FIM)"]:::modules
    M3["Log Collector"]:::modules
    M4["AWS"]:::modules
    M5["Azure"]:::modules
    M6["GCP"]:::modules
    M7["Microsoft Graph"]:::modules
    M8["Office365"]:::modules
    M9["Inventory"]:::modules
    M10["Rootcheck"]:::modules
    M11["Security Configuration Assessment (SCA)"]:::modules
    M12["Command Module"]:::modules
    M13["Docker"]:::modules
    M14["OSQuery"]:::modules
    M15["GitHub"]:::modules
    M16["Upgrade"]:::modules
  end

  subgraph "Build, Packaging, CI/CD"
    C1["Build System"]:::cicd
    C2["Packaging"]:::cicd
    C3["CI/CD Pipeline"]:::cicd
  end

  E1["Wazuh Server"]:::external
  ED["External Dependencies (Boost, OpenSSL, JWT-cpp, SQLite)"]:::external
  
  %% Data Flow Connections
  A1 -->|"sends-data"| E1
  A2 -->|"sends-data"| E1
  E1 -->|"command-update"| B2
  B1 -->|"config"| B2
  B2 -->|"queues"| B3
  
  %% Core to Modules Interactions
  B3 -->|"events"| M1
  B3 -->|"events"| M2
  B3 -->|"events"| M3
  B3 -->|"events"| M4
  B3 -->|"events"| M5
  B3 -->|"events"| M6
  B3 -->|"events"| M7
  B3 -->|"events"| M8
  B3 -->|"events"| M9
  B3 -->|"events"| M10
  B3 -->|"events"| M11
  B3 -->|"events"| M13
  B3 -->|"events"| M14
  B3 -->|"events"| M15
  B3 -->|"events"| M16
  B2 -->|"commands"| M12
  
  %% Support and Persistence within Core
  B4 -.->|"stores"| B2
  B5 -.->|"platform_support"| B2
  B6 -.->|"platform_support"| B2
  
  %% Reporting and External Dependencies
  B2 -->|"reports"| ED
  
  %% CI/CD and Build Relations
  B1 --- C1
  B2 --- C1
  M1 --- C1
  C1 -->|"builds"| C2
  C2 -->|"deploys"| C3

  %% Classes
  classDef core fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
  classDef modules fill:#d9ead3,stroke:#38761d,stroke-width:2px;
  classDef cicd fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
  classDef external fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
  
  %% Click Events for Core Agent Subsystem
  click A1 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/communicator"
  click A2 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/http_client"
  click B1 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/configuration_parser"
  click B2 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/command_handler"
  click B3 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/multitype_queue"
  click B4 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/persistence"
  click B5 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/service"
  click B6 "https://github.com/wazuh/wazuh-agent/tree/main/src/agent/src/windows"
  
  %% Click Events for Modules/Plugin Architecture
  click M1 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/active_response"
  click M2 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/fim"
  click M3 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/logcollector"
  click M4 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/aws"
  click M5 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/azure"
  click M6 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/gcp"
  click M7 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/ms_graph"
  click M8 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/office365"
  click M9 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/inventory"
  click M10 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/rootcheck"
  click M11 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/sca"
  click M12 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/command"
  click M13 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/docker"
  click M14 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/osquery"
  click M15 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/github"
  click M16 "https://github.com/wazuh/wazuh-agent/tree/main/src/modules/upgrade"
  
  %% Click Events for Build, Packaging, CI/CD
  click C2 "https://github.com/wazuh/wazuh-agent/tree/main/packages/"
  click C3 "https://github.com/wazuh/wazuh-agent/tree/main/.github/actions"
```
