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

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

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:

Reads events.json from the classpath
Overrides index_patterns to ["wazuh-events-v5-cloud-services*"]
Overrides rollover_alias to "wazuh-events-v5-cloud-services"
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:

Data Stream	Template	Notes
`wazuh-events-raw-v5`	`templates/streams/raw.json`	Stores original unprocessed events
`wazuh-events-v5-unclassified`	`templates/streams/unclassified.json`	Stores uncategorized events for investigation
`wazuh-active-responses`	`templates/streams/active-responses.json`	Active Response execution requests

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

Hot State
- Actions: Rollover when primary shard reaches 25 GB or 200M documents
- Transition Condition: Transitions to delete after 1 hour
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

Hot State
- Actions: Rollover when primary shard reaches 25 GB or 200M documents
- Transition Condition: Transitions to delete after 90 days
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

Hot State
- Actions: Rollover when primary shard reaches 25 GB or 200M documents
- Transition Condition: Transitions to delete after 10 minutes
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:

The template file active-responses.json exists in templates/streams/
The ISM policy file stream-active-responses-policy.json exists in policies/
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

Wazuh Indexer technical documentation

Wazuh Indexer Setup Plugin — Development Guide

📦 Creating a New Index

1. Add a New Index Template

2. Register the Index in the Code

🔁 Creating a New ISM (Index State Management) Policy

1. Add Rollover Alias to the Index Template

2. Define the ISM Policy

3. Register the ISM Policy in the Plugin Code

📌 Additional Notes

🚀 Event Stream Templates

Overview

How it works

Verifying deployed templates

Specialized stream templates

🚀 Events Data Stream ISM Policy (`stream-events-policy`)

Overview

Policy Details

Policy States

🚀 Findings Data Stream ISM Policy (`stream-findings-policy`)

Overview

Policy Details

Policy States

🚀 Raw Events Data Stream ISM Policy (`stream-raw-events-policy`)

Overview

Policy Details

Policy States

🚀 Active Responses Data Stream (`wazuh-active-responses`)

Overview

Purpose

Data Stream Configuration

Index Template

Fields Included (WCS-compatible)

ISM Policy

Policy Details

Configuration

Testing

Keyboard shortcuts

Wazuh Indexer technical documentation