How wazuh/wazuh-agent works
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.