# Wazuh

Open source security platform.<br/>
Provides unified XDR and SIEM protection for endpoints and cloud workloads.

1. [TL;DR](#tldr)
1. [Components](#components)
   1. [Indexer](#indexer)
   1. [Server](#server)
   1. [Dashboard](#dashboard)
   1. [Agent](#agent)
1. [Installation](#installation)
   1. [Requirements](#requirements)
   1. [Procedure](#procedure)
1. [Configuration](#configuration)
   1. [Local configuration](#local-configuration)
   1. [Shared configuration](#shared-configuration)
1. [AWS integration](#aws-integration)
   1. [Instances](#instances)
   1. [Services](#services)
1. [Further readings](#further-readings)
   1. [Sources](#sources)

## TL;DR

<details>
  <summary>Installation</summary>
  <details style="margin-left: 1em">
    <summary>Docker compose</summary>

```sh
git clone 'https://github.com/wazuh/wazuh-docker.git' -b 'v4.7.4'
cd 'wazuh-docker/single-node'
[[ $(uname -s) == 'Linux' ]] && sudo sysctl -w vm.max_map_count=262144
docker-compose -f 'generate-indexer-certs.yml' run --rm 'generator'
docker-compose up -d
```

  </details>

```sh
open 'https://localhost'
xdg-open 'https://localhost'
```

</details>

<details>
  <summary>Configuration</summary>

| FIle         | Paths                                                                                     | Description                                                                                                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ossec.conf` | `/var/ossec/etc/`<br/>`C:\Program Files (x86)\ossec-agent\`                               | Local configuration.<br/>Main configuration file for the manager.                                                                                                                           |
| `agent.conf` | `/var/ossec/etc/shared/default/`<br/>`C:\Program Files (x86)\ossec-agent\shared\default\` | Shared configuration.<br/>Main configuration file for the agents.<br/>Validated by `/var/ossec/bin/verify-agent-conf`.<br/>Overrides settings from `ossec.conf` unless specified otherwise. |

  <details style="margin-left: 1em">
    <summary>Docker compose</summary>

| File                                      | Description                  |
| ----------------------------------------- | ---------------------------- |
| `config/wazuh_cluster/wazuh_manager.conf` | Manager's configuration file |
| `config/wazuh_indexer_ssl_certs/`         | Certificates                 |

  </details>
</details>
<details>
  <summary>Usage</summary>
  <details style="margin-left: 1em">
    <summary>Docker compose</summary>

```sh
# Run commands in the components.
docker compose exec -it 'wazuh.manager' env
```

  </details>
</details>

## Components

| Component | Type     | Description                                                                                                                                            |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Indexer   | Central  | Full-text search and analytics engine.<br/>Indexes and stores alerts generated by the server.                                                          |
| Server    | Central  | Analyzes data received from the agents.<br/>Can set up in a cluster.<br/>Manages the agents.                                                           |
| Dashboard | Central  | Web UI for data visualization and analysis.<br/>Used to configure and monitor Wazuh.                                                                   |
| Agent     | Endpoint | Installed on monitored endpoints (i.e.: laptops, servers, cloud instances, virtual machines).<br/>Used for threat prevention, detection, and response. |

Wazuh can also monitor agent-less devices (e.g: firewalls, switches, routers) via Syslog, SSH or APIs.

![components and data flow](components%20and%20data%20flow.png)

### Indexer

Stores data as JSON documents.

_Indexes_ are collections of documents related to each other.<br/>
The stored documents are distributed across multiple different _shards_.<br/>
Shards are distributed on multiple nodes for redundancy.

Different indices store different event types.

| Index              | Content                                      | Notes                                                                                                                     |
| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `wazuh-alerts`     | Alerts generated by the server               | Created each time an event trips a rule with a high enough priority.                                                      |
| `wazuh‑archives`   | Events received by the server                | Created whether or not events trip a rule.                                                                                |
| `wazuh‑monitoring` | Data related to the agent's status over time | Used by the web interface to show when individual agents are or have been _active_, _disconnected_, or _never connected_. |
| `wazuh‑statistics` | Data related to the server's performance     | Used by the web interface to show performance statistics.                                                                 |

One can interact with the indexer cluster using its REST API.

### Server

Runs the analysis engine, the RESTful API, the agent enrollment and connection services, the cluster daemon, and
Filebeat.

Analyzes data received from the agents, triggers alerts when threats or anomalies are detected, and manages and monitors
the agents' configuration and state remotely.

![server architecture](server%20architecture.png)

| Component                | Description                                                                                                                                                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent enrollment service | Used to enroll new agents.<br/>Provides and distributes unique authentication keys to each agent.                                                                                                                                                                                                        |
| Agent connection service | Receives data from the agents.<br/>Uses the keys shared by the enrollment service to validate each agent's identity and encrypt the communications between the agents and the server.<br/>Provides centralized configuration management.                                                                 |
| Analysis engine          | Performs the data analysis by using decoders to identify the type of information being processed and extracting relevant data elements from the log messages. Then, by using rules, identifies patterns in the decoded events that could trigger alerts and possibly call for automated countermeasures. |
| RESTful API              | Provides an interface to interact with the Wazuh infrastructure.<br/>Manages configuration settings of agents and servers, monitors the infrastructure status and overall health, manages and edits decoders and rules, and queries monitored endpoints. Also used by the dashboard.                     |
| Cluster daemon           | Scales servers horizontally by deploying them as a cluster to provide high availability and load balancing. Used by servers to communicate with each other and keep synchronized.                                                                                                                        |
| Filebeat                 | Sends events and alerts to the indexer, reads the output of the analysis engine and ships events in real time, and provides load balancing when connected to a multi-node indexer cluster.                                                                                                               |

### Dashboard

User interface for mining, analyzing, and visualizing security events and alerts data.<br/>
Used for the management and monitoring of the platform.<br/>
Provides features for role-based access control (RBAC) and single sign-on (SSO).

Wazuh provides out-of-the-box dashboards for regulatory compliance (e.g.: PCI DSS, GDPR, HIPAA, and NIST 800-53).<br/>
It also provides an interface to navigate through the MITRE ATT&CK framework and related alerts.<br/>
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, and an API Console for users to interact with the API.

### Agent

Collects system and application data and forwards it to the server through an encrypted and authenticated channel.

Has a modular architecture where each component is in charge of its own tasks (monitoring the file system, reading log
messages, collecting inventory data, scanning the system configuration, looking for malware).

| Module                                  | Description                                                                                                                                                                                                                                                                                                                                         |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Log collector                           | Reads log files and system events, collects operating system and application log messages.                                                                                                                                                                                                                                                          |
| Command execution                       | Allows running authorized commands periodically to collect their output and report it back to the server for analysis.                                                                                                                                                                                                                              |
| File integrity monitoring (FIM)         | Monitors the file system to report when files are created, deleted or modified.<br/>Keeps track of changes in file attributes, permissions, ownership, and content. Captures who, what, and when details in real time when events occur. Builds and maintains a database with the state of the monitored files to allow queries to be run remotely. |
| Security configuration assessment (SCA) | Provides continuous configuration assessment.                                                                                                                                                                                                                                                                                                       |
| System inventory                        | Periodically runs scans and collects inventory data.<br/>Scan results are stored in local SQLite databases that can be queried remotely.                                                                                                                                                                                                            |
| Malware detection                       | Detects anomalies and the possible presence of rootkits.<br/>Looks for hidden processes, hidden files, and hidden ports while monitoring system calls.                                                                                                                                                                                              |
| Active response                         | Runs automatic actions when threats are detected.                                                                                                                                                                                                                                                                                                   |
| Container security monitoring           | Integrates with the Docker Engine API to monitor changes in containerized environments.<br/>Alerts about containers running in privileged mode and about users executing commands in a running container.                                                                                                                                           |
| Cloud security monitoring               | Monitors cloud providers by communicating with their APIs. Detects changes to the cloud infrastructure and collecting cloud services log data.                                                                                                                                                                                                      |

## Installation

### Requirements

Refer <https://documentation.wazuh.com/current/quickstart.html#requirements>.

[Open ports](https://documentation.wazuh.com/current/getting-started/architecture.html#required-ports).

### Procedure

Refer the [installation guide](https://documentation.wazuh.com/current/installation-guide/index.html) and
[installation alternatives](https://documentation.wazuh.com/current/deployment-options/index.html) pages.

<details style="margin-bottom: 1em">
  <summary>Docker compose</summary>

1. Clone the repository containing the compose files.<br/>
   Make sure to specify the branch:

   ```sh
   git clone 'https://github.com/wazuh/wazuh-docker.git' -b 'v4.7.4'
   ```

1. Enter the directory corresponding to the setup one wants:

   ```sh
   cd 'wazuh-docker/single-node'
   cd 'wazuh-docker/multi-node'
   ```

1. \[On Linux hosts]

   ```sh
   sudo sysctl -w vm.max_map_count=262144
   ```

1. Generate the self-signed certificates:

   ```sh
   docker-compose -f 'generate-indexer-certs.yml' run --rm 'generator'
   ```

   Or put one's own in the `config/wazuh_indexer_ssl_certs` directory:

   ```sh
   $ ls 'config/wazuh_indexer_ssl_certs'
   admin-key.pem            root-ca-manager.pem      wazuh.dashboard-key.pem      wazuh.indexer.pem
   admin.pem                root-ca.key              wazuh.dashboard.pem          wazuh.manager-key.pem
   root-ca-manager.key      root-ca.pem              wazuh.indexer-key.pem        wazuh.manager.pem
   ```

1. Run the composition:

   ```sh
   docker-compose up -d
   ```

   > Expect several `Failed to connect to Wazuh indexer port 9200` log messages and the _Wazuh dashboard server is not
   > ready yet_ message in the web UI until the Wazuh indexer finishes starting up.<br/>
   > It takes about 1 minute for the indexer to start up, then the dashboard setup process continues normally.<br/>
   > This is due to the dashboard container using `curl` to ping the indexer's API to know when it is up.

</details>

Once the service started, open <https://localhost>.<br/>
The default credentials are `admin`:`SecretPassword`.

## Configuration

### Local configuration

Refer <https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/index.html>.

The `ossec.conf` file is the main configuration file for the manager, and is used by the agents for defaults.<br/>
Errors in this file **will** prevent the manager from starting.

The file is in XML format. The outermost XML tag is `<ossec_config>`.<br/>
There can be more than one `<ossec_config>` tag. Repeating sections may override previously defined ones.

```xml
<ossec_config>
  <alerts>…</alerts>
  <wodle name="aws-s3">…</wodle>
</ossec_config>
```

### Shared configuration

Refer <https://documentation.wazuh.com/current/user-manual/reference/centralized-configuration.html>.

The `agent.conf` file is very similar to `ossec.conf` but is used to distribute configuration information to agents.

```xml
<agent_config>
  …
</agent_config>
```

When `agent.conf` is used, it is merged onto `ossec.conf`. Its settings will override or be added to the ones in the
local configuration.

Several configurations may be created based on the `name`, `OS` or `profile` of agents:

```xml
<agent_config name="agent_name">
    <localfile>
        <location>/var/log/my.log</location>
        <log_format>syslog</log_format>
    </localfile>
</agent_config>

<agent_config os="Linux">
    <localfile>
        <location>/var/log/linux.log</location>
        <log_format>syslog</log_format>
    </localfile>
</agent_config>

<agent_config profile="database">
    <localfile>
        <location>/var/log/database.log</location>
        <log_format>syslog</log_format>
    </localfile>
</agent_config>
```

## AWS integration

Refer <https://documentation.wazuh.com/current/cloud-security/amazon/index.html> and
<https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/wodle-s3.html>.

### Instances

Install the agent on hosts that need to be monitored.

### Services

Service monitoring requires one S3 bucket to save the data flow generated by Wazuh, and then redirect this to the rest
of the services from AWS.

The AWS module requires credentials to be able to pull log data from services.<br/>
`wazuh-modulesd` is executed by the `root` user, so the credentials file must be placed at `/root/.aws/credentials` if
used. Environment variables work as effectively.

Setup the module in the manager's configuration file.<br/>
Requires one `bucket` attribute.<br/>
Can be added in a separate `<ossec_config>` section.

```xml
…
<ossec_config>
  <wodle name="aws-s3">
    <bucket type="cloudtrail">
      <name>wazuh-bucket</name>
      <path>cloudtrail<path>
    </bucket>
    <bucket type="wpcflow">
      <name>wazuh-bucket-vpc</name>
    </bucket>
  </wodle>
</ossec_config>
```

## Further readings

- [Website]
- [Github]

### Sources

- [Documentation]
- [Docker installation repository]

<!--
  Reference
  ═╬═Time══
  -->

<!-- In-article sections -->
<!-- Knowledge base -->
<!-- Files -->
<!-- Upstream -->
[documentation]: https://documentation.wazuh.com/current/
[github]: https://github.com/wazuh/wazuh
[docker installation repository]: https://github.com/wazuh/wazuh-docker
[website]: https://wazuh.com/

<!-- Others -->
