Add documentation and update changelog

Update CHANGELOG.md format (#3647)

CHANGELOG.md

@@ -2,78 +2,89 @@
 
 ### Added
 
-- Set authd password in agents installation. ([#2524](https://github.com/wazuh/wazuh-docker/issues/2524))
+
-- Added bump-issue-link support for Revert Stage Bump. ([#2505](https://github.com/wazuh/wazuh-docker/pull/2505))
+| Issue | Comment |
-- Add integration test module docs ([#2491](https://github.com/wazuh/wazuh-docker/pull/2491))
+| - | - |
-- Implement the wazuh-docker integration testing module ([#2188](https://github.com/wazuh/wazuh-docker/issues/2188))
+| [#2524](https://github.com/wazuh/wazuh-docker/issues/2524) | Set authd password in agents installation. |
-- Support Revert bump functionality in wazuh-docker ([#2320](https://github.com/wazuh/wazuh-docker/issues/2320))
+| [#2505](https://github.com/wazuh/wazuh-docker/pull/2505) | Added bump-issue-link support for Revert Stage Bump. |
-- Docker and AMI workflows failing during stage release (v5.0.0-beta1) ([#35457](https://github.com/wazuh/wazuh/issues/35457))
+| [#2491](https://github.com/wazuh/wazuh-docker/pull/2491) | Add integration test module docs |
-- Add `--set-as-main` flag support to repository bumper — `wazuh-docker` ([#2276](https://github.com/wazuh/wazuh-docker/issues/2276))
+| [#2188](https://github.com/wazuh/wazuh-docker/issues/2188) | Implement the wazuh-docker integration testing module |
+| [#2320](https://github.com/wazuh/wazuh-docker/issues/2320) | Support Revert bump functionality in wazuh-docker |
+| [#35457](https://github.com/wazuh/wazuh/issues/35457) | Docker and AMI workflows failing during stage release (v5.0.0-beta1) |
+| [#2276](https://github.com/wazuh/wazuh-docker/issues/2276) | Add `--set-as-main` flag support to repository bumper — `wazuh-docker` |
 
 ### Changed
 
-- Update deployment for Wazuh Indexer 5.0.0 RBAC ([#2537](https://github.com/wazuh/wazuh-docker/issues/2537))
+
-- Add new WF for changelog check ([#2539](https://github.com/wazuh/wazuh-docker/pull/2539))
+| Issue | Comment |
-- Change artifact upload and download ([#2502](https://github.com/wazuh/wazuh-docker/issues/2502))
+| - | - |
-- Change runners on repository workflows 5.x ([#2471](https://github.com/wazuh/wazuh-docker/issues/2471))
+| [#2564](https://github.com/wazuh/wazuh-docker/issues/2564) | Add default AI assistant encryption key in the post installation script |
-- PR revamp modifications 5.x ([#2446](https://github.com/wazuh/wazuh-docker/issues/2446))
+| [#2537](https://github.com/wazuh/wazuh-docker/issues/2537) | Update deployment for Wazuh Indexer 5.0.0 RBAC |
-- Forbid pr_check workflow execution in draft PRs ([#2399](https://github.com/wazuh/wazuh-docker/issues/2399))
+| [#2539](https://github.com/wazuh/wazuh-docker/pull/2539) | Add new WF for changelog check |
-- Unification of user UID and GID ([#2375](https://github.com/wazuh/wazuh-docker/issues/2375))
+| [#2502](https://github.com/wazuh/wazuh-docker/issues/2502) | Change artifact upload and download |
-- Wazuh indexer engine requirements ([#2392](https://github.com/wazuh/wazuh-docker/issues/2392))
+| [#2471](https://github.com/wazuh/wazuh-docker/issues/2471) | Change runners on repository workflows 5.x |
-- Image build process update ([#2356](https://github.com/wazuh/wazuh-docker/issues/2356))
+| [#2446](https://github.com/wazuh/wazuh-docker/issues/2446) | PR revamp modifications 5.x |
-- Add new path on artifact_urls file ([#2344](https://github.com/wazuh/wazuh-docker/issues/2344))
+| [#2399](https://github.com/wazuh/wazuh-docker/issues/2399) | Forbid pr_check workflow execution in draft PRs |
-- Unable to generate single component in `Procedure_push_docker_images` ([#2341](https://github.com/wazuh/wazuh-docker/issues/2341))
+| [#2375](https://github.com/wazuh/wazuh-docker/issues/2375) | Unification of user UID and GID |
-- Adapt bumper workflows to change main branch ([#2294](https://github.com/wazuh/wazuh-docker/issues/2294))
+| [#2392](https://github.com/wazuh/wazuh-docker/issues/2392) | Wazuh indexer engine requirements |
-- Ensure default values are used for variables and passwords ([#2288](https://github.com/wazuh/wazuh-docker/issues/2288))
+| [#2356](https://github.com/wazuh/wazuh-docker/issues/2356) | Image build process update |
-- Docker - Ensure correct Wazuh manager certificates ownership ([#2283](https://github.com/wazuh/wazuh-docker/issues/2283))
+| [#2344](https://github.com/wazuh/wazuh-docker/issues/2344) | Add new path on artifact_urls file |
-- Docker - Standarize Artifact URL keys ([#2278](https://github.com/wazuh/wazuh-docker/issues/2278))
+| [#2341](https://github.com/wazuh/wazuh-docker/issues/2341) | Unable to generate single component in `Procedure_push_docker_images` |
-- Modify artifact URLs file name. ([#2266](https://github.com/wazuh/wazuh-docker/issues/2266))
+| [#2294](https://github.com/wazuh/wazuh-docker/issues/2294) | Adapt bumper workflows to change main branch |
-- URL presigned file -  Update the Wazuh Docker image creation workflow ([#2218](https://github.com/wazuh/wazuh-docker/issues/2218))
+| [#2288](https://github.com/wazuh/wazuh-docker/issues/2288) | Ensure default values are used for variables and passwords |
-- Updated wazuh-docker documentation config and tooling versions to meet new standards. ([#2264](https://github.com/wazuh/wazuh-docker/issues/2264))
+| [#2283](https://github.com/wazuh/wazuh-docker/issues/2283) | Docker - Ensure correct Wazuh manager certificates ownership |
-- Align cert generation steps with current cert-tool ip validation ([#2250](https://github.com/wazuh/wazuh-docker/issues/2250))
+| [#2278](https://github.com/wazuh/wazuh-docker/issues/2278) | Docker - Standarize Artifact URL keys |
-- Modify Healthchecks ([#2252](https://github.com/wazuh/wazuh-docker/issues/2252))
+| [#2266](https://github.com/wazuh/wazuh-docker/issues/2266) | Modify artifact URLs file name. |
-- Add deployment healthchecks ([#2251](https://github.com/wazuh/wazuh-docker/issues/2251))
+| [#2218](https://github.com/wazuh/wazuh-docker/issues/2218) | URL presigned file -  Update the Wazuh Docker image creation workflow |
-- Update artifact generation jobs to use wz-linux dedicated runner group ([#2242](https://github.com/wazuh/wazuh-docker/issues/2242))
+| [#2264](https://github.com/wazuh/wazuh-docker/issues/2264) | Updated wazuh-docker documentation config and tooling versions to meet new standards. |
-- Error during Wazuh manager entrypoint ([#2237](https://github.com/wazuh/wazuh-docker/issues/2237))
+| [#2250](https://github.com/wazuh/wazuh-docker/issues/2250) | Align cert generation steps with current cert-tool ip validation |
-- Adapt PR test for workflow_dispatch option ([#2230](https://github.com/wazuh/wazuh-docker/issues/2230))
+| [#2252](https://github.com/wazuh/wazuh-docker/issues/2252) | Modify Healthchecks |
-- Wazuh Manager/agent Separation - Breaking changes summary ([#2227](https://github.com/wazuh/wazuh-docker/issues/2227))
+| [#2251](https://github.com/wazuh/wazuh-docker/issues/2251) | Add deployment healthchecks |
-- Errors in wazuh-docker PR Test ([#2222](https://github.com/wazuh/wazuh-docker/issues/2222))
+| [#2242](https://github.com/wazuh/wazuh-docker/issues/2242) | Update artifact generation jobs to use wz-linux dedicated runner group |
-- Development - Separate Agent/Manager - Docker - Adapt image build process ([#2206](https://github.com/wazuh/wazuh-docker/issues/2206))
+| [#2237](https://github.com/wazuh/wazuh-docker/issues/2237) | Error during Wazuh manager entrypoint |
-- Remove revision input ([#2217](https://github.com/wazuh/wazuh-docker/issues/2217))
+| [#2230](https://github.com/wazuh/wazuh-docker/issues/2230) | Adapt PR test for workflow_dispatch option |
-- Build images script improvement ([#2196](https://github.com/wazuh/wazuh-docker/issues/2196))
+| [#2227](https://github.com/wazuh/wazuh-docker/issues/2227) | Wazuh Manager/agent Separation - Breaking changes summary |
-- Missing documentation in the wazuh-docker repository ([#2197](https://github.com/wazuh/wazuh-docker/issues/2197))
+| [#2222](https://github.com/wazuh/wazuh-docker/issues/2222) | Errors in wazuh-docker PR Test |
-- Add Wazuh version and revision into wazuh-certs-tool and config file ([#2195](https://github.com/wazuh/wazuh-docker/issues/2195))
+| [#2206](https://github.com/wazuh/wazuh-docker/issues/2206) | Development - Separate Agent/Manager - Docker - Adapt image build process |
-- Improve S3 artifact URLs handling ([#2172](https://github.com/wazuh/wazuh-docker/issues/2172))
+| [#2217](https://github.com/wazuh/wazuh-docker/issues/2217) | Remove revision input |
-- Allow building separate targets ([#2164](https://github.com/wazuh/wazuh-docker/issues/2164))
+| [#2196](https://github.com/wazuh/wazuh-docker/issues/2196) | Build images script improvement |
-- Add developement option when tag name is only version without stage ([#2179](https://github.com/wazuh/wazuh-docker/issues/2179))
+| [#2197](https://github.com/wazuh/wazuh-docker/issues/2197) | Missing documentation in the wazuh-docker repository |
-- Add IMAGE_TAG stage reference ([#2178](https://github.com/wazuh/wazuh-docker/issues/2178))
+| [#2195](https://github.com/wazuh/wazuh-docker/issues/2195) | Add Wazuh version and revision into wazuh-certs-tool and config file |
-- Remove Wazuh agent configuration template ([#2171](https://github.com/wazuh/wazuh-docker/issues/2171))
+| [#2172](https://github.com/wazuh/wazuh-docker/issues/2172) | Improve S3 artifact URLs handling |
-- Docker - Ensure `run_as` set to true for every deployment alternative ([#2156](https://github.com/wazuh/wazuh-docker/issues/2156))
+| [#2164](https://github.com/wazuh/wazuh-docker/issues/2164) | Allow building separate targets |
-- Change macOS and Windows deployment documentation ([#2150](https://github.com/wazuh/wazuh-docker/issues/2150))
+| [#2179](https://github.com/wazuh/wazuh-docker/issues/2179) | Add developement option when tag name is only version without stage |
-- Modify docker build image process ([#2131](https://github.com/wazuh/wazuh-docker/issues/2131))
+| [#2178](https://github.com/wazuh/wazuh-docker/issues/2178) | Add IMAGE_TAG stage reference |
-- Update documentation for Wazuh Docker image builder and workflow usage ([#2136](https://github.com/wazuh/wazuh-docker/issues/2136))
+| [#2171](https://github.com/wazuh/wazuh-docker/issues/2171) | Remove Wazuh agent configuration template |
-- Configure deployment with environment variables ([#2081](https://github.com/wazuh/wazuh-docker/issues/2081))
+| [#2156](https://github.com/wazuh/wazuh-docker/issues/2156) | Docker - Ensure `run_as` set to true for every deployment alternative |
-- Modify Wazuh components install method ([#2058](https://github.com/wazuh/wazuh-docker/issues/2058))
+| [#2150](https://github.com/wazuh/wazuh-docker/issues/2150) | Change macOS and Windows deployment documentation |
-- Image builder Workflow Rebuild ([#2054](https://github.com/wazuh/wazuh-docker/issues/2054))
+| [#2131](https://github.com/wazuh/wazuh-docker/issues/2131) | Modify docker build image process |
-- Remove Wazuh Manager deprecated daemons and CLI tools ([#1933](https://github.com/wazuh/wazuh-docker/issues/1933))
+| [#2136](https://github.com/wazuh/wazuh-docker/issues/2136) | Update documentation for Wazuh Docker image builder and workflow usage |
-- DevOps - Docker - OpenSearch 3.0 deprecated settings ([#1891](https://github.com/wazuh/wazuh-docker/issues/1891))
+| [#2081](https://github.com/wazuh/wazuh-docker/issues/2081) | Configure deployment with environment variables |
+| [#2058](https://github.com/wazuh/wazuh-docker/issues/2058) | Modify Wazuh components install method |
+| [#2054](https://github.com/wazuh/wazuh-docker/issues/2054) | Image builder Workflow Rebuild |
+| [#1933](https://github.com/wazuh/wazuh-docker/issues/1933) | Remove Wazuh Manager deprecated daemons and CLI tools |
+| [#1891](https://github.com/wazuh/wazuh-docker/issues/1891) | DevOps - Docker - OpenSearch 3.0 deprecated settings |
 
 ### Removed
 
-- None
+| Issue | Comment |
+| - | - |
 
 ### Fixed
 
-- Fix bumper workflow failure when bump produces no changes ([#2533](https://github.com/wazuh/wazuh-docker/pull/2533))
-- Bumper script issue when the tag is set to false ([#2477](https://github.com/wazuh/wazuh-docker/issues/2477))
-- Fix reported WF vulnerabilities ([#2443](https://github.com/wazuh/wazuh-docker/issues/2443))
-- Adapt Wazuh manager healthcheck with local binaries ([#2422](https://github.com/wazuh/wazuh-docker/issues/2422))
-- The Wazuh Docker image cannot be built during the Nightly ([#2337](https://github.com/wazuh/wazuh-docker/issues/2337))
-- Docker and AMI workflows failing during stage release (v5.0.0-beta1) ([#35457](https://github.com/wazuh/wazuh/issues/35457))
-- PR check issues ([#2274](https://github.com/wazuh/wazuh-docker/issues/2274))
-- Wazuh manager Healthcheck ([#2271](https://github.com/wazuh/wazuh-docker/issues/2271))
-- Delete WAZUH_AGENT_GROUPS of Wazuh 5.0.0 images build ([#2258](https://github.com/wazuh/wazuh-docker/issues/2258))
-- Development - DevOps 5.0 adaptation - Docker - Delete lists directory references ([#2128](https://github.com/wazuh/wazuh-docker/issues/2128))
 
-## Prior version
+| Issue | Comment |
+| - | - |
+| [#2533](https://github.com/wazuh/wazuh-docker/pull/2533) | Fix bumper workflow failure when bump produces no changes |
+| [#2477](https://github.com/wazuh/wazuh-docker/issues/2477) | Bumper script issue when the tag is set to false |
+| [#2443](https://github.com/wazuh/wazuh-docker/issues/2443) | Fix reported WF vulnerabilities |
+| [#2422](https://github.com/wazuh/wazuh-docker/issues/2422) | Adapt Wazuh manager healthcheck with local binaries |
+| [#2337](https://github.com/wazuh/wazuh-docker/issues/2337) | The Wazuh Docker image cannot be built during the Nightly |
+| [#35457](https://github.com/wazuh/wazuh/issues/35457) | Docker and AMI workflows failing during stage release (v5.0.0-beta1) |
+| [#2274](https://github.com/wazuh/wazuh-docker/issues/2274) | PR check issues |
+| [#2271](https://github.com/wazuh/wazuh-docker/issues/2271) | Wazuh manager Healthcheck |
+| [#2258](https://github.com/wazuh/wazuh-docker/issues/2258) | Delete WAZUH_AGENT_GROUPS of Wazuh 5.0.0 images build |
+| [#2128](https://github.com/wazuh/wazuh-docker/issues/2128) | Development - DevOps 5.0 adaptation - Docker - Delete lists directory references |
+
+## Prior versions
 - []()

build-docker-images/wazuh-dashboard/Dockerfile

@@ -44,6 +44,9 @@ RUN mkdir -p $INSTALL_DIR/data/wazuh/config && chmod -R 775 $INSTALL_DIR/data/wa
 RUN mkdir -p $INSTALL_DIR/data/wazuh/logs && chmod -R 775 $INSTALL_DIR/data/wazuh/logs
 RUN setcap 'cap_net_bind_service=-ep' /usr/share/wazuh-dashboard/node/bin/node
 
+# Delete default keystore
+RUN if [ -f /etc/wazuh-dashboard/opensearch_dashboards.keystore ]; then rm -f /etc/wazuh-dashboard/opensearch_dashboards.keystore; fi
+
 ################################################################################
 # Build stage 1 (the current Wazuh dashboard image):
 # Copy wazuh-dashboard from builder

build-docker-images/wazuh-dashboard/config/entrypoint.sh

@@ -20,9 +20,14 @@ DASHBOARD_PASSWORD="${DASHBOARD_PASSWORD:-kibanaserver}"
 
 # Create and configure Wazuh dashboard keystore
 
-yes | $OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore create --allow-root && \
+
-echo $DASHBOARD_USERNAME | $OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore add opensearch.username --stdin --allow-root && \
+if  [ ! -f "$OPENSEARCH_DASHBOARDS_HOME/config/opensearch_dashboards.keystore" ]; then
-echo $DASHBOARD_PASSWORD | $OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore add opensearch.password --stdin --allow-root
+    echo "The keystore is not available; creating a new keystore."
+    "$OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore" create --allow-root
+    head -c 32 /dev/urandom | base64 | tr -d '\n' | "$OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore" add wazuh_ai_assistant.encryptionKey --stdin --allow-root
+fi
+echo $DASHBOARD_USERNAME | "$OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore" add opensearch.username --stdin --allow-root -f
+echo $DASHBOARD_PASSWORD | "$OPENSEARCH_DASHBOARDS_HOME/bin/opensearch-dashboards-keystore" add opensearch.password --stdin --allow-root -f
 
 /wazuh_dashboard_config.sh
 

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 "<your-encryption-key>" | 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/)

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
 

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.