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

Add documentation for default users and roles (RBAC) (#535)

Browse Source 
* Add documentation for User and Roles

* Add Security Plugin and Configuration Files sections

Move the documentation to the corresponding files

* Update CHANGELOG

* Apply suggestions from code review

Signed-off-by: Álex Ruiz Becerra <alex-r-b@hotmail.com>

* Improve security plugin and access control documentation

* Update docs/ref/security/access-control.md

Signed-off-by: Kevin Ledesma <kevin.ledesma@wazuh.com>

* Fix typo on docs/ref/security/access-control.md

Signed-off-by: Kevin Ledesma <kevin.ledesma@wazuh.com>

* Review the development documentation for RBAC

* Review reference documentation

---------

Signed-off-by: Álex Ruiz Becerra <alex-r-b@hotmail.com>
Signed-off-by: Kevin Ledesma <kevin.ledesma@wazuh.com>
Co-authored-by: Álex Ruiz Becerra <alejandro.ruiz.becerra@wazuh.com>
This commit is contained in:
Kevin Ledesma 2025-07-04 08:50:52 -03:00 committed by GitHub
parent 64d81aa819
commit 65922e6ace
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 267 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
- 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)
- Add documentation for default users and roles (RBAC) [(#535)](https://github.com/wazuh/wazuh-indexer-plugins/pull/535)
### Dependencies
-

5
docs/SUMMARY.md
View File

@ -13,6 +13,7 @@
- [Run Tests](dev/run-tests.md)
- [Plugins]()
- [Setup](dev/plugins/setup.md)
- [Security](dev/plugins/security.md)
# Reference Manual
@ -27,7 +28,7 @@
- [Configuration]()
- [Environment variables]()
- [Command line options]()
- [Configuration files]()
- [Configuration files](ref/configuration/configuration-files.md)
- [Modules]()
- [Setup](ref/modules/setup/index.md)
- [Architecture](ref/modules/setup/architecture.md)
@ -36,6 +37,8 @@
- [Uninstall](ref/uninstall.md)
- [Back Up and Restore](ref/backup-restore.md)
- [Security]()
- [Access Control](ref/security/access-control.md)
- [Defining Users and Roles](ref/security/defining-users-and-roles.md)
- [Performance]()
- [Glossary]()

131
docs/dev/plugins/security.md Normal file
View File

@ -0,0 +1,131 @@
# 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/`.
```yaml
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](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#internal_usersyml)
## 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](https://docs.opensearch.org/docs/latest/security/access-control/default-action-groups/)_
```yaml
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](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#rolesyml)
- [action_groups.yml](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#action_groupsyml)
- [Default action groups](https://docs.opensearch.org/docs/latest/security/access-control/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.
```yaml
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](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#roles_mappingymll)
## 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](../build-packages.md)).
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](https://docs.opensearch.org/docs/latest/security/access-control/users-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.
<div class="warning">
The `indexer-security-init.sh` will overwrite your security configuration, including passwords. Use it under your own risk.
Alternatively, apply the new configuration using fine-grained options. See [Applying changes to configuration files](https://docs.opensearch.org/docs/latest/security/configuration/security-admin/)
</div>

2
docs/dev/plugins/setup.md
View File

@ -148,4 +148,4 @@ 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.
ISM policies and templates must be properly deployed before the indices are created.

0
docs/ref/configuration.md → docs/ref/configuration/README.md
View File

23
docs/ref/configuration/configuration-files.md Normal file
View File

@ -0,0 +1,23 @@
# Configuration Files
## Security - Access Control
Wazuh Indexer uses the [OpenSearch Security plugin](https://docs.opensearch.org/docs/latest/security/) to manage access control and security features.
The configuration files for the security plugin are located under the `/etc/wazuh-indexer/opensearch-security/` directory by default.
<div class="warning">
Modifying these files directly is not recommened. Instead, use the Wazuh Dashboard Security plugin to create new security resouces. See [Define Users and Roles](/ref/security/defining-users-and-roles.md).
</div>
Among these files, Wazuh Indexer uses these particularly to add its own security resources:
- **`internal_users.yml`**: Defines the internal users for the Wazuh Indexer. Each user has a hashed password, reserved status, backend roles, and a description.
- **`roles.yml`**: Defines the roles and their permissions within the Wazuh Indexer. Each role specifies the cluster permissions, index permissions, and tenant permissions.
- **`roles_mapping.yml`**: Maps users and backend roles to the defined roles. This file specifies which users or backend roles have access to each role.
The [Access Control](/ref/security/access-control.md) section contains information about the security resources added to the Wazuh Indexer by default.

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

@ -116,4 +116,4 @@ The plugin is documented using JavaDoc. You can compile the documentation using
```bash
./gradlew javadoc
```
```

0
docs/ref/security.md → docs/ref/security/README.md
View File

32
docs/ref/security/access-control.md Normal file
View File

@ -0,0 +1,32 @@
# Access Control
Wazuh Indexer uses the OpenSearch Security plugin to manage access control and security features. This allows you to define users, roles, and permissions for accessing indices and performing actions within the Wazuh Indexer.
> You can find a more detailed overview of the OpenSearch Security plugin in the [OpenSearch documentation](https://docs.opensearch.org/docs/latest/security/access-control/index/).
## Wazuh default Internal Users
Wazuh defines internal users and roles for the different Wazuh components to handle index management.
These default users and roles definitions are stored in the `internal_users.yml`, `roles.yml`, and `roles_mapping.yml` files on the `/etc/wazuh-indexer/opensearch-security/` directory.
> Find more info about the configurations files in the [Configuration Files](/ref/configuration/configuration-files.md) section.
### Users
| User | Description | Roles |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `wazuh-server` | User for the Wazuh Server with read/write access to stateful indices and write-only access to stateless indices. | `stateless-write`, `stateful-delete`, `stateful-write`, `stateful-read` |
| `wazuh-dashboard` | User for Wazuh Dashboard with read access to stateful and stateless indices, and management level permissionsfor the monitoring indices. | `sample-data-management`, `metrics-write`, `metrics-read`, `stateless-read`, `stateful-read` |
### Roles
| Role Name | Access Description | Index Patterns | Permissions |
| ------------------------ | --------------------------------------------------- | ---------------------------------------- | ----------------------- |
| `stateful-read` | Grants read-only permissions to stateful indices. | `wazuh-states-*` | `read` |
| `stateful-write` | Grants write-only permissions to stateful indices. | `wazuh-states-*` | `index` |
| `stateful-delete` | Grants delete permissions to stateful indices. | `wazuh-states-*` | `delete` |
| `stateless-read` | Grants read-only permissions to stateless indices. | `wazuh-alerts*`, `wazuh-archives*` | `read` |
| `stateless-write` | Grants write-only permissions to stateless indices. | `wazuh-alerts*`, `wazuh-archives*` | `index` |
| `metrics-read` | Grants read permissions to metrics indices. | `wazuh-monitoring*`, `wazuh-statistics*` | `read` |
| `metrics-write` | Grants write permissions to metrics indices. | `wazuh-monitoring*`, `wazuh-statistics*` | `index` |
| `sample-data-management` | Grants full permissions to sample data indices. | `*-sample-*` | `data_access`, `manage` |

74
docs/ref/security/defining-users-and-roles.md Normal file
View File

@ -0,0 +1,74 @@
# Defining Users and Roles
You can create and manage users and roles through the Wazuh Dashboard UI.
<div class="warning">
Default users and roles cannot be modified. Instead, duplicate them and modify the duplicates.
</div>
## Creating a New User, Role, and Role Mapping via the Wazuh Dashboard
> **Prerequisites**
>
> * You must be logged in as a user with administrative privileges (e.g., `admin`).
Follow these steps:
### 1. Create a Role
1. In the Wazuh Dashboard, go to **Index Management** -> **Security** -> **Roles**.
2. Click **Create role**.
3. Enter a **Role name** (e.g., `custom-read-write`).
4. Under **Cluster permissions**, select permissions if needed.
5. Under **Index permissions**:
* **Index**: e.g., `wazuh-*`
* **Index permissions**: choose appropriate actions such as:
* `read` (to allow read access)
* `index` (to allow write access)
* Optionally, configure [**Document-level security (DLS)**](https://docs.opensearch.org/docs/latest/security/access-control/index/) or [**Field-level security (FLS)**](https://docs.opensearch.org/docs/latest/security/access-control/field-level-security/).
6. Click **Create** to save the role.
### 2. Create a User
1. In the Wazuh Dashboard, go to **Index Management** -> **Security** -> **Internal users**.
2. Click **Create internal user**.
3. Fill in the following:
* **Username** (e.g., `new-user`)
* **Password** (enter and confirm)
* **Description** (optional)
4. Click **Create** to create the user.
### 3. Verify Role Mapping
When you assign a role to a user during creation, the mapping is created automatically. To review or edit:
1. In **Security**, go to **Roles**.
2. Find and click your role (`custom-read-write`).
3. Go to **Mapped users**
4. Click **Map users**.
5. Fill in the following:
* **Users** (e.g., `new-user`).
* **Backend roles** (optional).
6. Click **Map** to save the mapping.
### 4. Test Access
After creating the user and role:
1. Log out from the Dashboard.
2. Log in with the new user's credentials.
3. Navigate to **Index Management** -> **Dev Tools**.
4. Run a query to test access, such as:
```console
GET /wazuh-*/_search
```
---
## Additional Resources
* [OpenSearch Security Plugin - User Management](https://opensearch.org/docs/latest/security/access-control/users/)
* [OpenSearch Security Plugin - Roles](https://opensearch.org/docs/latest/security/access-control/roles/)