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

<!--
Provide a brief description of the problem this pull request addresses. Include relevant context to help reviewers understand the purpose and scope of the changes.

If this pull request resolves an existing issue, reference it here. For example:
Closes #<issue_number>
-->

## Proposed Changes

<!--
Summarize the changes made in this pull request. Include:
- Features added
- Bugs fixed
- Any relevant technical details
-->

### Results and Evidence

<!--
Provide evidence of the changes made, such as:
- Logs
- Screenshots
- Before/after comparisons
-->

### Artifacts Affected

<!--
List the artifacts impacted by this pull request, such as:
- Executables (specify platforms if applicable)
- Default configuration files
- Packages
-->

### Configuration Changes

<!--
If applicable, list any configuration changes introduced by this pull request, including:
- New configuration parameters
- Changes to default values
- Backward compatibility notes
-->

### Documentation Updates

<!--
If applicable, list the sections of documentation that have been updated as part of this pull request.
-->

### Tests Introduced

<!--
If applicable, describe any new unit or integration tests added as part of this pull request. Include:
- Scope of the tests
- Any relevant details about test coverage
-->

## Review Checklist

<!--
List any manual tests completed to verify the functionality of the changes. Include any manual tests that are still required for final approval.
-->

- [ ] Code changes reviewed
- [ ] Relevant evidence provided
- [ ] Tests cover the new functionality
- [ ] Configuration changes documented
- [ ] Developer documentation reflects the changes
- [ ] Meets requirements and/or definition of done
- [ ] No unresolved dependencies with other issues
- [ ] PR is linked to the relevant issue(s)
- [ ] Correct labels applied (e.g., `no-changelog`)
- [ ] ...

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, classified as Added, Changed, Removed, or Fixed. The 5_codequality_changelog.yml workflow enforces this. Apply the no-changelog label to bypass the check when the linked issue belongs to a private repository, or when the PR genuinely does not require a changelog update.

Changelog entries must always reference the issue, not the pull request, so the entry stays meaningful independently of how the change was implemented. An issue only belongs in the changelog if it affects the product and represents a change from a previously released version — internal/CI changes are never included, and neither are fixes for problems introduced in an unpublished version.

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 (check wazuh-indexer/gradle/libs.versions.toml).

Once the JDK is installed, configure it as the default system-wide Java installation using update-alternatives:

sudo update-alternatives --install /usr/bin/java java /home/$USER/.jdks/temurin-21.0.9/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=/usr/lib/jvm/temurin-24-jdk-amd64
export PATH=$PATH:/usr/lib/jvm/temurin-24-jdk-amd64/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:

sdk install java 24-tem
sdk use java 24-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:

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

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

cd wazuh-indexer-notifications
./gradlew build

For the Common Utils plugin (Shared Library):

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

For the Alerting plugin:

cd wazuh-indexer-alerting
./gradlew build

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 it will generate a wazuh-indexer package for Debian based systems, for the x64 architecture, using 1 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 wazuh-indexer/build-scripts/docker folder 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 present in the same folder as the Dockerfile in wazuh-indexer/build-scripts/docker.

docker build \
   --build-arg="VERSION=<version>" \
   --build-arg="INDEXER_TAR_NAME=wazuh-indexer_<version>-<revision>_linux-x64.tar.gz" \
   --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:
-n NAME         [required] Tarball name.
-r REVISION     [Optional] Revision qualifier, default is 0.
-h help

The script will stop if the credentials are not set, or if any of the required parameters are not provided.

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.

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 requires a specific JDK version (currently JDK 24, Eclipse Temurin). 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

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

Smoke tests on built packages are run via GitHub Actions Workflows. These install packages on supported operating systems:

• DEB packages — installed on the Ubuntu 24.04 GitHub Actions runner.
• RPM packages — installed in a Red Hat 9 Docker container.

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.

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

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

    %% 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 {
    }

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 two 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.

/**
* 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"));

  //...
}

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.

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

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 a short retention period to ensure timely cleanup of processed event data.

Policy details

• Policy Name: stream-events-policy
• Location: plugins/setup/src/main/resources/policies/stream-events-policy.json
• Index Pattern: wazuh-events-v5-*
• Retention Period: 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 after 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 a 90-day retention period to maintain detection findings for compliance and investigation purposes.

Policy details

• Policy Name: stream-findings-policy
• Location: plugins/setup/src/main/resources/policies/stream-findings-policy.json
• Index Pattern: wazuh-findings-v5-*
• Retention Period: 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 after 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 with an aggressive 10-minute retention for temporary raw event storage.

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*
• Retention Period: 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 after 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
• Retention Period: 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) with a 30-day retention period.

Policy details

• Policy Name: stream-metrics-policy
• Location: plugins/setup/src/main/resources/policies/stream-metrics-policy.json
• Index Pattern: wazuh-metrics-*
• Retention Period: 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 after 30 days

2. Delete State

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

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; writes carry no DLS query. The restriction also applies to users holding a role that grants read on the * index pattern.

Sessions are read and written by each user directly against the data stream, under that per-owner DLS; the setup plugin exposes no administrative API over them.

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
• 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": {},
  "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*
• Retention Period: 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 after 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:
  # Generate the hash using the tool at `plugins/opensearch-security/tools/hash.sh -p <new-password>`
  hash: "<HASHED-PASSWORD>"
  reserved: true
  hidden: false
  backend_roles: []
  description: "New user description"

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 wazuh-indexer:wazuh-indexer /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 local snapshots
    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)

When AbstractConsumerService.syncConsumerServices() detects a plan change (the plan-provided resource URL differs from the persisted one), it runs the shadow swap path:

1. Resolve shadow physical names (the -a/-b suffix not currently live)
2. Create hidden shadow physical indices (index.hidden=true, no alias)
3. Download snapshot into shadow indices (reuse SnapshotServiceImpl)
4. Reindex user content (space.name != “standard”) from live → shadow (only for consumer types with hasUserContent()=true, i.e., ruleset)
5. Unhide non-CVE shadow indices (set index.hidden=false)
6. Atomic alias swap (single IndicesAliasesRequest for all 8 aliases)
7. Rewrite consumer document in .wazuh-cti-consumers
8. Run post-sync cascade (onSyncComplete: Security Analytics sync, engine promote, etc.)
9. Delete old physical indices

Failure modes

Concurrency: The CatalogSyncJob semaphore spans the entire synchronize() call, which includes the shadow swap. No additional locking is needed, but it also means the swap holds that semaphore for its full duration — normal incremental syncs for other consumers queue behind it.

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>
  • Fire-and-forget behavior: callback logs success/failure without blocking scheduler threads.

CTI HTTP client User-Agent

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.

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.

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"
  content: { ... }

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, engine-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.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..."
    }
  }
}

Content synchronization pipeline

Overview

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

    Scheduler->>SyncJob: Trigger Execution
    activate SyncJob

    SyncJob->>Synchronizer: synchronize()

    Synchronizer->>ConsumerSvc: getLocalConsumer() / getRemoteConsumer()
    ConsumerSvc->>CTI: Fetch Metadata
    ConsumerSvc-->>Synchronizer: Offsets & Metadata

    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, no plan change)
        Synchronizer->>Update: update(localOffset, remoteOffset)
        Update->>CTI: Fetch Changes
        Update->>Indices: Apply JSON Patches
        Update-->>Synchronizer: Done
    else Plan change detected (resource URL differs)
        Synchronizer->>Swap: performShadowSwap()
        Swap->>Indices: Create hidden shadow indices (-a/-b spare suffix)
        Swap->>CTI: Download snapshot into shadow indices
        Swap->>Indices: Reindex user content (space.name != "standard")
        Swap->>Indices: Unhide shadow indices
        Swap->>Indices: Atomic alias swap (single IndicesAliasesRequest)
        Swap->>Consumers: Rewrite consumer document (new resource, local_offset = remote_offset)
        Swap->>Indices: Delete old physical indices
        Swap-->>Synchronizer: Done
    end

    opt Changes Applied (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 runs after all three branches, including the shadow swap — by the time it executes, Indices and Consumers already resolve through the swapped alias and rewritten consumer document.

Initialization phase

When local_offset = 0:

1. Downloads a ZIP snapshot from the CTI API.
2. Extracts and parses JSON files for each content type.
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. Fetches the changes in batches from the CTI API.
2. Applies JSON Patch operations (add, update, delete).
3. Pushes the changes to the Security Analytics Plugin via SecurityAnalyticsServiceImpl.
4. Updates the local offset.

Post-synchronization phase

1. Refreshes all content indices.
2. Upserts integrations, rules, and detectors into the Security Analytics Plugin via SecurityAnalyticsServiceImpl.
3. Recalculates SHA-256 hashes for policy integrity verification.
4. 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.

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]
    DeleteSAP --> 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 in Security Analytics cleanup are logged but do not block the reset — the primary goal is clearing the content indices and regenerating the policy.

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:admin --insecure \
  -d '{
    "integration": "<integration-id>",
    "resource": {
      "title": "Test Rule"
    }
  }'

# The response returns the UUID. Use it to fetch:
curl -X GET "https://localhost:9200/_plugins/_content_manager/rules/<uuid>" \
  -u admin:admin --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. It reads the raw request body into a LogtestRequest and calls client.execute(LogtestAction.INSTANCE, logtestRequest, listener). It performs no 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. Reads the request body and calls client.execute(LogtestNormalizationAction.INSTANCE, ...). No 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. Reads the request body and calls client.execute(LogtestDetectionAction.INSTANCE, ...). No 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.executeDetection(integrationId, space, inputEvent).

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()
• executeDetection() — Security Analytics-only: looks up integration, fetches rule IDs/bodies, evaluates via SecurityAnalyticsService.evaluateRules(), 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: "No integration 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 and rule bodies to SecurityAnalyticsService.evaluateRules().
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 / EventMatcher

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

• SecurityAnalyticsServiceImpl.evaluateRules() — Parses Sigma rule YAML strings into SigmaRule objects, then delegates to EventMatcher.
• EventMatcher.evaluate() — Flattens the normalized event JSON into dot-notation keys, then evaluates each rule’s detection conditions against the flat map. Returns a JSON result string.

The EventMatcher handles:

• Field-equals-value conditions (exact match, case-insensitive)
• Keyword (value-only) conditions (searches all event fields)
• Wildcards (* for multi-char, ? for single-char) via cached compiled regex patterns
• String modifiers: contains, startswith, endswith
• Explicit regex (re modifier)
• CIDR subnet matching (IPv4 and IPv6)
• Boolean, numeric (gt, gte, lt, lte), null, and string comparisons
• Composite conditions: AND, OR, NOT
• List values (any element matching counts as a match)

Match results use a nested rule object per match entry:

{
  "rule": { "id": "...", "title": "...", "level": "...", "tags": [...] },
  "matched_conditions": [...]
}

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.evaluateRules(normalizedEventJson, ruleBodies)
    │       → parses YAML → SigmaRule objects
    │       → EventMatcher flattens event + evaluates conditions
    │       → 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.evaluateRules(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.

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).

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

1. Modify EventMatcher.matchValue() to handle new SigmaType subclasses.
2. Add test cases in EventMatcherTests.
3. Update the Sigma rules doc (Sigma Rules) if new detection modifiers are supported.

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).
• 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

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: version 11 or 17 (depending on the target Wazuh Indexer version).
• Gradle: Use the included ./gradlew wrapper (no separate install needed).
• IDE: IntelliJ IDEA with Kotlin plugin is recommended.

Clone and build

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

The distribution zip will be generated at:

notifications/notifications/build/distributions/

Build packages

To create distribution packages:

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

# Assemble only (skip tests)
./gradlew assemble

The output zip can be installed on a running Wazuh Indexer using:

bin/opensearch-plugin install file:///path/to/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:

./gradlew :notifications:notifications:integTest

Key integration test classes:

Notification flow

The data flow when sending a notification follows this sequence:

Monitor/Alerting Plugin
        │
        ▼
Notification Plugin Interface (REST / Transport)
        │
        ▼
Security Plugin (verify permissions)
        │
        ▼
.notifications index (persist notification, status = pending)
        │
        ▼
Transport Action (resolve destination type)
        │
        ├──► WebhookDestinationTransport ──► Slack / Chime / Teams / Custom Webhook
        ├──► SmtpDestinationTransport    ──► External SMTP Server
        ├──► SesDestinationTransport     ──► AWS SES
        └──► SnsDestinationTransport     ──► AWS SNS
                                                  │
                                                  ▼
                                             Recipient

1. An internal plugin (Alerting, Reporting, ISM) or a user invokes the Notification plugin via Transport or REST API.
2. The Security plugin verifies the caller’s permissions.
3. The notification is persisted in the .notifications index with pending status.
4. The DestinationTransportProvider resolves the correct transport based on the channel type.
5. The transport client delivers the message to the external service.
6. On failure, retries are attempted up to the configured limit.
7. The notification status is updated to sent or failed.

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.

Enriched findings pipeline

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

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-pre-packaged-rules) and the custom rules index (opensearch-custom-rules). 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

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

Rule metadata is nested under wazuh.rule. 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.

Sequence diagram

sequenceDiagram
    participant A as Wazuh Manager
    participant I as Wazuh Indexer
    participant SA as Security Analytics
    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->>SA: Monitor evaluates event against Sigma rules
    SA->>SA: Rule matches → create raw finding
    SA->>TC: 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: buildAndIndex (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.comments (nested, array) — replaces the old single comment field. Each entry has author (keyword), created_at (date), updated_at (date), and comment (match_only_text).

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 endpoint allows up to 50 finding updates per call.

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.

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
• On partial failure (some docs not found): HTTP 207 MULTI_STATUS
• On total bulk failure: HTTP 500

Registration

The handler is registered in SecurityAnalyticsPlugin.getRestHandlers():

new RestUpdateFindingsAction()

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.

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 Security Analytics 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.

Security Analytics 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 Security Analytics 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, Security Analytics 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, Security Analytics). 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, Security Analytics, 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

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 230 GB.

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. 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 creation

Generating the SSL certificates

1. Download the wazuh-certs-tool.sh script and the config.yml configuration file. This creates the certificates that encrypt communications between the Wazuh central components.

   curl -sO https://packages-dev.wazuh.com/5.0/wazuh-certs-tool.sh
   curl -sO https://packages-dev.wazuh.com/5.0/config.yml
   

2. Edit ./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 ./wazuh-certs-tool.sh to create the certificates. For a multi-node cluster, these certificates need to be later deployed to all Wazuh instances in your cluster.

   ./wazuh-certs-tool.sh -A
   

4. Compress all the necessary files.

   tar -cvf ./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.

2. Nodes installation

Installing package dependencies

Install the following packages if missing:

yum

yum install coreutils

apt

apt-get install debconf adduser procps

Installing the Wazuh indexer package

rpm

rpm -ivh --replacepkgs wazuh-indexer-<VERSION>.rpm

dpkg

dpkg -i wazuh-indexer-<VERSION>.deb

Configuring the Wazuh indexer

Edit the /etc/wazuh-indexer/opensearch.yml configuration file and replace the following values:

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. 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.

c. cluster.initial_cluster_manager_nodes: List of the names of the master-eligible nodes. These names are defined in the config.yml file. Uncomment the node-2 and config.yml 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. Uncomment the lines for node-2 and node-3 and change the common names (CN) and values according to your settings and your config.yml definitions.

plugins.security.nodes_dn:
- "CN=node-1,OU=Wazuh,O=Wazuh,L=California,C=US"
- "CN=node-2,OU=Wazuh,O=Wazuh,L=California,C=US"
- "CN=node-3,OU=Wazuh,O=Wazuh,L=California,C=US"

Deploying certificates

Note: Make sure that a copy of the wazuh-certificates.tar file, created during the initial configuration step, is placed in your working directory.

Run the following commands, replacing <INDEXER_NODE_NAME> with the name of the Wazuh indexer node you are configuring as defined in config.yml. For example, node-1. This deploys the SSL certificates to encrypt communications between the Wazuh central components.

NODE_NAME=<INDEXER_NODE_NAME>

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 -n /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv -n /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
chmod 500 /etc/wazuh-indexer/certs
chmod 400 /etc/wazuh-indexer/certs/*
chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/certs

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

Starting the service

Enable and start the Wazuh indexer service.

Systemd

systemctl daemon-reload
systemctl enable wazuh-indexer
systemctl start 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.

   curl -k -u admin:admin https://$WAZUH_INDEXER_IP_ADDRESS:9200
   

   Output

   {
     "name" : "node-1",
     "cluster_name" : "wazuh-cluster",
     "cluster_uuid" : "095jEW-oRJSFKLz5wmo5PA",
     "version" : {
       "number" : "7.10.2",
       "build_type" : "rpm",
       "build_hash" : "db90a415ff2fd428b4f7b3f800a51dc229287cb4",
       "build_date" : "2023-06-03T06:24:25.112415503Z",
       "build_snapshot" : false,
       "lucene_version" : "9.6.0",
       "minimum_wire_compatibility_version" : "7.10.0",
       "minimum_index_compatibility_version" : "7.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 -k -u admin:admin https://$WAZUH_INDEXER_IP_ADDRESS:9200/_cat/nodes?v
   

Requirements

Requirements

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 230 GB.

Packages

Packages

Wazuh Indexer packages can be downloaded from the internal S3 buckets though 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. 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 creation

Generating the SSL certificates

1. Download the wazuh-certs-tool.sh script and the config.yml configuration file. This creates the certificates that encrypt communications between the Wazuh central components.

   curl -sO https://packages-dev.wazuh.com/5.0/wazuh-certs-tool.sh
   curl -sO https://packages-dev.wazuh.com/5.0/config.yml
   

2. Edit ./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 ./wazuh-certs-tool.sh to create the certificates. For a multi-node cluster, these certificates need to be later deployed to all Wazuh instances in your cluster.

   ./wazuh-certs-tool.sh -A
   

4. Compress all the necessary files.

   tar -cvf ./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.

2. Nodes installation

Installing package dependencies

Install the following packages if missing:

yum

yum install coreutils

apt

apt-get install debconf adduser procps

Installing the Wazuh indexer package

rpm

rpm -ivh --replacepkgs wazuh-indexer-<VERSION>.rpm

dpkg

dpkg -i wazuh-indexer-<VERSION>.deb

Configuring the Wazuh indexer

Edit the /etc/wazuh-indexer/opensearch.yml configuration file and replace the following values:

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. 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.

c. cluster.initial_cluster_manager_nodes: List of the names of the master-eligible nodes. These names are defined in the config.yml file. Uncomment the node-2 and config.yml 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. Uncomment the lines for node-2 and node-3 and change the common names (CN) and values according to your settings and your config.yml definitions.

plugins.security.nodes_dn:
- "CN=node-1,OU=Wazuh,O=Wazuh,L=California,C=US"
- "CN=node-2,OU=Wazuh,O=Wazuh,L=California,C=US"
- "CN=node-3,OU=Wazuh,O=Wazuh,L=California,C=US"

Deploying certificates

Note: Make sure that a copy of the wazuh-certificates.tar file, created during the initial configuration step, is placed in your working directory.

Run the following commands, replacing <INDEXER_NODE_NAME> with the name of the Wazuh indexer node you are configuring as defined in config.yml. For example, node-1. This deploys the SSL certificates to encrypt communications between the Wazuh central components.

NODE_NAME=<INDEXER_NODE_NAME>

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 -n /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv -n /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
chmod 500 /etc/wazuh-indexer/certs
chmod 400 /etc/wazuh-indexer/certs/*
chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/certs

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

Starting the service

Enable and start the Wazuh indexer service.

Systemd

systemctl daemon-reload
systemctl enable wazuh-indexer
systemctl start 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.

   curl -k -u admin:admin https://$WAZUH_INDEXER_IP_ADDRESS:9200
   

   Output

   {
     "name" : "node-1",
     "cluster_name" : "wazuh-cluster",
     "cluster_uuid" : "095jEW-oRJSFKLz5wmo5PA",
     "version" : {
       "number" : "7.10.2",
       "build_type" : "rpm",
       "build_hash" : "db90a415ff2fd428b4f7b3f800a51dc229287cb4",
       "build_date" : "2023-06-03T06:24:25.112415503Z",
       "build_snapshot" : false,
       "lucene_version" : "9.6.0",
       "minimum_wire_compatibility_version" : "7.10.0",
       "minimum_index_compatibility_version" : "7.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 -k -u admin:admin 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.
• 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.

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"

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) — timeout in seconds for index and search operations.
• plugins.setup.backoff (Integer, default 15) — delay in seconds for the retry mechanism involving initialization tasks.
• 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. See Protecting sensitive configuration for the full disable-endpoint pattern shared with Content Manager.

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.
• plugins.content_manager.catalog.sync_interval (Integer, default 60, range 10–1440) — sync interval in minutes.
• 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 999, range 10–999) — 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.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) — enable the periodic sync job.
• 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 Security Analytics 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.

Security Analytics settings

The Security Analytics 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 and retention management for the finding history indices.
• 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 and retention management for the alert history indices.
• 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 (see Architecture).
• 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 Security Analytics 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. 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.

Indices

The following tables list the indices created by this plugin.

Stream indices

Stateful indices

Internal indices

These indices support the plugin’s own operation rather than storing Wazuh data directly:

Install

The wazuh-indexer-setup plugin is part of the official Wazuh Indexer packages and is installed by default. However, to manually install the plugin, follow the next steps.

Note: You need to use the wazuh-indexer or root user to run these commands.

/usr/share/wazuh-indexer/bin/opensearch-plugin install file://[absolute-path-to-the-plugin-zip]

Once installed, restart the Wazuh Indexer service.

Uninstall

Note You need to use the wazuh-indexer or root user to run these commands.

To list the installed plugins, run: /usr/share/wazuh-indexer/bin/opensearch-plugin list

To remove a plugin, use its name as a parameter with the remove command: /usr/share/wazuh-indexer/bin/opensearch-plugin remove <plugin-name>

/usr/share/wazuh-indexer/bin/opensearch-plugin remove wazuh-indexer-setup

Architecture

Design

The plugin hooks into the node’s startup lifecycle and creates every required index template, index, and data stream before the node is considered ready to serve Wazuh data. By design, the plugin overwrites any existing index template under the same name, so template changes shipped in a new version take effect automatically on restart.

Retry mechanism

The plugin features a retry mechanism to handle transient faults. In case of a temporal failure (timeouts or similar) during the initialization of the indices, the task is retried after a given amount of time (back-off). If two consecutive faults occur during the initialization of the same index, the initialization process is halted, and the node is shut down. Proper logging is in place to notify administrators before the shutdown occurs.

The back-off time is configurable. Head to Configuration for more information.

Readiness marker

The plugin persists its initialization state in the hidden, single-document .wazuh-setup-status index. Other plugins (currently Content Manager) read this marker to defer their own startup work until Setup has finished creating its indices, avoiding races where a dependent index template doesn’t exist yet.

The marker transitions once per boot:

Writing the marker is best-effort: a failure to persist it is logged but never interrupts node startup.

Readiness marker

The plugin persists its initialization state in a hidden, single-document index, .wazuh-setup-status, managed by the SetupStatusIndex class. Other plugins (currently the Content Manager) read this marker to defer their own startup work until Setup has finished creating its indices, avoiding races where a dependent index template doesn’t exist yet.

The marker transitions once per boot:

Writing the marker is best-effort: a failure to persist it is logged but never interrupts node startup.

Replica configuration

During the node initialization, the plugin checks for the presence of the cluster.default_number_of_replicas setting in the node configuration. If this setting is defined, the plugin automatically updates the cluster’s persistent settings with this value. This ensures that the default number of replicas is consistently applied across the cluster as defined in the configuration file.

Wazuh Common Schema

Refer to the docs for complete definitions of the indices. The indices inherit the settings and mappings defined in the index templates.

Event stream templates

All event categories share a single base template. One index template per category is generated dynamically at deployment time from this shared base. Specialized streams (raw, active-responses) use their own dedicated template files.

The WCS field definitions are organized under wcs/stateless/events/:

wcs/stateless/events/
├── findings/   # Fields for findings events
├── main/       # Shared fields for all event categories
└── raw/        # Fields for raw (unprocessed) events

For the underlying class structure and implementation details, see the development guide.

Configuration

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) — timeout in seconds for index and search operations.
• plugins.setup.backoff (Integer, default 15) — delay in seconds for the retry mechanism involving initialization tasks.
• 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. See Protecting sensitive configuration for the full disable-endpoint pattern shared with Content Manager.

API reference

The Setup plugin exposes a REST API under /_plugins/_setup/. All endpoints require authentication.

Settings

Update settings

Persists configuration settings to the .wazuh-settings index. Currently, it supports the engine.index_raw_events boolean flag, which controls whether the Engine indexes raw events into the wazuh-events-raw-v5 data stream.

Request

• Method: PUT
• Path: /_plugins/_setup/settings

Request body

• engine (Object, required) — Engine settings object.
• engine.index_raw_events (Boolean, required) — whether the Engine indexes raw events into the wazuh-events-raw-v5 data stream.

Example request

curl -sk -u admin:admin -X PUT \
  "https://127.0.0.1:9200/_plugins/_setup/settings" \
  -H 'Content-Type: application/json' \
  -d '{
    "engine": {
      "index_raw_events": true
    }
  }'

Example response (success)

{
  "message": "Settings updated successfully.",
  "status": 200
}

Example response (missing field)

{
  "message": "Missing required field: 'engine.index_raw_events'.",
  "status": 400
}

Example response (invalid type)

{
  "message": "Field 'engine.index_raw_events' must be of type boolean.",
  "status": 400
}

Status codes

• 200 — settings updated successfully.
• 400 — invalid request body, missing required fields, or wrong field type.
• 500 — internal server error (e.g., failed to persist settings to the index).

Documentation maintenance — modifications to the REST API must be reflected in both openapi.yml and this file.

Wazuh Common Schema

The Wazuh Common Schema (WCS) is a standardized structure for organizing and categorizing security event data collected by Wazuh. It is designed to facilitate data analysis, correlation, and reporting across different data sources and types.

This page documents the event category taxonomy shared by the stateless event and finding data streams. WCS also covers stateful inventory indices (see Indices above), the metrics streams, and the content and CVE indices owned by the Content Manager plugin (see Content Manager) — those aren’t repeated here.

Categorization

The Wazuh Common Schema categorizes events into several key areas to streamline data management and analysis.

All event categories share a single base index template (events.json), and the same applies to findings categories with their own shared base (findings.json). At deployment time, the setup plugin generates one index template per category from the applicable shared base, overriding only two fields: index_patterns (set to wazuh-events-v5-<category>* or wazuh-findings-v5-<category>*) and, where present in the base template’s settings, rollover_alias (set to the category’s index name). The mappings are copied through unchanged — every category’s index template has identical mappings, since they all originate from the same base template. This means only one template file exists per stream family in the repository, but each category still gets its own index template registered in the cluster.

To list all deployed event templates:

GET /_index_template/wazuh-events-*

Categories

The Key column is the canonical identifier used throughout the system — in data stream names, integrations, rules, decoders, and the Security Analytics plugin. Use it exactly as shown when creating or referencing any of these resources.

Data streams

Each category maps to a dedicated data stream following the pattern wazuh-events-v5-{key}:

Events

wazuh-events-v5-access-management
wazuh-events-v5-applications
wazuh-events-v5-cloud-services
wazuh-events-v5-network-activity
wazuh-events-v5-other
wazuh-events-v5-security
wazuh-events-v5-system-activity
wazuh-events-v5-unclassified

Findings

wazuh-findings-v5-access-management
wazuh-findings-v5-applications
wazuh-findings-v5-cloud-services
wazuh-findings-v5-network-activity
wazuh-findings-v5-other
wazuh-findings-v5-security
wazuh-findings-v5-system-activity
wazuh-findings-v5-unclassified

Check Stream indices for details.

Content Manager

The Content Manager is a Wazuh Indexer plugin responsible for managing detection content — rules, decoders, integrations, key-value databases (KVDBs), and Indicators of Compromise (IoCs). It synchronizes content from the Wazuh Cyber Threat Intelligence (CTI) API, provides a REST API for user-generated content, and communicates with the Wazuh Engine to activate changes.

It also includes the Update check system, which communicates with the CTI Update check API once per day to let Wazuh determine whether a newer Wazuh version is available for the deployment.

Update check components are:

• Update check API (CTI)
• Update check system (Wazuh Indexer)
• Update check UI (Wazuh Dashboard)

Content synchronization

The Content Manager synchronizes three categories of detection content from the Wazuh CTI API, each updated independently:

• Catalog content — detection rules, decoders, integrations, key-value databases (KVDBs), and the routing policy.
• IoC feed — Indicators of Compromise (IoC) for threat detection enrichment.
• CVE feed — Common Vulnerabilities and Exposures (CVE) data for vulnerability detection. CVE entries are only added or updated, never removed.

On first start, the plugin initializes from a snapshot. If a custom CTI catalog URL is configured, it downloads the snapshot from that source; otherwise it uses the snapshot bundled with the Wazuh Indexer package, so detection content is available immediately even without network access.

Once initialized, the plugin keeps content current automatically. A sync check runs at startup and again on a regular schedule — every 60 minutes by default. Each check fetches only the changes since the last sync: new or updated resources are added, removed resources are deleted. If the local content cannot be reconciled with the remote state, the plugin recovers by re-downloading the latest snapshot.

Both behaviors are configurable in opensearch.yml:

• plugins.content_manager.catalog.update_on_start (Boolean, default true) — whether to check for updates when the plugin starts.
• plugins.content_manager.catalog.sync_interval (Integer, default 60) — how often periodic sync runs, in minutes.

When telemetry is enabled (the default), the plugin also sends a daily heartbeat to the Wazuh CTI service with the cluster UUID and the deployed Wazuh version. This powers the update notification shown in the Wazuh Dashboard when a newer release is available. To opt out, set plugins.content_manager.telemetry.enabled to false.

User-generated content

The Content Manager provides a full CUD (create, update, delete) REST API for creating custom detection content:

• Rules: custom detection rules associated with an integration.
• Decoders: custom log decoders associated with an integration.
• Integrations: logical groupings of related rules, decoders, and KVDBs.
• KVDBs: key-value databases used by rules and decoders for lookups.

User-generated content is stored in the draft space and is separate from the CTI-managed standard space. This separation ensures that user customizations never conflict with upstream CTI content.

See the API reference for endpoint details.

Content spaces

The Content Manager organizes content into spaces:

Content flows through spaces in a promotion chain: Draft → Test → Custom. The Standard space exists independently as the upstream CTI baseline. Each space maintains its own copies of rules, decoders, integrations, KVDBs, filters, and the routing policy within the system indices.

Policy management

The routing policy defines how the Wazuh Engine processes incoming events — which integrations are active and in what order. The Content Manager provides an API to update the draft policy:

curl -sk -u admin:admin -X PUT \
  "https://127.0.0.1:9200/_plugins/_content_manager/policy" \
  -H 'Content-Type: application/json' \
  -d '{"resource": { ... }}'

Policy changes are applied to the draft space and take effect after promotion.

Promotion workflow

The promotion workflow moves content through the space chain (Draft → Test → Custom):

1. Preview changes: GET /_plugins/_content_manager/promote?space=draft returns a diff of what will change (additions, updates, deletions for each content type).
2. Execute promotion: POST /_plugins/_content_manager/promote promotes the content from the source space to the next space in the chain.

The promotion chain works as follows:

• Draft → Test: content is promoted for validation and logtest operations.
• Test → Custom: once validated, content is promoted to the Custom space where it becomes active — the Wazuh Engine (via the manager package) uses this space to decode and process logs in production.

During promotion, the Content Manager:

• Sends updated content to the Engine
• Validates the configuration
• Triggers a configuration reload
• Updates the target space to reflect the promoted content

Engine communication

The Content Manager communicates with the Wazuh Engine through a Unix domain socket located at:

/usr/share/wazuh-indexer/engine/sockets/engine-api.sock

This socket is used for:

• Logtest: sends a log event to the Engine for analysis and returns the decoded/matched result.
• Content validation: validates rules and decoders before promotion.
• Configuration reload: signals the Engine to reload its configuration after promotion.

System indices

The Content Manager uses the following system indices:

For the alias-backed blue/green storage details and the exact hidden/alias status of each index, see the development guide’s system indices table.

Wazuh Cloud subscription

To synchronize content from the CTI API, the Wazuh Indexer requires a valid CTI access token. The token is registered via the REST API:

1. Store credentials by sending the CTI access token via POST /_plugins/_content_manager/subscription. The token is persisted in the .wazuh-internal-state hidden index and loaded into memory.
2. The Content Manager uses the in-memory token for all CTI API requests.
3. Without a registered token, sync operations return a 404 Token not found error.

See Subscription management in the API reference.

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.

Architecture

The Content Manager plugin operates within the Wazuh Indexer environment. It is composed of several components that handle REST API requests, background job scheduling, content synchronization, user-generated content management, and Engine communication.

Components

REST layer

Exposes HTTP endpoints under /_plugins/_content_manager/ for:

• Subscription management (store CTI access token)
• Manual content sync trigger
• Version check
• CUD operations on rules, decoders, integrations, filters, and KVDBs
• Policy management
• Promotion preview and execution
• Logtest execution (combined, normalization-only, and detection-only)
• Space reset

Credentials store

Manages the CTI access token used for all CTI API requests. The token is submitted via POST /subscription, persisted in the .wazuh-internal-state hidden index, and cached in memory. On node startup, the token is loaded from the index into memory. Without a registered token, sync and update operations are rejected.

All HTTP clients that communicate with CTI services send a custom User-Agent header in the format Wazuh Indexer <version> (e.g., Wazuh Indexer 5.0.0). This applies to the Catalog API client, Snapshot client, and Telemetry client.

Job scheduler

Registers a periodic job that triggers content synchronization at a configurable interval (default: 60 minutes). The job metadata is stored in .wazuh-content-manager-jobs.

Update check service

Runs a daily heartbeat job that calls the CTI Update check API endpoint (/ping).

• Enabled by default through plugins.content_manager.telemetry.enabled.
• Can be toggled at runtime because it is a dynamic setting.
• Sends deployment metadata required for update checks (cluster UUID, deployed Wazuh version, and user-agent).
• Job metadata is stored in .wazuh-content-manager-jobs.
• The first ping is dispatched immediately after the job is registered in the scheduler; subsequent runs follow the 1-day interval.

Consumer service

Orchestrates synchronization for each catalog consumer type (ruleset, IoCs, vulnerabilities). Compares local offsets (from .wazuh-cti-consumers) with remote offsets from the CTI API, then delegates to either the snapshot service or the update service. Tracks the sync lifecycle through the status field in .wazuh-cti-consumers — see Index structure below for the status values.

Snapshot service

Handles initial content loading. Initializes from either a remote CTI snapshot (when a custom consumer URL is configured) or a local packaged snapshot, then extracts and bulk-indexes content into the appropriate system indices. Performs data enrichment (e.g., converting JSON payloads to YAML for decoders).

Update service

Handles incremental updates. Fetches change batches from the CTI API based on offset differences and applies create, update, and delete operations to content indices.

Security Analytics service

Interfaces with the Security Analytics plugin. Creates, updates, and deletes Security Analytics rules, integrations, and detectors to keep them in sync with CTI content.

Dynamic configuration: instead of using hardcoded defaults, the service extracts the enabled state, interval, and source index patterns directly from the CTI integration payload. This allows CTI to control detector behavior dynamically.

Document ID model: Security Analytics documents use their own auto-generated UUIDs as primary IDs, independent of the CTI document UUIDs. Each Security Analytics document stores the UUID of the original CTI document and the space it belongs to (draft, test, custom, or standard), so the same CTI resource can exist across multiple spaces without ID collisions.

Note: Security Analytics enforces a configurable maximum number of rules per detector (plugins.security_analytics.max_rules_per_detector, default 50). If an integration has more enabled rules than the configured limit, the detector creation or update request will be rejected. See Security Analytics — Detector constraints for details.

Space service

Manages the four content spaces (standard, draft, test, custom). Routes CUD operations to the correct space partitions within system indices. Handles promotion by computing diffs between spaces in the promotion chain (draft → test → custom).

Engine client

Communicates with the Wazuh Engine via Unix domain socket at /usr/share/wazuh-indexer/engine/sockets/engine-api.sock. Used for logtest execution, content validation, and configuration reload.

Data flows

CTI sync (snapshot)

Job scheduler triggers
  → Consumer service checks .wazuh-cti-consumers (offset = 0)
  → If custom catalog URL is configured: try remote snapshot first
  → If remote init fails: fallback to local packaged snapshot
  → If no custom catalog URL: initialize from local packaged snapshot
  → Extracts and bulk-indexes into wazuh-threatintel-rules, wazuh-threatintel-decoders, etc.
  → Updates .wazuh-cti-consumers with new offset
  → Security Analytics service creates detectors using dynamic CTI configuration (max rules per detector configurable, default 50)

CTI sync (incremental)

Job scheduler triggers
  → Consumer service checks .wazuh-cti-consumers (local_offset < remote_offset)
  → Update service fetches change batches from CTI API
  → Applies create/update/delete operations to content indices
  → Updates .wazuh-cti-consumers offset
  → Security Analytics service syncs changes

Update check heartbeat

Registration (on node start or dynamic enable)
  → Heartbeat job document indexed in .wazuh-content-manager-jobs
  → Immediate first ping fired once the document is written

Job scheduler triggers (every 24h thereafter)
  → Checks plugins.content_manager.telemetry.enabled
  → Reads cluster UUID and current Wazuh version
  → Sends GET /ping to CTI Update check API
  → Wazuh Dashboard can surface update availability to users

User-generated content (CUD)

REST request (POST/PUT/DELETE)
  → Space service routes to draft space
  → Writes to wazuh-threatintel-rules / wazuh-threatintel-decoders / wazuh-threatintel-integrations / wazuh-threatintel-kvdbs
  → Returns created/updated/deleted resource

Standard policy Engine loading

The local Wazuh Engine must always reflect the latest version of the standard space policy. Whenever the standard space policy hash changes, the full policy — including all referenced integrations, decoders, KVDBs, filters, and rules — is built and sent to the Engine for loading.

The policy hash is an aggregate SHA-256 computed from the individual hashes of the policy and every resource it references. Any change to the policy will trigger a reload. These changes include:

• New or updated integrations, decoders, rules, KVDBs, or filters (via CTI sync)
• Changes to policy settings (enabled, index_unclassified_events, index_discarded_events)
• Changes to the enrichment types list
• Reordering of the filters list

The engine load is best-effort: if the Engine is unreachable, the error is logged but the operation (sync or REST update) still succeeds.

Promotion

GET /promote?space=draft
  → Space service computes diff (draft vs test, or test vs custom)
  → Returns changes preview (adds, updates, deletes per content type)

POST /promote
  → Capture pre-promotion snapshots of target-space resources
  → Engine validates configuration (draft → test only, and only when the
    changeset includes decoders, kvdbs, or filters — promotions limited to
    integrations, rules, or the policy skip the engine call)
  → Consolidate changes to Content Manager indices (tracked for rollback)
      → Apply adds/updates: policy, integrations, kvdbs, decoders, filters, rules
      → Apply deletes: integrations, kvdbs, decoders, filters, rules
  → Sync integrations and rules to Security Analytics:
      → Adds use POST (new document)
      → Updates use PUT (existing document)
  → Delete removed integrations/rules from Security Analytics

Rollback on failure

If any Content Manager index mutation fails during the consolidation phase, the promotion endpoint automatically performs a last-in-first-out (LIFO) rollback to restore the system to its pre-promotion state.

Pre-promotion snapshots

Before any writes, the system captures:

• Old versions: for each resource being added or updated, the current target-space version is fetched and stored. If the resource does not exist in the target space, no version is stored.
• Delete snapshots: for each resource being deleted, the full document is fetched from the source space and stored.

Content Manager index rollback

Each successful index mutation is recorded as a rollback step. On failure, steps are replayed in strict reverse (LIFO) order:

Individual rollback step failures are logged and skipped so remaining steps can proceed.

Security Analytics reconciliation

After the Content Manager rollback completes, a best-effort Security Analytics reconciliation runs in dependency order:

1. Revert applied rules — adds are deleted from Security Analytics; updates are restored to the old version.
2. Revert applied integrations — same as above.
3. Restore deleted integrations — re-created from pre-deletion snapshots via POST.
4. Restore deleted rules — same as above.

Security Analytics reconciliation failures are logged as warnings but do not cause the overall rollback to fail, since the sync is considered best-effort.

Consolidation fails at step N
  → LIFO rollback: undo step N-1, N-2, ..., 1
      → Add + no old version → delete from target index
      → Add/update + old version → restore old version to target index
      → Delete → re-index snapshot to target index
  → Security Analytics reconciliation (best-effort):
      → Delete rules that were added
      → Restore rules that were updated
      → Restore integrations that were added/updated
      → Re-create integrations/rules that were deleted
  → Return 500 with error message

Plan change handling (blue/green swap)

When a subscription plan changes (e.g., free → pro, or vice versa), all downloaded content must be replaced with the content matching the new plan. The Content Manager uses a blue/green index swap to perform this replacement without any user-visible downtime.

How it works

1. Detection. During each sync cycle, the Content Manager compares the plan-provided catalog URL against the one stored locally. If they differ, a plan change is detected.
2. Shadow download. New content is downloaded into hidden staging indices. These shadow indices are invisible to users, dashboards, and REST queries during the rebuild.
3. User content preservation. Any user-created content (draft rules, test decoders, custom integrations, etc.) is copied from the live indices into the shadow indices.
4. Atomic switch. Once the shadow indices are fully ready, all index aliases are swapped in a single atomic operation. Users see either the entire old content or the entire new content — never a mix or an empty state.
5. Cleanup. The old indices are deleted, freeing the temporary disk space.

Failure behavior

If the new content cannot be downloaded or processed (network error, source unavailable, etc.), the swap is abandoned cleanly: the staging indices are discarded, users continue to see the old content, and the system retries on the next scheduled sync. A failed swap is invisible to the end user.

Index structure

Each content index (e.g., wazuh-threatintel-rules) is backed by an alias. The public alias name is the stable identifier used by all queries, dashboards, and REST APIs. The actual data lives in a physical index suffixed with -a or -b:

Only one physical index is live at a time. The other is reserved as the staging slot for the next plan-change swap. Administrators and users should always address indices by their alias name — the physical suffix is an internal implementation detail.

Each content index stores documents from all spaces. Documents are differentiated by internal metadata fields that indicate their space membership. The document _id is a UUID assigned at creation time.

Example document structure in wazuh-threatintel-rules:

{
  "_index": "wazuh-threatintel-rules-a",
  "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "_source": {
    "title": "SSH brute force attempt",
    "integration": "openssh",
    "space.name": "draft",
    ...
  }
}

The .wazuh-cti-consumers index stores one document per consumer type:

{
  "_index": ".wazuh-cti-consumers",
  "_id": "cti:catalog:consumer:ruleset",
  "_source": {
    "name": "public-ruleset-5",
    "context": "beta-2-ruleset-5",
    "type": "cti:catalog:consumer:ruleset",
    "resource": "https://api.pre.cloud.wazuh.com/api/v1/catalog/contexts/beta-2-ruleset-5/consumers/public-ruleset-5",
    "is_public": true,
    "status": "ready",
    "local_offset": 3932,
    "remote_offset": 3932
  }
}

The status field reflects the consumer’s synchronization lifecycle:

The status is set to running at the very start of a sync cycle and transitions to ready after all post-sync work finishes — including hash recalculation, Security Analytics Plugin synchronization, and Engine IoC notification — or to failed if an unexpected exception interrupts the cycle. The job scheduler logs the failure and retries on the next scheduled run regardless of the consumer’s status.

Configuration

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.
• plugins.content_manager.catalog.sync_interval (Integer, default 60, range 10–1440) — sync interval in minutes.
• 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 999, range 10–999) — 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.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) — enable the periodic sync job.
• 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 Security Analytics 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.

Offline configuration / disabling automatic updates

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

On online installations, manual synchronization can be performed on demand using the Content Manager API:

POST /_plugins/_content_manager/update"

Custom scheduled synchronization interval

The plugin checks for new content every 60 minutes by default, but this can be customized by changing the plugins.content_manager.catalog.sync_interval setting. The value is specified in minutes and must be between 10 and 1440 (24 hours).

# opensearch.yml
plugins.content_manager.catalog.sync_interval: 1440

Setup readiness wait (startup race)

On node startup, the catalog sync job waits for the Setup plugin to finish creating its indices (signaled by the .wazuh-setup-status marker document) before it runs. If Setup has not finished within that wait, the sync is skipped for that run and deferred to the next scheduled run (plugins.content_manager.catalog.sync_interval minutes later, an hour by default) — on a slow-starting node (e.g. cluster still recovering shards), this can leave .wazuh-cti-consumers and the CTI content indices empty for up to that long.

The wait uses exponential backoff, controlled by plugins.content_manager.setup_wait.max_retries and plugins.content_manager.setup_wait.backoff_base_seconds. With the defaults (4 retries, 20s base), the schedule is 20s, 40s, 80s, 160s — 300s (5 min) total before giving up. Increase these on environments where Setup is known to take longer to initialize:

# opensearch.yml
plugins.content_manager.setup_wait.max_retries: 4
plugins.content_manager.setup_wait.backoff_base_seconds: 30

The example above raises the total worst-case wait to 30+60+120+240 = 450s (7.5 min).

CTI rate-limit retries (HTTP 429)

When the CTI API rate-limits a request it responds with HTTP 429 and a Retry-After header. The HTTP client honors that header: it waits the indicated time and retries the request, so a rate-limit no longer fails the synchronization pass. If the response carries no usable Retry-After header, it falls back to exponential backoff (base * 2^n).

The behavior is controlled by plugins.content_manager.client.max_retries and plugins.content_manager.client.retry_backoff_base_seconds. With the defaults (3 retries, 30s base), the fallback schedule is 30s, 60s, 120s — 210s (3.5 min) worst case before the 429 is surfaced and the pass defers to the next scheduled run:

# opensearch.yml
plugins.content_manager.client.max_retries: 3
plugins.content_manager.client.retry_backoff_base_seconds: 30

The Retry-After header, when present, always takes precedence over the backoff base — the base applies only when the header is missing or unparseable.

Custom CTI API endpoint

To point to a different CTI API (e.g., production):

# opensearch.yml
plugins.content_manager.cti.api: "https://cti.wazuh.com/api/v1"

Custom catalog consumer URLs

To override default consumers, provide full HTTP(S) consumer URLs:

# opensearch.yml
plugins.content_manager.catalog.ruleset: "https://api.pre.cloud.wazuh.com/api/v1/catalog/contexts/beta-2-ruleset-5/consumers/public-ruleset-5"
plugins.content_manager.catalog.iocs: "https://api.pre.cloud.wazuh.com/api/v1/catalog/contexts/t1-iocs-5/consumers/public-iocs-5"
plugins.content_manager.catalog.vulnerabilities: "https://api.pre.cloud.wazuh.com/api/v1/catalog/contexts/t1-vulnerabilities-5/consumers/public-vulnerabilities-5"

Behavior:

• If a setting is non-empty, Content Manager attempts remote snapshot initialization first.
• If remote initialization fails, it falls back to the local packaged snapshot when available.
• If a setting is empty, initialization uses the local packaged snapshot directly.

Tune bulk operations

For environments with limited resources, reduce the bulk operation concurrency:

# opensearch.yml
plugins.content_manager.max_items_per_bulk: 10
plugins.content_manager.max_concurrent_bulks: 2
plugins.content_manager.client.timeout: 30

Disable Security Analytics detector creation

If you do not use the OpenSearch Security Analytics plugin:

# opensearch.yml
plugins.content_manager.catalog.create_detectors: false

CTI communication headers

All HTTP clients that communicate with Wazuh CTI services send a custom User-Agent header:

User-Agent: Wazuh Indexer <version>

For example: Wazuh Indexer 5.0.0. This applies to the Console API client, Catalog API client, Snapshot client, and Telemetry client. The version is read from VERSION.json at plugin startup.

Update check service behavior

The update check service is enabled by default and runs once per day, with an immediate first ping fired as soon as the job is registered in the scheduler.

• It is implemented by a scheduled job (wazuh-telemetry-ping-job) in .wazuh-content-manager-jobs.
• It sends a request to the CTI Update check API endpoint (/ping).
• The request includes:
  • Deployment identifier (wazuh-uid: cluster UUID)
  • Running version (wazuh-tag: v<version>)
  • User agent (Wazuh Indexer <version>)

This data allows Wazuh to determine if a newer version is available and notify users in the update check UI.

The service only sends deployment identification/version metadata required for update checks. It does not send rules, events, or log payloads.

Enable or disable the update check service dynamically

The update check service can be enabled or disabled at runtime without restarting the node using the Cluster Settings API:

curl -sk -u admin:admin -X PUT "https://192.168.56.6:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "plugins.content_manager.telemetry.enabled": false
  }
}'

Protecting sensitive configuration

Some endpoints modify configuration with a high impact on the platform and are protected by two independent controls:

• PUT /_plugins/_content_manager/policy/{space} — permission cluster:admin/content_manager/policy/update.
• POST /_plugins/_content_manager/update — permission cluster:admin/content_manager/update/trigger.
• PUT /_plugins/_setup/settings — permission plugin:wazuh/settings/write.

1. RBAC — each endpoint is gated by a cluster permission (the action name above), enforced by the security plugin. Among the bundled users, only wazuh-admin holds these permissions; wazuh-manager, wazuh-demo and wazuh-readonly are excluded. The superuser admin (role all_access, cluster wildcard *) also holds them. To delegate any of these actions without granting full superuser, create a dedicated role for the permission(s) above. See the access control reference.

2. Per-endpoint disable settings — each endpoint can be disabled independently with its own node setting; when disabled it returns 403 Forbidden for every caller, including admin / all_access. This is intended for externally managed (e.g. Wazuh Cloud) deployments.

   • POST /_plugins/_content_manager/update — disable via plugins.content_manager.catalog.update_on_demand: false.
   • PUT /_plugins/_content_manager/policy/{space} — disable via plugins.content_manager.catalog.policy_update.enabled: false.
   • PUT /_plugins/_setup/settings — disable via plugins.setup.settings_update.enabled: false.

# opensearch.yml — disable sensitive configuration endpoints on a managed deployment
plugins.content_manager.catalog.update_on_demand: false
plugins.content_manager.catalog.policy_update.enabled: false
plugins.setup.settings_update.enabled: false

Resource creation limits

The plugin enforces configurable upper bounds on the number of resources that can be created. Each limit applies to POST (creation) requests only — existing resources are not affected when a limit is lowered. The count is checked against the relevant index at request time; if the index does not yet exist, the check is skipped and creation proceeds.

All limit settings are dynamic and can be changed at runtime:

curl -X PUT "https://localhost:9200/_cluster/settings" \
  -H 'Content-Type: application/json' \
  -d '{
    "persistent": {
      "plugins.content_manager.max_integrations": 50,
      "plugins.content_manager.max_decoders": 100,
      "plugins.content_manager.max_rules": 100,
      "plugins.content_manager.max_kvdbs": 50,
      "plugins.content_manager.max_filters": 50
    }
  }'

Setting a limit to 0 blocks all new creation of that resource type.

Notes

• Changes to opensearch.yml require a restart of the Wazuh Indexer to take effect, except for dynamic settings, which can be updated at runtime via the OpenSearch API. Dynamic settings include plugins.content_manager.telemetry.enabled and all five resource creation limits (max_integrations, max_decoders, max_rules, max_kvdbs, max_filters).
• The catalog URL settings (plugins.content_manager.catalog.ruleset, plugins.content_manager.catalog.iocs, and plugins.content_manager.catalog.vulnerabilities) should only be changed if instructed by Wazuh support or documentation, and must point to valid absolute HTTP(S) CTI consumer endpoints.
• The sync interval is enforced by the OpenSearch Job Scheduler. The actual sync timing may vary slightly depending on cluster load.
• The update check service runs with a fixed interval of 1 day when enabled. The first ping is sent immediately after the job is registered (on node start or when the setting is dynamically enabled); subsequent pings follow the 1-day interval.
• Detector configuration: the settings for Security Analytics detectors (interval, enabled status, and source indices) are managed directly via CTI integration files. If an integration’s detector object is missing in the CTI source, the system will use built-in safety defaults.

API reference

The Content Manager plugin exposes a REST API under /_plugins/_content_manager/. All endpoints require authentication. The full machine-readable specification is available in openapi.yml.

Sections

• Timestamps on create and update
• YAML content-type support
• Subscription management
• Content updates
• Logtest
• Policy
• Rules
• Decoders
• Filters
• Integrations
• KVDBs
• Promotion
• Spaces
• Version check

Timestamps on create and update

Rules, decoders, filters, integrations, KVDBs, and the policy all accept optional date and modified fields inside their metadata object, but the two fields behave differently depending on whether the request is a create or an update:

• On create — both date and modified are optional. If provided, the value is used as-is; if omitted, the server generates it from the current time.
• On update — date is always read-only: any caller-supplied value is ignored, and the resource’s original creation date is preserved from the existing document. modified still accepts a caller-supplied value; if omitted, the server generates it from the current time.

If provided, either value is stored as-is — the plugin does not validate or reformat it beyond what the underlying index mapping requires (strict_date_optional_time||epoch_millis). A malformed value fails the request with 400 Bad Request.

YAML content-type support

The Decoders, KVDBs, and Filters endpoints accept requests with Content-Type: application/yaml in addition to the standard Content-Type: application/json. When using YAML, the request body uses the same envelope structure as JSON — the only difference is the serialization format.

Envelope structure

Both JSON and YAML requests use the same envelope:

JSON example

{
  "integration": "<uuid>",
  "resource": {
    "metadata": { "title": "My Decoder", "author": "Wazuh" },
    "name": "decoder/my-decoder/0",
    "enabled": true
  }
}

Equivalent YAML example

---
integration: <uuid>
resource:
  metadata:
    title: "My Decoder"
    author: "Wazuh"
  name: decoder/my-decoder/0
  enabled: true

For resource types that do not require an integration field (e.g., Filters, which use space instead), the corresponding field appears at the top level of the envelope in both formats.

YAML field in responses

When a Decoder, KVDB, or Filter is created or updated, a yaml field is stored alongside the document in the indexed record. This field contains a YAML representation of the resource content:

• YAML requests: the yaml field is generated from the resource subtree of the parsed envelope.
• JSON requests: the yaml field is auto-generated from the resource content.

Type fidelity

YAML parsing preserves numeric type fidelity. Floating-point values like 5.0 are stored as 5.0 in both the yaml field and the document field — they are not coerced to integers.

Supported endpoints

• /_plugins/_content_manager/decoders (POST, PUT) — YAML supported.
• /_plugins/_content_manager/kvdbs (POST, PUT) — YAML supported.
• /_plugins/_content_manager/filters (POST, PUT) — YAML supported.
• /_plugins/_content_manager/integrations (POST, PUT) — JSON only.
• /_plugins/_content_manager/rules (POST, PUT) — JSON only.
• /_plugins/_content_manager/policy/{space} (PUT) — JSON only.

Subscription management

Store CTI credentials

Stores the provided CTI access token in the .wazuh-internal-state hidden index and loads it into memory. If the index does not exist it is recreated automatically before writing.

Request

• Method: POST
• Path: /_plugins/_content_manager/subscription

Request body

• access_token (String, required) — the CTI access token used to authenticate against the CTI API.

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/subscription" \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"
  }'

Example response

{
  "message": "Credentials received",
  "status": 201
}

Status codes

• 201 — credentials stored successfully.
• 400 — missing or empty access_token field.
• 412 — a required precondition is not met (for example, the credentials index is not declared as a system index — see plugins.security.system_indices.indices in opensearch.yml).
• 500 — internal error.

Get CTI subscription status

Returns the current subscription status and active plan. For registered instances the plan comes from the authenticated CTI endpoint; for unregistered instances, the public free plan is returned.

If the stored token is rejected by the CTI API (e.g. expired or revoked), the credentials document is deleted automatically, the in-memory token is cleared, and the response falls back to the public free plan as if the instance were unregistered.

Request

• Method: GET
• Path: /_plugins/_content_manager/subscription

Example request

curl -sk -u admin:admin -X GET \
  "https://127.0.0.1:9200/_plugins/_content_manager/subscription"

Example response (registered)

{
  "message": {
    "plan": {
      "name": "Premium Plan",
      "is_public": false
    },
    "is_registered": true
  },
  "status": 200
}

Example response (unregistered)

{
  "message": {
    "plan": {
      "name": "Free",
      "is_public": true
    },
    "is_registered": false
  },
  "status": 200
}

Status codes

• 200 — subscription status returned successfully.
• 500 — internal error.

Delete CTI credentials

Clears the stored CTI access token document from the credentials index and clears the in-memory token. The credentials index is preserved. After this operation the instance is unregistered. If the credentials index does not exist the operation succeeds without error.

Request

• Method: DELETE
• Path: /_plugins/_content_manager/subscription

Example request

curl -sk -u admin:admin -X DELETE \
  "https://127.0.0.1:9200/_plugins/_content_manager/subscription"

Example response

{
  "message": "Credentials removed",
  "status": 200
}

Status codes

• 200 — credentials removed successfully.
• 500 — internal error.

Content updates

Trigger manual sync

Triggers an immediate content synchronization with the CTI API. Requires a valid subscription.

Request

• Method: POST
• Path: /_plugins/_content_manager/update

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/update"

Example response (accepted)

{
  "message": "The update request has been accepted for processing.",
  "status": 202
}

Example response (no credentials)

{
  "message": "Token not found. Please create a subscription before attempting to update.",
  "status": 404
}

Example response (update in progress)

{
  "message": "A content update is already in progress.",
  "status": 409
}

Status codes

• 202 — update request accepted for processing.
• 404 — no access token registered.
• 409 — a content update is already in progress.
• 500 — internal error during sync.

Logtest

Execute logtest

Sends a log event to the Wazuh Engine for analysis. If an integration ID is provided, the integration’s Sigma rules are also evaluated against the normalized event via the Security Analytics plugin. If integration is omitted, only the normalization step is performed and the detection section is returned with status: "skipped".

Note: A testing policy must be loaded in the Engine for logtest to execute successfully. Load a policy via the policy promotion endpoint. When an integration is specified, it must exist in the specified space.

Request

• Method: POST
• Path: /_plugins/_content_manager/logtest

Request body

• integration (String, optional) — ID of the integration to test against. If omitted, only normalization is performed.
• space (String, required) — "test", "standard", or "custom".
• queue (Integer, required) — queue number for logtest execution.
• location (String, required) — log file path or logical source location.
• event (String, required) — raw log event to test.
• metadata (Object, optional) — optional metadata passed to the Engine.
• trace_level (String, optional) — trace verbosity: NONE, ASSET_ONLY, or ALL.

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/logtest" \
  -H 'Content-Type: application/json' \
  -d '{
    "integration": "a0b448c8-3d3c-47d4-b7b9-cbc3c175f509",
    "space": "test",
    "queue": 1,
    "location": "/var/log/cassandra/system.log",
    "event": "INFO  [main] 2026-03-31 10:00:00 StorageService.java:123 - Node is ready to serve",
    "trace_level": "NONE"
  }'

Example response (success with rule match)

{
  "status": 200,
  "message": {
    "normalization": {
      "output": {
        "event": {
          "category": ["database"],
          "kind": "event",
          "original": "INFO  [main] 2026-03-31 10:00:00 StorageService.java:123 - Node is ready to serve"
        },
        "wazuh": {
          "integration": {
            "name": "test-integ",
            "category": "other",
            "decoders": ["decoder/cassandra-default/0"]
          }
        },
        "message": "Node is ready to serve"
      },
      "asset_traces": [],
      "validation": {
        "valid": true,
        "errors": []
      }
    },
    "detection": {
      "status": "success",
      "rules_evaluated": 2,
      "rules_matched": 1,
      "matches": [
        {
          "rule": {
            "id": "85bba177-a2e9-4468-9d59-26f4798906c9",
            "title": "Cassandra Database Event Detected",
            "level": "low",
            "tags": []
          },
          "matched_conditions": [
            "event.category matched 'database'",
            "event.kind matched 'event'"
          ]
        }
      ]
    }
  }
}

Example response (Engine error, detection skipped)

{
  "status": 200,
  "message": {
    "normalization": {
      "status": "error",
      "error": {
        "message": "Failed to parse protobuff json request: invalid value",
        "code": "ENGINE_ERROR"
      }
    },
    "detection": {
      "status": "skipped",
      "reason": "Engine processing failed"
    }
  }
}

Example response (no rules in integration)

{
  "status": 200,
  "message": {
    "normalization": {
      "output": { "..." : "..." },
      "asset_traces": [],
      "validation": { "valid": true, "errors": [] }
    },
    "detection": {
      "status": "success",
      "rules_evaluated": 0,
      "rules_matched": 0,
      "matches": []
    }
  }
}

Example request (normalization only, no integration)

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/logtest" \
  -H 'Content-Type: application/json' \
  -d '{
    "space": "test",
    "queue": 1,
    "location": "/var/log/syslog",
    "event": "Mar 31 10:00:00 myhost sshd[1234]: Accepted publickey for user from 192.168.1.1 port 22 ssh2",
    "trace_level": "NONE"
  }'

Example response (normalization only)

{
  "status": 200,
  "message": {
    "normalization": {
      "output": {
        "event": {
          "original": "Mar 31 10:00:00 myhost sshd[1234]: Accepted publickey for user from 192.168.1.1 port 22 ssh2"
        }
      },
      "asset_traces": [],
      "validation": { "valid": true, "errors": [] }
    },
    "detection": {
      "status": "skipped",
      "reason": "No integration provided"
    }
  }
}

Response fields

• normalization.output (Object) — Engine normalized event output.
• normalization.asset_traces (Array) — list of decoders that processed the event.
• normalization.validation (Object) — validation result (valid, errors).
• normalization.status (String) — present on error: "error".
• normalization.error (Object) — present on error: message and code.
• detection.status (String) — "success", "error", or "skipped".
• detection.reason (String) — present when status is "skipped".
• detection.rules_evaluated (Integer) — number of Sigma rules evaluated.
• detection.rules_matched (Integer) — number of rules that matched.
• detection.matches (Array) — list of matched rules with details.
• detection.matches[].rule (Object) — rule metadata: id, title, level, tags.
• detection.matches[].matched_conditions (Array) — human-readable descriptions of conditions that matched.

Status codes

• 200 — logtest executed (check inner status fields).
• 400 — missing/invalid fields or integration not found.
• 500 — Engine socket communication error or internal error.

Normalization only

Sends a log event to the Wazuh Engine for decoding and normalization without performing Sigma rule detection. Use this to validate that decoders correctly parse events before testing detection rules.

Note: A testing policy must be loaded in the Engine for normalization to execute successfully.

Request

• Method: POST
• Path: /_plugins/_content_manager/logtest/normalization

Request body

• space (String, required) — "test", "standard", or "custom".
• queue (Integer, optional) — queue number for logtest execution.
• location (String, optional) — log file path or logical source location.
• event (String, optional) — raw log event to normalize.
• metadata (Object, optional) — optional metadata passed to the Engine.
• trace_level (String, optional) — trace verbosity: NONE, ASSET_ONLY, or ALL.

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/logtest/normalization" \
  -H 'Content-Type: application/json' \
  -d '{
    "space": "test",
    "queue": 1,
    "location": "/var/log/cassandra/system.log",
    "metadata": {},
    "trace_level": "NONE",
    "event": "INFO  [CompactionExecutor-3] 2025-11-30 14:23:45 CassandraDaemon.java:250 - Some message - 7500 - 4"
  }'

Example response

{
  "status": 200,
  "message": {
    "output": {
      "log": {
        "level": "INFO",
        "origin": {
          "file": {
            "name": "CassandraDaemon.java",
            "line": 250
          }
        }
      },
      "wazuh": {
        "space": { "name": "test" },
        "protocol": { "location": "/var/log/cassandra/system.log", "queue": 1 },
        "integration": {
          "decoders": ["decoder/cassandra-default/0"],
          "name": "my-integration",
          "category": "other"
        }
      },
      "message": "Some message",
      "event": {
        "duration": 7500,
        "category": ["database"],
        "kind": "event",
        "severity": 4
      },
      "source": { "ip": "10.42.3.15" },
      "process": {
        "thread": { "name": "CompactionExecutor-3" }
      }
    },
    "asset_traces": [],
    "validation": {
      "valid": true,
      "errors": []
    }
  }
}

Response fields

• message.output (Object) — Engine normalized event output.
• message.asset_traces (Array) — list of decoders that processed the event.
• message.validation (Object) — validation result (valid, errors).

Status codes

• 200 — normalization executed successfully.
• 400 — missing/invalid fields.
• 500 — Engine socket communication error or internal error.

Detection only

Evaluates an already-normalized event against the Sigma rules of a given integration via the Security Analytics plugin. This endpoint does not call the Wazuh Engine — the normalized event must be provided directly in the input field.

Use this after obtaining a normalized event from the /logtest/normalization endpoint, or when you already have a normalized event and want to test different integrations’ rules against it.

Note: The integration must exist in the specified space. The input field must be a JSON object (the normalized event), not a raw log string.

Request

• Method: POST
• Path: /_plugins/_content_manager/logtest/detection

Request body

• space (String, required) — "test", "standard", or "custom".
• integration (String, required) — UUID of the integration whose rules to evaluate.
• input (Object, required) — normalized event object to evaluate rules against.

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/logtest/detection" \
  -H 'Content-Type: application/json' \
  -d '{
    "space": "test",
    "integration": "d3f3b0b8-4e25-4273-83ef-56a62003bcf7",
    "input": {
      "event": {
        "duration": 7500,
        "category": ["database"],
        "kind": "event",
        "severity": 4,
        "type": ["info"]
      },
      "source": { "ip": "10.42.3.15" },
      "process": {
        "thread": { "name": "CompactionExecutor-3" },
        "command_line": "/query tables"
      },
      "log": {
        "origin": {
          "file": { "name": "CassandraDaemon.java", "line": 250 }
        }
      }
    }
  }'

Example response (matches found)

{
  "status": 200,
  "message": {
    "status": "success",
    "rules_evaluated": 12,
    "rules_matched": 6,
    "matches": [
      {
        "rule": {
          "id": "4e52f215-bccc-4c0f-a37c-70606022be8e",
          "title": "TEST: Numeric gte+lt only",
          "level": "high",
          "tags": ["attack.execution", "attack.t1059"]
        },
        "matched_conditions": [
          "event.duration matched '>= 5000'",
          "event.severity matched '< 10'"
        ]
      },
      {
        "rule": {
          "id": "1d489ded-7523-4329-8cd0-ebb21865a318",
          "title": "TEST: Exact match event.kind=event",
          "level": "low",
          "tags": ["attack.execution", "attack.t1059"]
        },
        "matched_conditions": [
          "event.kind matched 'event'"
        ]
      }
    ]
  }
}

Example response (no rules in integration)

{
  "status": 200,
  "message": {
    "status": "success",
    "rules_evaluated": 0,
    "rules_matched": 0,
    "matches": []
  }
}

Response fields

• message.status (String) — "success" or "error".
• message.rules_evaluated (Integer) — number of Sigma rules evaluated.
• message.rules_matched (Integer) — number of rules that matched.
• message.matches (Array) — list of matched rules with details.
• message.matches[].rule (Object) — rule metadata: id, title, level, tags.
• message.matches[].matched_conditions (Array) — human-readable descriptions of matched conditions.

Status codes

• 200 — detection executed (check message.status).
• 400 — missing/invalid fields or integration not found.
• 500 — internal error.

Policy

Update policy

Updates the routing policy in the specified space. The policy defines which integrations are active, the root decoder, enrichment types, and how events are routed through the Engine.

Note: The integrations and filters arrays allow reordering but do not allow adding or removing entries — membership is managed via their respective CRUD endpoints.

Space-specific behavior

• Draft space (/policy/draft): all policy fields are accepted. The metadata fields author, description, documentation, and references are required in addition to the boolean fields.
• Standard space (/policy/standard): 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. If the update changes the space hash, the full standard policy is automatically loaded to the local Engine.

Request

• Method: PUT
• Path: /_plugins/_content_manager/policy/{space}

Path parameters

• space (String, required) — target space (draft or standard).

Request body

• resource (Object, required) — the policy resource object.

Fields within resource:

• metadata (Object, required in draft) — policy metadata (see below).
• root_decoder (String, optional) — identifier of the root decoder for event processing.
• integrations (Array, optional) — list of integration IDs (reorder only, no add/remove).
• filters (Array, optional) — list of filter UUIDs (reorder only, no add/remove).
• enrichments (Array, optional) — enrichment types (no duplicates; values depend on engine capabilities).
• enabled (Boolean, required) — whether the policy is active and synchronized by the Engine.
• index_unclassified_events (Boolean, required) — whether uncategorized events are indexed.
• index_discarded_events (Boolean, required) — whether discarded events are indexed.

Fields within resource.metadata:

• title (String, optional) — human-readable policy name.
• author (String, required in draft) — author of the policy.
• description (String, required in draft) — brief description.
• documentation (String, required in draft) — documentation text or URL.
• references (Array, required in draft) — external reference URLs.
• modified (String, optional) — see Timestamps on create and update. date cannot be modified here either; any caller-supplied value is ignored, and the policy’s original creation date is preserved.

Example request (draft space)

curl -sk -u admin:admin -X PUT \
  "https://127.0.0.1:9200/_plugins/_content_manager/policy/draft" \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": {
      "metadata": {
        "title": "Draft policy",
        "author": "Wazuh Inc.",
        "description": "Custom policy",
        "documentation": "",
        "references": [
          "https://wazuh.com"
        ]
      },
      "root_decoder": "",
      "integrations": [
        "f16f33ec-a5ea-4dc4-bf33-616b1562323a"
      ],
      "filters": [],
      "enrichments": [],
      "enabled": true,
      "index_unclassified_events": false,
      "index_discarded_events": false
    }
  }'

Example request (standard space)

curl -sk -u admin:admin -X PUT \
  "https://127.0.0.1:9200/_plugins/_content_manager/policy/standard" \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": {
      "enrichments": ["connection"],
      "filters": [],
      "enabled": true,
      "index_unclassified_events": false,
      "index_discarded_events": false
    }
  }'

Example response

{
  "message": "kQPmV5wBi_TgruUn97RT",
  "status": 200
}

The message field contains the OpenSearch document ID of the updated policy.

Status codes

• 200 — policy updated.
• 400 — invalid space, missing resource field, missing required fields, invalid enrichments, or disallowed modification of integrations/filters.
• 500 — internal error.

Rules

Rules follow the Sigma format with Wazuh extensions. See Sigma Rules for the full format reference, including the mitre, compliance, and metadata blocks.

Validation notes:

• The logsource.product field must exactly match the metadata.title of the parent integration.
• Detection fields are validated against the Wazuh Common Schema (WCS); rules referencing unknown fields are rejected. A field used in a check or detection expression that is not part of WCS must be prefixed with an underscore to mark it as temporary (see Troubleshooting) — otherwise the Engine rejects the resource.
• IPv6 addresses are supported in detection conditions (standard, compressed, and CIDR notation).

Create rule

Creates a new detection rule in the draft space. The rule is linked to the specified parent integration and validated by the Security Analytics plugin.

The rule is also synchronized to Security Analytics, where a separate document is created with its own auto-generated UUID. That document stores the CTI document UUID in a document.id field and the space in a source field (e.g., “Draft”) for cross-reference.

Request

• Method: POST
• Path: /_plugins/_content_manager/rules

Request body

• integration (String, required) — UUID of the parent integration (must be in draft space).
• resource (Object, required) — the rule definition.

Fields within resource:

• metadata (Object, required) — rule metadata (see below).
• sigma_id (String, optional) — Sigma rule ID.
• enabled (Boolean, optional) — whether the rule is enabled.
• status (String, optional) — rule status (e.g., experimental, stable).
• level (String, optional) — alert level (e.g., low, medium, high, critical).
• logsource (Object, optional) — log source definition (product, category).
• detection (Object, optional) — Sigma detection logic with condition and selection fields.
• mitre (Object, optional) — MITRE ATT&CK mapping (see Sigma Rules).
• compliance (Object, optional) — compliance framework mapping (see Sigma Rules).

Fields within resource.metadata:

• title (String, required) — rule title (must be unique within the draft space).
• author (String, optional) — rule author.
• description (String, optional) — rule description.
• references (Array, optional) — reference URLs.
• documentation (String, optional) — documentation text or URL.
• date, modified (String, optional) — see Timestamps on create and update.

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/rules" \
  -H 'Content-Type: application/json' \
  -d '{
    "integration": "6b7b7645-00da-44d0-a74b-cffa7911e89c",
    "resource": {
      "metadata": {
        "title": "Test Rule",
        "description": "A Test rule",
        "author": "Tester",
        "references": [
          "https://wazuh.com"
        ]
      },
      "sigma_id": "19aefed0-ffd4-47dc-a7fc-f8b1425e84f9",
      "enabled": true,
      "status": "experimental",
      "logsource": {
        "product": "system",
        "category": "system"
      },
      "detection": {
        "condition": "selection",
        "selection": {
          "event.action": [
            "hash_test_event"
          ]
        }
      },
      "level": "low",
      "mitre": {
        "tactic": ["TA0001"],
        "technique": ["T1190"],
        "subtechnique": []
      },
      "compliance": {
        "pci_dss": ["6.5.1"]
      }
    }
  }'

Example response

{
  "message": "6e1c43f1-f09b-4cec-bb59-00e3a52b7930",
  "status": 201
}

The message field contains the UUID of the created rule.

Status codes

• 201 — rule created.
• 400 — missing fields, duplicate title, integration not in draft space, validation failure, or max_rules limit reached (default: 100).
• 500 — internal error or Security Analytics unavailable.

Update rule

Updates an existing rule in the draft space. Unlike on create, detection and logsource are required on update, in addition to metadata.

Request

• Method: PUT
• Path: /_plugins/_content_manager/rules/{id}

Parameters

• id (Path, String/UUID, required) — rule document ID.

Request body

• resource (Object, required) — updated rule definition (same fields as create, except metadata.date, which is read-only on update; see Timestamps on create and update).

Example request

curl -sk -u admin:admin -X PUT \
  "https://127.0.0.1:9200/_plugins/_content_manager/rules/6e1c43f1-f09b-4cec-bb59-00e3a52b7930" \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": {
      "metadata": {
        "title": "Test Hash Generation Rule",
        "description": "A rule to verify that SHA-256 hashes are calculated correctly upon creation.",
        "author": "Tester"
      },
      "enabled": true,
      "status": "experimental",
      "logsource": {
        "product": "system",
        "category": "system"
      },
      "detection": {
        "condition": "selection",
        "selection": {
          "event.action": [
            "hash_test_event"
          ]
        }
      },
      "level": "low"
    }
  }'

Example response

{
  "message": "6e1c43f1-f09b-4cec-bb59-00e3a52b7930",
  "status": 200
}

Status codes

• 200 — rule updated.
• 400 — invalid request, not in draft space, or validation failure.
• 404 — rule not found.
• 500 — internal error.

Delete rule

Deletes a rule from the draft space. The rule is also removed from any integrations that reference it.

Request

• Method: DELETE
• Path: /_plugins/_content_manager/rules/{id}

Parameters

• id (Path, String/UUID, required) — rule document ID.

Example request

curl -sk -u admin:admin -X DELETE \
  "https://127.0.0.1:9200/_plugins/_content_manager/rules/6e1c43f1-f09b-4cec-bb59-00e3a52b7930"

Example response

{
  "message": "6e1c43f1-f09b-4cec-bb59-00e3a52b7930",
  "status": 200
}

Status codes

• 200 — rule deleted.
• 404 — rule not found.
• 500 — internal error.

Decoders

Create decoder

Creates a new log decoder in the draft space. The decoder is validated against the Wazuh Engine before being stored, and automatically linked to the specified integration.

Note: A testing policy must be loaded in the Engine for decoder validation to succeed.

Request

• Method: POST
• Path: /_plugins/_content_manager/decoders

Request body

• integration (String, required) — UUID of the parent integration (must be in draft space).
• resource (Object, required) — the decoder definition.

Fields within resource:

• name (String) — decoder name identifier (e.g., decoder/core-wazuh-message/0).
• enabled (Boolean) — whether the decoder is enabled.
• check (Array) — decoder check logic — array of condition objects. Fields referenced here that aren’t part of WCS must be prefixed with an underscore (see the validation note under Rules).
• normalize (Array) — normalization rules — array of mapping objects.
• metadata (Object) — decoder metadata (see below).

Fields within metadata:

• title (String) — human-readable decoder title.
• description (String) — decoder description.
• module (String) — module name.
• compatibility (String) — compatibility description.
• author (String) — author name, stored as a keyword.
• references (Array) — reference URLs.
• versions (Array) — supported versions.
• date, modified (String, optional) — see Timestamps on create and update.

Example request

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/decoders" \
  -H 'Content-Type: application/json' \
  -d '{
    "integration": "0aa4fc6f-1cfd-4a7c-b30b-643f32950f1f",
    "resource": {
      "enabled": true,
      "metadata": {
        "author": "Wazuh, Inc.",
        "compatibility": "All wazuh events.",
        "description": "Base decoder to process Wazuh message format.",
        "module": "wazuh",
        "references": [
          "https://documentation.wazuh.com/"
        ],
        "title": "Wazuh message decoder",
        "versions": [
          "Wazuh 5.*"
        ]
      },
      "name": "decoder/core-wazuh-message/0",
      "check": [
        {
          "_tmp_json.event.action": "string_equal(\"netflow_flow\")"
        }
      ],
      "normalize": [
        {
          "map": [
            {
              "@timestamp": "get_date()"
            }
          ]
        }
      ]
    }
  }'

Example response

{
  "message": "d_0a6aaebe-dd0b-44cc-a787-ffefd4aac175",
  "status": 201
}

The message field contains the UUID of the created decoder (prefixed with d_).

Example request (YAML)

curl -sk -u admin:admin -X POST \
  "https://127.0.0.1:9200/_plugins/_content_manager/decoders" \
  -H 'Content-Type: application/yaml' \
  --data-binary '---
integration: 0aa4fc6f-1cfd-4a7c-b30b-643f32950f1f
resource:
  enabled: true
  metadata:
    author: "Wazuh, Inc."
    compatibility: "All wazuh events."
    description: "Base decoder to process Wazuh message format."
    module: wazuh
    references:
      - "https://documentation.wazuh.com/"
    title: "Wazuh message decoder"
    versions:
      - "Wazuh 5.*"
  name: decoder/core-wazuh-message/0
  check:
    - _tmp_json.event.action: "string_equal(\"netflow_flow\")"
  normalize:
    - map:
        - "@timestamp": "get_date()"
'

Note: See YAML content-type support for details on the YAML envelope format and type fidelity.

Status codes

• 201 — decoder created.
• 400 — issing integration field, integration not in draft space, Engine validation failure, or max_decoders limit reached (see Troubleshooting if the failure mentions an unrecognized WCS field).
• 500 — Engine unavailable or internal error.

Update decoder

Updates an existing decoder in the draft space. The decoder is re-validated against the Wazuh Engine.

Request

• Method: PUT
• Path: /_plugins/_content_manager/decoders/{id}

Parameters

• id (Path, String, required) — decoder document ID.

Request body

• resource (Object, required) — updated decoder definition (same fields as create, except metadata.date, which is read-only on update; see Timestamps on create and update).

Example request

curl -sk -u admin:admin -X PUT \
  "https://127.0.0.1:9200/_plugins/_content_manager/decoders/bb6d0245-8c1d-42d1-8edb-4e0907cf45e0" \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": {
      "name": "decoder/test-decoder/0",
      "enabled": false,
      "metadata": {
        "title": "Test Decoder UPDATED",
        "description": "Updated description",
        "author": "Hello there"
      },
      "check": [],
      "normalize": []
    }
  }'

Example response

{
  "message": "bb6d0245-8c1d-42d1-8edb-4e0907cf45e0",
  "status": 200
}

Status codes

• 200 — decoder updated.
• 400 — invalid request, not in draft space, or Engine validation failure.
• 404 — decoder not found.
• 500 — internal error.

Delete decoder

Deletes a decoder from the draft space. The decoder is also removed from any integrations that reference it. A decoder cannot be deleted if it is currently set as the root decoder in the draft policy.

Request

• Method: DELETE
• Path: /_plugins/_content_manager/decoders/{id}

Parameters

• id (Path, String/UUID, required) — decoder document ID.

Example request

curl -sk -u admin:admin -X DELETE \
  "https://127.0.0.1:9200/_plugins/_content_manager/decoders/acbdba85-09c4-45a0-a487-61c8eeec58e6"

Example response

{
  "message": "acbdba85-09c4-45a0-a487-61c8eeec58e6",
  "status": 200
}

Example response (set as root decoder)

{
  "message": "Cannot remove decoder [acbdba85-09c4-45a0-a487-61c8eeec58e6] as it is set as root decoder.",
  "status": 400
}

Status codes

• 200 — decoder deleted.
• 400 — decoder is set as root decoder.
• 404 — decoder not found.
• 500 — internal error.

Filters

Create filter

Creates a new filter in the draft or standard space. The filter is validated against the Wazuh Engine before being stored and automatically linked to the specified space’s policy.

Request

• Method: POST
• Path: /_plugins/_content_manager/filters

Request body

• space (String, required) — target space: draft or standard.
• resource (Object, required) — the filter definition.

Fields within resource:

• name (String) — filter name identifier (e.g., filter/prefilter/0).
• enabled (Boolean) — whether the filter is enabled.
• check (String) — filter check expression.
• type (String) — filter type (e.g., pre-filter).
• metadata (Object) — filter metadata (see below).