Wazuh Indexer Technical Documentation

This folder contains the technical documentation for the Wazuh Indexer. The documentation is organized into the following guides:

• Development Guide: Instructions for building, testing, and packaging the Indexer.
• Reference Manual: Detailed information on the Indexer’s architecture, configuration, and usage.

Requirements

To work with this documentation, you need mdBook installed.

• Get the latest cargo (hit enter when prompted for a default install)

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

• Install mdbook and mdbook-mermaid

  cargo install mdbook --version 0.5.2 --locked
  cargo install mdbook-mermaid --version 0.17.0 --locked
  

Usage

• To build the documentation, run:

  ./build.sh
  

  The output will be generated in the book directory.

• To serve the documentation locally for preview, run:

  ./server.sh
  

  The documentation will be available at http://127.0.0.1:3000.

Development documentation

Under this section, you will find the development documentation of Wazuh Indexer. This documentation contains instructions to compile, run, test and package the source code. Moreover, you will find instructions to set up a development environment in order to get started at developing the Wazuh Indexer.

This documentation assumes basic knowledge of certain tools and technologies, such as Docker, Bash (Linux) or Git.

Before you start coding, read the sections below: they cover how to open good pull requests and how our GitHub Actions behave when you do. Getting this right up front saves CI minutes and review cycles for everyone.

Pull requests

These are the standard procedures for creating, updating, and reviewing pull requests across the Wazuh Indexer repositories.

Lifecycle

┌──────────┐    ┌──────────────┐    ┌─────────────────┐    ┌───────┐
│  Draft   │───▶│ Local build  │───▶│ Ready for       │───▶│ Merge │
│  PR      │    │ & test       │    │ review (CI runs)│    │       │
└──────────┘    └──────────────┘    └─────────────────┘    └───────┘

Every pull request must start in Draft status. Workflows do not run on Draft PRs — this is enforced across all repositories to avoid wasting GitHub Actions minutes on work in progress — so use Draft status freely while iterating on your changes.

Before marking the PR as ready, build the project successfully and run the tests locally to verify they pass. This prevents avoidable CI failures that waste runner time and delay reviews. Once everything is complete and locally validated, click “Ready for review” and move the linked issue to Pending review. This is the moment workflows are triggered for the first time.

To address review feedback, push new commits on top of the branch and re-request review once you have resolved all comments. Avoid amending or rebasing published commits during review, and if CI fails after pushing, investigate and fix it before requesting re-review. When the PR is approved and CI passes, it can be merged. Use squash merge for single-purpose PRs to keep a clean history.

Body template

Use the following template when creating a pull request:

## Description

<!-- Brief description of the changes and the reasoning behind them. -->

Resolves #<issue_number>

## Checklist

- [ ] ...

Always link the related issue with Resolves #<number> so it auto-closes on merge, and describe why rather than just what — the diff already shows what changed, so the description should explain the motivation.

Include instructions to test your changes, and any other relevant information for reviewers. Use the checklist to indicate that you have completed all required steps before requesting review.

Reviewing a PR

Start from the linked issue to understand the context and acceptance criteria, then read the description and checklist before reading the code. Focus your feedback on correctness, clarity, and maintainability, and use GitHub’s suggestion feature for small fixes to speed up the process. Approve only when you are confident the changes are correct and complete.

Changelog

Every PR is expected to include a changelog entry. The 5_codequality_changelog.yml workflow enforces this. Apply the skip-changelog label to bypass the check when the linked issue belongs to a private repository, or when the PR is linked to a public issue but genuinely does not require a changelog update.

Best practices

• Keep PRs small and focused. One issue per PR whenever possible.
• Write descriptive commit messages. They should explain why, not just what.
• Do not trigger CI unnecessarily. Keep PRs in Draft until ready, and validate locally first.

Workflows and Actions

This section defines the naming conventions and operational rules for the GitHub Actions and Workflows used across the Wazuh Indexer repositories.

Naming convention

Both Actions and Workflows follow the same pattern:

<major>_<prefix>_<target>

The prefix is drawn from the following set of use cases:

For workflows triggered on PR or push events, append _onpush to the name to distinguish them from their workflow_dispatch counterparts:

5_builderpackage_indexer.yml          ← workflow_dispatch (manual)
5_builderpackage_indexer_onpush.yml   ← PR / push trigger (automatic)

When composing jobs from Actions, a single job step cannot mix Actions with different prefixes, and steps must use matrices whenever possible.

Runners

Two types of runners are available:

• Default (GitHub-hosted) — used for all workflows unless there is a justified reason to use the dedicated runner.
• Dedicated (self-hosted) — reserved for resource-intensive workflows only. Currently used exclusively by 5_builderpackage_indexer (the full package builder).

Always prefer the default runner. The dedicated runner is a shared, limited resource — use it only when the workflow genuinely requires the extra capacity (e.g. the full product builder).

Draft PR enforcement

All PR workflows must be configured to skip Draft PRs, so that no CI minutes are consumed on work-in-progress PRs. This is enforced by adding the following condition to every PR-triggered workflow:

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  <job_name>:
    if: ${{ !github.event.pull_request.draft }}

Set up the development environment

1. Git

Install and configure Git (SSH keys, commits and tags signing, user and email).

1. Set your username.
2. Set your email address.
3. Generate an SSH key.
4. Add the public key to your GitHub account for authentication and signing.
5. Configure Git to sign commits with your SSH key.

2. Repositories

Clone the Wazuh Indexer repositories (use SSH). Before you start, you need to properly configure your working repositories to have origin and upstream remotes.

mkdir -p ~/wazuh && cd ~/wazuh

# Plugins (no upstream fork)
git clone git@github.com:wazuh/wazuh-indexer-plugins.git

# Indexer core (forked from OpenSearch)
git clone git@github.com:wazuh/wazuh-indexer.git
cd wazuh-indexer
git remote add upstream git@github.com:opensearch-project/opensearch.git
cd ..

# Reporting plugin (forked from OpenSearch)
git clone git@github.com:wazuh/wazuh-indexer-reporting.git
cd wazuh-indexer-reporting
git remote add upstream git@github.com:opensearch-project/reporting.git
cd ..

# Security Analytics (forked from OpenSearch)
git clone git@github.com:wazuh/wazuh-indexer-security-analytics.git
cd wazuh-indexer-security-analytics
git remote add upstream git@github.com:opensearch-project/security-analytics.git
cd ..

# Notifications plugin (forked from OpenSearch)
git clone git@github.com:wazuh/wazuh-indexer-notifications.git
cd wazuh-indexer-notifications
git remote add upstream git@github.com:opensearch-project/notifications.git
cd ..

# Common Utils plugin (forked from OpenSearch)
git clone git@github.com:wazuh/wazuh-indexer-common-utils.git
cd wazuh-indexer-common-utils
git remote add upstream git@github.com:opensearch-project/common-utils.git
cd ..

# Alerting plugin (forked from OpenSearch)
git clone git@github.com:wazuh/wazuh-indexer-alerting.git
cd wazuh-indexer-alerting
git remote add upstream git@github.com:opensearch-project/alerting.git
cd ..

3. Vagrant

Install Vagrant with the Libvirt provider following the guide.

Then install the Vagrant SCP plugin:

vagrant plugin install vagrant-scp

4. IntelliJ IDEA

Prepare your IDE:

1. Install IDEA Community Edition as per the official documentation.
2. Set a global SDK to Eclipse Temurin following this guide.

You can find the JDK version to use under the wazuh-indexer/gradle/libs.versions.toml file. IntelliJ IDEA includes some JDKs by default. If you need to change it, or if you want to use a different distribution, follow the instructions in the next section.

5. Set up Java

When you open a Java project for the first time, IntelliJ will ask you to install the appropriate JDK for the project.

Using IDEA, install a JDK following this guide. The version to install must match the JDK version used by the Indexer, currently Eclipse Temurin 25 (check bundled_jdk in wazuh-indexer/gradle/libs.versions.toml).

Once the JDK is installed, configure it as the default system-wide Java installation using update-alternatives. IntelliJ installs JDKs under ~/.jdks/; adjust the path to the version you installed:

sudo update-alternatives --install /usr/bin/java java /home/$USER/.jdks/temurin-25.0.2/bin/java 0

Check Java is correctly configured:

java --version

If you need to install or switch JDK versions, use sudo update-alternatives --config java to select the JDK of your preference.

Set the JAVA_HOME and PATH environment variables by adding these lines to your shell RC file (.bashrc, .zshrc, etc.):

export JAVA_HOME=/home/$USER/.jdks/temurin-25.0.2
export PATH=$PATH:$JAVA_HOME/bin

After that, restart your shell or run source ~/.zshrc (or similar) to apply the changes. Verify with java --version.

Tip: SDKMAN is a convenient tool for managing multiple JDK versions. Its identifiers carry the full patch version, so run sdk list java to find the current Temurin 25 identifier:

sdk install java 25.0.4-tem
sdk use java 25.0.4-tem

6. Docker (optional)

Docker is useful for running integration tests and local test environments. Install Docker Engine following the official instructions.

Verify the installation:

docker --version
docker run hello-world

7. Test cluster (optional)

The repository includes a Vagrant-based test cluster at tools/test-cluster/ for end-to-end testing against a real Wazuh Indexer instance.

Prerequisites:

• Vagrant
• VirtualBox or another supported provider

Refer to the tools/test-cluster/README.md for provisioning and usage instructions.

8. Verify the setup

After completing the setup, verify everything works:

For the Common Utils plugin (Shared Library):

cd wazuh-indexer-common-utils
./gradlew clean publishToMavenLocal

For the Alerting plugin:

cd wazuh-indexer-alerting
./gradlew clean publishToMavenLocal

For the Notifications plugin (Kotlin-based, separate repository):

cd wazuh-indexer-notifications/notifications
./gradlew clean publishToMavenLocal

For the Security Analytics plugin:

cd wazuh-indexer-security-analytics/commons
../gradlew clean publishToMavenLocal
cd ..
./gradlew clean publishToMavenLocal

cd wazuh-indexer-plugins
./gradlew :wazuh-indexer-content-manager:compileJava

If compilation succeeds, your environment is ready. See Build from Sources for more build commands.

How to generate a package

This guide includes instructions to generate distribution packages locally using Docker.

Wazuh Indexer supports any of these combinations:

• distributions: ['tar', 'deb', 'rpm']
• architectures: ['x64', 'arm64']

Windows is currently not supported.

For more information navigate to the compatibility section.

Before you get started, make sure to clean your environment by running ./gradlew clean on the root level of the wazuh-indexer repository.

Prerequisites

The process to build packages requires Docker and Docker Compose.

• Install Docker
• Install Docker Compose

Your workstation must meet the minimum hardware requirements (the more resources the better):

• 8 GB of RAM (minimum)
• 4 cores

The tools and source code to generate a package of Wazuh Indexer are hosted in the wazuh-indexer repository, so clone it if you haven’t done already.

A wazuh-engine tarball is required to build the Wazuh Indexer package. Follow the Engine build instructions in the wazuh/wazuh repository to produce it. The resulting .tar.gz is passed to builder.sh via the -e flag.

Building wazuh-indexer packages

The Docker environment under wazuh-indexer/build-scripts/builder automates the build and assemble process for the Wazuh Indexer and its plugins, making it easy to create packages on any system.

Use the builder.sh script to build a package.

./builder.sh -h
Usage: ./builder.sh [args]

Arguments:
-p INDEXER_PLUGINS_BRANCH       [Optional] wazuh-indexer-plugins repo branch, default is 'main'.
-r INDEXER_REPORTING_BRANCH     [Optional] wazuh-indexer-reporting repo branch, default is 'main'.
-s SECURITY_ANALYTICS_BRANCH    [Optional] wazuh-indexer-security-analytics repo branch, default is 'main'.
-n NOTIFICATIONS_BRANCH         [Optional] wazuh-indexer-notifications repo branch, default is 'main'.
-t INDEXER_ALERTING_BRANCH      [Optional] wazuh-indexer-alerting repo branch, default is 'main'.
-c COMMON_UTILS_BRANCH          [Optional] wazuh-indexer-common-utils repo branch, default is 'main'.
-e ENGINE_TARBALL               [Required] Path to wazuh-engine tarball (.tar.gz) on the host.
-R REVISION     [Optional] Package revision, default is '0'.
-S STAGE        [Optional] Staging build, default is 'false'.
-d DISTRIBUTION [Optional] Distribution, default is 'rpm'.
-a ARCHITECTURE [Optional] Architecture, default is 'x64'.
-D      Destroy the docker environment
-h      Print help

The example below generates a wazuh-indexer package for Debian based systems, for the x64 architecture, using 0 (the default) as revision number and using the production naming convention.

# Within wazuh-indexer/build-scripts/builder
bash builder.sh -d deb -a x64 -R 0 -S true -e ./wazuh-engine-5.0.0-linux-amd64.tar.gz

The resulting package will be stored at wazuh-indexer/artifacts/dist.

The STAGE option defines the naming of the package. When set to false, the package will be unequivocally named with the commits’ SHA of the wazuh-indexer, wazuh-indexer-plugins, wazuh-indexer-reporting, wazuh-indexer-security-analytics, wazuh-indexer-notifications and wazuh-indexer-alerting repositories, in that order. For example: wazuh-indexer_5.0.0-0_x86_64_aff30960363-846f143-494d125-9c0c1fe-3b2a8d1-7e5f094.rpm.

Installing the generated package

The package produced under wazuh-indexer/artifacts/dist is the input to the standard Wazuh Indexer installation procedure. Follow the Installation guide for certificate creation, node configuration, and cluster initialization steps.

How to generate a container image

This guide includes instructions to generate distribution packages locally using Docker.

Wazuh Indexer supports any of these combinations:

• distributions: ['tar', 'deb', 'rpm']
• architectures: ['x64', 'arm64']

Windows is currently not supported.

For more information navigate to the compatibility section.

Before you get started, make sure to clean your environment by running ./gradlew clean on the root level of the wazuh-indexer repository.

Prerequisites

The process to build packages requires Docker and Docker Compose.

• Install Docker
• Install Docker Compose

Your workstation must meet the minimum hardware requirements (the more resources the better):

• 8 GB of RAM (minimum)
• 4 cores

The tools and source code to generate a package of Wazuh Indexer are hosted in the wazuh-indexer repository, so clone it if you haven’t done already.

Building wazuh-indexer Docker images

The docker folder (wazuh-indexer/build-scripts/docker) contains the code to build Docker images. Below there is an example of the command needed to build the image. Set the build arguments and the image tag accordingly.

The Docker image is built from a wazuh-indexer tarball (tar.gz), which must be placed in wazuh-indexer/build-scripts/docker and named following the convention wazuh-indexer-<arch>.tar.gz, where <arch> matches Docker’s architecture naming (amd64 or arm64).

# Copy and rename the tarball to the expected name (from wazuh-indexer/build-scripts/docker)
cp wazuh-indexer_<version>-<revision>_linux-x64.tar.gz wazuh-indexer-amd64.tar.gz

# Build the image
docker build --build-arg="VERSION=<version>" --tag=wazuh-indexer:<version>-<revision> --progress=plain --no-cache .

Then, start a container with:

docker run -p 9200:9200 -it --rm wazuh-indexer:<version>-<revision>

The build-and-push-docker-image.sh script automates the process to build and push Wazuh Indexer Docker images to our repository in quay.io. The script takes several parameters. Use the -h option to display them.

To push images, credentials must be set at environment level:

• QUAY_USERNAME
• QUAY_TOKEN

Usage: build-scripts/build-and-push-docker-image.sh [args]

Arguments:
-a ARCHITECTURE [Optional] Target architecture (amd64 or arm64), default is host arch.
-r REVISION     [Optional] Revision qualifier, default is 0.
-h help

The script will stop if the credentials are not set, or if the expected tarball is not found.

This script is used in the 5_builderpackage_docker.yml GitHub Workflow, which is used to automate the process even more. When possible, prefer this method.

Note: all the scripts under the ci folder are used in the GitHub workflows and are not intended to be used manually..

How to build from sources

The Wazuh Indexer Plugins repository uses Gradle as its build system. The root project contains multiple subprojects, one per plugin.

Building the entire project

To build all plugins (compile, test, and package):

./gradlew build

When completed, distribution artifacts for each plugin are located in their respective build/distributions/ directories.

Building a specific plugin

To build only the Content Manager plugin:

./gradlew :wazuh-indexer-content-manager:build

Other plugin targets follow the same pattern. To see all available projects:

./gradlew projects

Compile only (no tests)

For a faster feedback loop during development, compile without running tests:

./gradlew :wazuh-indexer-content-manager:compileJava

This is useful for checking that your code changes compile correctly before running the full test suite.

Output locations

Common build issues

JDK version mismatch

The project is built and tested with JDK 25 (Eclipse Temurin — the bundled_jdk in wazuh-indexer/gradle/libs.versions.toml), and the build refuses to run on anything older than JDK 21. If you see compilation errors related to Java version, check:

java --version

Ensure JAVA_HOME points to the correct JDK. See Setup for details.

Dependency resolution failures

If Gradle cannot resolve dependencies:

1. Check your network connection (dependencies are downloaded from Maven Central and repositories).
2. Try clearing the Gradle cache: rm -rf ~/.gradle/caches/
3. Re-run with --refresh-dependencies: ./gradlew build --refresh-dependencies

Out of memory

For large builds, increase Gradle’s heap size in gradle.properties:

org.gradle.jvmargs=-Xmx4g

Linting and formatting errors

The build includes code quality checks (Spotless, etc.). If formatting checks fail:

./gradlew spotlessApply

Then rebuild.

Useful Gradle flags

• --info — verbose output.
• --debug — debug-level output.
• --stacktrace — print stack traces on failure.
• --parallel — run tasks in parallel (faster on multi-core).
• -x test — skip tests: ./gradlew build -x test.
• --continuous — watch mode; rebuilds on file changes.

How to run from sources

Every Wazuh Indexer repository includes one or more Gradle projects with predefined tasks to run and build the source code.

In this case, to run a Gradle project from source code, run the ./gradlew run command.

For Wazuh Indexer, additional plugins may be installed by passing the -PinstalledPlugins flag:

./gradlew run -PinstalledPlugins="['plugin1', 'plugin2']"

The ./gradlew run command will build and start the project, writing its log above Gradle’s status message. A lot of stuff is logged on startup, specifically these lines tell you that OpenSearch is ready.

[2020-05-29T14:50:35,167][INFO ][o.e.h.AbstractHttpServerTransport] [runTask-0] publish_address {127.0.0.1:9200}, bound_addresses {[::1]:9200}, {127.0.0.1:9200}
[2020-05-29T14:50:35,169][INFO ][o.e.n.Node               ] [runTask-0] started

It’s typically easier to wait until the console stops scrolling, and then run curl in another window to check if OpenSearch instance is running.

curl localhost:9200

{
  "name" : "runTask-0",
  "cluster_name" : "runTask",
  "cluster_uuid" : "oX_S6cxGSgOr_mNnUxO6yQ",
  "version" : {
    "number" : "1.0.0-SNAPSHOT",
    "build_type" : "tar",
    "build_hash" : "0ba0e7cc26060f964fcbf6ee45bae53b3a9941d0",
    "build_date" : "2021-04-16T19:45:44.248303Z",
    "build_snapshot" : true,
    "lucene_version" : "8.7.0",
    "minimum_wire_compatibility_version" : "6.8.0",
    "minimum_index_compatibility_version" : "6.0.0-beta1"
  }
}

Use -Dtests.opensearch. to pass additional settings to the running instance. For example, to enable OpenSearch to listen on an external IP address, pass -Dtests.opensearch.http.host. Make sure your firewall or security policy allows external connections for this to work.

./gradlew run -Dtests.opensearch.http.host=0.0.0.0

How to run the tests

This section explains how to run the Wazuh Indexer Plugins tests at various levels.

Full suite

To execute all tests and code quality checks (linting, documentation, formatting):

./gradlew check

This runs unit tests, integration tests, and static analysis tasks.

Unit tests

Run all unit tests across the entire project:

./gradlew test

Run unit tests for a specific plugin:

./gradlew :wazuh-indexer-content-manager:test

Integration tests

Run integration tests for a specific plugin:

./gradlew :wazuh-indexer-content-manager:integTest

YAML REST tests

Plugins can define REST API tests using YAML test specs. To run them:

./gradlew :wazuh-indexer-content-manager:yamlRestTest

Reproducible test runs

Tests use randomized seeds. When a test fails, the output includes the seed that was used. To reproduce the exact same run:

./gradlew :wazuh-indexer-content-manager:test -Dtests.seed=DEADBEEF

Replace DEADBEEF with the actual seed from the failure output.

Viewing test reports

After running tests, HTML reports are generated at:

plugins/<plugin-name>/build/reports/tests/test/index.html

Open this file in a browser to see detailed results with pass/fail status, stack traces, and timing.

For integration tests:

plugins/<plugin-name>/build/reports/tests/integTest/index.html

Code coverage

Code coverage is measured with JaCoCo. The configuration lives in gradle/coverage.gradle, which both plugins apply.

Coverage of the unit tests:

./gradlew :wazuh-indexer-content-manager:jacocoTestReport

jacocoTestReport runs the unit tests first if needed. To also measure the plugin code that runs inside the integration test cluster, add -Dtests.coverage=true. This runs integTest as well:

./gradlew :wazuh-indexer-content-manager:jacocoTestReport -Dtests.coverage=true

The reports are written in three formats:

plugins/<plugin-name>/build/reports/jacoco/test/html/index.html
plugins/<plugin-name>/build/reports/jacoco/test/jacocoTestReport.xml
plugins/<plugin-name>/build/reports/jacoco/test/jacocoTestReport.csv

Open the HTML report in a browser to browse the coverage per package, class and source line.

In CI, the Gradle check workflow runs ./gradlew check jacocoTestReport -PnumNodes=1 -Dtests.coverage=true for each modified plugin. It adds a coverage table to the job summary and uploads the reports as the coverage-<plugin-name> workflow artifact.

The workflow also runs on every push to main or to a release branch (<major>.<minor>.<patch>) that changes plugin code. There it measures both plugins, and its coverage-badge job generates the coverage and branches badges from the two CSV reports and commits them to the badges branch, in a folder named after the pushed branch (for example 5.0.0/jacoco.svg). It creates the badges branch on the first run. The README’s coverage badge shows main/jacoco.svg, the default branch’s.

The integration test nodes are stopped with SIGKILL, so the JaCoCo agent on each node cannot write its data on exit. Instead, each node’s agent serves its data over TCP on a free port, and integTest pulls it into build/jacoco/integTestCluster.exec after the last test, before the cluster stops.

Running a single test class

To run a specific test class:

./gradlew :wazuh-indexer-content-manager:test --tests "com.wazuh.contentmanager.rest.service.RestPostRuleActionTests"

Test cluster (Vagrant)

For end-to-end testing on a real Wazuh Indexer service, the repository includes a Vagrant-based test cluster at tools/test-cluster/. This provisions a virtual machine with Wazuh Indexer installed and configured.

Refer to its README.md for setup and usage instructions.

Package testing

Built packages are tested by the package builder Workflow, each test in a throwaway container:

• DEB packages — an Ubuntu 22.04 container running systemd, started by build-scripts/run_in_systemd_container.sh.
• RPM packages — Red Hat UBI 9 containers: redhat/ubi9, or redhat/ubi9-init when the test needs systemd, through the same script with SYSTEMD_IMAGE set.

The tests cover:

• Installation and removal — the package installs, and removes (DEB: purges) without errors.
• Removal leftovers — build-scripts/ci/test_purge.sh: a purge always removes the wazuh-indexer user and group; what the service account owned in the package’s four directories belongs to root and keeps its mode, and the directories are closed to everyone but root; only a directory that still holds files is listed as kept; the engine’s runtime files and the JVM’s performance data in /tmp do not outlive the purge; the certificates issued from the removed CA go with it, and an operator’s own pair stays; a custom path.repo is left exactly as it was; a directory that cannot be handed over is reported and not listed as kept; a reinstall restores every owner and mode, and the node’s certificates chain to its CA; and the resolver refuses a pair the CA did not issue. See When the package is purged.
• Credential and TLS resolution — build-scripts/ci/test_credentials.sh. See Credential and TLS resolution.
• Host tools — build-scripts/ci/test_host_tools.sh: the maintainer scripts and the scripts the package ships run no host tool outside the declared dependencies. See Host dependencies.
• Upgrades — from the previous version, with the indexer stopped and running. Only when a previous version exists.
• 4.x upgrade block — build-scripts/ci/test_upgrade_block.sh: the package refuses to upgrade a 4.x installation.

Each script documents its requirements in its header and can also be run on a throwaway VM.

Useful test flags

• -Dtests.seed=<seed> — reproduce a specific randomized test run.
• -Dtests.verbose=true — print test output to stdout.
• --tests "ClassName" — run a single test class.
• --tests "ClassName.methodName" — run a single test method.
• -x test — skip unit tests in a build.

Packages

This page is for the people who build and maintain the Wazuh Indexer Debian (DEB) and RPM packages: how a package is put together, how it is named, built in continuous integration (CI) and tested, and how its maintainer scripts behave on installation, upgrade and removal. For the commands to build a package yourself, see Build packages.

Everything described here lives in the wazuh-indexer repository, and every path on this page is relative to it: the build tooling is in build-scripts/, the package definitions and maintainer scripts in distribution/packages/src/.

• Packages
  • Supported systems
  • How a package is built
    • Build
    • Assemble
    • The Docker builder
    • The artifacts directory
  • Package naming
  • Continuous integration
  • Testing
  • Maintainer scripts
    • Upgrades keep the service state
    • Configuration files
    • Further reading
  • Credential and TLS resolution
    • Where things live
    • Resolution happens once
    • The password rule
    • How a password reaches the cluster
    • Resolver modes
    • Certificate resolution
  • File ownership
    • When the package is purged
  • Host dependencies

Supported systems

The build produces three formats, deb, rpm and tar, each for the x64 and arm64 architectures. Windows is not supported.

The operating systems the packages are supported and tested on are listed in Compatibility. That table is the one to update when support changes, and it must always match the list in the Wazuh documentation. The Indexer team keeps both up to date.

How a package is built

A package is built in two stages, each driven by its own script:

• Build — build-scripts/build.sh compiles the OpenSearch fork with Gradle and produces the minimal package, wazuh-indexer-min: the search engine alone, with no plugins and no Wazuh configuration.
• Assemble — build-scripts/assemble.sh unpacks the minimal package, adds everything that makes it the Wazuh Indexer, and packs the final package, wazuh-indexer, the one installed on hosts.

flowchart LR
    src["wazuh-indexer sources"] -->|build.sh| min["wazuh-indexer-min package"]
    min --> asm["assemble.sh"]
    plugins["Wazuh plugin ZIPs"] --> asm
    central["OpenSearch plugins<br/>(Maven Central)"] --> asm
    engine["Wazuh Engine tarball"] --> asm
    cti["CTI snapshots"] --> asm
    asm --> final["wazuh-indexer package<br/>and .sha512 checksum"]

GitHub Actions provides the infrastructure, but the build logic is self-contained in Gradle and these Bash scripts, so the same process runs unchanged in the Docker builder, in CI and on a workstation. build.sh keeps the shape of the per-component build script that OpenSearch’s opensearch-build repository expects, which is why it also publishes Maven artifacts.

Build

build.sh runs publishToMavenLocal and publishNebulaPublicationToTestRepository, then the :distribution:<type>:<target>:assemble Gradle task for the requested format and architecture (<type> is packages for DEB and RPM, archives for the tarball), and bundles the workload-management plugin, which is built from this repository rather than downloaded. Gradle writes the package to distribution/<type>/<target>/build/distributions/, and the script copies it to artifacts/dist/ under the name given with -n.

Assemble

assemble.sh finds the minimal package in artifacts/dist/, unpacks it in artifacts/tmp/ (with ar and tar for DEB, rpm2cpio and cpio for RPM), and then:

1. Writes VERSION.json into the product directory, with a commit field holding the commit hashes the package was built from (see Package naming).
2. Installs the plugins with opensearch-plugin, from three lists at the top of the script: plugins, the OpenSearch plugins, downloaded from Maven Central at the OpenSearch version in buildSrc/version.properties; internal_plugins, built by build.sh; and wazuh_plugins, read from artifacts/plugins/.
3. Copies the Content Manager’s Cyber Threat Intelligence (CTI) snapshots, when artifacts/snapshots/ exists, into plugins/wazuh-indexer-content-manager/snapshots/.
4. Installs the Wazuh Engine from the tarball in artifacts/engine/ into engine/.
5. Applies the Wazuh configuration. Once the Security plugin has created its default files in opensearch-security/, the script appends Wazuh’s *.wazuh.yml files to them (see Security), deletes the demo users and role mappings the product does not use, replaces the admin and kibanaserver hashes with credential placeholders (see How a password reaches the cluster) and disables multi-tenancy. It then installs opensearch.prod.yml as opensearch.yml, and removes symbolic links, .bat files and the Security plugin’s install_demo_configuration.sh.
6. Builds the installation assistant tools from that repository’s sources: config.yml, wazuh-passwords-tool.sh and wazuh-certs-tool.sh go into tools/, with the indexer’s own wazuh-indexer-credentials.sh put in place of the assistant’s shared library they embed (see Where things live), and that library itself goes into lib/.
7. Packs the result, with debmake and debuild from distribution/packages/src/deb/, or with rpmbuild from distribution/packages/src/rpm/wazuh-indexer.rpm.spec. It drops the -min from the name and writes a .sha512 checksum beside the package.

Assembly needs network access, to Maven Central and to the installation assistant’s repository on GitHub.

To add a plugin to the package, add an OpenSearch plugin to the plugins list in assemble.sh. A Wazuh plugin goes in wazuh_plugins there and in the maven_plugins list of copy_builds in build-scripts/builder/entrypoint.sh; one from a new repository also needs a clone entry and a build function in that file. A file the service writes at runtime also needs an ownership exception, as described in File ownership.

The Docker builder

build-scripts/builder/builder.sh runs both stages inside a container (compose.yml and Dockerfile in the same directory) that carries JDK 21 and every packaging tool, so nothing has to be installed on the host. The container’s entrypoint.sh:

1. Clones the six plugin repositories at the branch, tag or commit given for each, into named volumes that persist between runs.
2. Downloads the CTI snapshots with build-scripts/download_snapshots.sh from CTI_API_URL, which defaults to the pre-production CTI API.
3. Builds the plugins with ./gradlew publishToMavenLocal -x check, versioned <version>.<revision>, in dependency order: Common Utils, Alerting, Security Analytics (its commons module first), Notifications, Reporting, and last the Setup and Content Manager plugins from wazuh-indexer-plugins.
4. Copies the plugin ZIPs to artifacts/plugins/ and the Engine tarball to artifacts/engine/.
5. Clears artifacts/dist/ and artifacts/tmp/, names the minimal package with baptizer.sh, and runs build.sh and assemble.sh.

The builder’s flags and prerequisites, including how to obtain the Engine tarball, are in Build packages.

build.sh and assemble.sh can also run directly, from the repository root, once artifacts/plugins/ and artifacts/engine/ are populated. The builder exists so that this is rarely worth doing: the host then needs jq at /usr/bin/jq, Maven, a JDK and debmake or rpmbuild; assemble.sh overwrites ~/.devscripts when it packs a DEB; and a minimal package left in artifacts/dist/ by an earlier run breaks assembly, because the script finds the minimal package by pattern.

The artifacts directory

Both stages read from and write to artifacts/, at the repository root:

Package naming

The stages hand packages to each other by file name, so names are generated rather than typed: build-scripts/baptizer.sh prints the name for a combination of parameters. It only prints, so it is safe to run with any combination to get familiar with the convention. Run it from the repository root.

The version comes from the version field of VERSION.json, and the Wazuh plugins are versioned <version>.<revision> from it. The stage field (rc1, for example) is not part of the name: it is only sent as the version tag when the builder requests the CTI snapshots.

There are two conventions:

• Release — the name a published package carries. Selected with -x (the builder’s -S true, the Workflow’s is_stage).
  • DEB and tarball: wazuh-indexer_<version>-<revision>_<architecture>.<extension>
  • RPM: wazuh-indexer-<version>-<revision>.<architecture>.rpm
• Development — the default, the same for every format: wazuh-indexer_<version>-<revision>_<architecture>_<commits>.<extension>. <commits> is the short hash of the wazuh-indexer commit or, when all five plugin hashes are given (the builder always gives them), six hashes joined by -: wazuh-indexer, wazuh-indexer-plugins, wazuh-indexer-reporting, wazuh-indexer-security-analytics, wazuh-indexer-notifications and wazuh-indexer-alerting, in that order.

-m replaces the wazuh-indexer prefix with wazuh-indexer-min, the name build.sh gives the minimal package. assemble.sh drops the -min again.

The architecture is spelled the way each package manager expects:

bash build-scripts/baptizer.sh -d rpm -a x64 -r 0 -x
# wazuh-indexer-5.0.0-0.x86_64.rpm
bash build-scripts/baptizer.sh -d deb -a arm64 -r 0 -x
# wazuh-indexer_5.0.0-0_arm64.deb
bash build-scripts/baptizer.sh -d rpm -a x64 -r 0
# wazuh-indexer_5.0.0-0_x86_64_a55f704b69c.rpm

The commit field assemble.sh writes into /usr/share/wazuh-indexer/VERSION.json holds the same six hashes, so an installed node records what it was built from even under a release name. The wazuh-indexer-common-utils commit, which several of the plugins are built against, appears in neither the name nor that field.

Continuous integration

Packages are built by the 5_builderpackage_indexer.yml Workflow, (5.x) Build packages. To run it by hand, open the repository’s Actions tab, select (5.x) Build packages, fill in the form and click Run workflow. The inputs that change the result:

• revision (default 0) — the package revision.
• is_stage (default false) — use the release naming convention.
• distribution and architecture — the formats and architectures to build, one job per combination.
• plugins_ref (default main) — the branch, tag or commit to build the plugin repositories and the Wazuh Engine from. Each repository uses the same-named branch when it has one, and otherwise the branch for the product version, so a feature branch pushed with the same name to several repositories is built together.
• upload and checksum — upload the packages, and their checksums, to the S3 bucket.

The Workflow first checks that every repository declares the same product and OpenSearch versions (build-scripts/check_compatibility_versions.sh) and builds the Wazuh Engine through the wazuh/wazuh repository’s 5_builderpackage_engine-standalone.yml. It then runs the same builder.sh described above, on the dedicated runner, followed by the package tests. 5_builderpackage_indexer_onpush.yml calls it for every pull request that is ready for review and changes more than Markdown files.

Testing

Every package the Workflow builds is installed, removed and, when a previous version exists, upgraded, in throwaway containers before it is uploaded. Package testing lists those tests and the scripts behind them.

To try a package on a real service, use the Vagrant environment described in Test cluster (Vagrant). More extensive testing, including end-to-end (E2E) tests, is done by the quality assurance (QA) team.

Maintainer scripts

Paths are relative to distribution/packages/src/. The systemd unit, its environment file, the SysV init script and the sysctl settings are shared by both packages, under common/. A change to one package’s scripts almost always needs its counterpart in the other.

The two package managers run these scripts in a different order, and that order decides where each step has to go. Fedora’s scriptlet ordering and the Debian maintainer scripts flowcharts are the references.

Upgrades keep the service state

An upgrade leaves the service as it found it: a node that was running is running again afterwards, with no operator action, and a stopped node stays stopped.

1. Before the new files are unpacked, DEB preinst upgrade or RPM %pre (with $1 set to 2) refuses to upgrade a 4.x installation, then stops the service if it is active and creates the flag file /etc/wazuh-indexer/.was_active.
2. The package manager replaces the files.
3. DEB postinst configure (with the previous version in $2) or RPM %posttrans restarts the service if the flag exists, and deletes it. Without the flag, it prints how to start the service instead.

The RPM restart is in %posttrans, not %post, because during an RPM upgrade the new package’s %post runs before the old package’s %preun, its file removal and its %postun. %posttrans is the only scriptlet that runs after all of them. The old package’s removal scriptlets act only when $1 is 0, a real erase, and DEB prerm upgrade and postrm upgrade do nothing, so an upgrade never disables the service. The spec declares the flag file %ghost, so RPM owns it without shipping it.

For the operator’s side of an upgrade, see Upgrade.

Configuration files

The package manager never overwrites a configuration file the operator changed. The two formats handle the conflict differently:

• RPM — the files marked %config(noreplace) in %files: opensearch.yml, jvm.options, log4j2.properties, the opensearch-security/ files, /etc/sysconfig/wazuh-indexer and a few others. An upgrade replaces an unmodified file. A modified one is kept, and when the packaged version changed, the new version is written beside it with the .rpmnew suffix. On erase, a modified file is saved with the .rpmsave suffix.
• DEB — debhelper marks every file under /etc as a conffile. An upgrade replaces an unmodified conffile. For a modified one whose packaged version also changed, dpkg asks the operator which to keep, unless --force-confold or --force-confnew answers for them; the CI upgrade tests pass --force-confnew. remove keeps conffiles and purge deletes them.

resolve-credentials.sh writes the node and admin distinguished names (DNs) into opensearch.yml and the password digests into internal_users.yml when it resolves them, normally at installation, so on every host both files count as modified from the start. Any change to their shipped content therefore produces an .rpmnew file or a dpkg prompt on every upgrade. For the same reason, the RPM erase deletes their .rpmsave copies: they carry credential material.

Further reading

• Debian Policy: configuration file handling
• Debian Wiki: maintainer scripts
• Fedora Packaging Guidelines: scriptlets
• rpm.org: spec file format
• Maximum RPM: directives for the %files list

Credential and TLS resolution

The Wazuh Indexer package resolves its own credentials and Transport Layer Security (TLS) material rather than shipping defaults. This section covers when that runs and what it does; the commands it needs from the host are listed in Host dependencies. For the accounts and roles themselves, see Security.

Where things live

Everything the package resolves is under its own configuration directory, /etc/wazuh-indexer, and nothing is shared with the other Wazuh packages on the host:

The lookup order for a value is the process environment, then local.env, then what the package already published in export/credentials.env, then generation. The indexer owns its three accounts and consumes nothing from another package, so a password is never left unresolved.

The manager and the dashboard read export/ when they are installed or started on the same host, after checking that it is root’s; on other hosts the operator copies the values into their own local.env and certs/. The names and formats of the files in export/ are a contract with those packages.

lib/wazuh-indexer-credentials.sh, shipped beside the resolver, is the library that reads and writes these files, mints and validates the CA, and generates and validates passwords. wazuh-certs-tool.sh and wazuh-passwords-tool.sh carry a copy of it, put there by assemble.sh in place of the installation assistant’s shared library they are built with.

Files root reads and writes

Every file the resolver reads as root must be a regular file, not a symbolic link, owned by root and writable by nobody else, in a directory with the same properties; export/ and ca/ may carry the service group, never a group write bit, and local.env, export/credentials.env and ca/root-ca.key must be readable by root alone. Anything else is reported as UNSAFE <path>: <reason>, never repaired and never followed. Writes go to a temporary file in the target directory followed by a rename, so nothing is ever written through an existing path. The same checks run at every start — --check, which --prestart runs first — whether or not anything is left to resolve, so trust material planted after the install stops the service rather than being used.

The security plugin walks the whole configuration directory at start and logs a warning for every file readable by others and every directory others can enter. Nothing under /etc/wazuh-indexer is therefore world-readable, including the CA certificates, which the other packages read as root.

Resolution happens once

resolve-credentials.sh runs from four places — postinst / %post, the unit’s ExecStartPre, the SysV start path, and a container entrypoint — but it does its work once. A run that resolves everything it was responsible for records the fact in /var/lib/wazuh-indexer/.initialized, and every later run only checks the files and exits without resolving anything again.

The marker, not the mode, is what makes that true. Every mode resolves the same things — the passwords, the certificates and the trust anchor in the bundled JDK — so a run that finds the marker absent finishes whatever an earlier one could not.

That is not an optimisation. A password an operator rotated, or a certificate pair they replaced with their own, has to survive a service restart and a package upgrade, and the only way to guarantee that is to stop looking. A partial run — one that could not issue a certificate, say — deliberately does not record completion, so the next install can still finish the job.

resolve-credentials.sh --clear is the one way back. It takes back every half of everything this component resolved: the passwords and the CA certificate published in export/ and the digests in internal_users.yml, which return to their ${NAME} placeholders; the certificates, a CA it minted itself, and the node and admin DNs derived from them; and the CA entry in the bundled JDK truststore. A CA the package did not mint — one the operator staged, with or without its key — stays, and so does local.env.

It exists for container images built by installing the package, which would otherwise bake one host’s credentials into a layer every container shares. The next start resolves all of it again.

indexer-security-init.sh keeps no state of its own. It is run by an operator, once, and the package never calls it — so there is nothing for it to guard against repeating.

The password rule

A password, supplied or generated, has 12 to 64 characters from A-Z a-z 0-9 . , _ + : @ % ^ = ~ -, with at least one uppercase letter, one lowercase letter, one digit and one symbol. It is the same rule the Server API applies, so one value is accepted in both realms.

wazuh_password_validate in lib/wazuh-indexer-credentials.sh is the only place that checks it. The start-time error that names a rejected key restates the rule, so that an operator can correct the value without reading the library.

How a password reaches the cluster

internal_users.wazuh.yml ships each account’s hash as a ${NAME} placeholder rather than a digest, so the package carries no usable credential. resolve-credentials.sh resolves the value, bcrypts it with the Security plugin’s hash.sh, and substitutes the digest in place.

The placeholder is deliberately bare. The Security plugin substitutes ${env.X}, ${envbc.X} and ${envbase64.X} itself, node-side, at every configuration load — which would tie each account to a variable that has to stay in the service environment for the life of the deployment. A placeholder with no such prefix is left untouched by the plugin.

The digest and the published password are one credential in two halves, and resolution keeps them together rather than writing either alone. An account whose placeholder is already gone while nothing supplies its password — a host upgrading from a version that predates this mechanism, whose internal_users.yml the package manager kept — is reported and left as it is, instead of being given a freshly generated password that its digest would not match.

Loading the result into the cluster stays a manual step, indexer-security-init.sh. A package cannot know whether other nodes of the same cluster are still to be installed elsewhere, so running it automatically would either race those nodes or overwrite what they uploaded.

Resolver modes

resolve-credentials.sh takes one of five modes:

• --install — from postinst / %post on a fresh install. Creates what it can and never fails: a maintainer script that aborts leaves the package half-configured. It is the only mode that replaces a DN setting that already has a value.
• --upgrade — from postinst / %post on an upgrade. Fills in only what this host never had.
• --prestart — from the unit’s ExecStartPre and from the SysV start path. Runs the file checks first, on every start, then refuses to start the service when something is unresolved or unsafe, naming it.
• --check — the file checks alone, for an operator or a test: one line per problem, exit 1 on any. See Files root reads and writes.
• --clear — takes back everything this component resolved, so a later run resolves from nothing. Nothing in the package calls it; see Resolution happens once.

-q / --quiet silences the progress lines, and is not a mode. The maintainer scripts pass it so that the install ends with the next steps an operator needs — where the passwords are, how to start and enable the service, and that the security configuration is loaded once from one node — rather than with a list of resolved keys. Anything that could not be resolved still prints.

Certificate resolution

Which case applies is decided entirely by what is present in the certificate authority (CA) directory, with no mode flag — the presence of a private key beside the trust anchor is the signal, so a host never given one cannot sign:

A pair already in place is used only once openssl verify confirms that it chains to the anchor the node will trust: the CA directory’s, or, with nothing there, the root-ca.pem staged beside the pair, which is then published as export/ca.pem too. The check passes -partial_chain, so the anchor can be the CA that issued the pair rather than a self-signed root, as the node’s trust store accepts. The helper takes only a self-signed root into the CA directory, so an issuing CA can only be staged beside the pair. A pair that does not chain, or one with nothing to verify it against, is unresolved. The resolver names it and records no completion, rather than leaving a node whose own certificate its trust anchor rejects while the resolution reports success. With no anchor, the error names both places to stage one, and the ownership and modes the CA directory requires. With nothing in the CA directory and a pair in place, no CA is minted: a new one could not have issued that pair.

A staged pair must be root’s, like everything else in certs/: root:wazuh-indexer 0640 for the node’s pair and the anchor, root:root 0600 for the admin pair. One owned by the service account is reported as UNSAFE and refused, never chowned: a repair would turn a planted file into a trusted one.

The Subject Alternative Names (SANs) default to the hostname, the fully qualified domain name (FQDN), loopback and the global addresses of default-route interfaces. WAZUH_INDEXER_CERT_SANS, from the process environment or from local.env, replaces that list wholesale: a comma-separated list in OpenSSL’s form, each entry a DNS: name or an IP: address, for example WAZUH_INDEXER_CERT_SANS=DNS:node-1.example.com,IP:10.0.0.1. localhost and the loopback addresses are always appended; an empty list, or an entry without one of those prefixes, is refused with a message that names the variable.

The host name comes from the kernel (/proc/sys/kernel/hostname) and the FQDN from getent hosts, the addresses from ip: the resolver runs no other host tool, and every text transformation is shell. The certificates are issued with openssl, because the bundled JDK has no tool that issues PEM certificates.

Every certificate the package issues, the CA included, is signed through openssl ca with a throwaway database (wazuh_ca_sign in the helper): RSA 2048, SHA-256, valid for ten years and backdated one day, so that a consumer whose clock lags does not refuse a certificate minted a minute ago. openssl ca is the one command on the supported OpenSSL versions that can set the start of the validity; -preserveDN keeps the subject in the order of the request, so the DNs written into opensearch.yml are the same as before.

Client pairs

The indexer trusts only its own CA, so a client that presents a certificate to it has to present one this CA issued, and only this package holds the key. At every resolution where ca/ holds the key, the resolver issues a pair for the manager (CN=wazuh-manager) and one for the dashboard (CN=wazuh-dashboard), OU=Wazuh, O=Wazuh, L=California, C=US, with extendedKeyUsage = clientAuth and no Subject Alternative Name, and publishes them in export/ as root’s private files; a pair already there that chains to the current CA and whose key matches is kept. The manager imports its pair as certs/indexer-connector.pem; the dashboard does not use its pair yet. A consumer on another host takes a copy of the pair from any indexer node of the cluster: the pair names no host, and the indexer maps its subject to nothing.

The pairs grant no rights by themselves, and three things keep it so, asserted by the acceptance suite: the security plugin’s certificate authentication domain stays disabled in the shipped config.yml, plugins.security.ssl.http.clientauth_mode stays at its default (OPTIONAL), and the subjects are in neither admin_dn nor nodes_dn, which --check verifies. With OPTIONAL, a client that presents a certificate from any other CA fails the TLS handshake, which is what makes trust separation testable. --clear removes the pairs with the rest of export/.

The package and wazuh-certs-tool.sh issue these certificates with the same subject, in the same order. That order is part of the contract, not a detail: the Security plugin compares the rendered DN, so a deployment that replaces the package certificates with the tool’s own keeps the DNs already written into opensearch.yml valid only while both agree.

Distinguished names

A node whose DN is not listed is rejected by the cluster, so plugins.security.nodes_dn and plugins.security.authcz.admin_dn are filled from the certificates in the same step that resolves them. --install replaces whatever those keys hold. Every other mode fills them only when they are empty, because by then the list may be the operator’s own — one entry per node of their cluster.

This is what makes the deferred case work. A deployment that brings its own public key infrastructure (PKI) installs the package with only the trust anchor in the CA directory, so the install cannot issue anything and records no completion; the pair is staged afterwards, and the next start finishes the job, DNs included.

The JDK truststore

The bundled JDK has to trust the Wazuh CA, so the resolver imports certs/root-ca.pem into jdk/lib/security/cacerts under the alias wazuh-root-ca whenever it resolves the certificates, and --clear deletes it again. It belongs to the resolver rather than to the maintainer scripts for both of those reasons: a pair staged after the install reaches the truststore too, and an image built by installing the package does not keep the build host’s CA in every copy.

File ownership

Root runs bin/resolve-credentials.sh — from the maintainer scripts and from the unit’s ExecStartPre — and that script sources lib/wazuh-indexer-credentials.sh. So the product tree is root-owned, group wazuh-indexer, mode 750/640: the service account reads and executes everything and writes nothing. A service account able to rewrite either file could have root run its own code.

Two directories under the product tree are exceptions, because the service writes them at runtime:

• engine/ — sockets, logs and data
• plugins/wazuh-indexer-content-manager/snapshots/ — the content manager deletes the shipped snapshot once it has consumed it

Adding a file the service must write means adding a third exception, in the DEB postinst and in the spec’s %files. Adding one it only reads needs nothing: the default covers it. The acceptance suite asserts both the root ownership and the two exceptions, so getting this wrong fails the build rather than shipping quietly.

The same reasoning applies outside the product tree. /etc/default/wazuh-indexer and /usr/lib/sysctl.d/wazuh-indexer.conf are read by systemd as root, so both stay root-owned.

The configuration directory, /etc/wazuh-indexer, is root’s as well: directories root:wazuh-indexer 0750, files 0640, so the service reads its configuration, its keystore and its trust material through its group and can rewrite none of them. The one file the node used to write there, opensearch.keystore, is created by postinst / %post when absent and upgraded when its format changed, as root, so the node never writes it. The admin certificate pair is root’s alone (0600): indexer-security-init.sh runs securityadmin.sh as root, and the service account must not be able to act as the security administrator. The ownership is set by a walk in postinst / %post that touches regular files and directories only, never through a symbolic link, with chown -h, and the spec’s %files attributes say the same, so rpm -V reports no ownership or mode change.

The data and log directories, /var/lib/wazuh-indexer and /var/log/wazuh-indexer, are the service’s: the node writes its indices and logs there. The resolver’s completion marker lives in the data directory, so a link planted in its place is never followed: the marker is written by renaming a fresh file over whatever the entry is, and a link is not read as a marker. The same rule covers the SysV script, which reads a pid from a file the service account owns and therefore confirms the process is the indexer’s before signalling it.

When the package is purged

A purge (DEB purge, RPM erase) always deletes the wazuh-indexer user and group. That frees their IDs: the next system account created would inherit them, and with them anything still on disk that they own — the keystore, the logs, the indexed data and any certificates left behind. So before userdel runs, the purge hands every file the account or its group owns in the package’s own directories over to root, and closes those directories:

• Files owned by wazuh-indexer become root:root; files that only its group owns get group root. Their modes do not change.
• Each of the four directories loses group and other access (go-rwx). That, not the files’ own modes, is what keeps what is inside unreadable to anyone but root, and it is all a reinstall has to undo. On DEB, postinst sets the four back to their packaged 750 on a fresh install, beside the ownership it sets anyway, and an upgrade leaves the operator’s modes alone. RPM needs no such step: rpm applies the packaged mode of every directory in its file list on each install and upgrade, and %post sets the ownership again.
• The walk never enters a symbolic link, and chown -h changes links themselves, so a link the service account planted cannot aim the purge at another file. One pass hands over both the files the account owns and those only its group owns. The DEB postrm uses find -H for it, which is Essential on Debian; the RPM %postun walks the tree in shell, because findutils is not a dependency of the package.

The package’s own directories are these four, and only these:

• /etc/wazuh-indexer — configuration
• /usr/share/wazuh-indexer — home
• /var/lib/wazuh-indexer — data
• /var/log/wazuh-indexer — logs

Nothing outside them is touched, including a custom path.data, path.logs or path.repo. Such a directory is not necessarily this node’s alone: a shared file system (fs) snapshot repository is mounted on every node of the cluster, and handing it over to root on the node being purged would stop the others from writing snapshots. Files there keep the removed account’s ID. Handling them is the operator’s job, and the purge prints a note saying so every time it runs.

If a handover fails, on a read-only mount or a network file system that squashes root, say, the purge names the directory and still deletes the user and group. A directory is reported as kept for root only when its handover succeeded and it still holds something other than directories. dpkg removes the package’s own empty directories only after postrm purge has run, so a directory that holds nothing but directories at that point is about to go, and reporting it as kept would be wrong.

The purge deletes only what the package itself created:

• tmp/, and each of the four directories once nothing else is left in it. On RPM, opensearch-security/ and the product directory go as well: rpm could not remove them while the .rpmsave file and the engine’s runtime files that %postun deletes were still in them.
• /tmp/hsperfdata_wazuh-indexer, when the account owns it. A Java Virtual Machine (JVM) keeps its performance data there, and a node the SysV script starts runs outside the unit’s private /tmp. The directory is empty once the JVM exits, but the next account given the freed ID would own it.
• export/, ca/ and the completion marker: what the package published for the other components, its CA, and the record that it resolved its credentials.
• opensearch.keystore, when it is still exactly as the package created it. postinst / %post record its digest in .wazuh-indexer-keystore at creation; a keystore the operator added secrets to has another digest and is kept, with the marker.
• The certificates it issued from that CA. Without it they are an identity nothing trusts, and a reinstall would find them beside a new one. Only a CA with its key in ca/ issued anything on this host, and each pair is checked against it with openssl verify first, so a pair it did not issue — the operator’s own — stays, and a reinstall with nothing to verify it against reports it rather than minting a CA beside it.

What the operator sees is described in Uninstall.

A directory the package itself creates outside those four must be added to the purge’s list, in the DEB postrm and in the spec’s %postun, or its files are left with an orphaned owner. build-scripts/ci/test_purge.sh asserts that no file with an orphaned owner is left in the four directories, that only a directory still holding files is reported as kept, that the engine’s runtime files and the JVM’s performance data do not outlive the purge, that a reinstall restores every owner and mode, that the node’s certificates chain to its CA afterwards, and that a custom path.repo is left exactly as it was.

Host dependencies

Both packages declare these (Depends: in debian/control, Requires: in the spec, where AutoReqProv is off so nothing is inferred). The list is exactly the set of host tools the maintainer scripts, the resolver and the scripts they start run: everything else they run is a shell builtin or coreutils, which rpm itself requires and which is Essential on Debian, plus getent (glibc), systemctl, and restorecon when the host has it.

coreutils is not listed: rpm requires it, and it is Essential on Debian. The DEB maintainer scripts may also use grep, sed and find, which are Essential on Debian; the RPM scriptlets and every shipped script may not, so the privilege drop in the SysV script uses chroot --userspec (coreutils) rather than runuser (util-linux), process checks read /proc rather than calling ps or pgrep (procps), the host name comes from /proc/sys/kernel/hostname rather than hostname, and the text handling of the resolver and the init scripts is done in shell rather than with awk, sed, grep or cut. build-scripts/ci/test_host_tools.sh scans the scripts of a built package for anything outside this closure and fails the build on a hit.

A minimal or container base image frequently carries neither openssl nor ip, and the failures are quiet and easy to misread: a missing openssl leaves the node with no certificates, and a missing ip leaves the certificate without the host’s addresses. Both are declared so that the package manager installs them.

Wazuh Indexer Setup plugin — development guide

This document describes how to extend the Wazuh Indexer setup plugin to create new index templates and index management policies (ISM) for OpenSearch. See Architecture for the conceptual overview.

Class diagram

---
title: Wazuh Indexer setup plugin
---
classDiagram
    %% Classes
    class IndexInitializer
    <<interface>> IndexInitializer
    class Index
    <<abstract>> Index
    class IndexStateManagement
    class WazuhIndex
    <<abstract>> WazuhIndex
    class StateIndex
    class StreamIndex
    class ContentIndex

    %% Relations
    IndexInitializer <|-- Index : implements
    Index <|-- IndexStateManagement
    Index <|-- WazuhIndex
    WazuhIndex <|-- StateIndex
    WazuhIndex <|-- StreamIndex
    WazuhIndex <|-- ContentIndex

    %% Schemas
    class IndexInitializer {
        +createIndex(String index) void
        +createTemplate(String template) void
    }
    class Index {
        Client client
        ClusterService clusterService
        IndexUtils utils
        String index
        String template
        +Index(String index, String template)
        +setClient(Client client) IndexInitializer
        +setClusterService(ClusterService clusterService) IndexInitializer
        +setIndexUtils(IndexUtils utils) IndexInitializer
        +indexExists(String indexName) bool
        +initialize() void
        +createIndex(String index) void
        +createTemplate(String template) void
    }
    class IndexStateManagement {
        -List~String~ policies
        +initialize() void
        -createPolicies() void
        -indexPolicy(String policy) void
    }
    class WazuhIndex {
    }
    class StreamIndex {
        -String alias
        +StreamIndex(String index, String template, String alias)
        +createIndex(String index)
    }
    class StateIndex {
    }
    class ContentIndex {
        +String SUFFIX_A
        +ContentIndex(String index, String template)
        +getPhysicalName() String
        +createIndex(String index)
        +createTemplate(String template)
        -deleteSquatterIndex(String alias) void
        -ensureAlias(String alias, String physicalName) void
    }

The SetupPlugin class holds the list of indices to create. The logic for the creation of the index templates and the indices is encapsulated in the Index abstract class. Each subclass can override this logic if necessary. The SetupPlugin::onNodeStarted() method invokes the Index::initialize() method, effectively creating every index in the list. The plugin implements the ClusterPlugin interface to hook into this method.

Sequence diagram

Note Calls to Client are asynchronous.

sequenceDiagram
    actor Node
    participant SetupPlugin
    participant Index
    participant Client
    Node->>SetupPlugin: plugin.onNodeStarted()
    activate SetupPlugin
    Note over Node,SetupPlugin: Invoked on Node::start()

    activate Index
    loop i..n indices
        SetupPlugin->>Index: i.initialize()


        Index-)Client: createTemplate(i)
        Client--)Index: response

        Index-)Client: indexExists(i)
        Client--)Index: response
        alt index i does not exist
            Index-)Client: createIndex(i)
            Client--)Index: response
        end
    end

    deactivate Index
    deactivate SetupPlugin

JavaDoc

The plugin is documented using JavaDoc. You can compile the documentation using the Gradle task for that purpose. The generated JavaDoc is in the build/docs folder.

./gradlew javadoc

Creating a new index

1. Add a new index template

Create a new JSON file in the directory: /plugins/setup/src/main/resources

Follow the existing structure and naming convention. Example:

{
  "index_patterns": ["<pattern>"],
  "mappings": {
    "date_detection": false,
    "dynamic": "strict",
    "properties": {
      <custom mappings and fields>
    }
  },
  "order": 1,
  "settings": {
    "index": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    }
  }
}

2. Register the index in the code

Edit the constructor of the SetupPlugin class located at: /plugins/setup/src/main/java/com/wazuh/setup/SetupPlugin.java

Add the template and index entry to the indices map. There are three kinds of indices:

• Stream index. Stream indices contain time-based events of any kind (alerts, statistics, logs…). These are created as Data Streams.
• Stateful index. Stateful indices represent the most recent information of a subject (active vulnerabilities, installed packages, open ports, …). These indices are different from Stream indices as they do not contain timestamps. The information is not based on time, as they always represent the most recent state.
• Content index. Content indices hold the CTI catalog content the Content Manager downloads. They are not addressed by their own name: see Threat intel content indices below.

/**
* Main class of the Indexer Setup plugin. This plugin is responsible for the creation of the index
* templates and indices required by Wazuh to work properly.
*/
public class SetupPlugin extends Plugin implements ClusterPlugin {

  // ...

  // Stream indices
  this.indices.add(new StreamIndex("my-stream-index", "templates/streams/my-index-template-1"));
  // State indices
  this.indices.add(new StateIndex("my-state-index", "templates/states/my-index-template-2"));
  // Content indices
  this.indices.add(new ContentIndex("my-content-index", "templates/content/my-index-template-3"));

  //...
}

Verifying template and index creation After building the plugin and deploying the Wazuh Indexer with it, you can verify the index templates and indices using the following commands:

curl -X GET <indexer-IP>:9200/_index_template/
curl -X GET <indexer-IP>:9200/_cat/indices?v

Alternatively, use the Developer Tools console from the Wazuh Dashboard, or your browser.

Creating a new ISM (Index State Management) policy

1. Add rollover alias and policy ID to the index template

Edit the existing index template JSON file and add the following settings:

"plugins.index_state_management.rollover_alias": "<index-name>",
"plugins.index_state_management.policy_id": "<index-name>-policy"

2. Define the ISM policy

Refer to the OpenSearch ISM Policies documentation for more details.

Here is an example ISM policy:

{
  "policy": {
    "policy_id": "<index-name>-policy",
    "description": "<policy-description>",
    "last_updated_time": <unix-timestamp-in-milliseconds>,
    "schema_version": 1,
    "default_state": "hot",
    "states": [
      {
        "name": "hot",
        "actions": [
          {
            "retry": {
              "count": 3,
              "backoff": "exponential",
              "delay": "1m"
            },
            "rollover": {
              "min_doc_count": 200000000,
              "min_primary_shard_size": "20gb"
            }
          }
        ],
        "transitions": [
          {
            "state_name": "delete",
            "conditions": {
              "min_index_age": "<retention-time>"
            }
          }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "retry": {
              "count": 3,
              "backoff": "exponential",
              "delay": "1m"
            },
            "delete": {}
          }
        ],
        "transitions": []
      }
    ],
    "ism_template": [
      {
        "index_patterns": [
          "wazuh-<pattern>-*"
        ],
        "priority": <priority-int>
      }
    ]
  }
}

3. Register the ISM policy in the plugin code

Edit the IndexStateManagement class located at: /plugins/setup/src/main/java/com/wazuh/setup/index/IndexStateManagement.java

Register the new policy constant and add it in the constructor:

// ISM policy name constant (filename without .json extension)
static final String MY_POLICY = "my-policy-filename";

...

/**
 * Constructor
 *
 * @param index    Index name
 * @param template Index template name
 */
public IndexStateManagement(String index, String template) {
    super(index, template);
    this.policies = new ArrayList<>();

    // Register the ISM policy to be created
    this.policies.add(MY_POLICY);
}

Additional notes

Always follow existing naming conventions to maintain consistency.

Use epoch timestamps (in milliseconds) for last_updated_time fields. Update the policy’s one whenever you change the policy, and keep it in the past: IndexStateManagement.indexPolicy() copies it into every ism_template entry before indexing the policy, and ISM applies a template only to indices created after that timestamp. A template without it is stamped with the current time on every read, so it matches no index at all.

ISM policies and templates must be properly deployed before the indices are created.

IndexStateManagement.initialize() runs on every cluster-manager election, and indexPolicy() writes each policy with a plain IndexRequest keyed by policy id, so the six shipped policies are overwritten on every restart. Any edit an operator makes to one of them through the ISM API is reverted on the next boot. This is why Retention tells operators to create a policy under their own id rather than editing a shipped one.

Event stream templates

Overview

Event and findings data streams are both category-based: 8 event categories share a single base template (templates/streams/events.json), and the 8 corresponding findings categories share their own base template (templates/streams/findings.json). At deployment time, StreamIndex.createTemplate() generates one index template per category from the applicable base, overriding exactly two fields:

• index_patterns — always set to <category-index-name>*.
• settings["plugins.index_state_management.rollover_alias"] — set to the category’s index name, but only if that key already exists in the base template’s settings.

Every other part of the generated template — most importantly mappings — is copied through unchanged. This means all category templates within a stream family (all 8 event categories, or all 8 findings categories) have identical mappings; only the index pattern and rollover alias differ.

• Source of truth: Only events.json and findings.json exist in the repository; no per-category template files exist.
• At runtime: One index template is created for each category (e.g., wazuh-events-v5-cloud-services-template, wazuh-events-v5-security-template, etc.), and likewise for each findings category.

The StreamIndex class handles this: when constructed with only an index name (no explicit template path), it defaults to templates/streams/events and rewrites index_patterns and (conditionally) rollover_alias to match the specific index. Findings categories are registered the same way but with the two-arg constructor pointing at templates/streams/findings.

How it works

// Single-arg constructor defaults to the shared events template
new StreamIndex("wazuh-events-v5-cloud-services");
// Equivalent to:
new StreamIndex("wazuh-events-v5-cloud-services", "templates/streams/events")

During createTemplate(), the plugin:

1. Reads events.json from the classpath
2. Overrides index_patterns to ["wazuh-events-v5-cloud-services*"]
3. If rollover_alias is present in the base template’s settings, overrides it to "wazuh-events-v5-cloud-services"
4. Creates the composable index template in OpenSearch, with mappings copied through unchanged

Verifying deployed templates

To list all event templates in a running cluster:

GET /_index_template/wazuh-events-*

Likewise, to list all findings templates:

GET /_index_template/wazuh-findings-*

Specialized stream templates

Some data streams use their own dedicated templates instead of the shared events.json:

These are registered with the two-arg constructor:

new StreamIndex("wazuh-events-raw-v5", "templates/streams/raw");
new StreamIndex("wazuh-active-responses", "templates/streams/active-responses");
new StreamIndex("wazuh-ai-assistant-sessions", "templates/streams/ai-assistant-sessions");

Events data stream ISM policy (stream-events-policy)

Overview

The stream-events-policy manages all wazuh-events-v5-* data streams. It combines rollover (based on shard size or document count) with deletion of rolled-over indices once they reach a minimum age. See Retention for the effective retention this yields.

Policy details

• Policy Name: stream-events-policy
• Location: plugins/setup/src/main/resources/policies/stream-events-policy.json
• Index Pattern: wazuh-events-v5-*
• Deletion age (floor): 1 hour
• Rollover Conditions: 20 GB primary shard size or 200,000,000 documents
• ISM template priority: 0

Policy states

1. Hot State

   • Actions: Rollover when primary shard reaches 20 GB or 200M documents
   • Transition Condition: Transitions to delete once the index reaches an age of 1 hour

2. Delete State

   • Actions: Deletes the index
   • Retry Policy: 3 attempts with exponential backoff (1-minute initial delay)

Findings data stream ISM policy (stream-findings-policy)

Overview

The stream-findings-policy manages all wazuh-findings-v5-* data streams. It combines rollover with deletion of rolled-over indices once they reach 90 days of age, to maintain detection findings for compliance and investigation purposes. See Retention.

Policy details

• Policy Name: stream-findings-policy
• Location: plugins/setup/src/main/resources/policies/stream-findings-policy.json
• Index Pattern: wazuh-findings-v5-*
• Deletion age (floor): 90 days
• Rollover Conditions: 20 GB primary shard size or 200,000,000 documents
• ISM template priority: 0

Policy states

1. Hot State

   • Actions: Rollover when primary shard reaches 20 GB or 200M documents
   • Transition Condition: Transitions to delete once the index reaches an age of 90 days

2. Delete State

   • Actions: Deletes the index
   • Retry Policy: 3 attempts with exponential backoff (1-minute initial delay)

Raw events data stream ISM policy (stream-raw-events-policy)

Overview

The stream-raw-events-policy manages the wazuh-events-raw-v5 data stream. Rolled-over indices are deleted once they reach 10 minutes of age. Note that the write index only rolls over on volume, so raw events are not bounded in time — see Retention.

Policy details

• Policy Name: stream-raw-events-policy
• Location: plugins/setup/src/main/resources/policies/stream-raw-events-policy.json
• Index Pattern: wazuh-events-raw-v5*
• Deletion age (floor): 10 minutes
• Rollover Conditions: 20 GB primary shard size or 200,000,000 documents
• ISM template priority: 0

Policy states

1. Hot State

   • Actions: Rollover when primary shard reaches 20 GB or 200M documents
   • Transition Condition: Transitions to delete once the index reaches an age of 10 minutes

2. Delete State

   • Actions: Deletes the index
   • Retry Policy: 3 attempts with exponential backoff (1-minute initial delay)

Active responses data stream (wazuh-active-responses)

Overview

The wazuh-active-responses data stream stores Active Response execution requests generated when monitor triggers match their conditions. This is part of the Active Response 5.0 integration with Wazuh XDR, using the Indexer Alerting and Notifications plugins as the foundation.

Purpose

• Active Response Pipeline: Structured and auditable execution pipeline for Active Response actions
• Manager Retrieval: The Wazuh manager retrieves documents from this index to distribute and execute Active Responses on agents
• Event Correlation: Each document references the source event (document ID and index) that triggered the response

Data stream configuration

Index template

• Location: plugins/setup/src/main/resources/templates/streams/active-responses.json
• Index Pattern: wazuh-active-responses*
• Rollover Alias: wazuh-active-responses
• Priority: 1

Fields included (WCS-compatible)

• @timestamp: When the document was inserted into the wazuh-active-responses index (indexing time)
• event.doc_id: Document ID of the matched alert that triggered the active response
• event.index: Source index of the matched alert
• wazuh.active_response.name: Name of the active response configured in the channel
• wazuh.active_response.executable: Executable configured in the active response channel
• wazuh.active_response.extra_arguments: Arguments configured in the channel
• wazuh.active_response.location: Where to execute (local, defined-agent, all)
• wazuh.active_response.agent_id: Agent configured in the channel
• wazuh.active_response.type: Response type (stateless, stateful)
• wazuh.active_response.stateful_timeout: Seconds configured in the channel (for stateful)
• wazuh.agent.*: Agent metadata
• wazuh.cluster.*: Cluster information
• wazuh.space.name: Wazuh space/tenant information

ISM policy

Policy details

• Policy Name: stream-active-responses-policy
• Location: plugins/setup/src/main/resources/policies/stream-active-responses-policy.json
• Deletion age (floor): 3 days
• Rollover Conditions: 20 GB primary shard size or 200,000,000 documents
• ISM template priority: 0

Configuration

The data stream is created automatically during plugin initialization. Ensure:

1. The template file active-responses.json exists in templates/streams/
2. The ISM policy file stream-active-responses-policy.json exists in policies/
3. Both are registered in SetupPlugin.java and IndexStateManagement.java

Testing

Integration tests for the active responses data stream are located at: plugins/setup/src/test/java/com/wazuh/setup/ActiveResponsesIT.java

Metrics data stream ISM policy (stream-metrics-policy)

Overview

The stream-metrics-policy manages all wazuh-metrics-* data streams (wazuh-metrics-agents, wazuh-metrics-comms-v4, wazuh-metrics-normalization). Rolled-over indices are deleted once they reach 30 days of age. See Retention.

Policy details

• Policy Name: stream-metrics-policy
• Location: plugins/setup/src/main/resources/policies/stream-metrics-policy.json
• Index Pattern: wazuh-metrics-*
• Deletion age (floor): 30 days
• Rollover Conditions: 20 GB primary shard size or 200,000,000 documents
• ISM template priority: 0

Policy states

1. Hot State

   • Actions: Rollover when primary shard reaches 20 GB or 200M documents
   • Transition Condition: Transitions to delete once the index reaches an age of 30 days

2. Delete State

   • Actions: Deletes the index
   • Retry Policy: 3 attempts with exponential backoff (1-minute initial delay)

Threat intel content indices

Overview

The wazuh-threatintel-* indices hold the CTI catalog content the Content Manager downloads: IoCs, CVEs and the Engine ruleset. The setup plugin provisions all of them.

Why the alias

A content index is never addressed by its own name. ContentIndex creates the concrete index as <name>-a and points a write alias named <name> at it. The Content Manager needs that indirection: when the content source changes (a plan upgrade or downgrade), it rebuilds the whole catalog into a hidden <name>-b shadow index and swaps the alias in a single atomic action, so readers never see a partially populated index. The two slots alternate on each swap.

ContentIndex.createTemplate() therefore rewrites the template’s index_patterns to <name>*, whatever the shipped JSON declares. That covers the live slot, the shadow slot and — as a last line of defence — the alias name itself.

Who creates them

This plugin does, and only this plugin. The Content Manager no longer provisions these indices: it waits for the .wazuh-setup-status readiness marker, and if setup has not marked itself ready it aborts its own initialization instead of creating anything. On a deployment without this plugin the threat-intel indices are therefore never created and the custom-ruleset endpoints do not work. Previously the Content Manager created them from its own copies, and without that wait it won the race by a wide margin — it created six of the eight about 16 seconds before this plugin reached its threat-intel block, so they were created before their index templates were installed and did not pick them up. That race is the bug this change removes.

Downloading CTI content requires two things to be true, and the Content Manager checks both before any write reaches these indices:

1. .wazuh-setup-status reports status: ready, which this plugin writes only after every index it owns exists.
2. The target indices of that consumer exist.

If either check fails the consumer skips its pass and logs at ERROR; it creates nothing. That is what keeps a mis-provisioned index from becoming a squatted one: a write through the alias name would otherwise auto-create a concrete index there with dynamic mappings. See issues #1476 and #1481, where the second of those took out vulnerability detection and package inventory because the global-map documents could not be indexed into an inferred mapping.

To confirm on a running cluster, read the templates field of the creation entries in the log:

grep 'creating index' /var/log/wazuh-indexer/wazuh-cluster.log | grep threatintel

Every wazuh-threatintel-*-a line must name its own <name>-template. An empty templates [] means something created the index before the template existed.

Recovering an index that squats the alias name

If a write reaches the alias name before anything creates the alias, OpenSearch auto-creates a concrete index called <name> with dynamic mappings. Every keyword the schema declares becomes a text field, which has no doc_values and so cannot be aggregated or sorted on, and the index occupies the name the alias needs. ContentIndex.createIndex() deletes such an index before creating <name>-a. The Content Manager then finds the index empty with a non-zero local offset and resets the offset, so the content is downloaded again on the same synchronization pass.

Where the mappings live

The mappings exist in two places on purpose. This plugin ships them as index templates under plugins/setup/src/main/resources/templates/content/, and the Content Manager keeps its own copies under plugins/content-manager/src/main/resources/mappings/cti-*-mappings.json, which it needs to create the <name>-b shadow indices during a blue/green content swap, without setup intervention. The verifyContentTemplates Gradle task, wired into check, fails the build if the two sets diverge.

All eight templates/content/*.json are generated by the WCS generator from the modules under wcs/content/, and the Content Manager copies are derived from them by sync_content_mappings.py; editing either set by hand is overwritten on the next generator run. templates/cve.json is not the CVE content template: it is a WCS artifact for the unrelated wazuh-cve* pattern and is intentionally not registered.

Testing

./gradlew :wazuh-indexer-setup:integTest --tests '*ThreatIntelIndicesIT*'

Against a deployed cluster, the alias must resolve to the -a index and its fields must be aggregatable:

curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD 'https://localhost:9200/_alias/wazuh-threatintel-*'
curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD \
  'https://localhost:9200/wazuh-threatintel-enrichments/_field_caps?fields=document.type'

The indices array in the _field_caps response names what the alias resolved to. It must read ["wazuh-threatintel-enrichments-a"] with "aggregatable": true.

AI assistant indices

Overview

The AI assistant stores its conversation history in the wazuh-ai-assistant-sessions data stream (a StreamIndex). Its providers configuration, assistant-wide settings and field policy live in the hidden .wazuh-internal-state index reached only through the setup plugin’s administrative AI assistant API, described below. Both indices use strict mappings.

Sessions data stream (wazuh-ai-assistant-sessions)

Index template

• Location: plugins/setup/src/main/resources/templates/streams/ai-assistant-sessions.json
• Index Pattern: wazuh-ai-assistant-sessions*
• Rollover Alias: wazuh-ai-assistant-sessions
• Priority: 1

Fields

• @timestamp: Indexing time of the document (data stream timestamp field, required)
• user: Username the conversation belongs to. Used as the Document Level Security discriminator
• title: Conversation title, usually the first user message
• created_at / updated_at: Conversation creation and last update times
• messages: The conversation turns (e.g. created_at, role, content, plus whatever else a given AI provider returns). Mapped as {"type": "object", "enabled": false}: stored in _source and returned as-is on _search/_get, but not parsed into the mapping at all — no sub-fields, no indexing, no strict-mapping enforcement inside it. This is deliberate: the shape of a message varies by provider, so there is no fixed schema to declare, and the assistant never queries into messages — it only reads whole documents back to reconstruct a conversation in the UI.

Access control

Access is granted by the wazuh_ai_assistant role, defined in the wazuh-indexer repository and mapped to every authenticated user. Reads are filtered with DLS parameter substitution ({"term": {"user": "${user.name}"}}), so a user only retrieves their own conversations. The restriction also applies to users holding a role that grants read on the * index pattern.

Reads and writes are scoped differently on purpose. DLS is a read-path filter and cannot scope a write: no role syntax can express “this document’s user must equal your name”. An index-level write grant on this data stream would therefore be unscoped, and every authenticated user holds this role.

So the role grants no index-level write. Sessions are still read directly against the data stream, under the per-owner DLS, but every write goes through the session API below, gated by the plugin:wazuh/ai_assistant/session/write cluster permission, which derives user from the authenticated principal. That is also what the read filter depends on: user is only meaningful to filter on because the server, not the client, decides it.

Session write API

There is deliberately no read endpoint and no session/read permission. Listing sessions and reading a transcript are plain DLS-scoped searches, and OpenSearch already provides search, sorting, pagination, track_total_hits and source filtering; putting an endpoint in front of that would be reimplementing the search API for nothing. The consequence to accept is that the index mapping stays part of the Dashboard’s contract.

TransportPutAiAssistantSessionAction resolves the caller from the _opendistro_security_user_info thread-context transient (com.wazuh.setup.utils.AuthenticatedUser) before stashing the context, stamps it onto user, and only then calls AiAssistantSessionsIndex with the plugin’s own privileges. Every lookup behind PUT/PATCH/DELETE filters on that same resolved owner, so a session belonging to somebody else simply is not found — reported as 404, never 403, since a 403 would confirm that another user’s session id exists. There is no impersonation and no administrative override, not even for all_access, which preserves the DLS behaviour that already applied to admin.

Three data-stream mechanics shape the implementation, all of them platform constraints rather than choices:

• A get-by-id is unusable. The backing index rolls over daily and the get API targets exactly one concrete index. findHit searches the stream instead, which fans out across every backing index and reports the one holding the document (hit.getIndex()), together with the seq_no/primary_term pair the following write needs — one round trip for all three facts.
• Update and delete must target the backing index, never the stream name, which accepts appends only. And they must be a full index replace: the partial _update API is refused outright wherever DLS applies to the role (security_exception: Update is not supported when FLS or DLS or Fieldmasking is activated).
• Optimistic concurrency is mandatory. A backing index rejects an unconditional write (illegal_argument_exception: index request with op_type=index and no if_primary_term and if_seq_no set targeting backing indices is disallowed), so every write carries a pair — the caller’s expected_version when it sent a decodable one, otherwise the pair the request just read. The version the API returns is that pair encoded as "<seq_no>:<primary_term>", opaque to clients. A genuine mismatch is a 409, never retried: retrying with a freshly read pair is exactly the silent overwrite expected_version exists to prevent.

Request bodies are capped at 5 MiB on every write route, checked against the raw payload before parsing so an oversized body never becomes a map in heap. MAX_MESSAGES (1000) bounds the number of turns but not their size, and the fallback ceiling would otherwise be http.max_content_length (100MB), which would leave the 500-session per-owner cap meaningless as a storage bound.

Two smaller rules worth knowing: PATCH deliberately does not re-stamp updated_at (a rename is not session activity, and bumping it would reorder a list sorted by last activity), and PUT’s title is optional (a chat client auto-saves every turn, and resending a recomputed title would silently revert a rename the user had just made). Every write uses RefreshPolicy.WAIT_UNTIL, because every read here is a search and a search only sees a write after the shard refreshes.

With the security plugin absent — the integTest cluster — there is no transient and the owner resolves to the _shared sentinel, treated as a real owner rather than as a bypass, so the tests exercise the whole stamp-and-scope path. See AiAssistantSessionsIT and TransportPutAiAssistantSessionActionTests.

Settings, field policy and providers (.wazuh-internal-state)

.wazuh-internal-state is created and owned by the Content Manager plugin (CredentialsIndex), not by setup — setup only reads and writes it through the administrative AI assistant API described below. Its mapping is generated by the wcs/internal-state WCS module and lands at plugins/content-manager/src/main/resources/mappings/internal-state-mapping.json; it is dynamic: strict.

The index holds several kinds of documents under one mapping, avoiding a separate index for what would otherwise be a handful of settings fields.

• One document per configured AI provider, id an arbitrary UUID: name, type, base_url, model, api_key, is_default, updated_at. listProviders() caps the result at AiAssistantSettingsAdminIndex.MAX_PROVIDERS = 500.
• A single reserved-id document (id "wazuh-ai-assistant-settings") holding the assistant-wide settings and the field anonymization policy, under field_policy. Its privacy_default_per_provider is keyed by provider document id, so it is mapped as flat_object: the keys are UUIDs minted at runtime and a plain object would reject every one of them under this index’s dynamic: strict mapping.
• A single reserved-id document ("credentials"), owned entirely by Content Manager. The administrative AI assistant API never reads or returns this document.

Example documents:

// Provider document
{ "name": "test-ai", "type": "anthropic", "base_url": "https://api.anthropic.com", "model": "claude-opus-4-6", "api_key": "enc:v1:SC/RyOIBkdm+kGl", "is_default": true, "updated_at": "2026-08-03T09:54:52.193Z" }

// Settings + field policy document (reserved id "wazuh-ai-assistant-settings")
{
  "privacy_default_on": false,
  "privacy_default_per_provider": { "3f6b5f7e-6f2d-4a4f-9c1e-2f6d0a1b2c3d": true },
  "user_can_override": true,
  "field_policy": [
    { "field": "wazuh.agent.name", "action": "anonymize", "kind": "HOST" },
    { "field": "wazuh.agent.host.ip", "action": "anonymize", "kind": "IP" },
    { "field": "wazuh.agent.id", "action": "allow" }
  ]
}

Administrative AI assistant API

.wazuh-internal-state is registered as an OpenSearch Security system index, so no role’s index permissions can reach its documents. Every query to this index goes through the administrative API below:

| Endpoint | Method | Cluster permission | Backed by |

GET /ai_assistant/settings returns the settings document’s source as-is, with its fields flat at the root. Providers are a separate resource, listed via GET /ai_assistant/providers, which excludes the two reserved document ids ("wazuh-ai-assistant-settings" and "credentials").

PUT /ai_assistant/settings always replaces the whole document: the caller sends the complete set of settings fields and the complete field_policy array on every write, not a partial diff

POST /ai_assistant/providers’s body must include an id field, since other integrations depend on the document ending up with the exact id they sent: it must be a UUID, rejected with 400 when missing or malformed

DELETE /ai_assistant/providers/{id} returns 404 when no provider exists with that id, including on a repeated delete.

PUT/DELETE /ai_assistant/providers/{id} both reject the reserved document ids (wazuh-ai-assistant-settings, credentials) with 400, checked in TransportPutAiAssistantSettingsAction before either operation reaches the index.

GET /ai_assistant/providers returns {"providers": [{..., "_id": "..."}]}, each entry the provider document’s source flattened with its _id, assembled by AiAssistantSettingsAdminIndex.listProviders().

ISM policy (ai-assistant-sessions-policy)

Policy details

• Policy Name: ai-assistant-sessions-policy
• Location: plugins/setup/src/main/resources/policies/ai-assistant-sessions-policy.json
• Index Patterns: .ds-wazuh-ai-assistant-sessions-*, wazuh-ai-assistant-sessions*
• Deletion age (floor): 7 days
• Rollover Conditions: index age of 1 day (daily rotation), or 20 GB primary shard size / 200,000,000 documents, whichever comes first
• ISM template priority: 0

Policy states

1. Hot State

   • Actions: Rollover when the index is 1 day old, or reaches 20 GB / 200M documents
   • Transition Condition: Transitions to delete once the index reaches an age of 7 days

2. Delete State

   • Actions: Deletes the index
   • Retry Policy: 3 attempts with exponential backoff (1-minute initial delay)

Testing

Integration tests for the AI assistant indices are located at: plugins/setup/src/test/java/com/wazuh/setup/AIAssistantIndicesIT.java

Integration tests for the administrative AI assistant API are located at: plugins/setup/src/test/java/com/wazuh/setup/AiAssistantSettingsAdminIT.java

Defining default users and roles for Wazuh Indexer

The Wazuh Indexer packages include a set of default users and roles specially crafted for Wazuh’s use cases. This guide provides instructions to extend or modify these users and roles so they end up being included in the Wazuh Indexer package by default.

Note that the access control and permissions management are handled by the OpenSearch’s security plugin. As a result, we provide configuration files for it. The data is applied during the cluster’s initialization, as a result of running the indexer-security-init.sh script.

Considerations and conventions

As these configuration files are included in the Wazuh Indexer package, they are hosted in the wazuh-indexer repository. Be aware of that when reading this guide.

Any security related resource (roles, action groups, users, …) created by us must be reserved (reserved: true). This ensures they cannot be modified by the users, in order to guarantee the correct operation of Wazuh Central Components. Also, they should be visible (hidden: false) unless explicitly defined otherwise.

1. Adding a new user

Add the new user to the internal_users.wazuh.yml file located at: wazuh-indexer/distribution/src/config/security/.

new-user:
  hash: "${WAZUH_INDEXER_NEWUSER_PASSWORD}"
  reserved: true
  hidden: false
  backend_roles: []
  description: "New user description"

Do not write a hash. hash carries a ${NAME} placeholder naming the environment variable that will hold the password; a password generated at installation replaces it with a bcrypt digest. A literal hash would ship the same password in every deployment, which is what the placeholder exists to prevent. Add the variable to the resolver’s list of owned accounts — see Credential and TLS resolution.

OpenSearch’s reference:

• internal_users.yml

2. Adding a new role

Add the new role to the roles.wazuh.yml file located at: wazuh-indexer/distribution/src/config/security/.

• Under index_permissions.index_patterns, list the index patterns the role will have effect on.
• Under index_permissions.allowed_actions, list the allowed action groups or individual permissions granted to this role.

The default action groups for cluster_permissions and index_permissions are listed in the Default action groups documentation

role-read:
   reserved: true
   hidden: false
   cluster_permissions: []
   index_permissions:
     - index_patterns:
         - "wazuh-*"
       dls: ""
       fls: []
       masked_fields: []
       allowed_actions:
         - "read"
   tenant_permissions: []
   static: true
role-write:
   reserved: true
   hidden: false
   cluster_permissions: []
   index_permissions:
     - index_patterns:
         - "wazuh-*"
       dls: ""
       fls: []
       masked_fields: []
       allowed_actions:
         - "index"
   tenant_permissions: []
   static: true

OpenSearch’s reference:

• roles.yml
• action_groups.yml
• Default action groups

3. Adding a new role mapping

Add the new role mapping to roles_mapping.wazuh.yml file located at: wazuh-indexer/distribution/src/config/security/. Note that the mapping name must match the role name.

• Under users, list the users the role will be mapped to.

role-read:
   reserved: true
   hidden: false
   backend_roles: [ ]
   hosts: [ ]
   users:
     - "new-user"
   and_backend_roles: [ ]
role-write:
   reserved: true
   hidden: false
   backend_roles: [ ]
   hosts: [ ]
   users:
     - "new-user"
   and_backend_roles: [ ]

OpenSearch’s reference:

• roles_mapping.yml

Testing the configuration

The validation of the new configuration needs to be tested on a running deployment of Wazuh Indexer containing the security plugin.

You can follow any of these paths:

A. Generating a new Wazuh Indexer package

1. Apply your changes to the configuration files in wazuh-indexer/distribution/src/config/security/.
2. Generate a new package (see Build Packages).
3. Follow the official installation and configuration steps.
4. Check the new changes are applied (you can use the UI or the API).

B. Applying the new configuration to an existing Wazuh Indexer deployment (using the UI or API)

1. Use the Wazuh Indexer API or the Wazuh Dashboard to create a new security resource. Follow the steps in Defining users and roles.

C. Applying the new configuration to an existing Wazuh Indexer deployment (using configuration files)

1. Add the new configuration to the affected file within /etc/wazuh-indexer/opensearch-security/.
2. Run the /usr/share/wazuh-indexer/bin/indexer-security-init.sh script to load the new configuration.

Wazuh Indexer Reporting plugin — development guide

This document describes the Reporting plugin’s structure and REST surface. For setting up a local test environment (Vagrant + Mailpit) to exercise the plugin end to end, see Reporting test environment.

Overview

The wazuh-indexer-reporting plugin is a Wazuh fork of the OpenSearch reports-scheduler plugin. It manages report definitions (what to generate and on what schedule) and report instances (individual generation runs), and integrates with the Job Scheduler plugin for scheduled reports and the Notifications plugin for email delivery.

Plugin structure

The plugin registers as an OpenSearch Plugin, ActionPlugin, SystemIndexPlugin, and JobSchedulerExtension. Report definitions and instances are persisted in two system indices:

REST handlers

All routes are registered under a base URI (with a legacy alias for backwards compatibility) and grouped by concern:

Scheduling

ReportDefinitionJobRunner and ReportDefinitionJobParser integrate with the OpenSearch Job Scheduler plugin to run report definitions on their configured schedule, alongside the on-demand generation path exposed via the REST API.

Security

UserAccessManager and SecurityAccess enforce RBAC on report definitions and instances, consistent with the rest of the Wazuh Indexer’s Security plugin integration.

Notification delivery

Report delivery (e.g., emailing a generated report) goes through the Notifications plugin rather than implementing its own delivery transport.

Reporting test environment

This document describes how to build a local test environment to exercise the Reporting plugin, including email delivery through a local SMTP server.

Working from a minimal environment

To deploy a minimal environment for developing the reporting plugin for testing purposes, you must have at least a Wazuh Indexer and a Wazuh Dashboard environment running. Then, you can create your own SMTP server to test the email notifications from the following Mailpit configuration. To verify everything is working correctly, try generating reports following the user’s guide.

Working from real scenario packages

Preparing packages

• Wazuh Indexer package (debian package based on OpenSearch 3.1.0). Compiled locally using the Docker builder: bash builder.sh -d deb -a x64.
• Wazuh Dashboard package (debian package based on OpenSearch 3.1.0). Downloaded from wazuh-dashboard actions.

Note: Artifacts are no longer uploaded to the public wazuh-dashboard actions workflow. You must now use an specific workflow to obtain the S3 links and download the artifacts directly from the S3 bucket.

Note: To test using RPM packages, update the Vagrant configuration and provisioning scripts accordingly (for example, change generic/ubuntu2204 to generic/centos7 in the Vagrantfile and replace Debian-specific installation commands with RPM equivalents).

Preparing a development environment

Prepare a multi-VM Vagrant environment with the following components:

• Server
  • Wazuh Indexer (including the reporting plugin).
  • Wazuh Dashboard (including the reporting plugin).
• Mailpit
  • Mailpit SMTP server.

File location should be:

working-dir/
├── Vagrantfile
├── data/
│   ├── wazuh-indexer_*.deb
│   ├── wazuh-dashboard_*.deb
│   ├── gencerts.sh
│   ├── mailpit.sh
│   └── server.sh

Vagrantfile

class VagrantPlugins::ProviderVirtualBox::Action::Network
  def dhcp_server_matches_config?(dhcp_server, config)
    true
  end
end

Vagrant.configure("2") do |config|

    config.vm.define "server" do |server|
      server.vm.box = "generic/ubuntu2204"
      server.vm.provider "virtualbox" do |vb|
        vb.memory = "8192"
      end
      # For Hyper-V provider
      #server.vm.provider "hyperv" do |hv|
      #  hv.memory = 8192
      #end
      server.vm.network "private_network", type: "dhcp"
      server.vm.hostname = "rhel-server"
      config.vm.provision "file", source: "data", destination: "/tmp/vagrant_data"

      server.vm.provision "shell", privileged: true, path: "data/server.sh"
    end

    config.vm.define "mailpit" do |mailpit|
      mailpit.vm.box = "generic/ubuntu2204"
      mailpit.vm.provider "virtualbox" do |vb|
        vb.memory = "1024"
      end
      # For Hyper-V provider
      #client.vm.provider "hyperv" do |hv|
      #  hv.memory = 8192
      #end
      mailpit.vm.network "private_network", type: "dhcp"
      mailpit.vm.hostname = "mailpit"

      config.vm.provision "file", source: "data", destination: "/tmp/vagrant_data"

      mailpit.vm.provision "shell", privileged: true, path: "data/mailpit.sh"
    end

end

server.sh

#!/bin/bash

# Install
dpkg -i /tmp/vagrant_data/wazuh-indexer*.deb
dpkg -i /tmp/vagrant_data/wazuh-dashboard*.deb

# Setup

## Create certs
mkdir certs
cd certs || exit 1
bash /tmp/vagrant_data/gencerts.sh .

mkdir -p /etc/wazuh-indexer/certs
cp admin.pem  /etc/wazuh-indexer/certs/admin.pem
cp admin.key /etc/wazuh-indexer/certs/admin-key.pem
cp indexer.pem  /etc/wazuh-indexer/certs/indexer.pem
cp indexer-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
cp ca.pem /etc/wazuh-indexer/certs/root-ca.pem
chown -R wazuh-indexer.wazuh-indexer /etc/wazuh-indexer/certs/

mkdir -p /etc/wazuh-dashboard/certs
cp dashboard.pem  /etc/wazuh-dashboard/certs/dashboard.pem
cp dashboard-key.pem /etc/wazuh-dashboard/certs/dashboard-key.pem
cp ca.pem /etc/wazuh-dashboard/certs/root-ca.pem
chown -R wazuh-dashboard.wazuh-dashboard /etc/wazuh-dashboard/certs/

systemctl daemon-reload

## set up Indexer
systemctl enable wazuh-indexer
systemctl start wazuh-indexer
/usr/share/wazuh-indexer/bin/indexer-security-init.sh

## set up Dashboard
systemctl enable wazuh-dashboard
systemctl start wazuh-dashboard

## enable IPv6
modprobe ipv6
sysctl -w net.ipv6.conf.all.disable_ipv6=0

## turn off firewalld
sudo ufw disable

mailpit.sh

#!/bin/bash

# Install
curl -sOL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh && INSTALL_PATH=/usr/bin sudo bash ./install.sh

# Setup
## set up Mailpit
useradd -r -s /bin/false mailpit
groupadd -r mailpit
### Create directories
mkdir -p /var/lib/mailpit
chown -R mailpit.mailpit /var/lib/mailpit

### Create password file
mkdir -p /etc/mailpit
echo "admin:$(openssl passwd -apr1 admin)" > /etc/mailpit/passwords
chown -R mailpit.mailpit /var/lib/mailpit

## Create certs
mkdir certs
cd certs || exit 1
bash /tmp/vagrant_data/gencerts.sh .

mkdir -p /etc/mailpit/certs
cp admin.pem  /etc/mailpit/certs/admin.pem
cp admin.key /etc/mailpit/certs/admin-key.pem
cp mailpit.pem  /etc/mailpit/certs/mailpit.pem
cp mailpit-key.pem /etc/mailpit/certs/mailpit-key.pem
cp ca.pem /etc/mailpit/certs/root-ca.pem
chown -R mailpit.mailpit /etc/mailpit/certs/

## enable IPv6
modprobe ipv6
sysctl -w net.ipv6.conf.all.disable_ipv6=0

## turn off firewalld
sudo ufw disable

echo "======================================================"
echo "Start Mailpit with the following command:"
echo ""
echo "mailpit --listen 0.0.0.0:8025 --smtp 0.0.0.0:1025 --database /var/lib/mailpit.db --ui-auth-file /etc/mailpit/passwords --ui-tls-cert /etc/mailpit/certs/admin.pem --ui-tls-key /etc/mailpit/certs/admin-key.pem --smtp-tls-cert /etc/mailpit/certs/mailpit.pem --smtp-tls-key /etc/mailpit/certs/mailpit-key.pem"
echo "======================================================"

# Adding HTTPS: https://mailpit.axllent.org/docs/configuration/http/
# mailpit --ui-tls-cert /path/to/cert.pem --ui-tls-key /path/to/key.pem

# Adding basic authentication: https://mailpit.axllent.org/docs/configuration/passwords/
# mailpit --ui-auth-file /path/to/password-file

gencerts.sh

#!/bin/bash

if [[ $# -ne 1 ]]; then
fs=$(mktemp -d)
else
fs=$1
shift
fi

echo Working directory $fs
cd $fs

if [[ ! -e $fs/cfssl ]]; then
curl -s -L -o $fs/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
curl -s -L -o $fs/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64
chmod 755 $fs/cfssl*
fi

cfssl=$fs/cfssl
cfssljson=$fs/cfssljson

if [[ ! -e $fs/ca.pem ]]; then

cat << EOF | $cfssl gencert -initca - | $cfssljson -bare ca -
{
  "CN": "Wazuh",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [
  {
    "C": "US",
    "L": "San Francisco",
    "O": "Wazuh",
    "OU": "Wazuh Root CA"
  }
 ]
}
EOF

fi

if [[ ! -e $fs/ca-config.json ]]; then
$cfssl print-defaults config > ca-config.json
fi

gencert_rsa() {
        name=$1
        profile=$2
cat << EOF | $cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=$profile -hostname="$name,127.0.0.1,localhost" - | $cfssljson -bare $name -
{
  "CN": "$i",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [
  {
    "C": "US",
    "L": "California",
    "O": "Wazuh",
    "OU": "Wazuh"
  }
  ],
  "hosts": [
    "$i",
    "localhost"
  ]
}
EOF
openssl pkcs8 -topk8 -inform pem -in $name-key.pem -outform pem -nocrypt -out $name.key
}

gencert_ec() {
    openssl ecparam -name secp256k1 -genkey -noout -out jwt-private.pem
    openssl ec -in jwt-private.pem -pubout -out jwt-public.pem
}

hosts=(indexer dashboard mailpit)
for i in "${hosts[@]}"; do
        gencert_rsa $i www
done

users=(admin)
for i in "${users[@]}"; do
        gencert_rsa $i client
done

gencert_ec

1. Bring up the environment with vagrant up. Use the command provided in the console to start mailpit from within its VM. mailpit is configured to use TLS and access credentials (admin:admin). Use ip addr to check for the public IP address given to the VM and use that IP to access mailpit UI (e.g: https://172.28.128.136:8025/).
2. Add the username and password for mailpit to the Wazuh Indexer keystore.

   echo "admin" | /usr/share/wazuh-indexer/bin/opensearch-keystore add opensearch.notifications.core.email.mailpit.username
   echo "admin" | /usr/share/wazuh-indexer/bin/opensearch-keystore add opensearch.notifications.core.email.mailpit.password
   chown root:wazuh-indexer /etc/wazuh-indexer/opensearch.keystore
   chmod 640 /etc/wazuh-indexer/opensearch.keystore
   

3. Ensure mailpit is accessible within the server VM (e.g curl https://172.28.128.136:8025 -k -u admin:admin should return HTML code). If not, add it to the list of known hosts in /etc/hosts (e.g echo "172.28.128.136 mailpit mailpit" >> /etc/hosts).

Wazuh Indexer Content Manager plugin — development guide

This document describes the architecture, components, and extension points of the Content Manager plugin, which manages threat intelligence content synchronization from the Wazuh CTI API and provides REST endpoints for user-generated content management.

Overview

The Content Manager plugin handles:

• Wazuh Cloud credentials: stores the CTI access token in .wazuh-internal-state and caches it in PluginSettings.accessToken for REST handler use.
• Pre-registration with Wazuh Cloud: supports pre-registration of the Wazuh instance with Wazuh Cloud, via environment variable.
• Job scheduling: periodically checks for updates using the OpenSearch Job Scheduler.
• Update check service: sends a daily heartbeat to CTI so Wazuh can notify users when a newer version is available.
• Content synchronization: keeps local indices in sync with the Wazuh CTI Catalog via snapshots and incremental JSON Patch updates.
• Security Analytics integration: pushes rules, integrations, and detectors to the Security Analytics plugin.
• User-generated content: full CUD (create, update, delete) for rules, decoders, integrations, KVDBs, and policies in the draft space.
• Engine communication: validates and promotes content via Unix Domain Socket (UDS) to the Wazuh Engine.
• Space management: manages content lifecycle through draft → test → custom promotion.

Tuning the development environment

The build.gradlefile defines the development environment for the plugin. There, you can configure and modify the plugin’s behavior by setting custom values for any of the settings exposed by the plugin, or by setting up environment variables, as follows:

testClusters.integTest {
  // JVM tweaks.
  jvmArgs '-Xms2g', '-Xmx2g'

  // Environment variables.
  systemProperty "wazuh.version", "${wazuh_version}-beta3"

  // Plugin settings.
  setting 'plugins.content_manager.catalog.update_on_start', 'true'
}

Pre-registration with Wazuh Cloud

The Content Manager supports pre-registration of the Wazuh instance with Wazuh Cloud using the DEPLOY_KEY environment variable. If this variable is set at startup, the Content Manager automatically registers the token as if it were sent through the REST API, enabling immediate synchronization with the CTI API without manual intervention. Snapshots bundled with the package are removed in favor of fetching the latest content directly from the CTI API using the provided token. This streamlines the setup process for new deployments and ensures that they start with the most up-to-date detection content from their subscription plan.

State diagram

---
title: XDR pre-deploy on Cloud
---
stateDiagram-v2
    state if_state <<choice>>
    env_var_exists: Does env var exist?
    no_state: Unregistered mode
    yes_state: Registered mode
    initialization: Initialization


    [*] --> env_var_exists
    env_var_exists --> if_state
    if_state --> no_state: No
    if_state --> yes_state : yes

    no_state --> initialization : Init from the public catalog, packaged snapshot as fallback
    yes_state --> initialization : Init from active plan
    initialization --> [*]

Sequence diagram

---
title: XDR pre-deploy on Cloud
---
sequenceDiagram
    onNodeStarted->>onNodeStarted: deployKeyExists()
    alt DEPLOY_KEY env var exists
        onNodeStarted->>SubscriptionService: register(deployKey)
        onNodeStarted->>SnapshotService: deleteSnapshots(snapshotsDir)
    end
    onNodeStarted->>CatalogSyncJob: trigger()

System indices

The plugin manages the following indices. The 8 content indices marked “alias-backed” use the alias-backed blue/green storage scheme (see Index alias convention below); .wazuh-cti-consumers, .wazuh-internal-state, and .wazuh-content-manager-jobs are single physical indices, not blue/green’d.

This is the authoritative index list for the plugin; the Reference Manual’s System Indices table links here rather than repeating it.

Index alias convention

Each content index uses an alias-backed blue/green storage scheme to enable zero-downtime content replacement during subscription plan changes.

Naming

• Alias (public name): the stable name used by all readers, REST handlers, and dashboards. Example: wazuh-threatintel-rules.
• Physical index: the actual index storing data, suffixed with -a or -b. Example: wazuh-threatintel-rules-a.

Only one physical index is live at a time. The alias points to it with is_write_index: true. The other suffix is reserved as the shadow (staging) slot for the next plan-change swap.

Key classes

Shadow swap flow (plan change)

CatalogSyncJob looks the plan up once per pass (SyncPass.resolve()) and runs ShadowSwapService.swapChangedSources() before any consumer synchronizes. Every consumer whose plan-provided resource URL differs from the persisted one, and every consumer left mid-swap by an interrupted pass, moves in one swap:

1. Pre-flight, all or nothing: each moving consumer needs its target indices and a remote consumer whose snapshot link is available. If any fails, nothing is created or written and the consumers stay on their content (PENDING). The same happens when whether a consumer changes cannot be determined, for example because its document cannot be read: that consumer is HELD and the others wait for it, since it may be changing as well.
2. Create hidden shadow physical indices for every moving consumer (the -a/-b suffix not currently live; stale ones are deleted first)
3. Rewrite the documents of all moving consumers in one bulk request: new identity, running, local_offset 0, remote_offset = new head
4. Download each snapshot into its shadow indices, one consumer after another (SnapshotServiceImpl.forStaging(), which leaves the consumer documents alone)
5. Reindex user content (space.name != “standard”) from live → shadow (only for consumer types with hasUserContent()=true, i.e., ruleset)
6. onBeforeAliasSwap() hooks (the ruleset collects its pre-swap Security Analytics resources)
7. Refresh all shadow indices, so the last bulks of the loads are searchable the moment they go live (a shard that fails to refresh fails the swap, which is then undone like any failure before the switch)
8. Unhide non-CVE shadow indices, then one atomic alias swap: a single IndicesAliasesRequest for the aliases of every moving consumer (all 8 for a full plan change)
9. Record the snapshot offsets in the documents of all moving consumers, in one bulk request
10. Delete the old physical indices

Each consumer’s synchronize(SyncPass) then catches up from its snapshot offset to the remote head and runs the post-sync cascade (onSyncComplete(true): Security Analytics sync, stale resource cleanup, engine reload, IoC notification) before reporting ready.

The order of the writes keeps an interrupted swap recognizable: the shadow indices exist before the documents change (step 2 before 3), local_offset leaves 0 only after the switch (step 8), and a rollback restores the documents before deleting the shadow indices. A document that is running with local_offset 0 while a shadow index of its consumer exists is a swap that did not finish, and the next pass redoes it. A shadow index next to a consumer whose document has content live is a leftover and is deleted.

Failure modes

Concurrency: The CatalogSyncJob semaphore and cluster lock span the whole pass, which includes the swap. No additional locking is needed, but it also means the swap holds them for its full duration — the incremental syncs of the consumers that do not change source run after it.

Disk: the shadow indices of every moving consumer coexist with the live ones until step 9, so a full plan change temporarily duplicates all the downloaded content.

Normal incremental syncs

Regular incremental updates (no plan change) write through the alias to the live physical index. They are completely unaware of the -a/-b scheme.

Plugin architecture

Entry point

ContentManagerPlugin is the main class. It implements Plugin, ClusterPlugin, JobSchedulerExtension, and SystemIndexPlugin (which extends ActionPlugin). On startup, it:

1. Initializes PluginSettings, ConsumersIndex, CredentialsIndex, CtiConsole, CatalogSyncJob, EngineServiceImpl, and SpaceService.
2. Registers all REST handlers via getRestHandlers().
3. Creates the .wazuh-cti-consumers and .wazuh-internal-state indices on cluster manager nodes.
4. Schedules the periodic CatalogSyncJob via the OpenSearch Job Scheduler.
5. Optionally triggers an immediate sync on start.
6. Registers/schedules TelemetryPingJob (wazuh-telemetry-ping-job) when plugins.content_manager.telemetry.enabled is true.
7. Registers a dynamic settings consumer to enable/disable telemetry at runtime.
8. Registers dynamic settings consumers for each resource creation limit (max_integrations, max_decoders, max_rules, max_kvdbs, max_filters) so limits can be updated at runtime via the Cluster Settings API.

Update check service internals

The update check flow is split into two classes:

• TelemetryPingJob (jobscheduler/jobs/TelemetryPingJob.java)

  • Runs through Job Scheduler every 1 day.
  • Reads cluster UUID from ClusterService metadata.
  • Reads Wazuh version through ContentManagerPlugin.getVersion().
  • Prevents overlap using a Semaphore (tryAcquire() guard).
  • Exposes a trigger() method for immediate invocation, used by ContentManagerPlugin to fire the first ping as soon as the job document is indexed.

• TelemetryClient (cti/console/client/TelemetryClient.java)

  • Sends an asynchronous GET request to CTI /ping.
  • Headers sent:
    • wazuh-uid: cluster UUID
    • wazuh-tag: v<version>
    • Accept-Encoding: gzip
  • Fire-and-forget behavior: callback logs success/failure without blocking scheduler threads.

Version check internals

GET /version/check is served by TransportVersionCheckAction, which delegates to VersionCheckService (cti/catalog/service/VersionCheckService.java):

• Dedicated thread pool. The blocking CTI request runs on the content_manager_version_check pool (fixed, size 1, queue 1, registered in ContentManagerPlugin.getExecutorBuilders(...)), never on the transport thread.
• Shared in-flight request. At most one CTI request is in flight per node. Checks that arrive while it runs wait for it and receive its answer.
• Token-bucket rate limit. BUCKET_CAPACITY (5) checks in a burst, refilled at one per TOKEN_REFILL_MILLIS (12 s). Every CTI request spends a token whatever its outcome; checks that join an in-flight request spend none. An empty bucket answers 429 with a Retry-After header. Nothing is cached.
• Single attempt. ApiClient.getReleaseUpdates() makes no 429 retries, so a CTI 429 is returned to the caller instead of being slept off. The catalog sync keeps its client.max_retries behaviour.
• Shared CTI client. One long-lived ApiClient, created on first use and closed when the plugin closes. Timed-out requests are cancelled so their pooled connections are released.

CTI HTTP client User-Agent and Accept-Encoding

All HTTP clients that communicate with CTI services include a custom User-Agent header set as a default header on the HTTP client builder:

User-Agent: Wazuh Indexer <version>

The version is read from VERSION.json at plugin startup and stored in PluginSettings. The user-agent string is built by PluginSettings.getUserAgent() using the Constants.USER_AGENT_PREFIX constant. If the version is unavailable, the fallback value unknown is used.

They also send Accept-Encoding: gzip (via Constants.ACCEPT_ENCODING_GZIP) so CTI responses are transferred compressed. Unlike User-Agent, this header is added per request (via each request builder) rather than as a client default header: HttpClient5’s ChainElement.COMPRESS step runs before ChainElement.PROTOCOL, where default headers (RequestDefaultHeaders) are applied. If no Accept-Encoding header is present yet when COMPRESS runs, it adds its own — HttpClient5’s built-in default (gzip, x-gzip, deflate), not ours — and RequestDefaultHeaders then skips a header whose name is already present. So a default header would never actually be inserted; it isn’t overwritten, it’s preempted. Setting it directly on each request is what makes it reach the wire as gzip.

Affected clients:

• Console ApiClient (cti/console/client/ApiClient.java) — async HTTP client for CTI Console authentication and plans.
• Catalog ApiClient (cti/catalog/client/ApiClient.java) — async HTTP client for CTI Catalog consumer and changes.
• SnapshotClient (cti/catalog/client/SnapshotClient.java) — sync HTTP client for downloading CTI snapshots.
• TelemetryClient (cti/console/client/TelemetryClient.java) — inherits from Console ApiClient.

Runtime toggle behavior:

• plugins.content_manager.telemetry.enabled is a dynamic setting.
• Enabling it schedules the job; the immediate first ping is fired from within scheduleTelemetryPingJob() only after the job document has been successfully indexed, guaranteeing the ping only runs when the scheduled job is correctly registered.
• Disabling it removes the telemetry job document from .wazuh-content-manager-jobs.

REST handlers

The plugin registers 27 REST handlers, grouped by domain:

Class hierarchy

The REST handlers follow a Template Method pattern through a three-level abstract class hierarchy. There are two parallel branches — one where the target space is always draft (AbstractCreateAction / AbstractUpdateAction / AbstractDeleteAction) and one where the target space is supplied at runtime from the request body (AbstractCreateActionSpaces / AbstractUpdateActionSpaces / AbstractDeleteActionSpaces). The latter is used for resources like Filters that can live in either draft or standard space.

BaseRestHandler
├── AbstractContentAction
│   ├── AbstractCreateAction               # Target space always: draft
│   │   ├── RestPostRuleAction
│   │   ├── RestPostDecoderAction
│   │   ├── RestPostIntegrationAction
│   │   └── RestPostKvdbAction
│   ├── AbstractUpdateAction               # Target space always: draft
│   │   ├── RestPutRuleAction
│   │   ├── RestPutDecoderAction
│   │   ├── RestPutIntegrationAction
│   │   └── RestPutKvdbAction
│   ├── AbstractDeleteAction               # Target space always: draft
│   │   ├── RestDeleteRuleAction
│   │   ├── RestDeleteDecoderAction
│   │   ├── RestDeleteIntegrationAction
│   │   └── RestDeleteKvdbAction
│   ├── AbstractCreateActionSpaces         # Target space from request body (draft|standard)
│   │   └── RestPostFilterAction
│   ├── AbstractUpdateActionSpaces         # Target space from request body (draft|standard)
│   │   └── RestPutFilterAction
│   └── AbstractDeleteActionSpaces         # Target space from request body (draft|standard)
│       └── RestDeleteFilterAction
├── RestPutPolicyAction
├── RestDeleteSpaceAction
├── RestPostSubscriptionAction
├── RestPostUpdateAction
├── RestPostLogtestAction
├── RestPostPromoteAction
└── RestGetPromoteAction

AbstractContentAction

Base class for all content CUD actions. It:

• Overrides prepareRequest() from BaseRestHandler.
• Initializes shared services: SpaceService, SecurityAnalyticsService, IntegrationService.
• Validates that a Draft policy exists before executing any content action.
• Delegates to the abstract executeRequest() method for concrete logic.

AbstractCreateAction / AbstractCreateActionSpaces

Handles POST requests to create new resources. AbstractCreateAction hard-codes the target space to draft. AbstractCreateActionSpaces reads the space from the request body instead, allowing draft or standard as the target.

The executeRequest() workflow:

1. Validate request body — ensures the request has content and valid JSON.
2. Validate payload structure — checks for required resource key and optional integration key.
3. Resource-specific validation — delegates to validatePayload() (abstract). Concrete handlers check required fields, duplicate titles, parent integration existence, and the configured creation limit. The limit check counts existing Draft documents in the target index and returns HTTP 400 if the count is at or above plugins.content_manager.max_<type>; if the index does not exist yet, the check is skipped.
4. Generate ID and metadata — creates a UUID; sets date and modified timestamps to the current time unless the caller already supplied a non-blank value for either (Resource.setCreationTime() / setLastModificationTime()); defaults enabled to true.
5. External sync — delegates to syncExternalServices() (abstract). Typically upserts the resource in Security Analytics or validates via the Engine.
6. Index — wraps the resource in the CTI document structure and indexes it in the Draft space.
7. Link to parent — delegates to linkToParent() (abstract). Usually adds the new resource ID to a parent integration’s resource list.
8. Update hash — recalculates the Draft space policy hash via SpaceService.

Returns 201 Created with the new resource UUID on success.

AbstractUpdateAction / AbstractUpdateActionSpaces

Handles PUT requests to update existing resources. AbstractUpdateAction restricts updates to the draft space. AbstractUpdateActionSpaces accepts a space value (draft or standard) from the request body.

The executeRequest() workflow:

1. Validate ID — checks the path parameter is present and correctly formatted.
2. Check existence and space — verifies the resource exists and belongs to the Draft space.
3. Parse and validate payload — same structural checks as create.
4. Resource-specific validation — delegates to validatePayload() (abstract).
5. Update timestamps — sets modified to the current time unless the caller already supplied a non-blank value. preserveMetadata() then unconditionally overwrites date with the existing document’s stored creation date, ignoring any caller-supplied value — date is fully immutable once a resource is created.
6. External sync — delegates to syncExternalServices() (abstract).
7. Re-index — overwrites the document in the index.
8. Update hash — recalculates the Draft space hash.

Returns 200 OK with the resource UUID on success.

AbstractDeleteAction / AbstractDeleteActionSpaces

Handles DELETE requests. AbstractDeleteAction restricts deletions to the draft space. AbstractDeleteActionSpaces resolves the target space from the stored document (allowing deletion from both draft and standard).

The executeRequest() workflow:

1. Validate ID — checks format and presence.
2. Check existence and space — resource must exist in Draft space.
3. Pre-delete validation — delegates to validateDelete() (optional override). Can prevent deletion if dependent resources exist.
4. External sync — delegates to deleteExternalServices() (abstract). Removes from Security Analytics. Handles 404 gracefully.
5. Unlink from parent — delegates to unlinkFromParent() (abstract). Removes the resource ID from the parent integration’s list.
6. Delete from index — removes the document.
7. Update hash — recalculates the Draft space hash.

Returns 200 OK with the resource UUID on success.

Integration mode field

Integration documents carry a document.mode field with one of two values:

• protected — the integration is Wazuh core content and cannot be modified or deleted through the REST API.
• user-managed — the integration can be modified by the user.

The value is set by whoever produces the content: CTI content carries its own mode (core integrations are protected, the rest user-managed), and integrations created through the REST API are always user-managed.

When a standard integration’s enabled is toggled, its related Security Analytics detector is disabled/enabled in lockstep as part of the same update flow. The detector shares the integration’s document id, so the Content Manager calls the Security Analytics WSetDetectorEnabledAction (setDetectorEnabled(id, enabled)) to flip only the enabled flag on the existing detector, preserving its inputs, triggers and monitors. If the detector sync fails the whole update is aborted, so the two never drift.

On the synchronization side, buildDetectorRequest resolves the detector’s state as:

detector.enabled = integration.enabled && (user override ?? document.detector.enabled)

The integration gates it, so a disabled integration never leaves a running detector whatever the user chose for it. When the integration is on, the user’s override wins and CTI’s document.detector.enabled is the default — absent there means CTI has no preference and the integration alone decides. The rest of the detector block is CTI-owned and supplies only the schedule and the source indices.

The override is the user’s Start/Stop from Security Analytics, kept in the registry. Toggling the integration clears it, so re-enabling an integration brings its detector back rather than leaving a stale decision in charge.

YAML content-type support

Decoders, KVDBs, and Filters accept Content-Type: application/yaml requests in addition to JSON. This is implemented through an opt-in pattern in the abstract handler hierarchy.

Architecture

The YAML support is built on three mechanisms in AbstractContentAction:

1. isYamlRequest(RestRequest) — Detects YAML content type via XContentType.YAML.equals(request.getMediaType()). Returns false on any exception (e.g., test mocks that don’t stub getMediaType()).

2. supportsYamlField() — Returns false by default. Overridden to true in concrete handlers that support YAML field storage: RestPostDecoderAction, RestPutDecoderAction, RestPostKvdbAction, RestPutKvdbAction, RestPostFilterAction, RestPutFilterAction.

3. YAML/JSON branching in executeRequest() — Both AbstractCreateAction and AbstractUpdateAction (and their *Spaces variants) branch on isYamlRequest() and supportsYamlField():

   • YAML path: Parses the body via YamlUtils.fromYaml(), then validates the envelope structure with the same validateResourcePayload() call as the JSON path. The rawYaml for the yaml field is generated from the resource subtree via YamlUtils.toYaml().
   • JSON path: Unchanged — parses via Jackson ObjectMapper.readTree().

Both paths converge after parsing: resource-specific validation, ID generation, external sync, and indexing are identical regardless of content type.

Envelope structure

YAML requests use the same envelope as JSON. The integration (or space for filters) and resource keys appear at the top level of the YAML document:

---
integration: <uuid>
resource:
  metadata:
    title: my-resource
    author: "Wazuh Inc."
  content:
    key1: value1

This is parsed into a JsonNode tree identical to what the JSON path produces.

YAML field storage

When supportsYamlField() returns true, the handler populates a yaml field on the CTI wrapper before indexing:

• YAML requests: rawYaml is generated from the parsed resource subtree (not the raw request body, which includes the envelope).
• JSON requests: YamlUtils.toYaml(resourceNode) auto-generates the YAML representation.

The yaml field is stored as text in the index mappings (see cti-decoders-mappings.json, cti-kvdbs-mappings.json, cti-filters-mappings.json).

Type fidelity

YamlUtils is configured with DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS to preserve floating-point precision. A post-parse fixDecimalScale() step ensures values like 5.0 retain scale 1 in their BigDecimal representation, preventing coercion to integer 5 during serialization.

The ContentIndex.create() method skips processPayload() when it receives a fully-formed CTI wrapper (with document, space, and hash keys), avoiding a lossy valueToTree() round-trip that would strip BigDecimal scale.

Key classes

Engine communication

The plugin communicates with the Wazuh Engine via a Unix Domain Socket (UDS) for validation and promotion of content.

EngineSocketClient

Located at: engine/client/EngineSocketClient.java

• Connects to the socket at /usr/share/wazuh-indexer/engine/sockets/engine-api-http.sock.
• Sends HTTP-over-UDS requests: builds a standard HTTP/1.1 request string (method, headers, JSON body) and writes it to the socket channel.
• Each request opens a new SocketChannel (using StandardProtocolFamily.UNIX) that is closed after the response is read.
• Parses the HTTP response, extracting the status code and JSON body.

EngineService interface

Defines the Engine operations:

EngineServiceImpl

Implementation using EngineSocketClient. Maps methods to Engine API endpoints:

Space model

Resources live in spaces that represent their lifecycle stage. The Space enum defines four spaces:

Promotion flow

Spaces promote in a fixed chain:

DRAFT → TEST → CUSTOM

The Space.promote() method returns the next space in the chain. STANDARD and CUSTOM spaces cannot be promoted further.

SpaceService

Located at: cti/catalog/service/SpaceService.java

Manages space-related operations:

• getSpaceResources(spaceName) — Fetches all resources (document IDs and hashes) from all managed indices for a given space.
• promoteSpace(indexName, resources, targetSpace) — Copies documents from one space to another via bulk indexing, updating the space.name field.
• calculateAndUpdate(targetSpaces) — Recalculates the aggregate SHA-256 hash for each policy in the given spaces. The hash is computed by concatenating hashes of the policy and all its linked resources (integrations, decoders, KVDBs, rules).
• buildEnginePayload(...) — Assembles the full policy payload (policy + all resources from target space with modifications applied) for Engine validation during promotion.
• deleteResources(indexName, ids, targetSpace) — Bulk-deletes resources from a target space.

Document structure

Every resource document follows this envelope structure:

{
  "document": {
    "id": "<uuid>",
    "title": "...",
    "date": "2026-01-01T00:00:00Z",
    "modified": "2026-01-15T00:00:00Z",
    "enabled": true
  },
  "hash": {
    "sha256": "abc123..."
  },
  "space": {
    "name": "draft",
    "hash": {
      "sha256": "xyz789..."
    }
  }
}

User overrides in the standard space

The standard space is rebuilt from CTI, so what the user changes there is recorded in a registry document and re-applied afterwards: the policy’s settings, the filters they created, and each integration’s enabled state along with its detector’s.

UserOverridesService manages a single document in the policies index under wazuh-user-overrides (Constants.USER_OVERRIDES_DOC_ID):

{
  "user_overrides": {
    "standard": {
      "policy": {
        "enabled": true,
        "index_unclassified_events": true,
        "index_discarded_events": false,
        "enrichments": ["connection", "url_full"]
      },
      "filters": [{ "id": "<uuid>", "document": "<the stored filter, serialized>" }],
      "integrations": {
        "<uuid>": { "enabled": false },
        "<another uuid>": { "detector_enabled": false }
      }
    }
  }
}

Both integration fields are optional, and absence means the user never decided: the two entries above are “the user disabled this integration” and “the user stopped this one’s detector without touching the integration”.

It is the one document in that index with no space field: the pre-snapshot wipe selects by space.name and never sees it, and the plan-change reindex carries it into the new physical index.

Enrichments are stored as the resulting list, and on apply only the values CTI still publishes are kept. Filters are stored as serialized strings, to keep their fields out of the "dynamic": "true" policies mapping. Integrations are keyed by id rather than listed, so Security Analytics can record a detector decision with a single partial update — a doc merge combines objects recursively but replaces arrays wholesale.

Written on a standard policy update, on filter create, update and delete, and on integration update. The detector decision is written by Security Analytics itself, which cannot call this plugin — the dependency only runs the other way — but writes the registry document directly. Applied at the start of ConsumerRulesetService.onSyncComplete, before the space hash is recalculated and the engine reloaded. Idempotent, and a failure is logged without aborting the synchronization.

Content synchronization pipeline

Overview

sequenceDiagram
    participant Scheduler as JobScheduler/RestAction
    participant SyncJob as CatalogSyncJob
    participant Swap as ShadowSwapService
    participant Synchronizer as ConsumerRulesetService
    participant ConsumerSvc as ConsumerService
    participant CTI as External CTI API
    participant Snapshot as SnapshotService
    participant Update as UpdateService
    participant Indices as Content Indices
    participant Consumers as .wazuh-cti-consumers
    participant SA as SecurityAnalyticsServiceImpl

    Scheduler->>SyncJob: Trigger Execution
    activate SyncJob

    SyncJob->>CTI: Look the plan up (SyncPass.resolve)

    SyncJob->>Swap: swapChangedSources(consumers, pass)
    opt A consumer's data source changes (resource URL differs)
        Swap->>CTI: Fetch the new remote consumer of every changing consumer
        Swap->>Indices: Create hidden shadow indices (-a/-b spare suffix)
        Swap->>Consumers: Rewrite every changing consumer (new resource, running, local_offset = 0)
        Swap->>CTI: Download each snapshot into its shadow indices
        Swap->>Indices: Reindex user content (space.name != "standard")
        Swap->>Indices: Refresh shadow indices
        Swap->>Indices: Unhide shadow indices
        Swap->>Indices: Atomic alias swap (single IndicesAliasesRequest for every changing consumer)
        Swap->>Consumers: Record the snapshot offsets (local_offset = snapshot offset)
        Swap->>Indices: Delete old physical indices
    end
    Swap-->>SyncJob: Outcome per consumer, in the pass

    SyncJob->>Synchronizer: synchronize(pass)

    Synchronizer->>ConsumerSvc: getLocalConsumer() / getRemoteConsumer()
    ConsumerSvc->>CTI: Fetch Metadata
    ConsumerSvc-->>Synchronizer: Offsets & Metadata
    Synchronizer->>Consumers: running, remote_offset = remote head

    alt Local Offset == 0 (Initialization)
        Synchronizer->>Snapshot: initialize(remoteConsumer)
        Snapshot->>CTI: Download Snapshot ZIP
        Snapshot->>Indices: Bulk Index Content (Rules/Integrations/etc.)
        Snapshot-->>Synchronizer: Done
    else Local Offset < Remote Offset (Update, or catch-up after a swap)
        Synchronizer->>Update: update(localOffset, remoteOffset)
        Update->>CTI: Fetch Changes
        Update->>Indices: Apply JSON Patches
        Update-->>Synchronizer: Done
    end

    opt Changes Applied, or swapped in this pass (onSyncComplete)
        Synchronizer->>Indices: Refresh Indices

        Synchronizer->>SA: upsertIntegration(doc)
        loop For each Integration
            SA->>SA: WIndexIntegrationAction
        end

        Synchronizer->>SA: upsertRule(doc)
        loop For each Rule
            SA->>SA: WIndexRuleAction
        end

        Synchronizer->>SA: upsertDetector(doc)
        loop For each Integration
            SA->>SA: WIndexDetectorAction
        end

        Synchronizer->>Synchronizer: calculatePolicyHash()
    end

    deactivate SyncJob

The opt Changes Applied (onSyncComplete) cascade also runs for a consumer the pass’s swap moved, even if nothing is left to catch up — by the time it executes, Indices and Consumers already resolve through the swapped alias and rewritten consumer document. A consumer whose data source changes but could not be swapped is not synchronized from its new source: it keeps its content until a swap of every changing consumer succeeds.

Initialization phase

When local_offset = 0:

1. Downloads a ZIP snapshot from the CTI API.
2. Reads each NDJSON entry of the ZIP straight from the archive, line by line and as bytes: a line is parsed in place in a reusable buffer (NdjsonLineReader), never decoded into a string, and each document is copied once, into its index request. The vulnerabilities snapshot alone is over 4 GB of NDJSON with documents of up to 17 MB, so string copies of its lines are enough to push a 2 GB heap over the parent circuit breaker.
3. Bulk-indexes content into respective indices.
4. Registers all content with the Security Analytics Plugin via SecurityAnalyticsServiceImpl.

Update phase

When local_offset > 0 and local_offset < remote_offset:

1. Marks the consumer running and, in the same write, records the remote head as remote_offset, so the document shows the gap still to be applied from its first running read.
2. Fetches the changes in batches from the CTI API.
3. Applies each change: creates or deletes the document, or patches it with the change’s JSON Patch (RFC 6902) operations through zjsonpatch. Patching is strict: an operation whose target does not exist fails the change (zjsonpatch needs FORBID_REMOVE_MISSING_OBJECT for removals). The operations are applied in place, without copying the document, on a tree parsed from the stored source bytes; if one fails, that tree is discarded and the stored document is left as it was. The patched document is serialized back to UTF-8 bytes for indexing. Several changes of the same document within a batch are applied in order, each on top of the previous one.
4. Pushes the changes to the Security Analytics Plugin via SecurityAnalyticsServiceImpl.
5. Updates the local offset.

Post-synchronization phase

1. Refreshes all content indices.
2. Re-applies the user overrides to the standard space, before anything reads the rebuilt content.
3. Upserts integrations, rules, and detectors into the Security Analytics Plugin via SecurityAnalyticsServiceImpl.
4. Recalculates SHA-256 hashes for policy integrity verification.
5. Sets consumer status to ready in .wazuh-cti-consumers (or failed if an unexpected exception interrupted the cycle). See the Reference Manual’s architecture page for the full ready / running / failed lifecycle.

Error handling

If a critical error or data corruption is detected, the system resets local_offset to 0, triggering a full snapshot re-initialization on the next run.

A change that cannot be applied to the stored content fails as a ContentIndex.PatchException, which carries the change’s offset and resource: its patch does not fit the stored document, or, for the consumers updated in batches (IoCs and vulnerabilities), the document is missing. Retrying it fails the same way, so AbstractConsumerService handles it in the same pass: when CTI has a snapshot newer than the consumer’s local offset, it rebuilds the content from that snapshot and applies the remaining changes from the snapshot’s offset. A snapshot at or past the failing offset already holds the change’s result; an older one still rebuilds stored content that diverged from CTI, which is what usually makes a valid change fail. The snapshot goes through the same blue/green path as a plan change (ShadowSwapService.rebuild(), for that consumer alone): it loads into hidden staging indices and the aliases are swapped only once it has loaded, so the current content stays available meanwhile and is kept if the snapshot cannot be loaded. The consumer document is not touched until the switch. After a rebuild the local offset is at or past the snapshot, so a given snapshot is used at most once; without a newer snapshot, the failure propagates and later runs retry the change. Any other failure (CTI unreachable, cluster errors) propagates as before and resumes from the last checkpoint.

Configuration settings

To register a new setting, follow the existing pattern in PluginSettings.java. That will make it available in opensearch.yml.

For existing settings, check the settings reference.

When registering a new setting, document it in the section linked above.

REST API URIs

All endpoints are under /_plugins/_content_manager. The URI constants are defined in PluginSettings:

REST API reference

The full API is defined in openapi.yml.

Logtest

The Indexer acts as a proxy between the UI and the Engine. POST /logtest accepts the payload and forwards it to the Engine via UDS. No validation is performed. If the Engine responds, its response is returned directly. If the Engine is unreachable, a 500 error is returned.

---
title: Logtest execution
---
sequenceDiagram
    actor User
    participant UI
    participant Indexer
    participant Engine

    User->>UI: run logtest
    UI->>Indexer: POST /logtest
    Indexer->>Engine: POST /logtest (via UDS)
    Engine-->>Indexer: response
    Indexer-->>UI: response

Content CUD (rules, decoders, integrations, KVDBs)

All four resource types follow the same patterns via the abstract class hierarchy:

Create (POST)

sequenceDiagram
    actor User
    participant Indexer
    participant EngineSA as Engine or Security Analytics
    participant ContentIndex
    participant IntegrationIndex

    User->>Indexer: POST /_plugins/_content_manager/{resource_type}
    Indexer->>Indexer: Validate payload, generate UUID, timestamps
    Indexer->>EngineSA: Sync (validate/upsert)
    EngineSA-->>Indexer: OK
    Indexer->>ContentIndex: Index in Draft space
    Indexer->>IntegrationIndex: Link to parent integration
    Indexer-->>User: 201 Created + UUID

Update (PUT)

sequenceDiagram
    actor User
    participant Indexer
    participant ContentIndex
    participant EngineSA as Engine or Security Analytics

    User->>Indexer: PUT /_plugins/_content_manager/{resource_type}/{id}
    Indexer->>ContentIndex: Check exists + is in Draft space
    Indexer->>Indexer: Validate, preserve metadata, update timestamps
    Indexer->>EngineSA: Sync (validate/upsert)
    Indexer->>ContentIndex: Re-index document
    Indexer-->>User: 200 OK + UUID

Delete (DELETE)

sequenceDiagram
    actor User
    participant Indexer
    participant ContentIndex
    participant EngineSA as Engine or Security Analytics
    participant IntegrationIndex

    User->>Indexer: DELETE /_plugins/_content_manager/{resource_type}/{id}
    Indexer->>ContentIndex: Check exists + is in Draft space
    Indexer->>EngineSA: Delete from external service
    Indexer->>IntegrationIndex: Unlink from parent
    Indexer->>ContentIndex: Delete document
    Indexer-->>User: 200 OK + UUID

Policy update

The policy endpoint now accepts a {space} path parameter (draft or standard), allowing the same handler to serve both spaces with different validation rules.

• Draft space — all policy fields are accepted. The integrations and filters arrays allow reordering but not adding or removing entries. author, description, documentation, and references are required in addition to the boolean fields.
• Standard space — only enrichments, filters, enabled, index_unclassified_events, and index_discarded_events can be modified. All other fields are preserved from the existing standard policy document. After a successful update, if the standard space hash changed, the updated policy is automatically loaded into the Engine.

flowchart TD
    UI[UI] -->|"PUT /policy/{space}"| Indexer
    Indexer -->|Validate space| SpaceCheck{is a valid space?}
    SpaceCheck -->|No| Error400[400 Bad Request]
    SpaceCheck -->|Yes| Parse[Parse & validate fields]
    Parse --> SpaceBranch{Space?}
    SpaceBranch -->|draft| StoreDraft[Update draft policy in wazuh-threatintel-policies]
    SpaceBranch -->|standard| StoreStd[Merge allowed fields into standard policy]
    StoreDraft --> Hash[Recalculate space hash]
    StoreStd --> Hash
    Hash --> EngineCheck{Standard hash changed?}
    EngineCheck -->|Yes| Engine[Load standard space into Engine]
    EngineCheck -->|No| OK[200 OK]
    Engine --> OK

Policy schema

The wazuh-threatintel-policies index stores policy configurations. See Document structure above for the envelope format.

Policy document fields

Filters CUD (Engine filters)

Filters follow the same CUD pattern as other resource types but use the AbstractCreateActionSpaces / AbstractUpdateActionSpaces / AbstractDeleteActionSpaces hierarchy. The key difference is that the target space is supplied in the request body rather than being fixed to draft. Both draft and standard are accepted.

Filters are linked directly to their space’s policy document (the filters array) rather than to a parent integration.

Create (POST)

sequenceDiagram
    actor User
    participant Indexer
    participant Engine
    participant FilterIndex as wazuh-threatintel-filters
    participant PoliciesIndex as wazuh-threatintel-policies

    User->>Indexer: POST /_plugins/_content_manager/filters
    Indexer->>Indexer: Validate payload + space (draft|standard)
    Indexer->>Engine: validateResource("filter", resource)
    Engine-->>Indexer: OK
    Indexer->>FilterIndex: Index in target space
    Indexer->>PoliciesIndex: Add filter ID to space policy filters[]
    Indexer-->>User: 201 Created + UUID

Update (PUT)

sequenceDiagram
    actor User
    participant Indexer
    participant Engine
    participant FilterIndex as wazuh-threatintel-filters

    User->>Indexer: PUT /_plugins/_content_manager/filters/{id}
    Indexer->>FilterIndex: Check exists + validate space (draft|standard)
    Indexer->>Indexer: Validate payload
    Indexer->>Engine: validateResource("filter", resource)
    Engine-->>Indexer: OK
    Indexer->>FilterIndex: Re-index document
    Indexer-->>User: 200 OK + UUID

Delete (DELETE)

sequenceDiagram
    actor User
    participant Indexer
    participant FilterIndex as wazuh-threatintel-filters
    participant PoliciesIndex as wazuh-threatintel-policies

    User->>Indexer: DELETE /_plugins/_content_manager/filters/{id}
    Indexer->>FilterIndex: Check exists + resolve space
    Indexer->>PoliciesIndex: Remove filter ID from space policy filters[]
    Indexer->>FilterIndex: Delete document
    Indexer-->>User: 200 OK + UUID

Space reset

flowchart TD
    UI[UI] -->|"DELETE /space/{space}"| Indexer
    Indexer -->|Validate space| Check{space == draft?}
    Check -->|No| Error400[400 Bad Request]
    Check -->|Yes| DeleteSA[Delete draft resources from Security Analytics]
    DeleteSA --> DeleteCTI[Delete all draft documents from wazuh-threatintel-* indices]
    DeleteCTI --> RegenPolicy[Re-generate default draft policy]
    RegenPolicy --> OK[200 OK]

Only the draft space can be reset. Attempting to reset any other space returns 400 Bad Request. Failures to delete individual Security Analytics detectors, rules or integrations are logged but do not block the reset — the primary goal is clearing the content indices and regenerating the policy. If the Security Analytics request fails outright (for example, the draft integration lookup fails), the reset stops and returns an error.

Debugging

Check consumer status

GET /.wazuh-cti-consumers/_search
{
  "query": { "match_all": {} }
}

The status field indicates the sync lifecycle state:

• ready — sync complete; content is safe to read.
• running — sync in progress; content may be partially written.
• failed — the previous sync cycle was interrupted by an unexpected exception.

To find consumers that are currently syncing or that failed mid-sync:

GET /.wazuh-cti-consumers/_search
{
  "query": { "terms": { "status": ["running", "failed"] } }
}

Check content by space

GET /wazuh-threatintel-rules/_search
{
  "query": { "term": { "space.name": "draft" } },
  "size": 10
}

Monitor plugin logs

tail -f var/log/wazuh-indexer/wazuh-cluster.log | grep -E "ContentManager|CatalogSyncJob|SnapshotServiceImpl|UpdateServiceImpl|AbstractContentAction"

Important notes

• The plugin only runs on cluster manager nodes.
• CTI API must be accessible for content synchronization.
• All user content CUD operations require a Draft policy to exist.
• The Engine socket must be available at the configured path for logtest, validation, and promotion.
• Offset-based synchronization ensures no content is missed.

Testing

The plugin includes integration tests defined in the tests/content-manager directory. These tests cover various scenarios for managing integrations, decoders, rules, and KVDBs through the REST API, grouped below by resource and operation.

Related documentation

• Content Manager tutorial: adding a REST endpoint
• Setup plugin guide
• OpenSearch plugin development

Tutorial: adding a REST endpoint to the Content Manager plugin

This tutorial walks through adding a new REST endpoint to the Content Manager plugin, using a concrete example: a GET endpoint to retrieve a single rule by ID.

By the end, you will have a working GET /_plugins/_content_manager/rules/{id} endpoint that fetches a rule document from the wazuh-threatintel-rules index.

Prerequisites

• Development environment set up (see Setup)
• The project compiles: ./gradlew :wazuh-indexer-content-manager:compileJava

Step 1: add the URI constant

If your endpoint uses a new base URI, add it to PluginSettings. In this case, rules already have RULES_URI, and our GET endpoint uses the same base path with an {id} parameter, so no changes are needed.

The existing constant in PluginSettings.java:

public static final String RULES_URI = PLUGINS_BASE_URI + "/rules";

Our endpoint will match /_plugins/_content_manager/rules/{id} using the same base URI.

Step 2: create the handler class

Create a new file at:

plugins/content-manager/src/main/java/com/wazuh/contentmanager/rest/service/RestGetRuleAction.java

package com.wazuh.contentmanager.rest.service;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.opensearch.core.rest.RestStatus;
import org.opensearch.rest.BaseRestHandler;
import org.opensearch.rest.BytesRestResponse;
import org.opensearch.rest.RestHandler.Route;
import org.opensearch.rest.RestRequest;
import org.opensearch.transport.client.node.NodeClient;

import java.util.List;

import com.wazuh.contentmanager.cti.catalog.index.ContentIndex;
import com.wazuh.contentmanager.settings.PluginSettings;
import com.wazuh.contentmanager.utils.Constants;

/**
 * GET /_plugins/_content_manager/rules/{id}
 *
 * Retrieves a single rule document by its ID from the wazuh-threatintel-rules index.
 */
public class RestGetRuleAction extends BaseRestHandler {

    private static final Logger log = LogManager.getLogger(RestGetRuleAction.class);
    private static final ObjectMapper MAPPER = new ObjectMapper();

    // A short identifier for log output and debugging.
    private static final String ENDPOINT_NAME = "content_manager_rule_get";

    @Override
    public String getName() {
        return ENDPOINT_NAME;
    }

    /**
     * Define the route. The {id} path parameter is automatically extracted
     * by OpenSearch and available via request.param("id").
     */
    @Override
    public List<Route> routes() {
        return List.of(
                new Route(RestRequest.Method.GET, PluginSettings.RULES_URI + "/{id}"));
    }

    /**
     * Prepare and execute the request. This method is called by the
     * OpenSearch REST framework for each incoming request.
     *
     * @param request the incoming REST request
     * @param client  the node client for index operations
     * @return a RestChannelConsumer that writes the response
     */
    @Override
    protected RestChannelConsumer prepareRequest(RestRequest request, NodeClient client) {
        // Extract the {id} path parameter.
        String id = request.param(Constants.KEY_ID);

        return channel -> {
            try {
                // Validate the ID parameter is present.
                if (id == null || id.isBlank()) {
                    channel.sendResponse(new BytesRestResponse(
                            RestStatus.BAD_REQUEST,
                            "application/json",
                            "{\"error\": \"Missing required parameter: id\"}"));
                    return;
                }

                // Use ContentIndex to retrieve the document.
                ContentIndex index = new ContentIndex(client, Constants.INDEX_RULES, null);
                JsonNode document = index.getDocument(id);

                if (document == null) {
                    channel.sendResponse(new BytesRestResponse(
                            RestStatus.NOT_FOUND,
                            "application/json",
                            "{\"error\": \"Rule not found: " + id + "\"}"));
                    return;
                }

                // Return the document as JSON.
                String responseBody = MAPPER.writeValueAsString(document);
                channel.sendResponse(new BytesRestResponse(
                        RestStatus.OK,
                        "application/json",
                        responseBody));

            } catch (Exception e) {
                log.error("Failed to retrieve rule [{}]: {}", id, e.getMessage(), e);
                channel.sendResponse(new BytesRestResponse(
                        RestStatus.INTERNAL_SERVER_ERROR,
                        "application/json",
                        "{\"error\": \"Internal server error: " + e.getMessage() + "\"}"));
            }
        };
    }
}

Key concepts

• getName() — Returns a short identifier used in logs and debugging.
• routes() — Defines the HTTP method and URI pattern. Uses Route to register the endpoint with OpenSearch’s REST framework.
• prepareRequest() — The core method. Returns a RestChannelConsumer lambda that executes asynchronously and writes the response to the channel.
• Path parameters — {id} in the route path is automatically parsed. Access it with request.param("id").

Step 3: register the handler

Open ContentManagerPlugin.java and add the new handler to getRestHandlers():

@Override
public List<RestHandler> getRestHandlers(
        Settings settings,
        RestController restController,
        ClusterSettings clusterSettings,
        IndexScopedSettings indexScopedSettings,
        SettingsFilter settingsFilter,
        IndexNameExpressionResolver indexNameExpressionResolver,
        Supplier<DiscoveryNodes> nodesInCluster) {
    return List.of(
            // ... existing handlers ...

            // Rule endpoints
            new RestPostRuleAction(),
            new RestPutRuleAction(),
            new RestDeleteRuleAction(),
            new RestGetRuleAction(),  // <-- Add the new handler

            // ... remaining handlers ...
    );
}

Make sure to add the import at the top of the file:

import com.wazuh.contentmanager.rest.service.RestGetRuleAction;

Step 4: build and verify

Compile the plugin to check for errors:

./gradlew :wazuh-indexer-content-manager:compileJava

If compilation succeeds, run the full build (including tests):

./gradlew :wazuh-indexer-content-manager:build

Step 5: test the endpoint

Manual testing

Start a local cluster (see tools/test-cluster) and test:

# Create a rule first (so there's something to fetch)
curl -X POST "https://localhost:9200/_plugins/_content_manager/rules" \
  -H "Content-Type: application/json" \
  -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD --insecure \
  -d '{
    "integration": "<integration-id>",
    "resource": {
      "metadata": {
        "title": "Test Rule",
        "author": "Tester"
      },
      "status": "experimental",
      "level": "low",
      "logsource": {
        "product": "<integration-title>",
        "category": "authentication"
      },
      "detection": {
        "condition": "selection",
        "selection": {
          "event.outcome": "failure"
        }
      }
    }
  }'

# The response returns the UUID. Use it to fetch:
curl -X GET "https://localhost:9200/_plugins/_content_manager/rules/<uuid>" \
  -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD --insecure

Writing a unit test

Create a test file at:

plugins/content-manager/src/test/java/com/wazuh/contentmanager/rest/service/RestGetRuleActionTests.java

At minimum, test that getName() and routes() return expected values:

package com.wazuh.contentmanager.rest.service;

import org.opensearch.rest.RestRequest;
import org.opensearch.test.OpenSearchTestCase;

public class RestGetRuleActionTests extends OpenSearchTestCase {

    public void testGetName() {
        RestGetRuleAction action = new RestGetRuleAction();
        assertEquals("content_manager_rule_get", action.getName());
    }

    public void testRoutes() {
        RestGetRuleAction action = new RestGetRuleAction();
        assertEquals(1, action.routes().size());
        assertEquals(RestRequest.Method.GET, action.routes().get(0).getMethod());
        assertTrue(action.routes().get(0).getPath().contains("/rules/{id}"));
    }
}

Run:

./gradlew :wazuh-indexer-content-manager:test

Summary

To add a new REST endpoint to the Content Manager plugin:

1. Create the handler class — Extend BaseRestHandler (for simple endpoints) or one of the abstract classes (AbstractCreateAction, AbstractUpdateAction, AbstractDeleteAction) for standard CUD.
2. Define routes — Use Route to declare the HTTP method and URI pattern.
3. Implement logic — Override prepareRequest() (or executeRequest() if extending the abstract hierarchy).
4. Register — Add the instance to ContentManagerPlugin.getRestHandlers().
5. Build and test — ./gradlew :wazuh-indexer-content-manager:compileJava then ./gradlew :wazuh-indexer-content-manager:test.

For content CUD endpoints that need Draft space validation, Engine sync, and hash updates, extend AbstractContentAction or one of its children instead of BaseRestHandler directly.

Logtest architecture and developer guide

Component overview

The logtest flow involves four layers: a thin REST handler, a transport action that owns request validation, an orchestration service, and the external services it calls.

RestPostLogtestAction               →  TransportLogtestAction               →  LogtestService  →  EngineService + SecurityAnalyticsService
RestPostLogtestNormalizationAction  →  TransportLogtestNormalizationAction  →       ↑                    ↑
RestPostLogtestDetectionAction      →  TransportLogtestDetectionAction      →       ↑                    ↑
       (REST handlers)                      (Validation)                     (Orchestration)       (External services)

REST handlers no longer validate requests or contain any business logic — that responsibility moved to the transport action layer. This is a plugin-wide pattern, not specific to logtest: every REST handler in rest/service/ delegates to a same-named Transport*Action via client.execute(), per AbstractContentAction’s own javadoc (“Business logic has been moved to transport actions; REST handlers now delegate to the transport layer via client.execute()”).

RestPostLogtestAction (combined)

Path: rest/service/RestPostLogtestAction.java

The REST handler for POST /_plugins/_content_manager/logtest. Before dispatch it enforces the request-body size cap via PayloadValidations.validateLogtestBodySize(...) — a body larger than plugins.content_manager.logtest.max_body_bytes is rejected with 413 at the REST layer, before parsing (see Request size limit and concurrency). Otherwise it reads the raw request body into a LogtestRequest and calls client.execute(LogtestAction.INSTANCE, logtestRequest, listener). It performs no field-level validation and does not interact with indices or external services directly.

TransportLogtestAction

Path: transport/TransportLogtestAction.java

The validation and dispatch layer for the combined endpoint. Responsibilities:

1. Validates the request has content and is valid JSON.
2. Validates the required field space.
3. Validates that space is not "draft".
4. Extracts the optional integration field (if present) and strips it from the Engine payload.
5. Delegates to LogtestService.executeLogtest(integrationId, space, enginePayload). If integrationId is null, only engine normalization is performed.

RestPostLogtestNormalizationAction

Path: rest/service/RestPostLogtestNormalizationAction.java

The REST handler for POST /_plugins/_content_manager/logtest/normalization. Enforces the body-size cap (413) the same way as the combined handler, then reads the request body and calls client.execute(LogtestNormalizationAction.INSTANCE, ...). No field-level validation.

TransportLogtestNormalizationAction

Path: transport/TransportLogtestNormalizationAction.java

Responsibilities:

1. Validates the request has content and is valid JSON.
2. Validates the required field space.
3. Validates that space is not "draft".
4. Strips the integration field if present (not used for normalization).
5. Delegates to LogtestService.executeNormalization(enginePayload).

RestPostLogtestDetectionAction

Path: rest/service/RestPostLogtestDetectionAction.java

The REST handler for POST /_plugins/_content_manager/logtest/detection. Enforces the body-size cap (413) the same way as the combined handler, then reads the request body and calls client.execute(LogtestDetectionAction.INSTANCE, ...). No field-level validation.

TransportLogtestDetectionAction

Path: transport/TransportLogtestDetectionAction.java

Responsibilities:

1. Validates the request has content and is valid JSON.
2. Validates the required fields space, integration, and input.
3. Validates that space is not "draft".
4. Validates that input is a JSON object (not a string or array).
5. Delegates to LogtestService.executeDetectionAsync(integrationId, space, inputEvent).

All three transport actions run this work on the dedicated content_manager_logtest thread pool rather than the transport thread (see Request size limit and concurrency).

Request size limit and concurrency

The logtest endpoints are deliberately reachable by low-privilege accounts. To keep that surface from being used to exhaust the indexer’s heap, two independent controls bound the work each request can cause:

• Body-size cap (413). Every logtest REST handler checks the raw request-body length against plugins.content_manager.logtest.max_body_bytes (default 1 MiB; dynamic; range 1 KiB–16 MiB) before parsing or dispatching, via the shared PayloadValidations.validateLogtestBodySize(...) helper. An oversized body is rejected with 413 REQUEST_ENTITY_TOO_LARGE and the message logtest payload exceeds the maximum allowed size of <N> bytes., and the offending account and size are logged at WARN. This removes the input-to-response amplification the endpoint would otherwise permit, since the input is bounded before any work happens.
• Bounded thread pool (429). The three transport actions offload execution onto a dedicated FixedExecutorBuilder pool named content_manager_logtest (size max(1, allocatedProcessors / 2), queue 100), registered in ContentManagerPlugin.getExecutorBuilders(...). This keeps the blocking Engine-socket call off the transport threads, and when the bounded queue is full excess requests are shed with 429 TOO_MANY_REQUESTS (logtest is busy: too many concurrent requests. Please retry later.) instead of accumulating on the heap. Worst-case in-flight payload is bounded to roughly (pool size + queue) * max_body_bytes.

LogtestService

Path: cti/catalog/service/LogtestService.java

The orchestrator. Provides three public entry points:

• executeLogtest() — Full combined flow (normalization + detection)
• executeNormalization() — Engine-only: forwards payload to EngineService.logtest() and returns the response directly with parseMessageAsJson()
• executeDetectionAsync() — Security Analytics-only: looks up integration, fetches rule IDs/bodies, evaluates via SecurityAnalyticsService.evaluateRulesAsync(), and returns the result

The full logtest flow:

1. No-integration shortcut — If integrationId is null, delegates to executeEngineOnly(): runs the Engine normalization and returns the result with detection.status: "skipped" and reason: "'integration' field not provided". Steps 2–5 below are skipped.
2. Integration lookup — Queries wazuh-threatintel-integrations for a document matching document.id == integrationId and space.name == space. Returns 400 if not found.
3. Engine processing — Sends the event payload to the Wazuh Engine via EngineService.logtest(). Extracts the normalized event from the output field. The engine result fields (output, asset_traces, validation) are included directly in the response (no wrapper).
4. Rule fetching — Extracts rule IDs from the integration’s document.rules array, then fetches rule bodies from wazuh-threatintel-rules by document.id, filtered by the same space.
5. Security Analytics evaluation — Passes the normalized event JSON, the rule bodies and the integration’s detector coordinates to SecurityAnalyticsService.evaluateRulesAsync().
6. Response building — Combines engine and Security Analytics results into a single JSON response under the keys normalization and detection.

Error handling:

• If the Engine fails (HTTP error or exception), Security Analytics evaluation is skipped and the response includes status: "skipped" with the reason.
• If no integration is provided, detection is skipped (normalization-only mode).
• If the integration has no rules, Security Analytics returns rules_evaluated: 0, rules_matched: 0 with success status.
• If Security Analytics evaluation returns unparseable JSON, the result is status: "error".

SecurityAnalyticsService / PercolateRuleEvaluator

The Security Analytics evaluation happens in the security-analytics repository:

• SecurityAnalyticsServiceImpl.evaluateRulesAsync() — Sends the event, the rule bodies and the integration’s detector coordinates (id, log type, source indices) to the WEvaluateRulesAction transport action.
• WTransportEvaluateRulesAction — Parses the rule bodies into SigmaRule objects and delegates to PercolateRuleEvaluator.
• PercolateRuleEvaluator.evaluate() — Compiles each rule with OSQueryBackend, stores the compiled queries in the logtest percolator index, and percolates the normalized event against them. Returns a JSON result string.

Why percolation. Detection has to answer one question: would the deployed detector fire on this event? A detector answers it by percolating compiled query_string queries against its query index, so logtest answers it the same way. Evaluating the Sigma condition directly in the JVM would answer a subtly different question — it cannot reproduce query_string parsing, the query index’s analyzers, or the percolator’s own field-mapping requirements — which makes its answer an approximation rather than a prediction. Sharing the compiler, the analyzers and the percolator makes the two answers the same by construction, and keeps them that way as any of the three changes.

Everything the evaluator relies on is the same artifact production uses:

LogtestQueryIndex owns the percolator index, one per log type (.opensearch-sap-<logtype>-detectors-queries-logtest). The name is deliberately inside the detector query index template’s pattern, so the index inherits the analysis settings rather than redefining them. The index is created on demand and document ids are content-addressed, so a rule whose text has not changed reuses its document and repeated calls neither overwrite nor accumulate; documents left by an earlier revision of a rule are pruned once past a short grace period.

Match results use a nested rule object per match entry, where matched_conditions lists the conditions the event satisfies, one entry per condition:

{
  "rule": { "id": "...", "title": "...", "level": "...", "tags": [...] },
  "matched_conditions": ["http.request.method matched 'GET'", "url.original matched '*UNION SELECT*'"]
}

Data flow

Client request
    │
    ▼
RestPostLogtestAction (combined)
    │  reads body into LogtestRequest, no validation
    │  client.execute(LogtestAction.INSTANCE, ...)
    ▼
TransportLogtestAction
    │  validates request
    │  strips "integration" field
    ▼
LogtestService.executeLogtest(integrationId, space, payload)
    │
    ├──► [if integrationId == null]
    │       → executeEngineOnly(payload)
    │       → returns normalization + detection: { status: "skipped" }
    │
    ├──► client.prepareSearch("wazuh-threatintel-integrations")
    │       → finds integration in given space (test or standard)
    │       → extracts rule IDs from document.rules
    │
    ├──► engineService.logtest(payload)
    │       → sends to Wazuh Engine socket
    │       → receives normalized event
    │       → extracts "output" node as normalized event JSON
    │
    ├──► client.prepareSearch("wazuh-threatintel-rules")
    │       → fetches rule bodies by document.id + space filter
    │
    ├──► securityAnalytics.evaluateRulesAsync(normalizedEventJson, ruleBodies,
    │                                          integrationId, logType, sourceIndices)
    │       → parses YAML → SigmaRule objects
    │       → OSQueryBackend compiles each rule to a query_string query
    │       → queries are upserted into the logtest percolator index
    │       → the event is percolated against them
    │       → returns JSON result
    │
    └──► builds combined response
            { normalization: {...}, detection: {...} }

Split endpoints

In addition to the combined flow, there are two dedicated endpoints that execute normalization and detection independently:

RestPostLogtestNormalizationAction           RestPostLogtestDetectionAction
    │  no validation, delegates via client.execute()  │  no validation, delegates via client.execute()
    ▼                                            ▼
TransportLogtestNormalizationAction          TransportLogtestDetectionAction
    │  validates: space                          │  validates: space, integration, input
    │  strips integration field                  │
    ▼                                            ▼
LogtestService.executeNormalization(payload)  LogtestService.executeDetection(id, space, input)
    │                                            │
    └──► engineService.logtest(payload)          ├──► client.prepareSearch(".cti-integrations")
         → returns engine response directly      │       → finds integration
                                                 ├──► extractRuleIds() + fetchRuleBodies()
                                                 │       → fetches rule content from .cti-rules
                                                 └──► securityAnalytics.evaluateRulesAsync(inputJson, ruleBodies, ...)
                                                         → returns Security Analytics result directly

Key differences from the combined endpoint

• Normalization returns the raw Engine response (no detection wrapper). The integration field is stripped if present but has no effect on behavior.
• Detection accepts a pre-normalized event as the input JSON object. It does not call the Engine — it goes straight to integration lookup → rule fetch → Security Analytics evaluation.

Index dependencies

Both indices must exist and have document.id mapped as keyword for term queries to work.

Security Analytics additionally reads the integration’s detector source indices (document.detector.source, or wazuh-events-v5-<category> when it names none) to build the percolator index mappings, and owns .opensearch-sap-<logtype>-detectors-queries-logtest.

Testing

Unit tests

Integration tests

Integration tests extend ContentManagerRestTestCase and run against a real OpenSearch cluster. Since the Wazuh Engine is not available in the test environment, engine-dependent tests validate graceful error handling (engine error → Security Analytics skipped). Detection is not mocked: the test cluster installs Security Analytics and alerting, and plugins.content_manager.security_analytics.mock is set to false there so rule evaluation percolates for real. plugins.content_manager.engine.mock stays true because the Engine’s Unix socket genuinely is absent; the two settings are separate for exactly this reason.

Adding new logtest features

Supporting a new validation field

1. Add the field constant to Constants.java.
2. Add validation logic in the relevant transport action(s): TransportLogtestAction, TransportLogtestNormalizationAction, and/or TransportLogtestDetectionAction. The REST handlers themselves need no changes — they only read the body and dispatch.
3. Add unit tests in the corresponding test classes.
4. Add integration test in LogtestIT.

Supporting a new Engine response field

1. Update LogtestService.executeEngine() to extract the field.
2. Include it in the normalization map within buildCombinedResponse().
3. Add unit test scenarios in LogtestServiceTests.
4. Update the API docs (api.md) response fields table.

Extending Security Analytics evaluation

Detection semantics live in the Sigma compiler, not in logtest: a new modifier is implemented in rules/modifiers/ and rendered by OSQueryBackend, and logtest picks it up for free because it compiles rules with the same backend.

1. Add the modifier under rules/modifiers/ and register it in SigmaModifierFacade.
2. Render it in OSQueryBackend, and pin the generated query in QueryBackendTests.
3. Cover it end to end in LogtestIT (detection endpoint) so the percolate path is exercised.
4. Update the Sigma rules doc (Sigma Rules), including the case-sensitivity behaviour.

Wazuh Indexer Notifications plugin — development guide

This document describes the architecture, components, and extension points of the Notifications plugin, which provides multi-channel notification capabilities to the Wazuh Indexer.

Overview

The Notifications plugin handles:

• Channel Management: CRUD operations for notification channels (Slack, Email, Chime, Microsoft Teams, Webhooks, SNS, SES, Wazuh Active Response).
• Message Delivery: Abstracts different communication protocols (SMTP, HTTP, AWS SES/SNS) into a unified transport layer.
• Test Notifications: Allows sending test messages to validate channel configuration.
• Plugin Features: Exposes dynamic feature discovery so other plugins can query supported notification types.
• Security Integration: Integrates with the Wazuh Indexer Security plugin for RBAC-based access control.

Project structure

The plugin is organized into three Gradle subprojects:

Class hierarchy

Destination models (core-spi)

BaseDestination
├── SlackDestination
├── ChimeDestination
├── MicrosoftTeamsDestination
├── CustomWebhookDestination
├── WebhookDestination
├── SmtpDestination
├── SesDestination
├── SnsDestination
└── ActiveResponseDestination

ActiveResponseDestination has no transport: active_response channels are handled in the notifications module (see Notification flow).

Transport layer (core)

DestinationTransport (interface)
├── WebhookDestinationTransport      (Slack, Chime, Teams, Webhooks)
├── SmtpDestinationTransport         (SMTP Email)
├── SesDestinationTransport          (AWS SES Email)
└── SnsDestinationTransport          (AWS SNS)

REST handlers (notifications)

Setup environment

Requirements

• JDK: 21 or later. The build compiles to Java 21 (sourceCompatibility, targetCompatibility and Kotlin jvmTarget in notifications/build.gradle). CI builds with JDK 21 and 25, and the Wazuh Indexer bundles JDK 25.
• Gradle: Use the included ./gradlew wrapper (no separate install needed).
• IDE: IntelliJ IDEA with Kotlin plugin is recommended.

Clone and build

The build resolves wazuh-indexer-common-utils from the local Maven repository, so publish it first by running ./gradlew publishToMavenLocal in a checkout of that repository. The Gradle wrapper lives in the notifications/ directory:

git clone <notifications-repo-url>
cd wazuh-indexer-notifications/notifications
./gradlew build

The distribution zips are generated at (paths relative to the repository root):

notifications/core/build/distributions/wazuh-indexer-notifications-core-<version>.zip
notifications/notifications/build/distributions/wazuh-indexer-notifications-<version>.zip

Build packages

To create distribution packages:

# Full build (compile + test + assemble)
./gradlew build

# Assemble only (skip tests)
./gradlew assemble

The output zips can be installed on a Wazuh Indexer node with opensearch-plugin. Install the core plugin first, since the Notifications plugin extends it:

bin/opensearch-plugin install file:///path/to/wazuh-indexer-notifications-core-<version>.zip
bin/opensearch-plugin install file:///path/to/wazuh-indexer-notifications-<version>.zip

Run tests

Unit tests

./gradlew test

Integration tests

The integration test suite is located at:

notifications/notifications/src/test/kotlin/org/opensearch/integtest/

To execute the full integration test suite, from the notifications/ directory:

./gradlew :notifications:integTest

Key integration test classes:

Notification flow

The data flow when sending a notification follows this sequence:

sequenceDiagram
    participant C as Alerting / Reporting / ISM
    participant N as SendNotificationAction
    participant CI as .opensearch-notifications-config
    participant T as DestinationTransportProvider
    participant EXT as External service
    participant B as ActiveResponseBulkIndexer
    participant AR as wazuh-active-responses

    C->>N: sendNotification (channel IDs, message)
    N->>N: UserAccessManager.validateUser
    N->>CI: Get channel configs (and email account/group configs)
    CI-->>N: Configs
    loop Each channel, in parallel (Dispatchers.IO)
        alt Missing, access denied or muted
            N->>N: Error EventStatus, nothing sent
        else Slack, Chime, Teams, webhook, email, SNS
            N->>T: NotificationCore.sendMessage(destination)
            T->>EXT: Webhook / SMTP / SES / SNS transport
            EXT-->>T: Response
            T-->>N: DestinationMessageResponse
        else active_response
            N->>N: Get the triggering document, build the request
            N->>B: add(IndexRequest)
            B->>AR: Bulk on flush interval or max actions
        end
    end
    N-->>C: SendNotificationResponse (EventStatus per channel)

1. An internal plugin (Alerting, Reporting, ISM) or a user invokes the Notification plugin via Transport or REST API. SendNotificationAction delegates to SendMessageActionHelper.executeRequest.
2. UserAccessManager.validateUser rejects a user without backend roles when filter_by_backend_roles is enabled.
3. The channel configs, and the smtp_account/ses_account/email_group configs that email channels reference, are read from the .opensearch-notifications-config index (NotificationConfigIndex). A missing, inaccessible or disabled (muted) channel gets an error EventStatus and is skipped.
4. For the remaining channels, in parallel, sendMessageThroughSpi calls NotificationCore.sendMessage, and the DestinationTransportProvider resolves the correct transport based on the destination type. Webhook URLs are checked against host_deny_list before sending.
5. The transport client delivers the message to the external service. There is no plugin-level retry: only the default retry strategy of the Apache HTTP client (DefaultHttpRequestRetryStrategy) applies, to webhook deliveries. A failed delivery is returned as a non-200 DeliveryStatus.
6. active_response channels never reach NotificationCore. sendActiveResponseMessage parses <doc_id>|<index> from the message, reads that document, copies its wazuh object (refusing with 400 when location is local and the document has no wazuh.agent.id), adds wazuh.active_response with the channel parameters, and adds an IndexRequest (op type create) for the wazuh-active-responses data stream to the ActiveResponseBulkIndexer. The status is 200 as soon as the request is queued; the BulkProcessor flushes every opensearch.notifications.active_response.bulk_flush_interval_ms or after bulk_max_actions requests, and bulk failures are only logged and counted in a metric.
7. The EventStatus list is returned to the caller in a SendNotificationResponse. If any channel’s status is not 200, the action fails with an OpenSearchStatusException that carries the whole event_status_list. Nothing is persisted about the delivery itself.

Default channel initialization

The plugin creates a set of default notification channels on startup so that users have pre-configured templates for common integrations (Slack, Jira, PagerDuty, Shuffle). These channels are created disabled with placeholder URLs.

Implementation

The feature is implemented in DefaultChannelInitializer (notifications/notifications/src/main/kotlin/.../index/DefaultChannelInitializer.kt).

Adding or modifying default channels

To add a new default channel:

1. Add a new ChannelDefinition entry to the DEFAULT_CHANNELS list in DefaultChannelInitializer.kt.
2. Choose a unique, stable id prefixed with default_ (e.g., default_teams_channel).
3. Set isEnabled = false and use a placeholder URL with clear instructions in the description.
4. Add a corresponding test case in DefaultChannelInitializerTests.kt.

ClusterPlugin interface

The NotificationPlugin class implements ClusterPlugin to gain access to the onNodeStarted(DiscoveryNode) lifecycle hook.

Testing

Unit tests for the default channel initialization are in:

notifications/notifications/src/test/kotlin/.../index/DefaultChannelInitializerTests.kt

The tests verify:

• All default channel definitions have valid configurations.
• Channel IDs are unique and follow the naming convention.
• The initializer correctly identifies missing channels and skips existing ones.

Extending with a new destination

To add a new notification destination:

1. Define the destination model in core-spi:

   • Create a new class extending BaseDestination in notifications/core-spi/src/main/kotlin/.../destination/.

2. Implement the transport in core:

   • Create a new class implementing DestinationTransport in notifications/core/src/main/kotlin/.../transport/.
   • Register it in DestinationTransportProvider.

3. Add the config type to the DEFAULT_ALLOWED_CONFIG_TYPES list in core/setting/PluginSettings.kt.

4. Write tests: Add integration tests in notifications/notifications/src/test/kotlin/org/opensearch/integtest/config/.

Security Analytics

The Security Analytics plugin is a fork of the OpenSearch Security Analytics plugin adapted for Wazuh. This page documents Wazuh-specific implementation details and extensions. See Architecture for the conceptual overview.

A note on naming: the Reference Manual documents this plugin as Ruleset Management, the name it is presented under in the Wazuh Dashboard. The Development Guide keeps the name Security Analytics, which is what the code, the plugins.security_analytics.* settings, the /_plugins/_security_analytics/ API paths, the .opensearch-sap-* indices and the wazuh-indexer-security-analytics repository all use. Both names describe the same plugin — see Ruleset Management for the user-facing reference.

Enriched findings pipeline

WazuhEnrichedFindingService implements the enrichment pipeline described in the Reference Manual’s architecture page.

Its input is the in-memory Finding the Alerting plugin publishes for every match: the doc-level monitor fan-out (TransportDocLevelMonitorFanOutAction.createFindings()) calls AlertingPluginInterface.publishFinding(), TransportCorrelateFindingAction receives it as SUBSCRIBE_FINDINGS_ACTION and dispatches it to enrich(). Publishing does not depend on Alerting storing the finding: the raw .opensearch-sap-{log_type}-findings-* indices are only written when plugins.alerting.alert_finding_enabled is true, which defaults to false in the Wazuh fork, so with the shipped defaults the enriched wazuh-findings-v5-{category}* documents are the only stored findings.

Fire-and-forget execution

WazuhEnrichedFindingService.enrich() returns immediately after adding the finding to the internal queue. All network I/O and document assembly happen on async transport threads. Failures are logged at WARN level and never surface to the Security Analytics write path.

Bounded, batch-oriented concurrency

Enrichment is batch-oriented, not per-finding: processQueue() drains the internal findingsQueue in batches of up to enriched_findings_enrich_batch_size findings (default 100, range 1–1000, dynamic) and acquires a single semaphore permit for the whole batch, not one permit per finding. The semaphore is an AdjustableSemaphore sized by enriched_findings_max_in_flight (default 5, range 1–10, dynamic) — its permit count can be resized live via setMaxInFlight() when the setting changes, with no restart required. Batches that arrive while all permits are held stay queued in findingsQueue until a permit frees up.

Within a batch, per-finding completion is tracked with an AtomicInteger remaining counter; the batch’s single permit is only released once every finding in the batch has completed (onOneDone callback).

Batched triggering-event fetch

Instead of one GetRequest per finding, the service fetches all triggering events for a batch in a single deduplicated MultiGetRequest (deduplicated by index|docId, since multiple findings in a batch can share the same source event). This is the core throughput optimization: it eliminates roughly enrichBatchSize - 1 out of every enrichBatchSize round-trips to the event index under load. Rule-metadata lookups are unaffected by this batching and remain per-finding (see below).

Rule metadata cache

Rule metadata (severity level, compliance mappings, MITRE ATT&CK tags) is cached in a LinkedHashMap in access-order mode wrapped with Collections.synchronizedMap, with an overridden removeEldestEntry providing LRU eviction — not a plain ConcurrentHashMap (which has no eviction capability). The cache is bounded by plugins.security_analytics.enriched_findings_rule_cache_max_size (default 10000, minimum 0). Unlike the other enriched-findings settings, this one is static: it has no registered settings-update-consumer, so changing it requires a node restart.

On a cache miss, the service issues a MultiGetRequest against both the pre-packaged rules index (.opensearch-sap-pre-packaged-rules-config, Rule.PRE_PACKAGED_RULES_INDEX) and the custom rules index (.opensearch-sap-custom-rules-config, Rule.CUSTOM_RULES_INDEX). Subsequent findings from the same detector reuse the cached entry, eliminating repeated round-trips.

Bulk indexing

Index requests are accumulated in a ConcurrentLinkedQueue<IndexRequest>. Two flush paths drain this queue:

• Batch trigger: every time the pending count reaches a multiple of enriched_findings_bulk_size (default 100, range 10–1000, dynamic), the thread that incremented the counter calls drainAndFlush() immediately.
• Periodic flush: a fixed-delay scheduler fires drainAndFlush() every enriched_findings_flush_interval (default 5 seconds, range 1–60, dynamic) to drain any remainder that has not yet reached the batch threshold. Changing this setting at runtime cancels and reschedules the flush job (setFlushInterval()).

drainAndFlush() polls all pending requests into a single BulkRequest and calls client.bulk(). The call is wrapped in threadPool.getThreadContext().stashContext() so the security plugin accepts the request regardless of which thread pool the flush runs on.

Document build offloading

Synchronous document-assembly work (copying event sources, interpolating templates) runs on the GENERIC thread pool rather than the transport/listener thread that completed the upstream MultiGetRequest — this keeps that work from competing with request handling on the transport thread.

Category resolution

Before assembling an enriched document, the service reads wazuh.integration.category from the triggering event. If the field is absent or its value is not one of the recognized LOG_CATEGORY values, enrichment is skipped for that finding and a WARN log entry is emitted.

Document layout

buildDocAndIndex starts from a shallow copy of the triggering event source and overlays the following fields:

Rule metadata is nested under wazuh.rule. title and tags come from the matched DocLevelQuery, not from the rule index entry: the query’s tags are the rule’s level, its log type (the integration) and then its Sigma tags, so wazuh.rule.tags carries all three. mitre keeps the per-category layout of SigmaMitre.toMitreMap(); subtechniques are never folded into technique. Because the event’s wazuh map (which carries wazuh.integration.*) is shared with the shallow copy, the service defensively copies it before adding rule, so the original event source is never mutated.

event.index is finding.getIndex(), the concrete backing index (.ds-wazuh-events-v5-<category>-<generation>), not the data stream name. The document _id is not generated by OpenSearch: dedupId() hashes the backing index, the event _id and the rule ID with SHA-256, keeps the first 128 bits and encodes them as base64url, and the request uses op type create. A finding replayed for the same event and rule therefore fails as a duplicate instead of being indexed twice, as long as it lands in the same backing index: OpenSearch only enforces _id uniqueness within a backing index, not across a data stream’s rollovers. No field holds the time the enriched finding was built: the timestamp of the Alerting Finding is not copied.

The user-facing description of these fields is in the Reference Manual’s Wazuh Common Schema page.

Sequence diagram

sequenceDiagram
    participant A as Wazuh Manager
    participant I as Wazuh Indexer
    participant AL as Alerting (doc-level monitor)
    participant TC as TransportCorrelateFindingAction
    participant WS as WazuhEnrichedFindingService
    participant SI as Source Index
    participant RI as Rules Index
    participant WF as wazuh-findings-v5-{category}*

    A->>I: Ingest event
    I->>AL: Monitor evaluates event against Sigma rules
    AL->>AL: Rule matches → create raw finding (indexed only if plugins.alerting.alert_finding_enabled)
    AL->>TC: publishFinding() → SUBSCRIBE_FINDINGS_ACTION
    TC->>WS: enrich(finding)
    WS->>WS: Add to findingsQueue
    WS->>WS: processQueue() drains a batch (up to enrichBatchSize findings)
    WS->>WS: Acquire semaphore permit for the whole batch (max_in_flight)
    WS->>SI: MultiGetRequest (deduplicated triggering events for the batch)
    SI-->>WS: Event source maps
    loop For each finding in the batch
        WS->>WS: resolveCategory(wazuh.integration.category)
        alt Rule metadata cache hit
            WS->>WS: Read from ruleMetadataCache
        else Cache miss
            WS->>RI: MultiGetRequest (pre-packaged + custom rules indices)
            RI-->>WS: Rule metadata
            WS->>WS: Store in ruleMetadataCache
        end
        WS->>WS: buildDocAndIndex (assemble enriched document, on GENERIC thread pool)
        WS->>WS: Add to pendingRequests queue
    end
    alt Batch trigger (bulk_size reached)
        WS->>WF: client.bulk (stashed thread context)
    else Periodic flush (every flush_interval)
        WS->>WF: client.bulk (stashed thread context)
    end
    WS->>WS: Release batch's semaphore permit once every finding in it has completed

Tuning settings

• plugins.security_analytics.enriched_findings_bulk_size (default 100, range 10–1000, dynamic) — bulk flush batch size: number of pending index requests accumulated before a batch-trigger flush.
• plugins.security_analytics.enriched_findings_max_in_flight (default 5, range 1–10, dynamic) — maximum number of concurrent in-flight enrichment batches.
• plugins.security_analytics.enriched_findings_flush_interval (default 5 seconds, range 1–60, dynamic) — interval between periodic flush runs.
• plugins.security_analytics.enriched_findings_enrich_batch_size (default 100, range 1–1000, dynamic) — number of findings drained from the queue per in-flight permit.
• plugins.security_analytics.enriched_findings_rule_cache_max_size (default 10000, minimum 0, static — requires a node restart) — maximum number of rule-metadata entries cached in memory.
• Index operation type (CREATE, not configurable) — prevents overwriting existing enriched findings.

See the Configuration reference for the full settings list.

Detector provisioning

Threat detectors for Wazuh integrations are created dynamically based on CTI content, via a request-driven model (WIndexDetectorRequest) rather than hardcoded configuration.

Dynamic detector factory

The DetectorFactory class assembles the Detector object, consuming parameters provided by the Content Manager:

• Enabled status: controlled by CTI to activate or deactivate detectors globally.
• Scan interval: customizable per integration (e.g., critical integrations can have shorter intervals).
• Source indices: defines the target indices or index patterns the detector monitors.

Fallback logic

To ensure system stability, DetectorFactory implements a fallback mechanism for source indices:

• If the sources list is provided and not empty, it is used as the detector’s input.
• If sources is null or empty, the factory defaults to the legacy pattern: wazuh-events-v5-{category}.

Dynamic configuration injection

WTransportIndexDetectorAction serves as the entry point for detector creation. It extracts the enabled, interval, and sources fields from the WIndexDetectorRequest and injects them into the factory method. This ensures that any change in the CTI catalog is reflected in the Security Analytics engine without requiring code changes or restarts.

Case management

Case management adds triage capabilities to Security Analytics findings, allowing analysts to track status, classification, a multi-comment discussion thread, tags, and user attribution on individual findings.

Case fields

WCS fields under wazuh.case, all defined in the findings index template:

• wazuh.case.title (match_only_text) — case summary.
• wazuh.case.description (match_only_text) — case description.
• wazuh.case.tags (keyword, array) — organizational tags.
• wazuh.case.user.name (keyword) — user who performed the update.
• wazuh.case.status (keyword) — workflow status: active, acknowledged, completed, error, deleted, audit (lowercase).
• wazuh.case.severity (keyword) — informational, low, medium, high, critical (lowercase).
• wazuh.case.priority (keyword) — low, medium, high, urgent (lowercase).
• wazuh.case.tlp (keyword) — TLP:RED, TLP:AMBER, TLP:GREEN, TLP:CLEAR (uppercase, TLP: prefix — the one enum field that isn’t lowercase).
• wazuh.case.created_at, wazuh.case.updated_at (date) — case timestamps.
• wazuh.case.comments (array of objects) — replaces the old single comment field. Each entry has author (keyword), created_at (date), updated_at (date), and comment (match_only_text). The WCS source declares the field nested, but the generated findings template maps it through dynamic templates, so the shipped indices map it as a plain object.

These fields are present in the index template but not populated at finding creation time — they are written exclusively through the update endpoint.

REST endpoint

RestUpdateFindingsAction

File: src/main/java/org/opensearch/securityanalytics/resthandler/RestUpdateFindingsAction.java

Route: PUT /_plugins/_security_analytics/findings/_update

Design decisions

1. Bulk-based: the number of finding updates per call is capped by the dynamic setting plugins.security_analytics.max_case_management_bulk_size (SecurityAnalyticsSettings.MAX_CASE_MANAGEMENT_BULK_SIZE, default 10, range 0–100), read from ClusterSettings on every request. 0 disables the endpoint.

2. Partial doc update: uses UpdateRequest.doc() which merges the provided fields into the existing document. Only wazuh.case is touched, other finding fields are never modified. Arrays (tags, comments) are replaced, not appended to.

3. Schema validation: CaseValidator.validateAndNormalize() checks each case object against the WCS fields before the bulk request is built. Unknown keys (in case, case.user or a comment) and enum values outside the allowed sets are rejected; status, severity and priority are lowercased and tlp uppercased in place, so stored values are always in the canonical case that keyword queries must use.

Request validation

The handler performs eager validation before building the bulk request:

Validation errors short-circuit, the first error aborts the entire request.

Response format

{
  "took": 12,
  "errors": false,
  "items": [
    {
      "_id": "...",
      "_index": "...",
      "status": 200,
      "result": "updated"
    }
  ]
}

• On full success: HTTP 200
• When any item fails (for example, a finding that does not exist), including when every item fails: HTTP 207 MULTI_STATUS, with each item’s own status
• When the bulk request itself fails: HTTP 500

Registration

The handler is registered in SecurityAnalyticsPlugin.getRestHandlers():

new RestUpdateFindingsAction(clusterSettings)

Testing

Integration tests live in src/test/java/org/opensearch/securityanalytics/resthandler/UpdateFindingsIT.java.

The test class extends SecurityAnalyticsRestTestCase and covers:

• Happy path: single update with all fields, partial updates, bulk updates, overwrite scenarios
• Validation: empty array, missing fields (_id, _index, case), invalid JSON, exceeding max bulk items
• Error handling: non-existent document (expects 207), response structure verification
• Helpers: creates a temporary index with the wazuh.case mapping and indexes minimal finding documents for testing

Tests use the REST test client (makeRequest) and don’t require a full detector/monitor setup since the endpoint operates directly on documents by _id and _index.

Sequence diagram

sequenceDiagram
    participant UI as Wazuh Dashboard
    participant SA as Security Analytics
    participant OS as OpenSearch (Bulk API)
    participant FI as Findings Index

    UI->>SA: PUT /findings/_update { findings: [...] }
    SA->>SA: Validate request (JSON, required fields, limits)
    alt Validation fails
        SA-->>UI: 400 Bad Request
    else Validation passes
        SA->>OS: BulkRequest (UpdateRequest per finding)
        OS->>FI: Update doc (merge wazuh.case)
        FI-->>OS: Update result
        OS-->>SA: BulkResponse
        alt All succeeded
            SA-->>UI: 200 OK { took, errors: false, items }
        else Partial failure
            SA-->>UI: 207 Multi-Status { took, errors: true, items }
        end
    end

Wazuh Indexer Common Utils — development guide

wazuh-indexer-common-utils is a Wazuh fork of the OpenSearch Common Utils library. It is not a standalone plugin — it ships as a shared JAR dependency consumed by the Wazuh forks of Alerting, Notifications, and Security Analytics, and by the Content Manager plugin.

What it provides

The library defines cross-plugin models and transport-action contracts so that plugins can call each other’s functionality without a direct compile-time dependency on each other’s internals:

• org.opensearch.commons.alerting — shared alerting models and AlertingPluginInterface, the transport bridge other plugins use to call into Alerting (e.g., Security Analytics fetches findings via AlertingPluginInterface.INSTANCE.getFindings()).
• org.opensearch.commons.notifications — shared notification channel/config models and NotificationsPluginInterface, used to send notifications from other plugins without depending on the Notifications plugin directly.
• org.opensearch.commons.notifications.model.ActiveResponse — the Active Response channel definition; the Wazuh-specific extension that lets a Notifications channel drive Active Response execution requests.
• org.opensearch.commons.replication — shared cross-cluster replication models and ReplicationPluginInterface.
• org.opensearch.commons.authuser — shared user/role context passed across plugin boundaries for RBAC enforcement.
• org.opensearch.commons.destination — shared destination message/response models used by notification transports.

Relationship to the Security Analytics commons/ submodule

Don’t confuse this repository with the commons/ submodule inside wazuh-indexer-security-analytics (wazuh-indexer-security-analytics/commons/src/main/java/com/wazuh/securityanalytics/action/). That submodule defines the W*Action classes (WIndexIntegrationAction, WIndexRuleAction, WIndexDetectorAction, etc.) used specifically for Content Manager → Security Analytics communication — it’s a separate, narrower set of shared classes scoped to that one integration, not part of this library.

Working with this library

Changes here affect every plugin that depends on it. When modifying a shared model or interface:

1. Check all consumers (wazuh-indexer-alerting, wazuh-indexer-notifications, wazuh-indexer-security-analytics, and wazuh-indexer-plugins’ Content Manager) for usages before changing a method signature or model field.
2. Bump the version and republish before consumers can pick up the change — this is a versioned dependency, not a monorepo shared source set.
3. See RELEASING.md and CHANGELOG.md in the repository root for the release process.

Claude Code skills

Wazuh Indexer development is assisted by Claude Code skills: packaged, versioned instructions that live under .claude/skills/<name>/ in this repository. A skill captures a process or a body of domain knowledge that’s too detailed to keep in a contributor’s head, too easily forgotten between sessions, or too specific to belong in the top-level CLAUDE.md.

Structure

Each skill is a directory containing:

• SKILL.md — required. Frontmatter with a name and a description (used to match the skill to a task automatically), followed by the actual instructions.
• Related artifacts — optional supporting files referenced from SKILL.md, such as a style guide or a settings catalog, kept alongside the skill so they version together with it.

A skill is invoked automatically when a task matches its description, or explicitly by name (for example, /docs-review).

Available skills

• Documentation review — audits the mdBook documentation tree for coverage gaps, staleness against source, and style violations.
• Performance tuning — reduces or validates Wazuh Indexer’s memory, CPU, and GC footprint via settings and index/shard topology changes.

When you add a new skill under .claude/skills/, add a corresponding page here so it stays discoverable outside of Claude Code itself.

Documentation review

The docs-review skill audits docs/ — the mdBook site covering the Development Guide and Reference Manual — for coverage gaps, staleness against source code, structural and navigation issues, and style inconsistency.

The skill produces a findings report; it does not rewrite prose itself. Rewriting is a separate, later phase driven by the style guide below.

Process

The audit runs in five passes, each building on the last:

1. Inventory the doc tree against SUMMARY.md — orphaned files, broken links, stub pages.
2. Cross-check coverage against source — plugins, REST endpoints, settings, and documented mechanisms or call chains, not just names that still technically exist.
3. Review structure and navigation — heading hierarchy, table-of-contents depth, cross-linking, and whether content sits in the right track.
4. Audit style and consistency against the style guide below, including a set of known bug patterns (bolded pseudo-headings, stale numeric claims baked into prose or diagrams, incomplete diagram branches) that have recurred since the last pass.
5. Write the findings report.

Related artifacts

• SKILL.md — the full instructions, including the known bug patterns to grep for and what’s already fixed versus intentionally deferred (for example, ref/glossary.md is a known-empty stub).
• STYLE_GUIDE.md — the actual rules produced from a prior audit (heading case, terminology, table-vs-list, register per track, and more). This is the checklist the style pass runs against.

Usage

Invoke with /docs-review when asked to review, audit, or assess the Wazuh Indexer documentation. A full audit and module-by-module rewrite has already been done once; re-running the skill is a regression/drift check against an already-conforming corpus, not a first pass.

Performance tuning

The perf-tuning skill reduces or validates Wazuh Indexer 5.0’s memory, CPU, and GC footprint by tuning existing OpenSearch and plugin settings, or by changing index/shard topology. It covers content-manager, security-analytics, alerting, and setup settings, plus OpenSearch core settings such as thread pools, circuit breakers, and indexing buffers.

Mental model

The skill separates every memory-relevant setting into one of three mechanisms: blast radius (peak memory held during a fan-out), retained state (steady-state resident bytes independent of any single burst), and structural shard count (Lucene index/shard objects resident regardless of load). Attributing an observed effect to the wrong mechanism is the most common way to draw a wrong conclusion from a load test.

Known traps

The skill documents confirmed dead ends and counterintuitive findings from prior investigation rounds — for example, a shard-consolidation attempt that increased memory rather than reducing it, because Security Analytics scopes detectors purely by which index they read, and why zeroing the correlation cache TTLs can trade heap for CPU/search-thread-pool load on a small VM instead of saving memory. See SKILL.md for the full list — re-deriving these costs real load-test time.

Related artifacts

• SKILL.md — methodology, known traps, and the Docker-versus-VM division of labor for running a test.
• SETTINGS_CATALOG.md — every candidate setting across content-manager, security-analytics, alerting, and setup, cross-checked against the actual registered Setting<?> objects in source, with confirmed defaults, ranges, dynamic/static status, and recommended test values.

Usage

Invoke when asked to investigate, reduce, or test Wazuh Indexer memory usage, heap pressure, circuit breaker trips, or shard/index count, or to tune throughput-versus-memory tradeoffs. The skill relies on an internal load-test harness and VM that aren’t part of this repository — see SKILL.md’s “Related artifacts” section for access.

Reference manual

This section contains the Wazuh Indexer reference manual, composed by installation, upgrade, removal, restore and configuration instructions, performance and security recommendations, architecture and API references for each of the modules composing the Wazuh Indexer.

About the examples

API examples authenticate as admin with $WAZUH_INDEXER_ADMIN_PASSWORD. That password is generated during installation and is unique to each deployment, so load it into your shell before running them:

WAZUH_INDEXER_ADMIN_PASSWORD=$(sudo grep '^WAZUH_INDEXER_ADMIN_PASSWORD=' /etc/wazuh-indexer/export/credentials.env | cut -d= -f2- | tail -n 1)

See Retrieving the generated credentials.

Description

The Wazuh Indexer is a highly scalable, full-text search and analytics engine built on top of OpenSearch 3. In Wazuh 5.0 it becomes the core component of the Wazuh platform: in addition to indexing and storing security data, it now embeds the Wazuh Engine and hosts the threat detection, alerting, notification, reporting, and content management logic that previously ran on the Wazuh Manager.

The Wazuh Indexer can be deployed as a single-node instance for development and small environments, or as a multi-node cluster for production workloads requiring high availability and horizontal scalability.

What’s new in 5.0

Wazuh 5.0 consolidates most of the platform’s data plane and detection logic inside the Indexer:

• The Wazuh Engine is bundled into the Wazuh Indexer packages and Docker images (x86_64 and aarch64). Plugins communicate with the Engine over a local Unix socket.
• Threat detection has been migrated from the Wazuh Manager to the Indexer through the Ruleset Management plugin (a Wazuh fork of the OpenSearch Security Analytics plugin), with extended Sigma rules syntax and per-space rules, log types and detectors.
• Active Response has been migrated to the Indexer, driven by a dedicated Alerting monitor and persisted in the wazuh-active-responses data stream.
• Filebeat is no longer used to forward events between the Wazuh Manager and the Indexer. Events now reach the Indexer through a built-in indexer connector.
• Time-series data (events, findings, metrics, raw events, active responses) is stored in data streams with ISM policies for automatic rollover and retention.
• A new Content Manager plugin owns the lifecycle of detection content (ruleset, vulnerabilities feed, IoC feed) and exposes a REST API for user-defined content with a draft → test → custom promotion workflow.
• Case Management is introduced as a first-class feature — analysts can create cases directly from findings, attach evidence, assign ownership, track status through a configurable workflow, and generate reports, without leaving the platform.
• The Wazuh Common Schema (WCS) has been reworked and now lives in the wazuh-indexer-plugins repository, bumped to ECS 9.1.0, with per-category event and finding data streams.

See the release notes for the full list of changes and breaking changes.

Core concepts

The Wazuh Indexer stores data as JSON documents. Each document contains a set of fields (keys) mapped to values — strings, numbers, booleans, dates, arrays, nested objects, and more.

An index is a collection of related documents. For time-series data such as events, findings, metrics and active responses, the Wazuh Indexer uses data streams backed by rolling indices, managed by Index State Management (ISM) policies that handle rollover and retention based on age and size.

Documents are distributed across shards spread across cluster nodes. This distribution provides redundancy against hardware failures and allows query throughput to scale as nodes are added.

Detection content (rules, decoders, integrations, KVDBs, filters, policies, IoCs and the vulnerabilities feed) is organized into spaces:

• standard — read-only content sourced from the Wazuh CTI API.
• draft — user-editable workspace for new or modified resources.
• test — staging space used to validate draft content against the Wazuh Engine.
• custom — promoted user-defined content active in the Engine.

The Content Manager enforces the draft → test → custom promotion workflow and keeps the Engine synchronized with the active content.

Bundled plugins

The Wazuh Indexer ships with a curated set of plugins. Some are Wazuh-developed; others are Wazuh forks of upstream OpenSearch plugins tailored for the platform.

Setup plugin

The Setup plugin initializes the indexer environment on cluster startup. It creates all required index templates, ISM policies, data streams, and internal state indices, ensuring the correct schema and lifecycle rules are in place before any data is ingested. It also defines the Wazuh Common Schema — the standardized field mappings used across all Wazuh indices — and exposes a Settings API used to manage Wazuh-level settings that now reside in the Indexer (including Engine settings).

Content Manager plugin

The Content Manager keeps the Wazuh detection content up to date. It synchronizes the ruleset, vulnerabilities feed, and IoC feed from the Wazuh CTI API, and provides a REST API for user-defined threat intelligence resources — rules, decoders, integrations, KVDBs, filters and policies — supporting drafting, testing, promotion, manual or scheduled updates, subscription management and version checks.

A daily ping to the Wazuh CTI API surfaces content updates and deployment telemetry. The plugin communicates with the bundled Wazuh Engine through a Unix socket to validate user content and execute the logtest feature, which is split into a normalization phase (decoders) and a detection phase (rules).

A snapshot of the ruleset, vulnerabilities feed and IoC feed is bundled with the Wazuh Indexer packages, so a freshly installed cluster has content available offline.

See Content Manager for details.

Ruleset Management plugin

A Wazuh fork of the OpenSearch Security Analytics plugin. It is the home of threat detection in 5.0:

• Per-space log types, rules and threat detectors.
• Extended Sigma rules syntax, including case-insensitive operators, the exists modifier, IPv6 support and dynamic event field referencing in findings.
• Enriched findings written to wazuh-findings-v5-{category} data streams, embedding the full triggering event source and rule metadata (id, title, tags, level, status, MITRE, compliance).

Alerting plugin

A Wazuh fork of the OpenSearch Alerting plugin. It provides real-time alerting based on predefined monitors. Monitors are the core component used by the Ruleset Management plugin for threat detection, and a dedicated monitor drives Active Response.

Notifications plugin

A Wazuh fork of the OpenSearch Notifications plugin. It supports multiple delivery channels — Slack, Microsoft Teams, Amazon Chime, Email (SMTP/SES), AWS SNS, and custom webhooks — and ships default webhooks for Slack, Jira, PagerDuty and Shuffle. It also provides a dedicated channel type that powers Active Response, batching execution requests through a bulk processor.

Reporting plugin

A Wazuh fork of the OpenSearch Reporting plugin, bundled by default in Wazuh Indexer packages. It generates PDF and CSV reports from dashboards and saved searches, on demand or on a schedule, with optional email delivery.

Common Utils library

A Wazuh fork of the OpenSearch Common Utils library. It provides the shared models and transport actions used across the Wazuh forks of Alerting, Notifications, Ruleset Management and the Content Manager — including the Active Response channel definition.

Security plugin

The Security plugin provides role-based access control (RBAC), user authentication, and TLS encryption for both the REST API and inter-node transport layers. Wazuh 5.0 ships with a new set of reserved users and roles aligned with the new plugins (Content Manager, Alerting, Notifications, Reporting, Ruleset Management). See Access Control for details.

Bundled Wazuh Engine

The Wazuh Engine is shipped inside the Wazuh Indexer packages and Docker images. It is responsible for:

• Decoding and normalizing events before they are indexed (only in Wazuh Manager).
• Validating user-defined threat intel content submitted through the Content Manager.
• Enrichment: IoC content management, GeoIP enrichment, and engine filters for event pre-processing.
• Executing logtest requests issued by the Content Manager.

The Engine listens on a local Unix socket with restricted permissions (750) and is reachable only by the Indexer plugins running on the same node.

Data storage

The Wazuh Indexer organizes data into purpose-specific indices and data streams. Time-series streams are categorized per event type (access management, applications, cloud services, network activity, security, system activity, other).

Agent and rule metadata is now relocated under the wazuh.* namespace, and inventory coverage has been extended to Linux systemd units and macOS launchd daemons/agents alongside Windows services. For a complete list of indices and their schemas, see the Setup Plugin documentation.

Integration with the Wazuh platform

In 5.0 the Wazuh Indexer is the central processing and storage tier of the platform:

• Wazuh Agents collect endpoint data and send it to the Wazuh Manager.
• Wazuh Manager acts as the ingestion gateway. It no longer runs analysis, threat detection, content management or active response — these have moved into the Indexer. Events are normalized and forwarded to the Indexer through the built-in indexer connector (Filebeat is no longer required).
• Wazuh Indexer, through the bundled Wazuh Engine and its plugins, analyzes events, runs threat detection, manages detection content, dispatches notifications and active responses, and stores all resulting data.
• Wazuh Dashboard (an OpenSearch Dashboards fork) provides the web UI for searching, visualizing and managing Wazuh data, and interacts with the Setup, Content Manager, Ruleset Management, Alerting, Notifications and Reporting plugin APIs.

The Indexer exposes a standard REST API compatible with the OpenSearch API, so existing OpenSearch tools, clients and integrations work with the Wazuh Indexer out of the box.

Architecture

The Wazuh Indexer is built on top of OpenSearch and extends it with a set of purpose-built plugins that provide security event indexing, content management, access control, and reporting capabilities.

Component overview

┌─────────────────────────────────────────────────────────────────────┐
│                        Wazuh Indexer                                │
│                                                                     │
│  ┌──────────────┐  ┌──────────────────┐  ┌──────────┐  ┌─────────┐  │
│  │ Setup Plugin │  │ Content Manager  │  │ Security │  │Reporting│  │
│  │              │  │     Plugin       │  │  Plugin  │  │ Plugin  │  │
│  └──────┬───────┘  └────────┬─────────┘  └────┬─────┘  └───┬─────┘  │
│         │                   │                 │            │        │
│  ┌──────┴────────┐   ┌──────┴───────────┐  ┌──┴───────┐    │        │
│  │Index Templates│   │  CTI API Client  │  │  RBAC &  │    │        │
│  │ISM Policies   │   │  Engine Client   │  │  Access  │    │        │
│  │Stream Indices │   │  Job Scheduler   │  │  Control │    │        │
│  │State Indices  │   │  Space Service   │  └──────────┘    │        │
│  └───────────────┘   └───────┬──────────┘                  │        │
│                              │                             │        │
│                    ┌─────────┴───────────────────────┐     │        │
│                    │  System Indices                 │     │        │
│                    │  .wazuh-cti-consumers           │     │        │
│                    │  wazuh-threatintel-rules        │     │        │
│                    │  wazuh-threatintel-decoders     │     │        │
│                    │  wazuh-threatintel-integrations │     │        │
│                    │  wazuh-threatintel-kvdbs        │     │        │
│                    │  wazuh-threatintel-policies     │     │        │
│                    │  wazuh-threatintel-enrichments  │     │        │
│                    └─────────────────────────────────┘     │        │
└─────────────────────────────────┬──────────────────────────┼────────┘
                                  │ Unix Socket              │
                          ┌───────┴────────┐          ┌──────┴───────┐
                          │  Wazuh Engine  │          │  Wazuh       │
                          │  (Analysis &   │          │  Dashboard   │
                          │   Detection)   │          │  (UI)        │
                          └────────────────┘          └──────────────┘

Plugins

Setup plugin

The Setup plugin initializes the Wazuh Indexer environment when the cluster starts. It is responsible for:

• Index templates: Defines the mappings and settings for all Wazuh indices (alerts, events, statistics, vulnerabilities, etc.).
• ISM (Index State Management) policies: Configures lifecycle policies for automatic rollover, deletion, and retention of time-series indices.
• Data streams: Creates the initial data stream indices that receive incoming event data.
• State indices: Sets up internal indices used by other Wazuh components to track operational state.

The Setup plugin runs once during cluster initialization and ensures the required infrastructure is in place before other plugins begin operating.

Content Manager plugin

The Content Manager is the most feature-rich plugin. It handles:

• CTI synchronization: Periodically fetches threat intelligence content (rules, decoders, integrations, KVDBs, IoCs) from the Wazuh CTI API. On first run, it downloads a full snapshot; subsequent runs apply incremental patches.
• User-generated content: Provides a REST API for creating, updating, and deleting custom decoders, rules, integrations, and KVDBs in a draft space.
• Promotion workflow: Changes made in the draft space can be previewed and promoted to the Wazuh Engine for activation.
• Engine communication: Communicates with the Wazuh Engine via a Unix socket for logtest execution, content validation, and configuration reload.
• Policy management: Manages the Engine routing policy that controls how events are processed.

See Content Manager for full details.

Security plugin

The Security plugin extends OpenSearch’s security capabilities for Wazuh-specific needs:

• Role-based access control (RBAC): Defines predefined roles and permissions for Wazuh operations.
• User management: Provides APIs and configuration for managing users and their access levels.
• TLS/SSL: Handles transport and REST layer encryption.

Reporting plugin

The Reporting plugin enables on-demand and scheduled report generation from the Wazuh Dashboard, producing PDF or CSV exports of dashboards and saved searches.

Data flow

1. Wazuh Agents collect security events from monitored endpoints and forward them to the Wazuh Manager.
2. The Wazuh Engine on the server analyzes events using rules and decoders, then forwards alerts and events to the Wazuh Indexer via the Indexer API.
3. The Setup plugin ensures the correct index templates, data streams, and lifecycle policies exist.
4. The Content Manager plugin keeps the Engine’s detection content up to date by synchronizing with the CTI API and managing user customizations.
5. The Wazuh Dashboard queries the Indexer to visualize alerts, events, and security analytics.

Compatibility

Supported operating systems

We aim to support as many operating systems as OpenSearch does. Wazuh indexer should work on many Linux distributions, but we only test a handful. The following table lists the operating system versions that we currently support.

For 5.0.0 and above, we support the operating system versions and architectures included in the table below.

OpenSearch

Currently, Wazuh indexer is using version 3.6.0 of OpenSearch.

Getting started

Requirements

Supported operating systems

The Wazuh indexer runs on 64-bit Linux, on x86_64 (AMD64) or aarch64 (ARM64) processors. See Compatibility for the supported distributions and versions.

Hardware recommendations

The Wazuh indexer can be installed as a single-node or as a multi-node cluster.

Hardware recommendations for each node

Disk space requirements

The amount of data depends on the generated events per second (EPS). This table details the estimated disk space needed per agent to store 90 days of events on a Wazuh indexer server, depending on the type of monitored endpoints.

For example, for an environment with 80 workstations, 10 servers, and 10 network devices, the storage needed on the Wazuh indexer server for 90 days of events is 231 GB.

Network ports

Allow the following inbound traffic on every Wazuh indexer node:

• 9200/TCP — REST API, over HTTPS. Must be reachable from the Wazuh Manager and Wazuh Dashboard nodes, and from any client that uses the API.
• 9300/TCP — transport, the communication between the nodes of a cluster, over TLS. Must be reachable from every other Wazuh indexer node. A single-node deployment does not need to expose it.

These are the default ports; http.port and transport.port in /etc/wazuh-indexer/opensearch.yml change them.

The Content Manager plugin also connects out to the Wazuh Cyber Threat Intelligence (CTI) API over HTTPS (443/TCP) to synchronize content, check for updates and send telemetry. An installation without internet access can disable those tasks instead; see Offline configuration.

Installation

Note: This documentation assumes you are already provisioned with a wazuh-indexer package through any of the possible methods:

• Local package generation (recommended).
• GH Workflows artifacts.
• Staging S3 buckets

Installing the Wazuh indexer step by step

Install and configure the Wazuh indexer as a single-node or multi-node cluster, following step-by-step instructions. To move an existing 4.x deployment to 5.x, see Migration guide. The installation process is divided into three stages.

1. Certificates creation

2. Nodes installation

3. Cluster initialization

Note: You need root user privileges to run all the commands described below.

1. Certificates

The Wazuh indexer issues its own certificates when the package is installed, signed by a certificate authority it creates in /etc/wazuh-indexer/ca/. A single-node deployment needs nothing from this stage — skip to Nodes installation.

Every node of a cluster must trust the same authority, and the authority each package creates is local to its own host. For a multi-node cluster, either stage one authority on every node before installing the package, or generate one set of certificates for the whole cluster and distribute it, as described below.

To stage the authority, install the package on the first node, then copy its /etc/wazuh-indexer/ca/root-ca.pem and /etc/wazuh-indexer/ca/root-ca.key into /etc/wazuh-indexer/ca/ on each other node before installing the package there: the directory owned by root:root with mode 750, the certificate 640 and the key 400. Each package then issues its own certificates from that authority, and the first node’s /etc/wazuh-indexer/export/credentials.env holds the passwords of the whole cluster once the security configuration is loaded. Add every node’s Distinguished Name to plugins.security.nodes_dn on every node, as described in Configuring the Wazuh indexer.

The same applies if you bring certificates from your own PKI: before installing the package, stage each node’s pair, the admin pair and the CA that issued them, as described in On every other Wazuh indexer node. The installation then uses them and creates no authority of its own. To have it also issue the client pairs of the Wazuh manager and the Wazuh dashboard from that CA, stage the CA’s key as well, as /etc/wazuh-indexer/ca/root-ca.key with mode 400.

Generating the SSL certificates

The certificates tool ships with the Wazuh indexer package, so install the package on one node first and generate the cluster’s certificates from there. Installing does not start the service, so nothing runs before you are ready.

1. Install the Wazuh indexer package on one node, following Nodes installation, and stop after the package is installed.

2. Edit /usr/share/wazuh-indexer/tools/config.yml and replace the node names and IP values with the corresponding names and IP addresses. You need to do this for all Wazuh Manager, Wazuh indexer, and Wazuh dashboard nodes. Add as many node fields as needed.

   nodes:
     # Wazuh indexer nodes
     indexer:
       - name: node-1
         ip: "<indexer-node-ip>"
       #- name: node-2
       #  ip: "<indexer-node-ip>"
       #- name: node-3
       #  ip: "<indexer-node-ip>"
   
     # Wazuh manager nodes
     # If there is more than one Wazuh manager
     # node, each one must have a node_type
     manager:
       - name: wazuh-1
         ip: "<wazuh-manager-ip>"
       #  node_type: master
       #- name: wazuh-2
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
       #- name: wazuh-3
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
   
     # Wazuh dashboard nodes
     dashboard:
       - name: dashboard
         ip: "<dashboard-node-ip>"
   

   To learn more about how to create and configure the certificates, see the Certificates deployment section.

3. Run the tool to create the certificates, signed by the authority this node already has in /etc/wazuh-indexer/ca/. It reads config.yml from beside itself and writes the result to wazuh-certificates/ in the same directory.

   WAZUH_CA_DIR=/etc/wazuh-indexer/ca /usr/share/wazuh-indexer/tools/wazuh-certs-tool.sh -A
   

   Without WAZUH_CA_DIR, the tool creates an authority of its own in /usr/share/wazuh-indexer/tools/wazuh-ca/ and signs with that one instead. This node published the authority it was installed with as /etc/wazuh-indexer/export/ca.pem and does not publish it again, so the Wazuh manager and the Wazuh dashboard on this host could no longer verify the Wazuh indexer.

4. Compress all the necessary files.

   cd /usr/share/wazuh-indexer/tools/
   tar -cvf /tmp/wazuh-certificates.tar -C ./wazuh-certificates/ .
   rm -rf ./wazuh-certificates
   

5. Copy the wazuh-certificates.tar file to all the nodes, including the Wazuh indexer, Wazuh Manager, and Wazuh dashboard nodes. This can be done by using the scp utility.

   On the node that generated them, replace the certificates the package issued with this node’s pair. On every other Wazuh indexer node, stage that node’s pair before installing the package. See Deploying certificates.

2. Nodes installation

Installing package dependencies

Install the following packages if missing:

yum

yum install iproute openssl shadow-utils

apt

apt-get install iproute2 openssl passwd

Supplying your own passwords

The installation generates a password for each internal user, but only for the users it does not already find a password for. To choose them yourself, write them to /etc/wazuh-indexer/local.env before installing the package.

That file is yours: the package reads it and never writes it. It holds passwords, so it must be owned by root with mode 600, and the installation refuses to read it otherwise:

install -d -m 0750 -o root -g root /etc/wazuh-indexer
cat > /etc/wazuh-indexer/local.env <<'EOF'
WAZUH_INDEXER_ADMIN_PASSWORD=<admin-password>
WAZUH_INDEXER_KIBANASERVER_PASSWORD=<kibanaserver-password>
WAZUH_INDEXER_MANAGER_PASSWORD=<wazuh-manager-password>
EOF
chmod 600 /etc/wazuh-indexer/local.env

Set as many or as few as you like: any key you leave out is generated. Each password must have 12 to 64 characters from A-Z a-z 0-9 . , _ + : @ % ^ = ~ -, with at least one uppercase letter, one lowercase letter, one digit and one symbol. A value that does not meet the rule is never replaced silently — the service refuses to start and names the key in its log.

The same file takes WAZUH_INDEXER_CERT_SANS, a comma-separated list of the names and addresses to put on the node’s certificate (for example DNS:node-1.example.com,IP:10.0.0.1) instead of the ones the installation discovers; localhost and the loopback addresses are always added.

Installing the Wazuh indexer package

If this node uses certificates generated in advance and is not the node that generated them, stage them first, as described in On every other Wazuh indexer node.

Replace the file name with that of the package you downloaded. <ARCH> is x86_64 or aarch64 for RPM packages, and amd64 or arm64 for DEB packages. See Packages.

rpm

rpm -ivh --replacepkgs wazuh-indexer-<VERSION>-<REVISION>.<ARCH>.rpm

dpkg

dpkg -i wazuh-indexer_<VERSION>-<REVISION>_<ARCH>.deb

Retrieving the generated credentials

The installation publishes one password per internal user in /etc/wazuh-indexer/export/credentials.env, readable only by root — the ones it generated, and the ones it was given:

cat /etc/wazuh-indexer/export/credentials.env

# Published by wazuh-indexer for the manager and the dashboard on this host. Do not edit.
WAZUH_INDEXER_ADMIN_PASSWORD=...
WAZUH_INDEXER_KIBANASERVER_PASSWORD=...
WAZUH_INDEXER_MANAGER_PASSWORD=...

Values are written as they are, without quotes — see About the examples. admin is the login for the Wazuh dashboard and the Wazuh indexer API; kibanaserver and wazuh-manager are the accounts the Wazuh dashboard and the Wazuh manager connect with. The directory also holds ca.pem, the certificate of the authority this node’s certificates are issued from, and the client certificate pairs that authority issued for the Wazuh manager (manager-client.pem, manager-client-key.pem) and the Wazuh dashboard (dashboard-client.pem, dashboard-client-key.pem), readable only by root. A client pair identifies the component to the Wazuh indexer; it grants no permission by itself, and each component keeps authenticating with its password.

The Wazuh Manager and the Wazuh Dashboard installed on the same host read export/ when they are installed and at every start, so keep it. On another host, copy the values they need into their own local.env and certs/ before installing them: WAZUH_INDEXER_MANAGER_PASSWORD, ca.pem and the manager client pair for the manager, WAZUH_INDEXER_KIBANASERVER_PASSWORD and ca.pem for the dashboard. The client pair of any Wazuh indexer node of the cluster serves: it names no host.

Passwords are generated once. Reinstalling, restarting or upgrading the Wazuh indexer does not change them. To change one afterwards, use the passwords tool, which also ships with the package. It prompts for the new password twice and echoes nothing, so the password does not reach your shell history:

/usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh -u admin -p

A new password must meet the same rule as a supplied one — see Supplying your own passwords.

When the standard input is not a terminal the tool reads the password from it instead of prompting, which is how a script sets one:

printf '%s' '<new-password>' | /usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh -u admin -p

-p takes no value: the tool prompts for the new password, or reads it from standard input when that is not a terminal, for example printf '%s\n' '<new-password>' | /usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh -u admin -p. Without -p, the tool generates a random password. Either way the new password is published in /etc/wazuh-indexer/export/credentials.env.

Configuring the Wazuh indexer

Edit the /etc/wazuh-indexer/opensearch.yml configuration file and replace the values in steps (a) to (e). Then set the JVM heap size in /etc/wazuh-indexer/jvm.options, as described in step (f).

The package ships a working single-node configuration: one node named node-1, listening on all interfaces (0.0.0.0). On a single node, steps (a) to (e) are optional: apply (a) to listen on a specific address, and (b) together with (c) to rename the node. Step (f) applies to every node, including a single node, because the package starts with a 1 GB heap. A multi-node cluster needs all six steps, on every node.

a. network.host: Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and use it as its publish address. Accepts an IP address or a hostname. On a multi-node cluster, use the same node address set in config.yml to create the SSL certificates.

b. node.name: Name of the Wazuh indexer node as defined in the config.yml file. For example, node-1. If you change it on a single node, change cluster.initial_cluster_manager_nodes to match.

c. cluster.initial_cluster_manager_nodes: List of the names of the master-eligible nodes. These names are defined in the config.yml file. A single node lists only its own node.name. For a multi-node cluster, uncomment the node-2 and node-3 lines, change the names, or add more lines, according to your config.yml definitions.

cluster.initial_cluster_manager_nodes:
- "node-1"
- "node-2"
- "node-3"

d. discovery.seed_hosts: List of the addresses of the master-eligible nodes. Each element can be either an IP address or a hostname. You may leave this setting commented if you are configuring the Wazuh indexer as a single node. For multi-node configurations, uncomment this setting and set the IP addresses of each master-eligible node.

discovery.seed_hosts:
- "10.0.0.1"
- "10.0.0.2"
- "10.0.0.3"

e. plugins.security.nodes_dn: List of the Distinguished Names of the certificates of all the Wazuh indexer cluster nodes. The installation writes the Distinguished Name of the certificate the package issued for this node, so a single node needs no change. For a multi-node cluster, list one line per node with the subjects of the certificates you deploy in Deploying certificates. The certificates tool issues them with the node name from config.yml as CN, and the Security plugin compares each entry as a string, so keep this order:

plugins.security.nodes_dn:
- "C=US,L=California,O=Wazuh,OU=Wazuh,CN=node-1"
- "C=US,L=California,O=Wazuh,OU=Wazuh,CN=node-2"
- "C=US,L=California,O=Wazuh,OU=Wazuh,CN=node-3"

f. JVM heap size: Set it in /etc/wazuh-indexer/jvm.options, before the first start. The package sets it to 1 GB. Use half of the system RAM when the Wazuh indexer is alone on the host, or a quarter when the Wazuh manager or the Wazuh dashboard runs on the same host. Set the initial (-Xms) and maximum (-Xmx) heap size to the same value. For example, on a dedicated node with 8 GB of RAM:

-Xms4g
-Xmx4g

For a size that is not a whole number of gigabytes, use megabytes, for example -Xms1536m and -Xmx1536m. See JVM heap size for the sizing limits, and Memory locking for the memory the node needs beyond the heap.

Deploying certificates

Note: This step applies only if you generated the certificates in advance, as described in Certificates. A single-node deployment already has the certificates the package issued.

Make sure that a copy of the wazuh-certificates.tar file, created during the initial configuration step, is placed in your working directory.

The installation takes in certificates only when the package is installed: certificates replaced afterwards are used, but their authority is not published to the Wazuh manager and the Wazuh dashboard on the host. Run with WAZUH_CA_DIR, as in Generating the SSL certificates, the certificates tool signs with the authority in /etc/wazuh-indexer/ca/, so that node can replace its pair afterwards, while every other node must have its pair and that authority staged before the package is installed.

In the commands below, replace <INDEXER_NODE_NAME> with the name of the Wazuh indexer node you are configuring as defined in config.yml. For example, node-1.

NODE_NAME=<INDEXER_NODE_NAME>

On the node that generated the certificates

The package is already installed here. Replace the pair it issued:

mkdir -p /etc/wazuh-indexer/certs
tar -xf ./wazuh-certificates.tar -C /etc/wazuh-indexer/certs/ ./$NODE_NAME.pem ./$NODE_NAME-key.pem ./admin.pem ./admin-key.pem ./root-ca.pem
mv -f /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv -f /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
chown -R root:wazuh-indexer /etc/wazuh-indexer/certs
chmod 750 /etc/wazuh-indexer/certs
chmod 640 /etc/wazuh-indexer/certs/*
chown root:root /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem
chmod 600 /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem

mv -f is required: the package already issued indexer.pem and indexer-key.pem, and the cluster’s pair must replace them. The files belong to root: the Wazuh indexer reads its own pair and the trust anchor through its group, and the admin pair is used by indexer-security-init.sh alone, which runs as root. A pair owned by the wazuh-indexer user is refused when the service starts.

The certificates tool and the package issue certificates with the same subject format, so the plugins.security.authcz.admin_dn the installation wrote into /etc/wazuh-indexer/opensearch.yml stays valid. The node Distinguished Name it wrote stays valid only if the host’s short name matches the node name in config.yml, because the package uses the hostname as CN and the certificates tool uses the node name.

On every other Wazuh indexer node

Run these commands before installing the package, replacing <INDEXER_NODE_NAME> with the name of this node as defined in config.yml. They stage this node’s pair, the admin pair and the authority that issued them, root-ca.pem, both beside the pair and in /etc/wazuh-indexer/ca/:

NODE_NAME=<INDEXER_NODE_NAME>
install -d -m 750 /etc/wazuh-indexer /etc/wazuh-indexer/certs /etc/wazuh-indexer/ca
tar -xf ./wazuh-certificates.tar -C /etc/wazuh-indexer/certs/ ./$NODE_NAME.pem ./$NODE_NAME-key.pem ./admin.pem ./admin-key.pem ./root-ca.pem
mv /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
cp /etc/wazuh-indexer/certs/root-ca.pem /etc/wazuh-indexer/ca/root-ca.pem
chmod 640 /etc/wazuh-indexer/certs/* /etc/wazuh-indexer/ca/root-ca.pem
chmod 600 /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem

The installation gives the node’s pair and the authority to the wazuh-indexer group, which does not exist before it, and writes the subjects of the pair and the admin pair into plugins.security.nodes_dn and plugins.security.authcz.admin_dn. It also checks that the authority issued the pair, and when it did not, the service does not start:

resolve-credentials: the certificate pair in /etc/wazuh-indexer/certs was not issued by /etc/wazuh-indexer/ca/root-ca.pem

The installation publishes the authority as /etc/wazuh-indexer/export/ca.pem for the Wazuh manager and the Wazuh dashboard on this host. Its key stays on the node that generated the certificates, so this node issues no client pairs for them: copy the client pairs from /etc/wazuh-indexer/export/ on that node, as described in Retrieving the generated credentials.

Distinguished Names

Make sure plugins.security.nodes_dn lists every node, as described in Configuring the Wazuh indexer: the installation writes only this node’s subject. To print the subject of a certificate in the form these settings expect, run:

openssl x509 -noout -subject -nameopt RFC2253 -in /etc/wazuh-indexer/certs/indexer.pem

indexer-security-init.sh warns when the admin certificate is not among the subjects in plugins.security.authcz.admin_dn.

Set up Wazuh Indexer in your environment

Follow the instructions in the Configuration section to set up Wazuh Indexer in your environment.

On offline installations, disable every task that requires an internet connection to prevent failures.

# opensearch.yml
plugins.content_manager.catalog.update_on_start: false
plugins.content_manager.catalog.update_on_schedule: false
plugins.content_manager.telemetry.enabled: false

plugins.content_manager.catalog.update_on_schedule and plugins.content_manager.telemetry.enabled are dynamic, so on a running deployment they can be applied without a restart:

curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X PUT "https://127.0.0.1:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "plugins.content_manager.catalog.update_on_schedule": false,
    "plugins.content_manager.telemetry.enabled": false
  }
}'

Disabling scheduled synchronization takes effect immediately and applies to an already-initialized node as well as a fresh one: the plugin updates the periodic job accordingly, and a run that is already scheduled is refused rather than reaching Wazuh CTI.

Disabling scheduled synchronization does not remove content that has already been downloaded. It only stops further updates from Wazuh CTI.

plugins.content_manager.catalog.update_on_start is not dynamic — it only governs the synchronization triggered as the plugin starts, so it takes effect on the next node start.

Starting the service

Enable and start the Wazuh indexer service. The installation does not start it, and it does not start at boot until it is enabled. The package reloads the service manager itself, so no systemctl daemon-reload is needed here.

Systemd

systemctl enable --now wazuh-indexer

SysV

Choose one option according to the operating system used.

a. RPM-based operating system:

chkconfig --add wazuh-indexer
service wazuh-indexer start

b. Debian-based operating system:

update-rc.d wazuh-indexer defaults 95 10
service wazuh-indexer start

Repeat this stage of the installation process for every Wazuh indexer node in your cluster. Then proceed with initializing your single-node or multi-node cluster in the next stage.

3. Cluster initialization

Run the Wazuh indexer indexer-security-init.sh script on any Wazuh indexer node to load the new certificates information and start the single-node or multi-node cluster.

/usr/share/wazuh-indexer/bin/indexer-security-init.sh

Note: You only have to initialize the cluster once, there is no need to run this command on every node.

Testing the cluster installation

1. Replace $WAZUH_INDEXER_IP_ADDRESS and run the following commands to confirm that the installation is successful. $WAZUH_INDEXER_ADMIN_PASSWORD is the admin password from /etc/wazuh-indexer/export/credentials.env. Load it with WAZUH_INDEXER_ADMIN_PASSWORD=$(sudo grep '^WAZUH_INDEXER_ADMIN_PASSWORD=' /etc/wazuh-indexer/export/credentials.env | cut -d= -f2- | tail -n 1).

   curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X GET "https://$WAZUH_INDEXER_IP_ADDRESS:9200"
   

   Output

   {
     "name" : "node-1",
     "cluster_name" : "wazuh-cluster",
     "cluster_uuid" : "lEzYZtwXTYaGiSAdbcqQmQ",
     "version" : {
       "distribution" : "opensearch",
       "number" : "3.6.0",
       "build_type" : "deb",
       "build_hash" : "1b0a897cd71105595b450b48b591581865f8b46b",
       "build_date" : "2026-10-01T01:45:08.798733103Z",
       "build_snapshot" : false,
       "lucene_version" : "10.4.0",
       "minimum_wire_compatibility_version" : "2.19.0",
       "minimum_index_compatibility_version" : "2.0.0"
     },
     "tagline" : "The OpenSearch Project: https://opensearch.org/"
   }
   

2. Replace $WAZUH_INDEXER_IP_ADDRESS and run the following command to check if the single-node or multi-node cluster is working correctly.

   curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X GET "https://$WAZUH_INDEXER_IP_ADDRESS:9200/_cat/nodes?v"
   

Requirements

Requirements

Supported operating systems

The Wazuh indexer runs on 64-bit Linux, on x86_64 (AMD64) or aarch64 (ARM64) processors. See Compatibility for the supported distributions and versions.

Hardware recommendations

The Wazuh indexer can be installed as a single-node or as a multi-node cluster.

Hardware recommendations for each node

Disk space requirements

The amount of data depends on the generated events per second (EPS). This table details the estimated disk space needed per agent to store 90 days of events on a Wazuh indexer server, depending on the type of monitored endpoints.

For example, for an environment with 80 workstations, 10 servers, and 10 network devices, the storage needed on the Wazuh indexer server for 90 days of events is 231 GB.

Network ports

Allow the following inbound traffic on every Wazuh indexer node:

• 9200/TCP — REST API, over HTTPS. Must be reachable from the Wazuh Manager and Wazuh Dashboard nodes, and from any client that uses the API.
• 9300/TCP — transport, the communication between the nodes of a cluster, over TLS. Must be reachable from every other Wazuh indexer node. A single-node deployment does not need to expose it.

These are the default ports; http.port and transport.port in /etc/wazuh-indexer/opensearch.yml change them.

The Content Manager plugin also connects out to the Wazuh Cyber Threat Intelligence (CTI) API over HTTPS (443/TCP) to synchronize content, check for updates and send telemetry. An installation without internet access can disable those tasks instead; see Offline configuration.

Packages

Packages

Wazuh Indexer packages can be downloaded from the internal S3 buckets through the following links. Note these links are placeholders, and that you need to replace the RELEASE_SERIES, the VERSION and the REVISION with the appropriate values.

wazuh_indexer_aarch64_rpm: "https://packages-staging.xdrsiem.wazuh.info/pre-release/<RELEASE_SERIES>/yum/wazuh-indexer-<VERSION>-<REVISION>.aarch64.rpm"
wazuh_indexer_amd64_deb: "https://packages-staging.xdrsiem.wazuh.info/pre-release/<RELEASE_SERIES>/apt/pool/main/w/wazuh-indexer/wazuh-indexer_<VERSION>-<REVISION>_amd64.deb"
wazuh_indexer_arm64_deb: "https://packages-staging.xdrsiem.wazuh.info/pre-release/<RELEASE_SERIES>/apt/pool/main/w/wazuh-indexer/wazuh-indexer_<VERSION>-<REVISION>_arm64.deb"
wazuh_indexer_x86_64_rpm: "https://packages-staging.xdrsiem.wazuh.info/pre-release/<RELEASE_SERIES>/yum/wazuh-indexer-<VERSION>-<REVISION>.x86_64.rpm"

Examples

wazuh_indexer_aarch64_rpm: "https://packages-staging.xdrsiem.wazuh.info/pre-release/5.x/yum/wazuh-indexer-5.0.0-alpha99.aarch64.rpm"
wazuh_indexer_amd64_deb: "https://packages-staging.xdrsiem.wazuh.info/pre-release/5.x/apt/pool/main/w/wazuh-indexer/wazuh-indexer_5.0.0-alpha99_amd64.deb"
wazuh_indexer_arm64_deb: "https://packages-staging.xdrsiem.wazuh.info/pre-release/5.x/apt/pool/main/w/wazuh-indexer/wazuh-indexer_5.0.0-alpha99_arm64.deb"
wazuh_indexer_x86_64_rpm: "https://packages-staging.xdrsiem.wazuh.info/pre-release/5.x/yum/wazuh-indexer-5.0.0-alpha99.x86_64.rpm"

Compatibility

Please refer to this section for information pertaining to compatibility.

Installation

Installation

Note: This documentation assumes you are already provisioned with a wazuh-indexer package through any of the possible methods:

• Local package generation (recommended).
• GH Workflows artifacts.
• Staging S3 buckets

Installing the Wazuh indexer step by step

Install and configure the Wazuh indexer as a single-node or multi-node cluster, following step-by-step instructions. To move an existing 4.x deployment to 5.x, see Migration guide. The installation process is divided into three stages.

1. Certificates creation

2. Nodes installation

3. Cluster initialization

Note: You need root user privileges to run all the commands described below.

1. Certificates

The Wazuh indexer issues its own certificates when the package is installed, signed by a certificate authority it creates in /etc/wazuh-indexer/ca/. A single-node deployment needs nothing from this stage — skip to Nodes installation.

Every node of a cluster must trust the same authority, and the authority each package creates is local to its own host. For a multi-node cluster, either stage one authority on every node before installing the package, or generate one set of certificates for the whole cluster and distribute it, as described below.

To stage the authority, install the package on the first node, then copy its /etc/wazuh-indexer/ca/root-ca.pem and /etc/wazuh-indexer/ca/root-ca.key into /etc/wazuh-indexer/ca/ on each other node before installing the package there: the directory owned by root:root with mode 750, the certificate 640 and the key 400. Each package then issues its own certificates from that authority, and the first node’s /etc/wazuh-indexer/export/credentials.env holds the passwords of the whole cluster once the security configuration is loaded. Add every node’s Distinguished Name to plugins.security.nodes_dn on every node, as described in Configuring the Wazuh indexer.

The same applies if you bring certificates from your own PKI: before installing the package, stage each node’s pair, the admin pair and the CA that issued them, as described in On every other Wazuh indexer node. The installation then uses them and creates no authority of its own. To have it also issue the client pairs of the Wazuh manager and the Wazuh dashboard from that CA, stage the CA’s key as well, as /etc/wazuh-indexer/ca/root-ca.key with mode 400.

Generating the SSL certificates

The certificates tool ships with the Wazuh indexer package, so install the package on one node first and generate the cluster’s certificates from there. Installing does not start the service, so nothing runs before you are ready.

1. Install the Wazuh indexer package on one node, following Nodes installation, and stop after the package is installed.

2. Edit /usr/share/wazuh-indexer/tools/config.yml and replace the node names and IP values with the corresponding names and IP addresses. You need to do this for all Wazuh Manager, Wazuh indexer, and Wazuh dashboard nodes. Add as many node fields as needed.

   nodes:
     # Wazuh indexer nodes
     indexer:
       - name: node-1
         ip: "<indexer-node-ip>"
       #- name: node-2
       #  ip: "<indexer-node-ip>"
       #- name: node-3
       #  ip: "<indexer-node-ip>"
   
     # Wazuh manager nodes
     # If there is more than one Wazuh manager
     # node, each one must have a node_type
     manager:
       - name: wazuh-1
         ip: "<wazuh-manager-ip>"
       #  node_type: master
       #- name: wazuh-2
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
       #- name: wazuh-3
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
   
     # Wazuh dashboard nodes
     dashboard:
       - name: dashboard
         ip: "<dashboard-node-ip>"
   

   To learn more about how to create and configure the certificates, see the Certificates deployment section.

3. Run the tool to create the certificates, signed by the authority this node already has in /etc/wazuh-indexer/ca/. It reads config.yml from beside itself and writes the result to wazuh-certificates/ in the same directory.

   WAZUH_CA_DIR=/etc/wazuh-indexer/ca /usr/share/wazuh-indexer/tools/wazuh-certs-tool.sh -A
   

   Without WAZUH_CA_DIR, the tool creates an authority of its own in /usr/share/wazuh-indexer/tools/wazuh-ca/ and signs with that one instead. This node published the authority it was installed with as /etc/wazuh-indexer/export/ca.pem and does not publish it again, so the Wazuh manager and the Wazuh dashboard on this host could no longer verify the Wazuh indexer.

4. Compress all the necessary files.

   cd /usr/share/wazuh-indexer/tools/
   tar -cvf /tmp/wazuh-certificates.tar -C ./wazuh-certificates/ .
   rm -rf ./wazuh-certificates
   

5. Copy the wazuh-certificates.tar file to all the nodes, including the Wazuh indexer, Wazuh Manager, and Wazuh dashboard nodes. This can be done by using the scp utility.

   On the node that generated them, replace the certificates the package issued with this node’s pair. On every other Wazuh indexer node, stage that node’s pair before installing the package. See Deploying certificates.

2. Nodes installation

Installing package dependencies

Install the following packages if missing:

yum

yum install iproute openssl shadow-utils

apt

apt-get install iproute2 openssl passwd

Supplying your own passwords

The installation generates a password for each internal user, but only for the users it does not already find a password for. To choose them yourself, write them to /etc/wazuh-indexer/local.env before installing the package.

That file is yours: the package reads it and never writes it. It holds passwords, so it must be owned by root with mode 600, and the installation refuses to read it otherwise:

install -d -m 0750 -o root -g root /etc/wazuh-indexer
cat > /etc/wazuh-indexer/local.env <<'EOF'
WAZUH_INDEXER_ADMIN_PASSWORD=<admin-password>
WAZUH_INDEXER_KIBANASERVER_PASSWORD=<kibanaserver-password>
WAZUH_INDEXER_MANAGER_PASSWORD=<wazuh-manager-password>
EOF
chmod 600 /etc/wazuh-indexer/local.env

Set as many or as few as you like: any key you leave out is generated. Each password must have 12 to 64 characters from A-Z a-z 0-9 . , _ + : @ % ^ = ~ -, with at least one uppercase letter, one lowercase letter, one digit and one symbol. A value that does not meet the rule is never replaced silently — the service refuses to start and names the key in its log.

The same file takes WAZUH_INDEXER_CERT_SANS, a comma-separated list of the names and addresses to put on the node’s certificate (for example DNS:node-1.example.com,IP:10.0.0.1) instead of the ones the installation discovers; localhost and the loopback addresses are always added.

Installing the Wazuh indexer package

If this node uses certificates generated in advance and is not the node that generated them, stage them first, as described in On every other Wazuh indexer node.

Replace the file name with that of the package you downloaded. <ARCH> is x86_64 or aarch64 for RPM packages, and amd64 or arm64 for DEB packages. See Packages.

rpm

rpm -ivh --replacepkgs wazuh-indexer-<VERSION>-<REVISION>.<ARCH>.rpm

dpkg

dpkg -i wazuh-indexer_<VERSION>-<REVISION>_<ARCH>.deb

Retrieving the generated credentials

The installation publishes one password per internal user in /etc/wazuh-indexer/export/credentials.env, readable only by root — the ones it generated, and the ones it was given:

cat /etc/wazuh-indexer/export/credentials.env

# Published by wazuh-indexer for the manager and the dashboard on this host. Do not edit.
WAZUH_INDEXER_ADMIN_PASSWORD=...
WAZUH_INDEXER_KIBANASERVER_PASSWORD=...
WAZUH_INDEXER_MANAGER_PASSWORD=...

Values are written as they are, without quotes — see About the examples. admin is the login for the Wazuh dashboard and the Wazuh indexer API; kibanaserver and wazuh-manager are the accounts the Wazuh dashboard and the Wazuh manager connect with. The directory also holds ca.pem, the certificate of the authority this node’s certificates are issued from, and the client certificate pairs that authority issued for the Wazuh manager (manager-client.pem, manager-client-key.pem) and the Wazuh dashboard (dashboard-client.pem, dashboard-client-key.pem), readable only by root. A client pair identifies the component to the Wazuh indexer; it grants no permission by itself, and each component keeps authenticating with its password.

The Wazuh Manager and the Wazuh Dashboard installed on the same host read export/ when they are installed and at every start, so keep it. On another host, copy the values they need into their own local.env and certs/ before installing them: WAZUH_INDEXER_MANAGER_PASSWORD, ca.pem and the manager client pair for the manager, WAZUH_INDEXER_KIBANASERVER_PASSWORD and ca.pem for the dashboard. The client pair of any Wazuh indexer node of the cluster serves: it names no host.

Passwords are generated once. Reinstalling, restarting or upgrading the Wazuh indexer does not change them. To change one afterwards, use the passwords tool, which also ships with the package. It prompts for the new password twice and echoes nothing, so the password does not reach your shell history:

/usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh -u admin -p

A new password must meet the same rule as a supplied one — see Supplying your own passwords.

When the standard input is not a terminal the tool reads the password from it instead of prompting, which is how a script sets one:

printf '%s' '<new-password>' | /usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh -u admin -p

-p takes no value: the tool prompts for the new password, or reads it from standard input when that is not a terminal, for example printf '%s\n' '<new-password>' | /usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh -u admin -p. Without -p, the tool generates a random password. Either way the new password is published in /etc/wazuh-indexer/export/credentials.env.

Configuring the Wazuh indexer

Edit the /etc/wazuh-indexer/opensearch.yml configuration file and replace the values in steps (a) to (e). Then set the JVM heap size in /etc/wazuh-indexer/jvm.options, as described in step (f).

The package ships a working single-node configuration: one node named node-1, listening on all interfaces (0.0.0.0). On a single node, steps (a) to (e) are optional: apply (a) to listen on a specific address, and (b) together with (c) to rename the node. Step (f) applies to every node, including a single node, because the package starts with a 1 GB heap. A multi-node cluster needs all six steps, on every node.

a. network.host: Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and use it as its publish address. Accepts an IP address or a hostname. On a multi-node cluster, use the same node address set in config.yml to create the SSL certificates.

b. node.name: Name of the Wazuh indexer node as defined in the config.yml file. For example, node-1. If you change it on a single node, change cluster.initial_cluster_manager_nodes to match.

c. cluster.initial_cluster_manager_nodes: List of the names of the master-eligible nodes. These names are defined in the config.yml file. A single node lists only its own node.name. For a multi-node cluster, uncomment the node-2 and node-3 lines, change the names, or add more lines, according to your config.yml definitions.

cluster.initial_cluster_manager_nodes:
- "node-1"
- "node-2"
- "node-3"

d. discovery.seed_hosts: List of the addresses of the master-eligible nodes. Each element can be either an IP address or a hostname. You may leave this setting commented if you are configuring the Wazuh indexer as a single node. For multi-node configurations, uncomment this setting and set the IP addresses of each master-eligible node.

discovery.seed_hosts:
- "10.0.0.1"
- "10.0.0.2"
- "10.0.0.3"

e. plugins.security.nodes_dn: List of the Distinguished Names of the certificates of all the Wazuh indexer cluster nodes. The installation writes the Distinguished Name of the certificate the package issued for this node, so a single node needs no change. For a multi-node cluster, list one line per node with the subjects of the certificates you deploy in Deploying certificates. The certificates tool issues them with the node name from config.yml as CN, and the Security plugin compares each entry as a string, so keep this order:

plugins.security.nodes_dn:
- "C=US,L=California,O=Wazuh,OU=Wazuh,CN=node-1"
- "C=US,L=California,O=Wazuh,OU=Wazuh,CN=node-2"
- "C=US,L=California,O=Wazuh,OU=Wazuh,CN=node-3"

f. JVM heap size: Set it in /etc/wazuh-indexer/jvm.options, before the first start. The package sets it to 1 GB. Use half of the system RAM when the Wazuh indexer is alone on the host, or a quarter when the Wazuh manager or the Wazuh dashboard runs on the same host. Set the initial (-Xms) and maximum (-Xmx) heap size to the same value. For example, on a dedicated node with 8 GB of RAM:

-Xms4g
-Xmx4g

For a size that is not a whole number of gigabytes, use megabytes, for example -Xms1536m and -Xmx1536m. See JVM heap size for the sizing limits, and Memory locking for the memory the node needs beyond the heap.

Deploying certificates

Note: This step applies only if you generated the certificates in advance, as described in Certificates. A single-node deployment already has the certificates the package issued.

Make sure that a copy of the wazuh-certificates.tar file, created during the initial configuration step, is placed in your working directory.

The installation takes in certificates only when the package is installed: certificates replaced afterwards are used, but their authority is not published to the Wazuh manager and the Wazuh dashboard on the host. Run with WAZUH_CA_DIR, as in Generating the SSL certificates, the certificates tool signs with the authority in /etc/wazuh-indexer/ca/, so that node can replace its pair afterwards, while every other node must have its pair and that authority staged before the package is installed.

In the commands below, replace <INDEXER_NODE_NAME> with the name of the Wazuh indexer node you are configuring as defined in config.yml. For example, node-1.

NODE_NAME=<INDEXER_NODE_NAME>

On the node that generated the certificates

The package is already installed here. Replace the pair it issued:

mkdir -p /etc/wazuh-indexer/certs
tar -xf ./wazuh-certificates.tar -C /etc/wazuh-indexer/certs/ ./$NODE_NAME.pem ./$NODE_NAME-key.pem ./admin.pem ./admin-key.pem ./root-ca.pem
mv -f /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv -f /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
chown -R root:wazuh-indexer /etc/wazuh-indexer/certs
chmod 750 /etc/wazuh-indexer/certs
chmod 640 /etc/wazuh-indexer/certs/*
chown root:root /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem
chmod 600 /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem

mv -f is required: the package already issued indexer.pem and indexer-key.pem, and the cluster’s pair must replace them. The files belong to root: the Wazuh indexer reads its own pair and the trust anchor through its group, and the admin pair is used by indexer-security-init.sh alone, which runs as root. A pair owned by the wazuh-indexer user is refused when the service starts.

The certificates tool and the package issue certificates with the same subject format, so the plugins.security.authcz.admin_dn the installation wrote into /etc/wazuh-indexer/opensearch.yml stays valid. The node Distinguished Name it wrote stays valid only if the host’s short name matches the node name in config.yml, because the package uses the hostname as CN and the certificates tool uses the node name.

On every other Wazuh indexer node

Run these commands before installing the package, replacing <INDEXER_NODE_NAME> with the name of this node as defined in config.yml. They stage this node’s pair, the admin pair and the authority that issued them, root-ca.pem, both beside the pair and in /etc/wazuh-indexer/ca/:

NODE_NAME=<INDEXER_NODE_NAME>
install -d -m 750 /etc/wazuh-indexer /etc/wazuh-indexer/certs /etc/wazuh-indexer/ca
tar -xf ./wazuh-certificates.tar -C /etc/wazuh-indexer/certs/ ./$NODE_NAME.pem ./$NODE_NAME-key.pem ./admin.pem ./admin-key.pem ./root-ca.pem
mv /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
cp /etc/wazuh-indexer/certs/root-ca.pem /etc/wazuh-indexer/ca/root-ca.pem
chmod 640 /etc/wazuh-indexer/certs/* /etc/wazuh-indexer/ca/root-ca.pem
chmod 600 /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem

The installation gives the node’s pair and the authority to the wazuh-indexer group, which does not exist before it, and writes the subjects of the pair and the admin pair into plugins.security.nodes_dn and plugins.security.authcz.admin_dn. It also checks that the authority issued the pair, and when it did not, the service does not start:

resolve-credentials: the certificate pair in /etc/wazuh-indexer/certs was not issued by /etc/wazuh-indexer/ca/root-ca.pem

The installation publishes the authority as /etc/wazuh-indexer/export/ca.pem for the Wazuh manager and the Wazuh dashboard on this host. Its key stays on the node that generated the certificates, so this node issues no client pairs for them: copy the client pairs from /etc/wazuh-indexer/export/ on that node, as described in Retrieving the generated credentials.

Distinguished Names

Make sure plugins.security.nodes_dn lists every node, as described in Configuring the Wazuh indexer: the installation writes only this node’s subject. To print the subject of a certificate in the form these settings expect, run:

openssl x509 -noout -subject -nameopt RFC2253 -in /etc/wazuh-indexer/certs/indexer.pem

indexer-security-init.sh warns when the admin certificate is not among the subjects in plugins.security.authcz.admin_dn.

Set up Wazuh Indexer in your environment

Follow the instructions in the Configuration section to set up Wazuh Indexer in your environment.

On offline installations, disable every task that requires an internet connection to prevent failures.

# opensearch.yml
plugins.content_manager.catalog.update_on_start: false
plugins.content_manager.catalog.update_on_schedule: false
plugins.content_manager.telemetry.enabled: false

plugins.content_manager.catalog.update_on_schedule and plugins.content_manager.telemetry.enabled are dynamic, so on a running deployment they can be applied without a restart:

curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X PUT "https://127.0.0.1:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "plugins.content_manager.catalog.update_on_schedule": false,
    "plugins.content_manager.telemetry.enabled": false
  }
}'

Disabling scheduled synchronization takes effect immediately and applies to an already-initialized node as well as a fresh one: the plugin updates the periodic job accordingly, and a run that is already scheduled is refused rather than reaching Wazuh CTI.

Disabling scheduled synchronization does not remove content that has already been downloaded. It only stops further updates from Wazuh CTI.

plugins.content_manager.catalog.update_on_start is not dynamic — it only governs the synchronization triggered as the plugin starts, so it takes effect on the next node start.

Starting the service

Enable and start the Wazuh indexer service. The installation does not start it, and it does not start at boot until it is enabled. The package reloads the service manager itself, so no systemctl daemon-reload is needed here.

Systemd

systemctl enable --now wazuh-indexer

SysV

Choose one option according to the operating system used.

a. RPM-based operating system:

chkconfig --add wazuh-indexer
service wazuh-indexer start

b. Debian-based operating system:

update-rc.d wazuh-indexer defaults 95 10
service wazuh-indexer start

Repeat this stage of the installation process for every Wazuh indexer node in your cluster. Then proceed with initializing your single-node or multi-node cluster in the next stage.

3. Cluster initialization

Run the Wazuh indexer indexer-security-init.sh script on any Wazuh indexer node to load the new certificates information and start the single-node or multi-node cluster.

/usr/share/wazuh-indexer/bin/indexer-security-init.sh

Note: You only have to initialize the cluster once, there is no need to run this command on every node.

Testing the cluster installation

1. Replace $WAZUH_INDEXER_IP_ADDRESS and run the following commands to confirm that the installation is successful. $WAZUH_INDEXER_ADMIN_PASSWORD is the admin password from /etc/wazuh-indexer/export/credentials.env. Load it with WAZUH_INDEXER_ADMIN_PASSWORD=$(sudo grep '^WAZUH_INDEXER_ADMIN_PASSWORD=' /etc/wazuh-indexer/export/credentials.env | cut -d= -f2- | tail -n 1).

   curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X GET "https://$WAZUH_INDEXER_IP_ADDRESS:9200"
   

   Output

   {
     "name" : "node-1",
     "cluster_name" : "wazuh-cluster",
     "cluster_uuid" : "lEzYZtwXTYaGiSAdbcqQmQ",
     "version" : {
       "distribution" : "opensearch",
       "number" : "3.6.0",
       "build_type" : "deb",
       "build_hash" : "1b0a897cd71105595b450b48b591581865f8b46b",
       "build_date" : "2026-10-01T01:45:08.798733103Z",
       "build_snapshot" : false,
       "lucene_version" : "10.4.0",
       "minimum_wire_compatibility_version" : "2.19.0",
       "minimum_index_compatibility_version" : "2.0.0"
     },
     "tagline" : "The OpenSearch Project: https://opensearch.org/"
   }
   

2. Replace $WAZUH_INDEXER_IP_ADDRESS and run the following command to check if the single-node or multi-node cluster is working correctly.

   curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X GET "https://$WAZUH_INDEXER_IP_ADDRESS:9200/_cat/nodes?v"
   

Configuration

Wazuh Indexer shares the same configuration system as OpenSearch. Refer to the OpenSearch documentation for general information about configuration files and settings.

Configuration files

Wazuh Indexer bundles two main configuration files on each node:

• /etc/wazuh-indexer/opensearch.yml - main configuration file for Wazuh Indexer. This file contains the settings for the Wazuh Indexer cluster, such as cluster name, node name, network settings, and more.
• /etc/wazuh-indexer/jvm.options - configuration file for the Java Virtual Machine (JVM) that runs Wazuh Indexer. This file contains settings for the JVM, such as heap size, garbage collection, and more.

System configuration

For production workloads, tune the following operating system and JVM settings on every Wazuh Indexer node before starting the service. The package installations create the wazuh-indexer service user; the settings below apply to that user and the host it runs on.

Note: All the commands in this section require root privileges.

JVM heap size

Wazuh Indexer runs on the Java Virtual Machine (JVM). The heap size determines how much memory the indexer can use for its internal data structures, caches, and request processing. Set it in the /etc/wazuh-indexer/jvm.options file.

Follow these recommendations when sizing the heap:

• Set the initial heap size (-Xms) and the maximum heap size (-Xmx) to the same value. This prevents performance degradation caused by the JVM resizing the heap at runtime.
• Set the heap to no more than 50% of the available system RAM. The other half is left for the operating system file system cache, which Wazuh Indexer relies on heavily. On a host that also runs the Wazuh manager or the Wazuh dashboard, set it to 25% of the RAM.
• Do not set the heap above approximately 32 GB. Above this threshold the JVM can no longer use compressed ordinary object pointers, which wastes memory and reduces performance.

For example, on a node with 8 GB of RAM, set the heap to 4 GB:

-Xms4g
-Xmx4g

Where:

• -Xms4g sets the initial heap size to 4 GB.
• -Xmx4g sets the maximum heap size to 4 GB.

During installation, set the heap before the service starts for the first time, as described in Configuring the Wazuh indexer. On a running node, restart the service after changing the heap size:

systemctl restart wazuh-indexer

Memory locking

Configure Wazuh Indexer to lock its process address space into RAM so that none of the JVM is ever swapped out.

1. bootstrap.memory_lock: true is enabled by default in /etc/wazuh-indexer/opensearch.yml. No changes are needed for package installations.

2. Grant the wazuh-indexer service user permission to lock unlimited memory. The RPM and Debian packages already configure this for both systemd-based and SysVinit-based systems — no additional configuration is required for package installations.

   • systemd: LimitMEMLOCK=infinity is set in the service file.
   • SysVinit: ulimit -l unlimited is applied by the init script before starting the process.

3. Reload the service manager and restart Wazuh Indexer:

   systemctl daemon-reload
   systemctl restart wazuh-indexer
   

4. Verify that memory locking is active by checking that the mlockall value is true:

   curl -k -u <INDEXER_USERNAME>:<INDEXER_PASSWORD> "https://<INDEXER_IP_ADDRESS>:9200/_nodes?filter_path=**.mlockall&pretty"
   

   {
     "nodes" : {
       "sRuGbIQRRfC54wzwIHjJWQ" : {
         "process" : {
           "mlockall" : true
         }
       }
     }
   }
   

   If the output is false, memory locking failed and the following line appears in /var/log/wazuh-indexer/wazuh-indexer.log:

   memory locking requested for wazuh-indexer process but memory is not locked
   

   This usually means the wazuh-indexer user lacks the memlock permission. For systemd-based systems, confirm that LimitMEMLOCK=infinity is present in the service file, reload with systemctl daemon-reload, and restart the service. For SysVinit-based systems, confirm that step 2 was applied correctly.

Note: Enabling bootstrap.memory_lock causes the JVM to reserve all the memory it needs at startup, including native memory beyond the configured heap. Make sure the node has enough physical RAM for the heap plus this overhead, otherwise the service may fail to start.

Virtual memory

Wazuh Indexer uses memory-mapped files (mmapfs) to store its indices. The default operating system limit on memory map areas is too low for production use, which can cause the node to fail to start or run out of memory.

Set vm.max_map_count to at least 262144. To check the current value:

sysctl vm.max_map_count

To increase it permanently, add the following line to /etc/sysctl.conf:

vm.max_map_count=262144

Apply the change without rebooting:

sysctl -p

Note: When running Wazuh Indexer in a container, set vm.max_map_count on the host machine, not inside the container.

File descriptors

Wazuh Indexer uses a large number of file descriptors. Running out of them can lead to data loss, so increase the limit for the wazuh-indexer user to 65535 or higher.

The RPM and Debian packages already set this limit to 65535 through the systemd service, so no additional configuration is required for package installations. To raise the limit manually, create or edit a systemd service override:

mkdir -p /etc/systemd/system/wazuh-indexer.service.d/
cat > /etc/systemd/system/wazuh-indexer.service.d/override.conf << EOF
[Service]
LimitNOFILE=65535
EOF

Reload and restart the service:

systemctl daemon-reload
systemctl restart wazuh-indexer

Verify the limit applied to the running node by checking max_file_descriptors:

curl -k -u <INDEXER_USERNAME>:<INDEXER_PASSWORD> "https://<INDEXER_IP_ADDRESS>:9200/_nodes/stats/process?filter_path=**.max_file_descriptors&pretty"

Avoiding unnecessary service restarts (needrestart)

On Debian and Ubuntu systems with needrestart installed, Wazuh Indexer may get restarted automatically every time apt installs or upgrades any package, even one unrelated to Wazuh Indexer. On Ubuntu 24.04 and 26.04 this happens silently, without asking for confirmation.

This happens because some bundled Java native libraries (used for compression and networking) extract a shared object file into /var/lib/wazuh-indexer/tmp/ and delete it right after loading it, keeping it mapped in memory but no longer present on disk. needrestart interprets processes with deleted mapped libraries as running outdated code and restarts them.

To stop needrestart from restarting Wazuh Indexer on unrelated apt operations, add one of the following to /etc/needrestart/conf.d/:

Ignore only the affected temporary files (recommended)

needrestart still checks the service for other legitimate reasons to restart:

echo 'push(@{$nrconf{blacklist_mappings}}, qr(^/var/lib/wazuh-indexer/tmp/));' > /etc/needrestart/conf.d/wazuh-indexer-tmp.conf

Ignore the service entirely

needrestart will never flag Wazuh Indexer for restart, including for legitimate reasons such as a libc update:

echo 'push(@{$nrconf{blacklist_rc}}, qr(^wazuh-indexer));' > /etc/needrestart/conf.d/wazuh-indexer.conf

Verify the change:

needrestart -v

wazuh-indexer.service should no longer appear in the list of services to restart.

Related documentation

• Security settings
• Plugin settings

Plugin settings

Setup settings

The Setup plugin is configured through settings in opensearch.yml. All settings use the plugins.setup prefix.

• plugins.setup.timeout (Integer, default 30, range 5–120) — timeout in seconds for index and search operations.
• plugins.setup.backoff (Integer, default 15, range 5–60) — delay in seconds for the retry mechanism involving initialization tasks.
• plugins.setup.max_retries (Integer, default 1, range 0–10) — number of times an initialization task that timed out is re-attempted, each attempt separated by plugins.setup.backoff. 0 disables retrying. The budget is per task: each index, index template and ISM policy gets its own. When it runs out the exception is rethrown, initialization stops, every index registered after the failing one is skipped, and the setup status is marked failed. Raise it on clusters where a cluster-manager election, and therefore the first index creation, routinely outlasts the default single re-attempt.
• plugins.setup.settings_update.enabled (Boolean, default true) — when false, the settings update endpoint (PUT /_plugins/_setup/settings) returns 403 Forbidden for every caller, regardless of role.

Content Manager settings

The Content Manager plugin is configured through settings in opensearch.yml. All settings use the plugins.content_manager prefix.

• plugins.content_manager.cti.api (String, default https://api.pre.cloud.wazuh.com/api/v1) — base URL for the Wazuh CTI API. Covers both the catalog endpoints (snapshots, changes, plans) and the CTI Console ones (instance registration, environment lookup, resource-token exchange).

• plugins.content_manager.catalog.sync_interval (Integer, default 60, range 10–1440, dynamic) — interval, in minutes, between scheduled synchronizations.

• plugins.content_manager.setup_wait.max_retries (Integer, default 4, range 0–10) — number of retries the catalog sync job performs while waiting for the Setup plugin to report readiness on startup, before giving up until the next scheduled sync.

• plugins.content_manager.setup_wait.backoff_base_seconds (Integer, default 20, range 1–120) — base delay, in seconds, for the exponential backoff between those retries (delay for retry n is base * 2^n; with the defaults, 20s/40s/80s/160s = 300s / 5 min worst case).

• plugins.content_manager.max_items_per_bulk (Integer, default 1000, range 10–1000) — maximum documents per bulk indexing request.

• plugins.content_manager.max_concurrent_bulks (Integer, default 5, range 1–5) — maximum concurrent bulk operations.

• plugins.content_manager.max_bulk_bytes (Long, default 5242880 / 5 MB, range 1048576–104857600 / 1–100 MB) — maximum request body size, in bytes, for a single bulk indexing request.

• plugins.content_manager.logtest.max_body_bytes (Long, default 1048576 / 1 MiB, range 1024–16777216 / 1 KiB–16 MiB, dynamic) — maximum size, in bytes, of a logtest request body (POST /logtest, /logtest/normalization, /logtest/detection). Requests whose body exceeds this are rejected with HTTP 413 at the REST layer, before parsing or dispatch, so an oversized event cannot be amplified into the response and exhaust the indexer’s heap.

• plugins.content_manager.client.timeout (Long, default 10, range 10–50) — HTTP client timeout in seconds for CTI API requests.

• plugins.content_manager.client.max_retries (Integer, default 3, range 0–10) — number of times a CTI API request is retried after an HTTP 429 (Too Many Requests) response, before the 429 is returned to the caller.

• plugins.content_manager.client.retry_backoff_base_seconds (Integer, default 30, range 1–300) — base delay, in seconds, for the exponential backoff used between 429 retries when the response carries no usable Retry-After header (delay for retry n is base * 2^n).

• plugins.content_manager.pit_keepalive (Long, default 120, range 60–600) — point-in-time keepalive in seconds used during paginated index scans.

• plugins.content_manager.engine.mock (Boolean, default false) — bypasses real Engine socket calls, returning mocked responses instead. Intended for testing only.

• plugins.content_manager.catalog.update_on_start (Boolean, default true) — trigger content sync when the plugin starts.

• plugins.content_manager.catalog.update_on_schedule (Boolean, default true, dynamic) — enable the periodic sync job. When false the job is disabled and any scheduled run is refused, so no content is fetched from Wazuh CTI on a schedule. Registering a CTI access token does not start a content update either. On-demand updates (POST /update) are unaffected — they are controlled by plugins.content_manager.catalog.update_on_demand.

• plugins.content_manager.catalog.ruleset (String, default "") — full CTI consumer URL for ruleset content.

• plugins.content_manager.catalog.iocs (String, default "") — full CTI consumer URL for IoC content.

• plugins.content_manager.catalog.vulnerabilities (String, default "") — full CTI consumer URL for vulnerabilities content.

• plugins.content_manager.catalog.create_detectors (Boolean, default true) — automatically create Ruleset Management detectors from CTI content.

• plugins.content_manager.telemetry.enabled (Boolean, default true, dynamic) — enable or disable the daily Update check service ping.

• plugins.content_manager.catalog.update_on_demand (Boolean, default true) — when false, on-demand content updates (POST /update) return 403 Forbidden for every caller, regardless of role.

• plugins.content_manager.catalog.policy_update.enabled (Boolean, default true) — when false, policy updates (PUT /policy/{space}) return 403 Forbidden for every caller, regardless of role.

• plugins.content_manager.max_integrations (Integer, default 100, minimum 0, no upper bound, dynamic) — maximum number of integrations that can be created. Requests that would exceed this limit are rejected with HTTP 400.

• plugins.content_manager.max_decoders (Integer, default 200, minimum 0, no upper bound, dynamic) — maximum number of decoders that can be created. Requests that would exceed this limit are rejected with HTTP 400.

• plugins.content_manager.max_rules (Integer, default 200, minimum 0, no upper bound, dynamic) — maximum number of rules that can be created. Requests that would exceed this limit are rejected with HTTP 400.

• plugins.content_manager.max_kvdbs (Integer, default 100, minimum 0, no upper bound, dynamic) — maximum number of KVDBs that can be created. Requests that would exceed this limit are rejected with HTTP 400.

• plugins.content_manager.max_filters (Integer, default 100, minimum 0, no upper bound, dynamic) — maximum number of filters that can be created per space. Requests that would exceed this limit are rejected with HTTP 400.

• plugins.content_manager.cti.console.timeout (Integer, default 5, range 1–120) — request timeout, in seconds, for CTI Console calls (instance registration, plans, token exchange). The catalog client has its own timeout in plugins.content_manager.client.timeout; the Console endpoints resolve against plugins.content_manager.cti.api, so moving that setting moves both services.

• plugins.content_manager.bulk.retry.shed.max_retries (Integer, default 3, range 0–10, dynamic) — number of times a bulk operation the cluster shed under load (circuit breaker trip, indexing-pressure rejection, HTTP 429/503) is re-submitted before its documents are counted as dropped.

• plugins.content_manager.bulk.retry.shed.initial_backoff_millis (Long, default 1000, range 100–60000, dynamic) — delay, in milliseconds, before the first re-submission of a shed bulk operation. Each subsequent retry doubles it, capped at the max backoff.

• plugins.content_manager.bulk.retry.shed.max_backoff_millis (Long, default 30000, range 100–60000, dynamic) — ceiling, in milliseconds, for the exponential backoff between shed bulk re-submissions.

• plugins.content_manager.bulk.retry.topology.max_retries (Integer, default 5, range 0–10, dynamic) — number of times a bulk operation deferred by a transient cluster-topology change (an index recreated mid-load, a shard left unavailable, the node holding it leaving) is re-submitted before its documents are counted as dropped. The default was sized to outlast one rolling restart; raise it on clusters where a restart takes longer, otherwise a synchronization running across a restart drops documents.

• plugins.content_manager.bulk.retry.topology.initial_backoff_millis (Long, default 5000, range 100–60000, dynamic) — delay, in milliseconds, before the first re-submission of a topology-deferred bulk operation. Each subsequent retry doubles it, capped at the max backoff.

• plugins.content_manager.bulk.retry.topology.max_backoff_millis (Long, default 30000, range 100–60000, dynamic) — ceiling, in milliseconds, for the exponential backoff between topology-deferred bulk re-submissions.

• plugins.content_manager.job_schedule.max_retries (Integer, default 3, range 0–10) — number of attempts to register a periodic job with the job scheduler before giving up and logging an error.

• plugins.content_manager.job_schedule.retry_backoff_seconds (Integer, default 15, range 1–300) — base delay, in seconds, for the linear backoff between job-registration attempts (delay before attempt n is base * n).

• plugins.content_manager.resource_lock.max_retries (Integer, default 20, range 1–100, dynamic) — number of attempts to acquire the resource-creation lock before the request is rejected with HTTP 503.

• plugins.content_manager.resource_lock.retry_backoff_millis (Long, default 100, range 10–10000, dynamic) — delay, in milliseconds, between resource-creation lock acquisition attempts.

• plugins.content_manager.resource_lock.stale_threshold_millis (Long, default 30000, range 5000–600000, dynamic) — age, in milliseconds, past which a held resource-creation lock is treated as orphaned by a crashed node and stolen by the next caller. Set this to the same value on every node, and above the worst-case resource-creation time: the lock is cluster-wide but the setting is read from each node’s own configuration, so nodes that disagree can both consider themselves inside the critical section. The holder never renews the lock, so a value below the time a creation takes lets every concurrent request steal it and the mutex stops working.

• plugins.content_manager.user_overrides.max_update_attempts (Integer, default 3, range 1–20, dynamic) — number of attempts to write the shared user-overrides registry document before giving up. The registry is a single document, so concurrent writers are serialized optimistically and each version conflict re-reads and re-applies.

• plugins.content_manager.integration.max_update_attempts (Integer, default 5, range 1–20, dynamic) — number of attempts to update an integration document on a version conflict, when linking or unlinking a resource, before the operation fails.

• plugins.content_manager.engine.socket_path (String, default /usr/share/wazuh-indexer/engine/sockets/engine-api-http.sock) — filesystem path of the Unix domain socket the Engine API listens on.

• plugins.content_manager.engine.reload_timeout_minutes (Integer, default 10, range 1–1440) — upper bound, in minutes, on how long a single Engine content reload may stay in flight. It guards against a lost callback wedging the single-flight guard forever.

• plugins.content_manager.engine.not_ready_grace_minutes (Integer, default 5, range 1–1440) — how long, in minutes, the content indices may stay unable to serve reads before the deferral is escalated from a debug line to a warning.

• plugins.content_manager.security_analytics.sync_timeout_seconds (Integer, default 60, range 1–3600) — how long, in seconds, a Ruleset Management bulk synchronization step (uploading rules or integrations) may run before it is abandoned and the pass reported as unsuccessful.

• plugins.content_manager.security_analytics.detector_timeout_seconds (Integer, default 30, range 1–3600) — how long, in seconds, to wait for the first detector creation to complete.

• plugins.content_manager.security_analytics.cleanup_timeout_seconds (Integer, default 120, range 120–3600) — how long, in seconds, to wait for the deletion of stale Ruleset Management rules and integrations after a content swap. The floor is the default: on timeout the deletion is not retried, so lowering it would make stale resources routine rather than exceptional.

• plugins.content_manager.security_analytics.detector_interval (Integer, default 2, range 1–10080, dynamic) — detector schedule interval, in minutes, applied when the CTI integration document does not specify one, or specifies one outside the bounds Ruleset Management accepts.

• plugins.content_manager.update_sub_batch_size (Integer, default 50, range 1–1000) — maximum number of UPDATE offsets batched into a single MultiGet + bulk request while applying a catalog changeset.

• plugins.content_manager.offset_flush_interval (Integer, default 10, range 1–1000) — how many batches (changeset application) or bulks (snapshot load) are processed between consumer-offset checkpoints. A smaller value narrows the window of work replayed after a crash, at the cost of more writes to the consumer-state document.

• plugins.content_manager.search_page_size (Integer, default 1000, range 100–10000) — page size used by the paginated IoC reconciliation scan and the IoC export to the Engine. Lower values mean more round trips over the same documents, not fewer documents. Higher values cost more heap per search, and on a busy node search backpressure may cancel the page.

Settings marked dynamic can be changed on a running cluster and take effect on the next operation:

curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X PUT "https://127.0.0.1:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "plugins.content_manager.bulk.retry.topology.max_retries": 8,
    "plugins.content_manager.bulk.retry.topology.max_backoff_millis": 45000
  }
}'

Ruleset Management settings

The Ruleset Management plugin is configured through settings in opensearch.yml. All node-scope settings use the plugins.security_analytics prefix. Almost every setting is dynamic and can be changed at runtime via the Cluster Settings API.

• plugins.security_analytics.alert_finding_enabled (Boolean, default false) — enable rollover for the finding history indices, and keep the current write index out of the retention sweep while it is on. Retention deletion itself runs either way. It does not make raw findings be stored; that is the Alerting plugin’s plugins.alerting.alert_finding_enabled.
• plugins.security_analytics.alert_finding_max_docs (Long, default 1000, minimum 0) — Deprecated. Maximum document count for a finding history index before rollover.
• plugins.security_analytics.alert_finding_rollover_period (Time, default 12h) — how often the finding history rollover job runs.
• plugins.security_analytics.alert_history_enabled (Boolean, default false) — enable rollover for the alert history indices, and keep the current write index out of the retention sweep while it is on. Retention deletion itself runs either way.
• plugins.security_analytics.alert_history_max_age (Time, default 30d) — maximum age of an alert history index before rollover.
• plugins.security_analytics.alert_history_max_docs (Long, default 1000, minimum 0) — maximum document count for an alert history index before rollover.
• plugins.security_analytics.alert_history_retention_period (Time, default 60d) — retention period after which alert history indices are deleted.
• plugins.security_analytics.alert_history_rollover_period (Time, default 12h) — how often the alert history rollover job runs.
• plugins.security_analytics.auto_correlations_enabled (Boolean, default false) — automatically generate correlation rules from new findings.
• plugins.security_analytics.correlation.detector_cache_ttl (Time, default 5m) — TTL for the in-memory monitor-id to detector cache. Set to 0s to disable the cache.
• plugins.security_analytics.correlation.events_backpressure.enabled (Boolean, default true) — write-block the events indices when the correlation backlog fills, so ingestion pauses and the backlog drains instead of the node running out of memory.
• plugins.security_analytics.correlation.events_backpressure.high_watermark_percent (Integer, default 100, range 1–100) — backlog level, as a percent of correlation.max_pending_findings, at or above which the events indices are write-blocked.
• plugins.security_analytics.correlation.events_backpressure.low_watermark_percent (Integer, default 60, range 0–99) — backlog level, as a percent of correlation.max_pending_findings, at or below which the events-index write block is lifted.
• plugins.security_analytics.correlation.max_in_flight_findings (Integer, default 50, range 1–1000) — maximum number of correlation pipelines running concurrently.
• plugins.security_analytics.correlation.max_pending_findings (Integer, default 10000, range 1–1000000) — maximum findings waiting for a free correlation slot. When the backlog is full, new findings are shed (correlation and enrichment skipped) so the node does not run out of memory under overload.
• plugins.security_analytics.correlation.metadata_cache_ttl (Time, default 5m) — TTL for the in-memory caches of log-type list and correlation rules by detector type. Set to 0s to disable both caches.
• plugins.security_analytics.correlation_history_max_age (Time, default 30d) — maximum age of a correlation history index before rollover.
• plugins.security_analytics.correlation_history_max_docs (Long, default 1000, minimum 0) — maximum document count for a correlation history index before rollover.
• plugins.security_analytics.correlation_history_retention_period (Time, default 60d) — retention period after which correlation history indices are deleted.
• plugins.security_analytics.correlation_history_rollover_period (Time, default 12h) — how often the correlation history rollover job runs.
• plugins.security_analytics.correlation_time_window (Time, default 5m) — time window used to group findings into correlations.
• plugins.security_analytics.enable_detectors_with_dedicated_query_indices (Boolean, default true) — create dedicated query indices for new detectors.
• plugins.security_analytics.enable_workflow_usage (Boolean, default true) — use Alerting composite workflows when running detectors.
• plugins.security_analytics.enriched_findings_bulk_size (Integer, default 100, range 10–1000) — number of enriched findings accumulated before a bulk index request is fired.
• plugins.security_analytics.enriched_findings_enrich_batch_size (Integer, default 100, range 1–1000) — maximum number of findings drained from the queue per in-flight permit, fetched via a single combined MultiGet.
• plugins.security_analytics.enriched_findings_flush_interval (Integer, default 5, range 1–60) — interval in seconds at which pending enriched findings are flushed regardless of batch size.
• plugins.security_analytics.enriched_findings_index_enabled (Boolean, default true) — toggle the enriched findings pipeline.
• plugins.security_analytics.enriched_findings_max_in_flight (Integer, default 5, range 1–10) — maximum number of concurrent async enrichment chains.
• plugins.security_analytics.enriched_findings_rule_cache_max_size (Integer, default 10000, minimum 0, static — requires a node restart to change) — maximum number of rule-metadata entries cached in memory. Least-recently-used entries are evicted past this size.
• plugins.security_analytics.filter_by_backend_roles (Boolean, default false) — restrict access to detectors, rules, and findings based on the requester’s backend roles.
• plugins.security_analytics.finding_history_max_age (Time, default 30d) — maximum age of a finding history index before rollover.
• plugins.security_analytics.finding_history_retention_period (Time, default 60d) — retention period after which finding history indices are deleted.
• plugins.security_analytics.index_timeout (Time, default 60s) — timeout for Ruleset Management index operations.
• plugins.security_analytics.max_case_management_bulk_size (Integer, default 10, range 0–100, dynamic) — maximum number of findings that can be updated in a single request to the update findings endpoint (PUT /_plugins/_security_analytics/findings/_update). Setting it to 0 disables the endpoint entirely.
• plugins.security_analytics.max_detectors (Integer, default 10, minimum 0, no upper bound, dynamic) — maximum number of user-created detectors (Content Manager detectors do not count).
• plugins.security_analytics.max_rules_per_detector (Integer, default 50, minimum 0, no upper bound, dynamic) — maximum number of rules (custom or pre-packaged) allowed in a single detector input. Requests that would exceed this limit are rejected with HTTP 400.
• plugins.security_analytics.mappings.default_schema (String, default ecs) — default field-mapping schema used to resolve a Sigma rule’s raw field names to Wazuh Common Schema fields when a log type does not declare its own schema.

Wazuh Indexer setup plugin

The wazuh-indexer-setup plugin is a module composing the Wazuh Indexer responsible for the initialization of the indices required by Wazuh.

The Wazuh Indexer Setup plugin is responsible for:

• Creating the index templates, to define the mappings and settings for the indices.
• Creating the initial indices. We distinguish between stateful and stream indices. While stream indices contain immutable time-series data and are rolled over periodically, stateful indices store dynamic data that can change over time and reside in a single index.
• Stream indices are created with a data stream configuration and an ISM rollover policy. See Retention for what those policies actually guarantee — rollover is driven by volume, so the deletion ages are a floor and not a ceiling.

Indices

The following tables list the indices created by this plugin.

Stream indices

Stateful indices