Passwortwechsel in verteilten Wazuh-Deployments ohne Downtime: Warum das Dashboard „down“ geht und wie man es sauber wieder verbindet

Einleitung
Passwortrotation ist in produktiven SIEM-/XDR-Umgebungen Pflicht – aber in verteilten Wazuh-Deployments kann ein unvollständig durchgezogener Passwortwechsel schnell zum Totalausfall des Dashboards führen. Typisches Symptom: opensearch-dashboards wirft fortlaufend [ResponseError], während der Manager und der Indexer scheinbar „laufen“. Dieser Artikel erklärt die häufigsten Ursachen in der Wazuh-Architektur, warum wazuh-passwords-tool.sh auf dem Manager nur die Help-Page ausgibt oder „Invalid admin user credentials“ meldet, und welche Best Practices ein Rollback vermeiden.

Ausgangslage / Problemstellung
In einem distributed deployment werden Passwörter nach Anleitung aus der Wazuh-Dokumentation geändert. Auf dem Indexer wurde ausgeführt:

• /usr/share/wazuh-indexer/plugins/opensearch-security/tools/wazuh-passwords-tool.sh --change-all

Danach auf dem Server/Manager (für API-Passwörter) ein Aufruf wie:

• bash wazuh-passwords-tool.sh --api --admin-user wazuh --admin-password <WAZUH_PASSWORD>

Statt einer Änderung erscheint jedoch nur die Help-Page bzw. bei file-basiertem Vorgehen Meldungen wie:

• INFO: Wazuh API admin credentials not provided, Wazuh API passwords not changed.
• ERROR: Invalid admin user credentials

Parallel fällt das produktive Dashboard aus, im Log z. B.:

• opensearch-dashboards ... [ResponseError]: Response Error

Technische Analyse

1) In verteilten Deployments ist Passwortwechsel ein Koordinationsproblem

Wazuh unterscheidet zwei große Credential-Welten:

• Indexer interne Nutzer (OpenSearch Security / Internal Users) – relevant für Indexer-Zugriffe des Dashboards und ggf. der Shipper-Komponenten.
• Wazuh Server API Nutzer – relevant für Dashboard↔API-Kommunikation und API-Calls (z. B. Integrationen, Automations, externe Tools).

Die Wazuh-Doku betont, dass in distributed environments nach dem Ändern eines Passworts häufig weitere Komponenten manuell aktualisiert und Dienste neu gestartet werden müssen. Genau das ist die häufigste Ursache für „Dashboard down nach Password Change“. Wazuh Dokumentation

2) Warum das Dashboard „down“ wirkt, obwohl Indexer läuft

Das Wazuh Dashboard hängt in der Praxis an zwei kritischen Verbindungen:

1. Dashboard → Indexer (OpenSearch)
2. Dashboard → Wazuh API

Wenn ein Passwort gewechselt wurde, aber nicht in allen Konfigurationsstellen aktualisiert ist, kommt es zu Auth-Fehlschlägen, die im Dashboard häufig generisch als ResponseError erscheinen.

Wazuh dokumentiert explizit, dass man nach Passwortänderungen die Dashboard-Konfiguration aktualisieren muss, und nennt das zentrale Config-File wazuh.yml. Wazuh Dokumentation+1

3) Das wazuh-passwords-tool.sh-Verhalten: „API admin credentials not provided“

Die Meldung ist wörtlich zu nehmen: Das Tool ändert API-Passwörter nur dann, wenn du zusätzlich gültige Admin-Credentials für die Wazuh API angibst. Ansonsten wird ausschließlich der Indexer-Teil geändert bzw. der API-Teil übersprungen. Dieses Vorgehen ist in der Password-Management-Dokumentation beschrieben und wird in Community-Fällen regelmäßig missverstanden. Wazuh Dokumentation+1

4) „Invalid admin user credentials“ – typischer Root Cause

Das tritt meist auf, wenn eines der folgenden Probleme vorliegt:

• Du verwendest nicht den tatsächlichen API-Admin-User (in einigen Setups ist das nicht „wazuh“).
• Das Passwort wurde zuvor bereits geändert, aber du nutzt noch den alten Stand.
• API ist nicht erreichbar/terminiert TLS anders (dann schlagen Auth-Versuche ebenfalls fehl).
• Credentials wurden am Indexer rotiert, aber du erwartest, dass das automatisch die API-Seite „mitzieht“ (tut es nicht).

Lösung / Best Practices

1) Sauberer Recovery-Ansatz: Dashboard wieder verbinden statt „Rollback“

In der Praxis ist „Rollback“ nach --change-all selten die beste Option – stabiler ist, die neuen Credentials überall konsistent zu setzen.

A) Dashboard↔API wiederherstellen
Wazuh dokumentiert das Dashboard-Config-File:

• /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml Wazuh Dokumentation

Dort müssen die API-Zugangsdaten (User/Pass) auf den neuen Stand gebracht werden. Danach wazuh-dashboard/opensearch-dashboards neu starten.

B) Dashboard↔Indexer wiederherstellen
Wenn du Indexer-User-Passwörter geändert hast, müssen auch die OpenSearch-Dashboard/Indexer-Credentials (je nach Deployment-Template) aktualisiert werden. Die Password-Management-Doku weist darauf hin, dass nach Änderungen je nach User Passwörter in Dashboard und weiteren Nodes zu aktualisieren sind. Wazuh Dokumentation

2) Passwortänderung korrekt durchführen: formatted file + Admin-Creds zwingend

Wenn du API-Passwörter per Datei ändern willst, musst du dem Tool zusätzlich die gültigen Admin-Credentials übergeben, sonst bekommst du genau die Info-Meldung, dass API-Passwörter nicht geändert wurden. Wazuh Dokumentation

Das ist kein „Formatproblem“ mit Quotes, sondern eine fehlende Authentisierung für die API-Passwortänderung.

3) Reihenfolge, die Ausfälle minimiert

Für produktive, verteilte Deployments hat sich folgende Reihenfolge bewährt:

1. Plan/Mapping: Welche Passwörter werden wo verwendet (Indexer, Dashboard, API, Shipper)?
2. Indexer-User ändern und unmittelbar die abhängigen Komponenten anpassen (Dashboard/Shipments) und Services neu starten. Wazuh Dokumentation
3. API-User ändern (mit gültigen Admin-Creds) und danach das Dashboard-wazuh.yml aktualisieren. Wazuh Dokumentation+1
4. Smoke Test: Dashboard Login, API Health, Indexer Query.

4) Operative Absicherung

• Vorher Konfigs sichern (Dashboard config, relevante Secrets, Indexer Security Config).
• Passwortwechsel in Wartungsfenster.
• Änderungen immer komponentenweise validieren (erst Indexer-Link, dann API-Link).

Lessons Learned / Best Practices

• In distributed Wazuh gilt: Passwortwechsel ist kein Single-Command-Event, sondern ein koordinierter Rollout über Indexer, Dashboard und API. Wazuh Dokumentation
• Ein Dashboard-Ausfall nach Passwortrotation ist fast immer ein Credential-Mismatch (Dashboard→API oder Dashboard→Indexer).
• Das Dashboard liest zentrale Parameter aus wazuh.yml; dort müssen API-Credentials konsistent gepflegt werden. Wazuh Dokumentation
• „Invalid admin user credentials“ beim Tool ist meist ein Auth- oder User-Mapping-Thema – kein Quote-/Shell-Escaping-Problem.

Fazit
Wenn nach --change-all das Wazuh Dashboard „down“ ist und opensearch-dashboards nur noch ResponseError loggt, ist die wahrscheinlichste Ursache ein nicht konsistent aktualisiertes Credential-Set zwischen Indexer, Dashboard und Wazuh API. In verteilten Deployments aktualisiert das Tool nicht automatisch alle abhängigen Komponenten; die Wazuh-Dokumentation weist explizit darauf hin, dass Passwörter im Dashboard und ggf. weiteren Nodes angepasst und Services neu gestartet werden müssen. Der stabile Weg ist daher kein Rollback, sondern das konsequente „Reconnect“-Vorgehen: neue Credentials korrekt in wazuh.yml und den relevanten Indexer-/Dashboard-Konfigurationen setzen und anschließend die Dienste neu starten. Wazuh Dokumentation+1

Mehr zu Wazuh …
https://wazuh.com/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program

Mehr zum Wazuh Ambassador Program …
https://wazuh.com/ambassadors-program/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program

https://wazuh.slack.com/archives/C07CCCCGHHP/p1767101648349039