Wazuh

Wazuh Indexer

Getting Started

Wazuh is a free and open source security platform that unifies XDR and SIEM capabilities. It protects workloads across on-premises, virtualized, containerized, and cloud-based environments.

Wazuh helps organizations and individuals to protect their data assets against security threats. It is widely used by thousands of organizations worldwide, from small businesses to large enterprises.

Wazuh Indexer

  • The Wazuh indexer is a highly scalable, full-text search and analytics engine. This central component indexes and stores alerts generated by the Wazuh server.

Index

Description

wazuh‑alerts

Stores alerts generated by the Wazuh server. These are created each time an event trips a rule with a high enough priority (this threshold is configurable).

wazuh‑archives

Stores all events (archive data) received by the Wazuh server, whether or not they trip a rule.

wazuh‑monitoring

Stores data related to the Wazuh agent status over time. It is used by the web interface to represent when individual agents are or have been Active, Disconnected, or Never connected.
wazuh‑statistics
Stores data related to the Wazuh server performance. It is used by the web interface to represent the performance statistics.

Example query

You can interact with the Wazuh indexer cluster using the Wazuh indexer REST API, which offers a lot of flexibility. You can perform searches, add or delete documents, modify indices, and more.

Here is an example of a query to Wazuh indexer that returns the last lateral movement alert using SSH technique:

GET /wazuh-alerts-4.x-*/_search
{
"query": {
"bool": {
"must": [
{"term": { "rule.mitre.tactic": "Lateral Movement" } },
{"term": { "rule.mitre.technique": "SSH" } }
]
}
},
"sort": [
{ "timestamp": { "order": "desc" } }
],
"size": 1
}

Below is an extract of the query result, which is a part of the indexed alert document:

Output

{
   "timestamp" : "2022-04-24T17:24:56.110+0000",
   "agent" : {
    "ip" : "10.0.1.52",
    "name" : "Amazon",
    "id" : "001"
   },
   "data" : {
     "srcip" : "68.183.216.91",
     "srcport" : "53820"
   },
   "rule" : {
     "description" : "sshd: insecure connection attempt (scan).",
     "id" : "5706",
     "level" : 6,
     "pci_dss" : ["11.4"],
     "mitre" : {
       "technique" : [
         "SSH"
       ],
       "id" : ["T1021.004"],
       "tactic" : [
         "Lateral Movement"
      ]
     }
   },
   "full_log" : "Apr 24 17:24:55 ip-10-0-1-52 sshd[32179]: Did not receive identification string from 68.183.216.91 port 53820",
   "location" : "/var/log/secure",
   "predecoder" : {
     "hostname" : "ip-10-0-1-52",
     "program_name" : "sshd",
     "timestamp" : "Apr 24 17:24:55"
   },
   "decoder" : {
     "parent" : "sshd",
     "name" : "sshd"
   },
   "GeoLocation" : {
     "city_name" : "Frankfurt am Main",
     "country_name" : "Germany",
     "region_name" : "Hesse"
   }
}

The Wazuh indexer is well suited for time-sensitive use cases like security analytics and infrastructure monitoring as it is a near real-time search platform. The latency from the time a document is indexed until it becomes searchable is very short, typically one second.

In addition to its speed, scalability, and resiliency, the Wazuh indexer has several powerful built-in features that make storing and searching data even more efficient, such as data rollups, alerting, anomaly detection, and index lifecycle management.

Wazuh server

  • The Wazuh server analyzes data received from the agents. It processes it through decoders and rules, using threat intelligence to look for well-known indicators of compromise (IOCs). A single server can analyze data from hundreds or thousands of agents, and scale horizontally when set up as a cluster. This central component is also used to manage the agents, configuring and upgrading them remotely when necessary.

Server architecture

The Wazuh server runs the analysis engine, the Wazuh RESTful API, the agent enrollment service, the agent connection service, the Wazuh cluster daemon, and Filebeat. The server is installed on a Linux operating system and usually runs on a stand-alone physical machine, virtual machine, docker container, or cloud instance.

The diagram below represents the server architecture and components:

Server components

The Wazuh server comprises several components listed below that have different functions, such as enrolling new agents, validating each agent identity, and encrypting the communications between the Wazuh agent and the Wazuh server.

  • Agent enrollment service: It is used to enroll new agents. This service provides and distributes unique authentication keys to each agent. The process runs as a network service and supports authentication via TLS/SSL certificates or by providing a fixed password.

  • Agent connection service: This service receives data from the agents. It uses the keys shared by the enrollment service to validate each agent identity and encrypt the communications between the Wazuh agent and the Wazuh server. Additionally, this service provides centralized configuration management, enabling you to push new agent settings remotely.

  • Analysis engine: This is the server component that performs the data analysis. It uses decoders to identify the type of information being processed (Windows events, SSH logs, web server logs, and others). These decoders also extract relevant data elements from the log messages, such as source IP address, event ID, or username. Then, by using rules, the engine identifies specific patterns in the decoded events that could trigger alerts and possibly even call for automated countermeasures (e.g., banning an IP address, stopping a running process, or removing a malware artifact).

  • Wazuh RESTful API: This service provides an interface to interact with the Wazuh infrastructure. It is used to manage configuration settings of agents and servers, monitor the infrastructure status and overall health, manage and edit Wazuh decoders and rules, and query about the state of the monitored endpoints. The Wazuh dashboard also uses it.

  • Wazuh cluster daemon: This service is used to scale Wazuh servers horizontally, deploying them as a cluster. This kind of configuration, combined with a network load balancer, provides high availability and load balancing. The Wazuh cluster daemon is what Wazuh servers use to communicate with each other and to keep synchronized.

  • Filebeat: It is used to send events and alerts to the Wazuh indexer. It reads the output of the Wazuh analysis engine and ships events in real time. It also provides load balancing when connected to a multi-node Wazuh indexer cluster.

Wazuh dashboard

  • The Wazuh dashboard is the web user interface for data visualization and analysis. It includes out-of-the-box dashboards for security events, regulatory compliance (e.g., PCI DSS, GDPR, CIS, HIPAA, NIST 800-53), detected vulnerable applications, file integrity monitoring data, configuration assessment results, cloud infrastructure monitoring events, and others. It is also used to manage Wazuh configuration and to monitor its status.

Data visualization and analysis

The web interface helps users navigate through the different types of data collected by the Wazuh agent, as well as the security alerts generated by the Wazuh server. Users can also generate reports and create custom visualizations and dashboards.

As an example, Wazuh provides out-of-the-box dashboards for regulatory compliance such as PCI DSS, GDPR, HIPAA, and NIST 800-53. It also provides an interface to navigate through the MITRE ATT&CK framework and related alerts.

Agents monitoring and configuration

The Wazuh dashboard allows users to manage agents configuration and to monitor their status. As an example, for each monitored endpoint, users can define what agent modules will be enabled, what log files will be read, what files will be monitored for integrity changes, or what configuration checks will be performed.

Platform management

The Wazuh dashboard provides a user interface dedicated to manage your Wazuh deployment. This includes monitoring the status, logs, and statistics of the different Wazuh components. It also includes configuring the Wazuh server, and creating custom rules and decoders for log analysis and threat detection.

Developer tools

The Wazuh dashboard includes a Ruleset Test tool that can process log messages to check how it is decoded and if it matches a threat detection rule or not. This feature is especially useful when custom decoders and rules have been created and the user wants to test them.

The Wazuh dashboard also includes an API Console for users to interact with the Wazuh API. This can be used to manage the Wazuh deployment (e.g., managing server or agent configurations, monitor status and log messages, adding or removing agents, etc.).

Wazuh agent

  • Wazuh agents are installed on endpoints such as laptops, desktops, servers, cloud instances, or virtual machines. They provide threat prevention, detection, and response capabilities. They run on operating systems such as Linux, Windows, macOS, Solaris, AIX, and HP-UX. The agent helps to protect your system by providing threat prevention, detection, and response capabilities. It is also used to collect different types of system and application data that it forwards to the Wazuh server through an encrypted and authenticated channel.

Agent architecture

The Wazuh agent has a modular architecture. Each component is in charge of its own tasks, including monitoring the file system, reading log messages, collecting inventory data, scanning the system configuration, and looking for malware. Users can manage agent modules via configuration settings, adapting the solution to their particular use cases.

The diagram below represents the agent architecture and components:

Agent modules

All agent modules are configurable and perform different security tasks. This modular architecture allows you to enable or disable each component according to your security needs. Below you can learn about the different purposes of all the agent modules.

  • Log collector: This agent component can read flat log files and Windows events, collecting operating system and application log messages. It supports XPath filters for Windows events and recognizes multi-line formats like Linux Audit logs. It can also enrich JSON events with additional metadata.

  • Command execution: Agents run authorized commands periodically, collecting their output and reporting it back to the Wazuh server for further analysis. You can use this module for different purposes, such as monitoring hard disk space left or getting a list of the last logged-in users.

  • File integrity monitoring (FIM): This module monitors the file system, reporting when files are created, deleted, or modified. It keeps track of changes in file attributes, permissions, ownership, and content. When an event occurs, it captures who, what, and when details in real time. Additionally, the FIM module builds and maintains a database with the state of the monitored files, allowing queries to be run remotely.

  • Security configuration assessment (SCA): This component provides continuous configuration assessment, utilizing out-of-the-box checks based on the Center of Internet Security (CIS) benchmarks. Users can also create their own SCA checks to monitor and enforce their security policies.

  • System inventory: This agent module periodically runs scans, collecting inventory data such as operating system version, network interfaces, running processes, installed applications, and a list of open ports. Scan results are stored in local SQLite databases that can be queried remotely.

  • Malware detection: Using a non-signature-based approach, this component is capable of detecting anomalies and the possible presence of rootkits. Also, it looks for hidden processes, hidden files, and hidden ports while monitoring system calls.

  • Active response: This module runs automatic actions when threats are detected, triggering responses to block a network connection, stop a running process, or delete a malicious file. Users can also create custom responses when necessary and customize, for example, responses for running a binary in a sandbox, capturing network traffic, and scanning a file with an antivirus.

  • Container security monitoring: This agent module is integrated with the Docker Engine API to monitor changes in a containerized environment. For example, it detects changes to container images, network configuration, or data volumes. Besides, it alerts about containers running in privileged mode and about users executing commands in a running container.

  • Cloud security monitoring: This component monitors cloud providers such as Amazon AWS, Microsoft Azure, or Google GCP. It natively communicates with their APIs. It is capable of detecting changes to the cloud infrastructure (e.g., a new user is created, a security group is modified, a cloud instance is stopped, etc.) and collecting cloud services log data (e.g., AWS Cloudtrail, AWS Macie, AWS GuardDuty, Azure Active Directory, etc.)

Communication with Wazuh server

The Wazuh agent communicates with the Wazuh server to ship collected data and security-related events. Besides, the agent sends operational data, reporting its configuration and status. Once connected, the agent can be upgraded, monitored, and configured remotely from the Wazuh server.

The communication of the agent with the server takes place through a secure channel (TCP or UDP), providing data encryption and compression in real time. Additionally, it includes flow control mechanisms to avoid flooding, queueing events when necessary, and protecting the network bandwidth.

You need to enroll the agent before connecting it to the server for the first time. This process provides the agent with a unique key used for authentication and data encryption.

Installing Wazuh - Linux Ubuntu

Requirements

Hardware

Hardware requirements highly depend on the number of protected endpoints and cloud workloads. This number can help estimate how much data will be analyzed and how many security alerts will be stored and indexed.

Following this quickstart implies deploying the Wazuh server, the Wazuh indexer, and the Wazuh dashboard on the same host. This is usually enough for monitoring up to 100 endpoints and for 90 days of queryable/indexed alert data. The table below shows the recommended hardware for a quickstart deployment:

Agents

CPU

RAM

Storage (90 days)

1–25

4 vCPU

8 GiB

50 GB

25–50

8 vCPU

8 GiB

100 GB

50–100

8 vCPU

8 GiB

200 GB

For larger environments we recommend a distributed deployment. Multi-node cluster configuration is available for the Wazuh server and for the Wazuh indexer, providing high availability and load balancing.

Operating system

Wazuh central components can be installed on a 64-bit Linux operating system. Wazuh recommends any of the following operating system versions:

Amazon Linux 2

CentOS 7, 8

Red Hat Enterprise Linux 7, 8, 9

Ubuntu 16.04, 18.04, 20.04, 22.04

Browser compatibility

Wazuh dashboard supports the following web browsers:

  • Chrome 95 or later

  • Firefox 93 or later

  • Safari 13.7 or later

Other Chromium-based browsers might also work. Internet Explorer 11 is not supported.

Installing Wazuh

  1. Download and run the Wazuh installation assistant.
curl -sO https://packages.wazuh.com/4.5/wazuh-install.sh && sudo bash ./wazuh-install.sh -a

Once the assistant finishes the installation, the output shows the access credentials and a message that confirms that the installation was successful.

INFO: --- Summary ---
INFO: You can access the web interface https://<wazuh-dashboard-ip>
User: admin
Password: <ADMIN_PASSWORD>
INFO: Installation finished.

You now have installed and configured Wazuh.

  1. Access the Wazuh web interface with https://<wazuh-dashboard-ip> and your credentials:
    • Username: admin
    • Password: <ADMIN_PASSWORD>

When you access the Wazuh dashboard for the first time, the browser shows a warning message stating that the certificate was not issued by a trusted authority. This is expected and the user has the option to accept the certificate as an exception or, alternatively, configure the system to use a certificate from a trusted authority.

Note

You can find the passwords for all the Wazuh indexer and Wazuh API users in the wazuh-passwords.txt file inside wazuh-install-files.tar. To print them, run the following command:

sudo tar -O -xvf wazuh-install-files.tar wazuh-install-files/wazuh-passwords.txt

If you want to uninstall the Wazuh central components, run the Wazuh installation assistant using the option -u or –-uninstall.

Next steps

Now that your Wazuh installation is ready, you can start deploying the Wazuh agent. This can be used to protect laptops, desktops, servers, cloud instances, containers, or virtual machines. The agent is lightweight and multi-purpose, providing a variety of security capabilities.

Wazuh agent

The Wazuh agent is multi-platform and runs on the endpoints that the user wants to monitor. It communicates with the Wazuh server, sending data in near real-time through an encrypted and authenticated channel.

The agent was developed considering the need to monitor a wide variety of different endpoints without impacting their performance. It is supported on the most popular operating systems, and it requires 35 MB of RAM on average.

The Wazuh agent provides key features to enhance your system’s security.

Log collector

Command execution

File integrity monitoring (FIM)

Security configuration assessment (SCA)

System inventory

Malware detection

Log collector

Command execution

Log collector

To install a Wazuh agent, select your operating system and follow the instructions.

APT (Ubuntu)

  1. Install the GPG key:
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg
  1. Add the repository:
echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list
  1. Update the package information:
apt-get update

Note

For Debian 7, 8, and Ubuntu 14 systems import the GCP key and add the Wazuh repository (steps 1 and 2) using the following commands.
apt-get install gnupg apt-transport-https
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | apt-key add -
echo "deb https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list

Deploy a Wazuh agent

  1. To deploy the Wazuh agent on your endpoint, select your package manager and edit the WAZUH_MANAGER variable to contain your Wazuh manager IP address or hostname.
WAZUH_MANAGER="10.0.0.2" apt-get install wazuh-agent
For additional deployment options such as agent name, agent group, and registration password, see the Deployment variables for Linux section.
  1. Enable and start the Wazuh agent service.
Systemd
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent
The deployment process is now complete, and the Wazuh agent is successfully running on your Linux system.
  • Recommended action – Disable Wazuh updatesCompatibility between the Wazuh agent and the Wazuh manager is guaranteed when the Wazuh manager version is later than or equal to that of the Wazuh agent. Therefore, we recommend disabling the Wazuh repository to prevent accidental upgrades. To do so, use the following command:
sed -i "s/^deb/#deb/" /etc/apt/sources.list.d/wazuh.list
apt-get update
Alternatively, you can set the package state to hold. This action stops updates but you can still upgrade it manually using apt-get install.
echo "wazuh-agent hold" | dpkg --set-selections

Uninstall a Wazuh agent

To uninstall the agent, run the following commands:
  1. Remove the Wazuh agent installation.
apt-get remove wazuh-agent
Some files are marked as configuration files. Due to this designation, the package manager does not remove these files from the filesystem. If you want to completely remove all files, run the following command:
apt-get remove --purge wazuh-agent
  1. Disable the Wazuh agent service.
systemctl disable wazuh-agent
systemctl daemon-reload
The Wazuh agent is now completely removed from your Linux endpoint.

Deployment variables for Linux

For an agent to be fully deployed and connected to the Wazuh server, it needs to be installed, registered, and configured. The installers can use variables that allow configuration provisioning to make the process simple.

Below you can find a table describing the variables used by Wazuh installers and a few examples of how to use them.

Log collector

Description

WAZUH_MANAGER

Specifies the manager IP address or hostname. If you want to specify multiple managers, you can add them separated by commas.

WAZUH_MANAGER_PORT

Specifies the manager connection port.

WAZUH_PROTOCOL

Sets the communication protocol between the manager and the agent. Accepts UDP and TCP. The default is TCP.

WAZUH_REGISTRATION_SERVER

Specifies the Wazuh registration server, used for the agent registration. If empty, the value set in WAZUH_MANAGER will be used.

WAZUH_REGISTRATION_PORT

Specifies the port used by the Wazuh registration server. See port.

WAZUH_REGISTRATION_PASSWORD

Sets password used to authenticate during register, stored in etc/authd.pass.

WAZUH_KEEP_ALIVE_INTERVAL

Sets the time between agent checks for manager connection.

WAZUH_TIME_RECONNECT

Sets the time interval for the agent to reconnect with the Wazuh manager when connectivity is lost.

WAZUH_REGISTRATION_CA

Host SSL validation need of Certificate of Authority. This option specifies the CA path.

WAZUH_REGISTRATION_CERTIFICATE

The SSL agent verification needs a CA signed certificate and the respective key. This option specifies the certificate path.

WAZUH_REGISTRATION_KEY

Specifies the key path completing the required variables with WAZUH_REGISTRATION_CERTIFICATE for the SSL agent verification process.

WAZUH_AGENT_NAME

Designates the agent’s name. By default, it will be the computer name.

WAZUH_AGENT_GROUP

Assigns the agent to one or more existing groups (separated by commas).

ENROLLMENT_DELAY

Assigns the time that agentd should wait after a successful registration.

Examples:

  • Registration with password:
WAZUH_MANAGER="10.0.0.2" WAZUH_REGISTRATION_PASSWORD="TopSecret" \
     WAZUH_AGENT_NAME="apt-agent" apt-get install wazuh-agent
  • Registration with password and assigning a group:
WAZUH_MANAGER="10.0.0.2" WAZUH_REGISTRATION_SERVER="10.0.0.2" WAZUH_REGISTRATION_PASSWORD="TopSecret" \
     WAZUH_AGENT_GROUP="my-group" apt-get install wazuh-agent
  • Registration with relative path to CA. It will be searched at your Wazuh installation folder:
WAZUH_MANAGER="10.0.0.2" WAZUH_REGISTRATION_SERVER="10.0.0.2" WAZUH_AGENT_NAME="apt-agent" \
     WAZUH_REGISTRATION_CA="rootCA.pem" apt-get install wazuh-agent
  • Registration with protocol:
WAZUH_MANAGER="10.0.0.2" WAZUH_REGISTRATION_SERVER="10.0.0.2" WAZUH_AGENT_NAME="apt-agent" \
     WAZUH_PROTOCOL="udp" apt-get install wazuh-agent
  • Registration and adding multiple addresses:
WAZUH_MANAGER="10.0.0.2,10.0.0.3" WAZUH_REGISTRATION_SERVER="10.0.0.2" \
     WAZUH_AGENT_NAME="apt-agent" apt-get install wazuh-agent
  • Absolute paths to CA, certificate or key that contain spaces can be written as shown below:
WAZUH_MANAGER="10.0.0.2" WAZUH_REGISTRATION_SERVER="10.0.0.2" WAZUH_REGISTRATION_KEY="/var/ossec/etc/sslagent.key" \
     WAZUH_REGISTRATION_CERTIFICATE="/var/ossec/etc/sslagent.cert" apt-get install wazuh-agent