Engineering Enterprise Security Orchestration with Wazuh and Ansible

The convergence of security information and event management (SIEM) with advanced configuration management represents a paradigm shift in how organizations approach endpoint detection and response (EDR). At the center of this convergence is the integration of Wazuh, an open-source security monitoring platform, and Ansible, a powerful automation engine. Deploying a security infrastructure of this magnitude manually is not only time-consuming but prone to human error, which in a security context, can lead to catastrophic gaps in visibility. By leveraging Ansible, administrators can transform the deployment of the Wazuh stack—comprising the indexer, dashboard, and manager—into a repeatable, version-controlled, and scalable process. This synergy ensures that every single node in a cluster is configured identically, eliminating "configuration drift" and ensuring that security policies are applied uniformly across the entire enterprise architecture.

The architectural complexity of Wazuh requires a robust deployment strategy. Whether an organization is opting for a lightweight all-in-one installation for a small office or a highly available production-ready cluster for a global data center, Ansible provides the abstraction layer necessary to manage these environments. The use of YAML-based playbooks allows for a declarative approach to infrastructure, where the desired state of the security stack is defined, and Ansible handles the idempotency—ensuring that running the playbook multiple times does not result in duplicate installations or corrupted configurations.

The Technical Foundations of Ansible Automation

To master the deployment of Wazuh, one must first understand the fundamental mechanics of the Ansible platform. Ansible is an open-source automation engine that utilizes a push-based architecture, meaning it does not require a resident agent on the target nodes, unlike many other configuration management tools. Instead, it communicates with every host over Secure Shell (SSH), providing a secure and encrypted channel for command execution.

The operational framework of Ansible is built upon several core components that dictate how tasks are delegated and executed:

• Control node: This is the primary management endpoint where Ansible is installed. It is the source of truth from which playbooks are executed and where the logic of the deployment resides.
• Managed node: These are the target endpoints—such as the servers destined to become Wazuh indexers or managers—that are controlled by the control node.
• Inventory file: A critical configuration file that defines the specific nodes, IP addresses, and logical groups of servers to be managed. It serves as the mapping tool that tells Ansible which playbooks apply to which servers.
• Playbook: A high-level orchestration file written in YAML that describes the sequence of operations to be performed.
• Play: An ordered list of tasks mapped to specific managed nodes defined in the inventory.
• Tasks: The smallest unit of action, consisting of one or more modules that define an operation in a declarative manner.
• Modules: The actual binaries or scripts that Ansible pushes to and executes on the managed nodes to achieve a specific state, such as installing a package or starting a service.

The impact of this architecture is a significant reduction in deployment time and a massive increase in reliability. By defining the infrastructure as code (IaC), the deployment process becomes transparent and auditable, which is a requirement for most regulatory compliance frameworks such as PCI-DSS or HIPAA.

Strategic Deployment of Wazuh Central Components

The Wazuh ecosystem consists of three primary central components: the Wazuh indexer, the Wazuh dashboard, and the Wazuh manager. Depending on the organizational needs, these can be deployed in various configurations, ranging from a single-server setup to a multi-node clustered environment.

All-in-One Deployment Architecture

The all-in-one deployment is designed for environments where resource constraints are present or where a rapid proof-of-concept is required. In this model, the Wazuh indexer, Wazuh dashboard, and Wazuh manager are all installed on a single endpoint.

This approach simplifies the network topology as there is no inter-component communication across different physical or virtual servers. However, it creates a single point of failure. To implement this, administrators use predefined playbooks from the Wazuh Ansible repository, which automate the sequential installation of the three components on one machine.

Production-Ready Clustered Deployment

For enterprise environments, the production-ready deployment is the gold standard. In a clustered setup, data and workloads are distributed across multiple nodes. This ensures redundancy; if one node fails, the others continue to process security events, ensuring that there is no gap in monitoring. Load balancing is also integrated into this architecture, preventing any single manager from becoming a bottleneck during a high-volume security event (such as a DDoS attack or a widespread malware outbreak).

The deployment of a cluster is achieved using the wazuh-production-ready.yml playbook. This playbook orchestrates the complex synchronization required between the indexer and the manager to ensure that the cluster maintains a consistent state of security data.

Initializing the Ansible Environment for Wazuh

Before the deployment of any Wazuh component, the Ansible control server must be properly prepared. This involves the acquisition of the official Wazuh Ansible repository, which contains the vetted roles and playbooks required for a successful installation.

The process begins by creating a dedicated directory for Ansible roles and cloning the specific versioned branch of the repository to ensure stability and compatibility.

The following commands must be executed on the Ansible server:

bash mkdir -p /etc/ansible/roles cd /etc/ansible/roles/ sudo git clone --branch v4.14.4 https://github.com/wazuh/wazuh-ansible.git ls

Upon execution, the directory structure will reveal the wazuh-ansible folder. This repository is not merely a collection of scripts but a sophisticated set of roles. A role in Ansible is a way of bundling together playbooks, variables, and tasks into a reusable unit.

The structure of the roles directory is as follows:

bash cd /etc/ansible/roles/wazuh-ansible/ tree roles -d

The resulting output displays the internal organization:

text roles ├── ansible-galaxy │ └── meta └── wazuh ├── ansible-filebeat-oss │ ├── defaults │ ├── handlers │ ├── meta │ ├── tasks │ └── templates ├── ansible-wazuh-agent │ ├── defaults │ ├── handlers │ ├── meta │ ├── tasks │ └── templates ├── ansible-wazuh-manager │ ├── defaults │ ├── files │ │ └── custom_ruleset │ │ ├── decoders │ │ └── rules │ ├── handlers │ ├── meta │ ├── tasks │ ├── templates │ └── vars ├── wazuh-dashboard │ ├── defaults │ ├── handlers │ ├── tasks │ ├── templates │ └── vars └── wazuh-indexer │ ├── defaults │ ├── handlers │ ├── meta │ ├── tasks │ └── templates

This modular structure allows administrators to target specific components. For example, if an organization only needs to update the indexer, they can utilize the wazuh-indexer role without affecting the manager or dashboard.

Orchestrating the Installation Process

The execution of the deployment is handled via playbooks. These are located in the playbooks/ directory of the cloned repository. To view the available automation paths, the following command is used:

bash tree playbooks/

The available playbooks provide various deployment paths:

• wazuh-single.yml: Used for the all-in-one installation.
• wazuh-production-ready.yml: Used for deploying a full manager and indexer cluster.
• wazuh-indexer.yml: Dedicated to the indexer component.
• wazuh-dashboard.yml: Dedicated to the dashboard component.
• wazuh-manager-oss.yml: Used for the Open Source Security (OSS) version of the manager.
• wazuh-agent.yml: Used for the mass deployment of agents to endpoints.

Deployment of the Indexer and Dashboard

The Wazuh indexer is the engine that stores and indexes the security logs, while the dashboard provides the visualization layer. To deploy these, the administrator must first ensure that the Ansible control server has SSH access to the target endpoints.

A critical part of the configuration involves the inventory and variable definition. For example, a node might be defined in the inventory as follows:

text node1: name: node-1 ip: 127.0.0.1 role: indexer indexer_custom_user: false

In this context, the IP address of the server is mapped to the indexer_network_host entry, ensuring the dashboard knows exactly where to look for the indexed data.

To initiate the deployment, the following command is executed:

bash ansible-playbook wazuh-indexer-and-dashboard.yml -b -K

The -b flag indicates the use of "become" (privilege escalation), and the -K flag prompts for the sudo password, ensuring the installation has the necessary permissions to modify system files and install packages.

Once the playbook completes, the administrator must verify that the services are operational. This is done by checking the status of the systemd units:

bash systemctl status wazuh-indexer systemctl status wazuh-dashboard

Upon successful verification, the Wazuh dashboard becomes accessible via a web browser at https://<WAZUH_SERVER_IP>. The initial security posture uses default credentials:

• Username: admin
• Password: changeme

It is an absolute requirement that these credentials be changed immediately via the Password Management section to prevent unauthorized access to the security console.

Advanced Agent Provisioning and Configuration Management

While the Wazuh server provides some remote management capabilities, there are critical limitations. Certain provisioning tasks and the installation of third-party endpoint-dependent applications cannot be handled remotely through the Wazuh server itself. This is where Ansible becomes indispensable for the "last mile" of security deployment.

By automating the deployment of agents across thousands of endpoints, organizations can minimize the "window of vulnerability"—the time between when a server is commissioned and when it is actually being monitored by the SIEM.

Multi-Platform Agent Deployment Strategy

The deployment of Wazuh agents differs significantly between Unix-based systems and Windows environments. Ansible abstracts these differences using a single playbook that targets different host groups.

Deployment on Unix Endpoints

For Ubuntu and other Debian-based systems, the process involves copying the .deb package and utilizing the dpkg tool. The following playbook structure is used:

```yaml

• name: "1 - DEPLOY WAZUH AGENT 4.7.0 ON UNIX ENDPOINTS"
  hosts: unix
  become: yes
  remoteuser: ansible
  vars:
  wazuhserver: ""
  tasks:
  • name: "1 - Copy the Wazuh agent package to the Ubuntu endpoint"
    
    tags: copywazuhdeb
    
    copy:
    
    src: /tmp/wazuh-agent4.7.0-1amd64.deb
    
    dest: /tmp
    
    mode: '0774'
  • name: "2 - Deploy the Wazuh agent on the Ubuntu endpoint"
    
    ansible.builtin.shell: WAZUHMANAGER={{wazuhserver}} WAZUHAGENTNAME="Ubuntu-23.04" sudo dpkg -i /tmp/wazuh-agent4.7.0-1amd64.deb
    
    when: ansibleosfamily == "Debian"
  • name: "3 - Start and enable the Wazuh agent service"
    
    systemd:
    
    name: wazuh-agent
    
    state: started
    
    enabled: yes
    
    ```

In this workflow, the copy module ensures the binary is present on the target, the shell module executes the installation with the specific WAZUH_MANAGER variable to ensure the agent knows where to report, and the systemd module ensures the agent persists across reboots.

Deployment on Windows Endpoints

Windows deployment requires the use of the win_ prefix modules, as Ansible communicates via WinRM (Windows Remote Management) rather than SSH. The process involves the .msi installer.

yaml - name: "2 - DEPLOY WAZUH AGENT 4.7.0 ON WINDOWS ENDPOINTS" hosts: windows remote_user: ansible vars: wazuh_server: "<WAZUH_SERVER_IP>" tasks: - name: "1 - Copy the Wazuh package to the Windows endpoint" tags: copy_wazuh_win win_copy: src: /tmp/wazuh-agent-4.7.0-1.msi dest: C:\Users\ansible\AppData\Local\Temp\ mode: '0774' - name: "2 - Deploy the Wazuh agent on the Windows endpoint" win_package: path: C:\Users\ansible\AppData\Local\Temp\wazuh-agent-4.7.0-1.msi product_id: Wazuh-4.7.0 arguments: '/q WAZUH_MANAGER={{wazuh_server}} WAZUH_AGENT_NAME="Windows-11"' state: present - name: "3 - Start and enable the Wazuh agent service" win_service: name: wazuh start_mode: auto state: restarted

The use of the /q argument in the win_package module ensures a quiet installation, preventing the installer from hanging while waiting for user interaction, which would cause the Ansible playbook to time out.

Component Relationship and Dependency Mapping

The successful deployment of Wazuh via Ansible relies on the correct interaction between the various roles. The ansible-wazuh-manager and ansible-filebeat-oss roles are fundamentally linked. Filebeat acts as the shipper that moves the alerts generated by the Wazuh manager to the Wazuh indexer. Without the correct configuration of Filebeat, the Wazuh manager will detect threats, but those threats will never appear on the Wazuh dashboard.

The interaction can be summarized in the following technical flow:

• Wazuh Manager (via ansible-wazuh-manager role) $\rightarrow$ Generates alerts.
• Filebeat (via ansible-filebeat-oss role) $\rightarrow$ Ships alerts to the indexer.
• Wazuh Indexer (via wazuh-indexer role) $\rightarrow$ Stores and indexes the alerts.
• Wazuh Dashboard (via wazuh-dashboard role) $\rightarrow$ Visualizes the indexed alerts.

Technical Specification Summary

The following table summarizes the primary components and their Ansible-driven deployment characteristics.

Conclusion

The integration of Wazuh and Ansible transforms security deployment from a manual, error-prone task into a streamlined engineering process. By utilizing the provided Ansible roles and playbooks, organizations can achieve a level of consistency in their security posture that is impossible to maintain manually. The transition from a simple all-in-one deployment to a production-ready cluster is managed not by rewriting the infrastructure, but by simply executing a different playbook—wazuh-production-ready.yml—which leverages the same underlying roles to distribute the load across a cluster.

Furthermore, the ability to manage heterogeneous environments (Unix and Windows) through a single Ansible control node ensures that security coverage is comprehensive. The use of the win_package and systemd modules allows for the simultaneous orchestration of diverse operating systems, ensuring that every endpoint is reporting to the central manager with a consistent configuration. Ultimately, this approach not only improves the organization's resilience and security posture but also ensures that the security infrastructure can scale dynamically with the growth of the network, providing a sustainable foundation for enterprise-grade threat detection and response.

Sources

1. Wazuh Deployment Guide - Ansible
2. Wazuh Deployment Options - Ansible Overview
3. Wazuh Blog - Configuration Management of Endpoints using Ansible