From 1da1f5083d4bff1067204333df325f594341658a Mon Sep 17 00:00:00 2001 From: Victor Carlos Erenu Date: Thu, 6 Aug 2026 00:17:40 +0700 Subject: [PATCH] Add documentation and update changelog --- CHANGELOG.md | 1 + docs/ref/configuration/configuration-files.md | 14 ++++++++++++++ docs/ref/security.md | 1 + docs/ref/upgrade.md | 2 ++ 4 files changed, 18 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 21edf381..361c23c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ | Issue | Comment | | - | - | +| [#2564](https://github.com/wazuh/wazuh-docker/issues/2564) | Add default AI assistant encryption key in the post installation script | | [#2537](https://github.com/wazuh/wazuh-docker/issues/2537) | Update deployment for Wazuh Indexer 5.0.0 RBAC | | [#2539](https://github.com/wazuh/wazuh-docker/pull/2539) | Add new WF for changelog check | | [#2502](https://github.com/wazuh/wazuh-docker/issues/2502) | Change artifact upload and download | diff --git a/docs/ref/configuration/configuration-files.md b/docs/ref/configuration/configuration-files.md index 0f591f6d..1c5c0151 100644 --- a/docs/ref/configuration/configuration-files.md +++ b/docs/ref/configuration/configuration-files.md @@ -17,6 +17,14 @@ * **`opensearch_dashboards.yml`**: The main configuration file for OpenSearch Dashboards. Controls server host/port, OpenSearch connection URL, SSL settings, and Wazuh plugin settings. * **Customization**: Mount a custom `opensearch_dashboards.yml` into the dashboard container at `/usr/share/wazuh-dashboard/config/opensearch_dashboards.yml` and custom `wazuh.yml` into the dashboard container at `/usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml` . * **Wazuh Plugin Settings**: The Wazuh plugin for the dashboard has its own configuration, often within `opensearch_dashboards.yml` or managed through environment variables, specifying the Wazuh API URL and credentials. +* **`opensearch_dashboards.keystore`**: Secure storage for the dashboard secrets, located at `/usr/share/wazuh-dashboard/config/opensearch_dashboards.keystore`. The image is shipped without a keystore; the container entrypoint creates it on the first start and adds a randomly generated `wazuh_ai_assistant.encryptionKey`, which the AI assistant uses to encrypt its data. The `opensearch.username` and `opensearch.password` entries are set on every start from the `DASHBOARD_USERNAME` and `DASHBOARD_PASSWORD` environment variables. + * **Customization**: To set your own key, add it through the keystore tool inside the dashboard container and restart the service: + ```bash + echo "" | docker compose exec -T wazuh.dashboard \ + /usr/share/wazuh-dashboard/bin/opensearch-dashboards-keystore add wazuh_ai_assistant.encryptionKey --stdin --allow-root -f + docker compose restart wazuh.dashboard + ``` + * **Important**: The keystore is created only when it does not already exist, so the encryption key stays stable across restarts as long as the `/usr/share/wazuh-dashboard/config` volume is kept. If the keystore is deleted, the entrypoint generates a new key on the next start and any data encrypted with the previous one becomes unreadable. ## Applying Configuration Changes @@ -42,6 +50,12 @@ To persist files or directories in your Wazuh deployment, you can mount them as > **Important**: Ensure that files exist on the host before starting the containers. If the file doesn't exist, Docker will create a directory instead, which may cause startup failures. +### Wazuh Dashboard keystore + +The `docker-compose.yml` files mount the named volume `wazuh-dashboard-config` on `/usr/share/wazuh-dashboard/config`, which is where `opensearch_dashboards.keystore` is stored. Keeping this volume preserves the `wazuh_ai_assistant.encryptionKey` generated on the first start. + +Removing the volume (for example, with `docker compose down -v`) deletes the keystore. The next start creates a new one with a different encryption key, and data encrypted by the AI assistant with the previous key can no longer be decrypted. + For more information on Docker volumes and bind mounts, refer to the official Docker documentation: - [Use volumes](https://docs.docker.com/storage/volumes/) - [Bind mounts](https://docs.docker.com/storage/bind-mounts/) diff --git a/docs/ref/security.md b/docs/ref/security.md index e2bd8e4a..7990b820 100644 --- a/docs/ref/security.md +++ b/docs/ref/security.md @@ -7,6 +7,7 @@ This section summarizes security recommendations for Wazuh Docker deployments (s - Do not use default credentials. The Compose examples include placeholder values for the Wazuh API, Dashboard, and Indexer access. - Prefer injecting secrets at runtime (for example, via your CI/CD secret store or an external secrets manager) instead of hardcoding them in `docker-compose.yml`. - Rotate credentials regularly and after any suspected exposure. +- The Wazuh dashboard keeps its secrets in `opensearch_dashboards.keystore`, persisted in the `wazuh-dashboard-config` volume. It stores the Indexer credentials and the `wazuh_ai_assistant.encryptionKey`, generated at random on the first start and unique per deployment. Restrict access to that volume and to `docker compose exec` on the dashboard container, and do not copy the keystore between deployments. ## Certificates and TLS diff --git a/docs/ref/upgrade.md b/docs/ref/upgrade.md index 7e15c983..3786bedb 100644 --- a/docs/ref/upgrade.md +++ b/docs/ref/upgrade.md @@ -10,6 +10,8 @@ Below is a step-by-step example of how to perform this update: docker-compose down ``` + > **Important**: Do not add the `-v` flag. It removes the named volumes, including `wazuh-dashboard-config`, which holds the Wazuh dashboard keystore. Losing that keystore regenerates the `wazuh_ai_assistant.encryptionKey` on the next start and makes the data previously encrypted by the AI assistant unreadable. + 2. **Update the image tags**: Edit your `docker-compose.yml` file and update the `image` field for all Wazuh services to the desired version.