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

Every repository provides the template below as its default .github/pull_request_template.md; it is pre-filled automatically when you open a PR. Every PR must be linked to an existing issue, and PRs should not be linked directly to GitHub Projects — track project status at the issue level instead.

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

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:

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.

Pre-requisites

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.

Pre-requisites

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

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

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.

📦 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": 1
    }
  }
}

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 kind of indices:

• Stream index. Stream indices contain time-based events of any kind (alerts, statistics, logs…).
• Stateful index. Stateful indices represent the most recent information of a subject (active vulnerabilities, installed packages, open ports, …). These indices are different of 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-000001", "my-index-template-1", "my-alias"));
  // State indices
  this.indices.add(new StateIndex("my-state-index", "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 to the Index Template

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

"plugins.index_state_management.rollover_alias": "<index-name>"

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

All event data streams share a single base template: templates/streams/events.json. At deployment time, the plugin generates one index template per event category by dynamically setting the index_patterns and rollover_alias fields from the base template. This means:

• Source of truth: Only events.json exists in the repository.
• At runtime: One index template is created for each category (e.g., wazuh-events-v5-cloud-services-template, wazuh-events-v5-security-template, etc.).

The StreamIndex class handles this: when constructed with only an index name (no explicit template path), it defaults to templates/streams/events and rewrites the index_patterns and rollover_alias to match the specific index.

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. Overrides rollover_alias to "wazuh-events-v5-cloud-services"
4. Creates the composable index template in OpenSearch

Verifying deployed templates

To list all event templates in a running cluster:

GET /_index_template/wazuh-events-*

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-events-v5-unclassified", "templates/streams/unclassified")
new StreamIndex("wazuh-active-responses", "templates/streams/active-responses")

🚀 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: 25 GB primary shard size or 200,000,000 documents
• Priority: 50

Policy States

1. Hot State

   • Actions: Rollover when primary shard reaches 25 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: 25 GB primary shard size or 200,000,000 documents
• Priority: 50

Policy States

1. Hot State

   • Actions: Rollover when primary shard reaches 25 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: 25 GB primary shard size or 200,000,000 documents
• Priority: 100

Policy States

1. Hot State

   • Actions: Rollover when primary shard reaches 25 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: 25 GB primary shard size or 200,000,000 documents
• Priority: 100

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

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 indiviual 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 how to build a Wazuh Reporting plugin development environment to create and test new features.

Working from a minimal environment

In order to deploy a minimal environment for developing the reporting plugin just for testing purposes, you must have at least a Wazuh Indexer and a Wazuh Dashboard environment running. Then, you can create your own SMPT 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: 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 security 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 (SAP).
• User-Generated Content: Full CUD for rules, decoders, integrations, KVDBs, and policies in the Draft space.
• Engine Communication: Validates and promotes content via Unix Domain Socket 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: Unresgistered mode
    yes_state: Registered mode
    inititalization: Initialization


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

    no_state --> inititalization : Init from local snapshots
    yes_state --> inititalization : Init from active plan
    inititalization --> [*]

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. All 8 content indices use an alias-backed blue/green storage scheme (see Index Alias Convention below).

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: SAP sync, engine promote, etc.)
9. Delete old physical indices

Error handling:

• Failure before step 6: shadow indices are deleted, alias and consumer doc unchanged. Next sync retries.
• Failure between steps 6–7: alias is swapped but consumer doc still says old resource. Next sync re-detects the plan change and re-runs the shadow path (at most one wasted rebuild, no user-visible corruption).

Concurrency: The CatalogSyncJob semaphore spans the entire synchronize() call, which includes the shadow swap. No additional locking is needed.

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.

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 26 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, and parent integration existence.
4. Generate ID and metadata — creates a UUID, sets date and modified timestamps, defaults enabled to true.
5. External sync — delegates to syncExternalServices() (abstract). Typically upserts the resource in SAP 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 timestamp. Preserves immutable fields (creation date, author) from the existing document.
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 SAP. 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.

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 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 Indices as Content Indices
    participant SAP 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)
        Synchronizer->>Update: update(localOffset, remoteOffset)
        Update->>CTI: Fetch Changes
        Update->>Indices: Apply JSON Patches
        Update-->>Synchronizer: Done
    end

    opt Changes Applied (onSyncComplete)
        Synchronizer->>Indices: Refresh Indices

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

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

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

        Synchronizer->>Synchronizer: calculatePolicyHash()
    end

    deactivate SyncJob

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 idle in .wazuh-cti-consumers.

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 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 Engine/SAP as Engine or SAP
    participant ContentIndex
    participant IntegrationIndex

    User->>Indexer: POST /_plugins/_content_manager/{resource_type}
    Indexer->>Indexer: Validate payload, generate UUID, timestamps
    Indexer->>Engine/SAP: Sync (validate/upsert)
    Engine/SAP-->>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 Engine/SAP as Engine or SAP

    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->>Engine/SAP: Sync (validate/upsert)
    Indexer->>ContentIndex: Re-index document
    Indexer-->>User: 200 OK + UUID

Delete (DELETE):

sequenceDiagram
    actor User
    participant Indexer
    participant ContentIndex
    participant Engine/SAP as Engine or SAP
    participant IntegrationIndex

    User->>Indexer: DELETE /_plugins/_content_manager/{resource_type}/{id}
    Indexer->>ContentIndex: Check exists + is in Draft space
    Indexer->>Engine/SAP: 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 the Policy 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| DeleteSAP[Delete draft resources from SAP]
    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 SAP 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.

01 - Integrations: Create Integration (9 scenarios)

01 - Integrations: Update Integration (8 scenarios)

01 - Integrations: Delete Integration (7 scenarios)

02 - Decoders: Create Decoder (7 scenarios)

02 - Decoders: Update Decoder (7 scenarios)

02 - Decoders: Delete Decoder (7 scenarios)

03 - Rules: Create Rule (7 scenarios)

03 - Rules: Update Rule (7 scenarios)

03 - Rules: Delete Rule (7 scenarios)

04 - KVDBs: Create KVDB (9 scenarios)

04 - KVDBs: Update KVDB (7 scenarios)

04 - KVDBs: Delete KVDB (7 scenarios)

05 - Policy: Policy Initialization (6 scenarios)

05 - Policy: Update Draft Policy (12 scenarios)

06 - Log Test (4 scenarios)

07 - Promote: Preview Promotion (7 scenarios)

07 - Promote: Execute Promotion (18 scenarios)

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 three layers:

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

RestPostLogtestAction (combined)

Path: rest/service/RestPostLogtestAction.java

The REST handler for POST /_plugins/_content_manager/logtest. Responsibilities:

1. Validates the request has content and is valid JSON.
2. Validates the required field space.
3. Validates that space is "test" or "standard".
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.

The handler does not interact with indices or external services directly, all business logic is in the service.

RestPostLogtestNormalizationAction

Path: rest/service/RestPostLogtestNormalizationAction.java

The REST handler for POST /_plugins/_content_manager/logtest/normalization. Responsibilities:

1. Validates the request has content and is valid JSON.
2. Validates the required field space.
3. Validates that space is "test" or "standard".
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. 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 "test" or "standard".
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() — SAP-only: looks up integration, fetches rule IDs/bodies, evaluates via SecurityAnalyticsService.evaluateRules(), and returns the SAP 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. SAP evaluation — Passes the normalized event JSON and rule bodies to SecurityAnalyticsService.evaluateRules().
6. Response building — Combines engine and SAP results into a single JSON response under the keys normalization and detection.

Error handling:

• If the Engine fails (HTTP error or exception), SAP 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, SAP returns rules_evaluated: 0, rules_matched: 0 with success status.
• If SAP evaluation returns unparseable JSON, the SAP result is status: "error".

SecurityAnalyticsService / EventMatcher

The SAP evaluation happens in the security-analytics:

• 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)
    │  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
    │  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 SAP 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 → SAP 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 → SAP 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 handler(s): RestPostLogtestAction, RestPostLogtestNormalizationAction, and/or RestPostLogtestDetectionAction.
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 SAP 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 (SAP) is a fork of the OpenSearch Security Analytics plugin adapted for Wazuh. This page documents Wazuh-specific implementation details and extensions.

Case Management

Case management adds triage capabilities to Security Analytics findings, allowing analysts to track status, comments, tags, and user attribution on individual findings.

Case fields

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 SAP as Security Analytics Plugin
    participant OS as OpenSearch (Bulk API)
    participant FI as Findings Index

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

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

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

Content manager settings

The Content Manager plugin is configured through settings in opensearch.yml. All settings use the plugins.content_manager prefix.

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.

Wazuh Indexer Initialization 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 in responsible for:

• Create the index templates, to define the mappings and settings for the indices.
• Create 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 table lists the indices created by this plugin.

Stream indices

Stateful indices

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 implements the ClusterPlugin interface in order to be able to hook into the node’s lifecycle overriding the onNodeStarted() method.

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.

By design, the plugin will overwrite any existing index template under the same name.

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 Files for more information.

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.

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
        %% initialize() podría reemplazarse por createIndex() y createTemplate()
    }
    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 {
    }

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

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: templates/streams/events.json. The StreamIndex class dynamically generates one index template per category at deployment time by overriding index_patterns and rollover_alias from the base template. Specialized streams (raw, unclassified, active-responses) use their own dedicated template files.

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

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

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

Configuration

Setup settings

The Setup plugin is configured through settings in opensearch.yml. All settings use the plugins.setup prefix.

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

Example Request

curl -sk -u admin:admin -X PUT \
  "https://192.168.56.6: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

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.

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). At deployment time, the setup plugin dynamically generates one index template per category from this shared base, setting the appropriate index_patterns and rollover_alias for each. This means only one template file exists in the repository, but each category gets its own index template in the cluster.

The index mappings and settings for subcategories take precedence over those from the main category. In OpenSearch, index templates are applied in order of their “priority” value: templates with a lower priority are applied first, and those with a higher priority are applied afterward, allowing them to override previous settings. This means the index template for the main category is applied first (priority=1), and then the subcategory template (priority=10) is applied on top of it, so subcategory-specific settings override the main category defaults.

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.

Note: unclassified is a catch-all for events that could not be assigned to any other category. It is managed automatically by the pipeline and should not be used as a target category when creating new integrations or rules.

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 periodically synchronizes content from the Wazuh CTI API. Three catalog consumers are managed:

• Catalog context: Contains detection rules, decoders, integrations, KVDBs, and the routing policy.
• IoC context: Contains Indicators of Compromise for threat detection.
• CVE context: Contains Common Vulnerabilities and Exposures data, stored in wazuh-threatintel-vulnerabilities. CVE documents do not have a space and are not subject to removals from CTI.

Each catalog type has an associated consumer state document in .wazuh-cti-consumers, keyed by consumer type (for example, cti:catalog:consumer:ruleset).

Snapshot Initialization

On first run (when the local offset is 0), the Content Manager performs snapshot initialization:

1. If a custom catalog URL is configured, it first attempts remote snapshot initialization using that consumer.
2. If remote initialization fails, it falls back to the local packaged snapshot when available.
3. If no custom catalog URL is configured, it initializes from the local packaged snapshot.
4. It indexes content into the appropriate system indices using bulk operations and updates .wazuh-cti-consumers offsets.

Incremental Updates

When the local offset is behind the remote offset, the Content Manager fetches changes in batches (up to 1000 per request) and applies creation, update, and removal operations to the content indices. The local offset is updated after each successful batch.

If the local offset is ahead of the remote offset (e.g., consumer was changed), or if the update fails, the Content Manager resets to the latest snapshot to realign with the CTI API.

Sync Schedule

By default, synchronization runs:

• On plugin startup (plugins.content_manager.catalog.update_on_start: true)
• Periodically every 60 minutes (plugins.content_manager.catalog.sync_interval: 60)

The periodic job is registered with the OpenSearch Job Scheduler and tracked in the .wazuh-content-manager-jobs index.

Update Check Service

When plugins.content_manager.telemetry.enabled is true (default), the Content Manager schedules a daily update check heartbeat job.

• Frequency: every 24 hours (with an immediate first ping as soon as the job is registered)
• Scheduler document ID: wazuh-telemetry-ping-job
• Endpoint: CTI /ping
• Data sent: cluster UUID and deployed Wazuh version (through headers)

This information is used to detect update availability and surface notifications through the Wazuh Dashboard.

User-Generated Content

The Content Manager provides a full CUD 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://192.168.56.6: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:

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
• CUD operations on rules, decoders, integrations, and KVDBs
• Policy management
• Promotion preview and execution
• Logtest execution
• Content validation and promotion

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 PluginSettings.accessToken (a volatile String field). 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 (CatalogSyncJob)

Implements the OpenSearch JobSchedulerExtension interface. Registers a periodic job (wazuh-catalog-sync-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 (TelemetryPingJob)

Implements a daily heartbeat job (wazuh-telemetry-ping-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 Update Service. Tracks the sync lifecycle through the status field in .wazuh-cti-consumers: set to running at the start of synchronize(), then to ready once all post-sync work (hash recalculation, Security Analytics sync, Engine notification) is complete, or to failed if an unexpected exception interrupts the sync.

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 OpenSearch 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 enabled, interval, and source (index patterns) directly from the CTI integration payload. This allows CTI to control detector behavior dynamically.

Document ID model: SAP documents use their own auto-generated UUIDs as primary IDs, independent of the CTI document UUIDs. Each SAP document stores:

• document.id — the UUID of the original CTI document in the Content Manager.
• source — the space the document belongs to (e.g., “draft”, “test”, “custom”, or “standard”).

This design allows the same CTI resource to exist across multiple spaces without ID collisions. Association and lookup between CTI and SAP documents is performed by querying document.id + source.

Note: SAP enforces a maximum of 100 rules per detector. If an integration has more than 100 enabled rules, 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 100 rules per detector)

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 to content indices
  → Updates .wazuh-cti-consumers offset
  → Security Analytics Service syncs changes

Update Check Heartbeat

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

Job Scheduler triggers (every 24h thereafter)
  → TelemetryPingJob checks plugins.content_manager.telemetry.enabled
  → Reads cluster UUID and current Wazuh version
  → TelemetryClient 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 space.hash changes, the full policy — including all referenced integrations, decoders, kvdbs, filters, and rules — is built and sent to the Engine via EngineService.promote().

The space.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 CM 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 SAP:
      → ADDs use POST (new SAP document)
      → UPDATEs use PUT (existing SAP document)
  → Delete removed integrations/rules from SAP

Rollback on Failure

If any Content Manager index mutation fails during the consolidation phase, the promotion endpoint automatically performs a LIFO (Last-In, First-Out) rollback to restore the system to its pre-promotion state.

Pre-Promotion Snapshots

Before any writes, the system captures:

• Old versions (captureOldVersions): 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, null is stored.
• Delete snapshots (captureDeleteSnapshots): For each resource being deleted, the full document is fetched from the source space and stored.

CM Index Rollback

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

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

SAP Reconciliation

After CM rollback completes, a best-effort SAP reconciliation runs in dependency order:

1. Revert applied rules — ADDs are deleted from SAP; UPDATEs are restored to 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.

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

Consolidation fails at step N
  → LIFO rollback: undo step N-1, N-2, ..., 1
      → APPLY + null old version → delete from target index
      → APPLY + old version → restore old version to target index
      → DELETE → re-index snapshot to target index
  → SAP reconciliation (best-effort):
      → Delete rules that were added to SAP
      → Restore rules that were updated in SAP
      → Restore integrations that were added/updated in SAP
      → Re-create integrations/rules that were deleted from SAP
  → 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.

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

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/Disable 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:

1. RBAC — each endpoint is gated by a cluster permission (the action name above), enforced by the security plugin. Only the superuser admin (role all_access, cluster wildcard *) holds these permissions; the bundled wazuh-server and wazuh-dashboard users do not. 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.

   Endpoint	Setting (set to false to disable)
   POST /_plugins/_content_manager/update	plugins.content_manager.catalog.update_on_demand
   PUT /_plugins/_content_manager/policy/{space}	plugins.content_manager.catalog.policy_update.enabled
   PUT /_plugins/_setup/settings	plugins.setup.settings_update.enabled

# 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

Notes

• Changes to opensearch.yml require a restart of the Wazuh Indexer to take effect, except for dynamic settings (like plugins.content_manager.telemetry.enabled), which can be updated at runtime via the OpenSearch API.
• 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.

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

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

Example Request

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

Example Response

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

Status Codes

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://localhost: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

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://localhost:9200/_plugins/_content_manager/subscription"

Example Response

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

Status Codes

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://192.168.56.6: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

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

Example Request

curl -sk -u admin:admin -X POST \
  "https://192.168.56.6: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, SAP 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://192.168.56.6: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

Status Codes

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

Example Request

curl -sk -u admin:admin -X POST \
  "https://192.168.56.6: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",
    "input": "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

Status Codes

Detection Only

Evaluates an already-normalized event against the Sigma rules of a given integration via the Security Analytics Plugin (SAP). 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

Example Request

curl -sk -u admin:admin -X POST \
  "https://192.168.56.6: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

Status Codes

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

Request Body

Fields within resource:

Fields within resource.metadata:

Example Request (draft space)

curl -sk -u admin:admin -X PUT \
  "https://192.168.56.6: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://192.168.56.6: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

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.
• 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 the SAP, where a separate document is created with its own auto-generated UUID. The SAP 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

Fields within resource:

Fields within resource.metadata:

Example Request

curl -sk -u admin:admin -X POST \
  "https://192.168.56.6: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

Update Rule

Updates an existing rule in the draft space.

Request

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

Parameters

Request Body

Note: On update, enabled, metadata.title, and metadata.author are required. The detection and logsource fields are also required.

Example Request

curl -sk -u admin:admin -X PUT \
  "https://192.168.56.6: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

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

Example Request

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

Example Response

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

Status Codes

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

Fields within resource:

Fields within metadata: