wazuh/wazuh-indexer-plugins
1
0
Fork 0
mirror of https://github.com/wazuh/wazuh-indexer-plugins.git synced 2025-12-10 14:32:28 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for the setup plugin (#498)

Browse Source 
* Dummy commit

* Update setup install documentation and indexer information

* Update setup plugin information and index description

* Improve setup plugin documentation

* Add groups and users indexes

* Modify setup plugin readme

* Improve install setup plugin documentation

* Review setup plugin development guide

* Apply suggestions

* Move indices table

* Review indices table

* Update sequence diagram of the initialization plugin

* Fix link checker

* Fix typos

* Add missing indices to the table in the docs

Fix typo and sort alphabetically

---------

Signed-off-by: Álex Ruiz Becerra <alejandro.ruiz.becerra@wazuh.com>
Co-authored-by: Kevin Ledesma <kevin.ledesma@wazuh.com>
Co-authored-by: Álex Ruiz <alejandro.ruiz.becerra@wazuh.com>
This commit is contained in:
Alvaro Gonzalez Luque 2025-06-30 12:28:53 +02:00 committed by GitHub
parent c5e00275ae
commit 162b39d968
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 304 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -12,7 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
- Add scripts to extract the product versions [(#483)](https://github.com/wazuh/wazuh-indexer-plugins/pull/483)
- Add SCA index to 5.0.0 [(#516)](https://github.com/wazuh/wazuh-indexer-plugins/pull/516)
- Add repository bumper [(#500)](https://github.com/wazuh/wazuh-indexer-plugins/pull/500)
- Add documentation for the setup plugin [(#498)](https://github.com/wazuh/wazuh-indexer-plugins/pull/498)
### Dependencies
-

4
docs/SUMMARY.md
View File

@ -11,6 +11,8 @@
- [Build from Sources](dev/build-sources.md)
- [Run from Sources](dev/run-sources.md)
- [Run Tests](dev/run-tests.md)
- [Plugins]()
- [Setup](dev/plugins/setup.md)
# Reference Manual
@ -27,7 +29,7 @@
- [Command line options]()
- [Configuration files](ref/getting-started/config-files.md)
- [Modules]()
- [Setup](ref/modules/setup/README.md)
- [Setup](ref/modules/setup/index.md)
- [Architecture](ref/modules/setup/architecture.md)
- [API Reference]()
- [Upgrade](ref/upgrade.md)

151
docs/dev/plugins/setup.md Normal file
View File

@ -0,0 +1,151 @@
# 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:
```json
{
"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.
```java
/**
* 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:
> ```bash
> 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:
```json
"plugins.index_state_management.rollover_alias": "<index-name>"
```
### 2. Define the ISM Policy
Refer to the [OpenSearch ISM Policies documentation](https://docs.opensearch.org/docs/latest/im-plugin/ism/policies/) for more details.
Here is an example ISM policy:
```json
{
"policy": {
"policy_id": "<index-name>-rollover-policy",
"description": "<policy-description>",
"last_updated_time": <unix-timestamp-in-milliseconds>,
"schema_version": 21,
"error_notification": null,
"default_state": "rollover",
"states": [
{
"name": "rollover",
"actions": [
{
"rollover": {
"min_doc_count": 200000000,
"min_index_age": "7d",
"min_primary_shard_size": "25gb"
}
}
],
"transitions": []
}
],
"ism_template": [
{
"index_patterns": [
"wazuh-<pattern1>-*"
// Optional additional patterns
// "wazuh-<pattern2>-*"
],
"priority": <priority-int>,
"last_updated_time": <unix-timestamp-in-milliseconds>
}
]
}
}
```
### 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:
```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.

2
docs/ref/compatibility.md
View File

@ -14,4 +14,4 @@ For 5.0.0 and above, we support the operating system versions and architectures
## OpenSearch
Currently, Wazuh indexer is using version `2.19.2` of OpenSearch.
Currently, Wazuh indexer is using version `3.0.0` of OpenSearch.

6
docs/ref/description.md
View File

@ -8,8 +8,4 @@ An **index** is a collection of documents that are related to each other. The do
![indexer shards](https://documentation.wazuh.com/current/_images/wazuh-indexer1.png)
The Wazuh indexer stores the data collected by the Wazuh agents in separate indices. Each index contains documents with specific inventory information. In this section, you can find a description of the information in each index.
| Index | Description |
|-------|-------------|
| | |
The Wazuh indexer stores the data collected by the Wazuh agents in separate indices. Each index contains documents with specific inventory information. In the [Indices table](./modules/setup/index.md#indices) section, you can find a description of the information in each index.

8
docs/ref/modules/setup/README.md
View File

@ -1,8 +0,0 @@
# Setup
The `wazuh-indexer-setup` plugin is a module composing the Wazuh Indexer responsible for the initialization of the indices required by Wazuh to store all the data gathered and generated by other Central Components, such as the agents and the server (engine).
The Wazuh Indexer Setup Plugin in responsible for:
- Create the index templates, to define the mappings and settings of the indices.
- Create the initial indices. We distinguish between **stateful** and **stateless** indices. Stateful indices are unique and its data is update over time (agents' inventory), stateless indices are rotated and static (alerts).
- For stateless indices, it creates the indices aliases and lifecycle policies for rollover.

135
docs/ref/modules/setup/architecture.md
View File

@ -2,22 +2,75 @@
## Design
The plugin implements the [ClusterPlugin](https://github.com/opensearch-project/OpenSearch/blob/2.13.0/server/src/main/java/org/opensearch/plugins/ClusterPlugin.java) interface in order to be able to hook into the node’s lifecycle overriding the `onNodeStarted()` method. The logic for the creation of the index templates and the indices is encapsulated in the `WazuhIndices` class. The `onNodeStarted()` method invokes the `WazuhIndices::initialize()` method, which handles everything.
The plugin implements the [ClusterPlugin](https://github.com/opensearch-project/OpenSearch/blob/3.1.0/server/src/main/java/org/opensearch/plugins/ClusterPlugin.java) 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.
## JavaDoc
## Class diagram
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.
```mermaid
---
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
```bash
./gradlew javadoc
%% 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 {
}
```
## Indices
Refer to the [docs](https://github.com/wazuh/wazuh-indexer-plugins/tree/main/ecs) for complete definitions of the indices. The indices inherit the settings and mappings defined in the [index templates](https://github.com/wazuh/wazuh-indexer-plugins/tree/main/plugins/setup/src/main/resources).
## Sequence diagram
> **Note** Calls to `Client` are asynchronous.
@ -27,60 +80,40 @@ Refer to the [docs](https://github.com/wazuh/wazuh-indexer-plugins/tree/main/ecs
sequenceDiagram
actor Node
participant SetupPlugin
participant WazuhIndices
participant Index
participant Client
Node->>SetupPlugin: plugin.onNodeStarted()
activate SetupPlugin
Note over Node,SetupPlugin: Invoked on Node::start()
activate WazuhIndices
SetupPlugin->>WazuhIndices: initialize()
Note over SetupPlugin,WazuhIndices: Create index templates and indices
loop i..n templates
WazuhIndices-)Client: templateExists(i)
Client--)WazuhIndices: response
alt template i does not exist
WazuhIndices-)Client: putTemplate(i)
Client--)WazuhIndices: response
end
end
activate Index
loop i..n indices
WazuhIndices-)Client: indexExists(i)
Client--)WazuhIndices: response
SetupPlugin->>Index: i.initialize()
Index-)Client: createTemplate(i)
Client--)Index: response
Index-)Client: indexExists(i)
Client--)Index: response
alt index i does not exist
WazuhIndices-)Client: putIndex(i)
Client--)WazuhIndices: response
Index-)Client: createIndex(i)
Client--)Index: response
end
end
deactivate WazuhIndices
deactivate Index
deactivate SetupPlugin
```
## Class diagram
## Wazuh Common Schema
```mermaid
---
title: Wazuh Indexer setup plugin
---
classDiagram
direction LR
SetupPlugin"1"-->WazuhIndices
WazuhIndices"1"-->Client
<<service>> Client
Refer to the [docs](https://github.com/wazuh/wazuh-indexer-plugins/tree/main/ecs) for complete definitions of the indices. The indices inherit the settings and mappings defined in the [index templates](https://github.com/wazuh/wazuh-indexer-plugins/tree/main/plugins/setup/src/main/resources).
SetupPlugin : -WazuhIndices indices
SetupPlugin : +createComponents()
SetupPlugin : +onNodeStarted()
## JavaDoc
WazuhIndices : -Client client
WazuhIndices : -ClusterService clusterService
WazuhIndices : +WazuhIndices(Client client, ClusterService clusterService)
WazuhIndices : +putTemplate(String template) void
WazuhIndices : +putIndex(String index) void
WazuhIndices : +indexExists(String index) bool
WazuhIndices : +templateExists(String template) bool
WazuhIndices : +initialize() void
```
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.
```bash
./gradlew javadoc
```

61
docs/ref/modules/setup/index.md Normal file
View File

@ -0,0 +1,61 @@
# 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 to store all the data gathered and generated by other Central Components, such as the agents and the server (engine).
The Wazuh Indexer Setup Plugin in responsible for:
- Create the index templates, to define the mappings and settings of the indices.
- Create the initial indices. We distinguish between **stateful** and **stateless** indices. Stateful indices are unique, and its data is update over time (agents' inventory), stateless indices are rotated and static (alerts).
- For stateless indices, it creates the indices aliases and lifecycle policies for rollover.
## Indices
The following table lists the indices created by this plugin.
| Index | Description |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wazuh‑alerts` | Stores alerts generated by the [Wazuh Server](https://documentation.wazuh.com/current/getting-started/components/wazuh-server.html). These are created each time an event trips a rule with a high enough severity (this threshold is configurable). |
| `wazuh‑archives` | Stores all events (archive data) received by the [Wazuh Server](https://documentation.wazuh.com/current/getting-started/components/wazuh-server.html), whether they trip a rule. |
| `wazuh‑states-sca` | Security Configuration Assessment (SCA) scan results. |
| `wazuh-states-fim-files` | File Integrity Monitoring: information about monitored files. |
| `wazuh-states-fim-registry-keys` | File Integrity Monitoring: information about the Windows registry (keys). |
| `wazuh-states-fim-registry-values` | File Integrity Monitoring: information about the Windows registry (values). |
| `wazuh-states-inventory-groups` | Stores existing groups on the endpoint. |
| `wazuh-states-inventory-hardware` | Basic information about the hardware components of the endpoint. |
| `wazuh-states-inventory-hotfixes` | Contains information about the updates installed on Windows endpoints. This information is used by the vulnerability detector module to discover what vulnerabilities have been patched on Windows endpoints. |
| `wazuh-states-inventory-interfaces` | Stores information (up and down interfaces) as well as packet transfer information about the interfaces on a monitored endpoint. |
| `wazuh-states-inventory-monitoring` | Stores the connection status history of Wazuh agents (active, disconnected, pending, or never connected). The index is used by the Wazuh Dashboard to display agent status and historical trends. |
| `wazuh-states-inventory-networks` | Stores the IPv4 and IPv6 addresses associated with each network interface, as referenced in the `wazuh-states-inventory-interfaces` index. |
| `wazuh-states-inventory-packages` | Stores information about the currently installed software on the endpoint. |
| `wazuh-states-inventory-ports` | Basic information about open network ports on the endpoint. |
| `wazuh-states-inventory-processes` | Stores the detected running processes on the endpoints. |
| `wazuh-states-inventory-protocols` | Stores routing configuration details for each network interface, as referenced in the `wazuh-states-inventory-interfaces` index. |
| `wazuh-states-inventory-system` | Operating system information, hostname and architecture. |
| `wazuh-states-inventory-users` | Stores existing users on the endpoint. |
| `wazuh-states-vulnerabilities` | Active vulnerabilities on the endpoint and its details. |
| `wazuh-statistics` | Stores statistics about the Wazuh Server usage and performance. The information includes the number of events decoded, bytes received, and TCP sessions. |
## 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.
```bash
/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>`
```bash
/usr/share/wazuh-indexer/bin/opensearch-plugin remove wazuh-indexer-setup
```

4
plugins/setup/src/main/java/com/wazuh/setup/SetupPlugin.java
View File

@ -77,6 +77,7 @@ public class SetupPlugin extends Plugin implements ClusterPlugin {
this.indices.add(new StreamIndex("wazuh-alerts-5.x-000001", "index-template-alerts", "wazuh-alerts"));
this.indices.add(new StreamIndex("wazuh-archives-5.x-000001", "index-template-archives", "wazuh-archives"));
// State indices
this.indices.add(new StateIndex("wazuh-states-sca", "index-template-sca"));
this.indices.add(new StateIndex("wazuh-states-fim-files", "index-template-fim-files"));
this.indices.add(new StateIndex("wazuh-states-fim-registry-keys", "index-template-fim-registry-keys"));
this.indices.add(new StateIndex("wazuh-states-fim-registry-values", "index-template-fim-registry-values"));
@ -90,11 +91,10 @@ public class SetupPlugin extends Plugin implements ClusterPlugin {
this.indices.add(new StateIndex("wazuh-states-inventory-ports", "index-template-ports"));
this.indices.add(new StateIndex("wazuh-states-inventory-processes", "index-template-processes"));
this.indices.add(new StateIndex("wazuh-states-inventory-protocols", "index-template-protocols"));
this.indices.add(new StateIndex("wazuh-statistics", "index-template-statistics"));
this.indices.add(new StateIndex("wazuh-states-inventory-system", "index-template-system"));
this.indices.add(new StateIndex("wazuh-states-inventory-users", "index-template-users"));
this.indices.add(new StateIndex("wazuh-states-vulnerabilities", "index-template-vulnerabilities"));
this.indices.add(new StateIndex("wazuh-states-sca", "index-template-sca"));
this.indices.add(new StateIndex("wazuh-statistics", "index-template-statistics"));
// spotless:on
// Inject dependencies