Wazuh Agent-Status nach Server-Upgrade: Ursachen, Upgrade-Strategien und Automatisierung

von

Einleitung

Upgrades der zentralen Wazuh-Komponenten (Manager, Indexer, Dashboard) gehören zum regulären Betrieb einer SIEM-Plattform. In der Praxis führt ein Versionssprung jedoch häufig zu Verunsicherung, wenn Agents nach dem Upgrade plötzlich als Pending erscheinen, nicht mehr Active sind oder ganz aus dem Dashboard verschwinden. Dieser Artikel fasst eine umfangreiche Community-Diskussion zusammen und zeigt, wie Agent-Status nach Server-Upgrades korrekt eingeordnet werden, welche Upgrade-Strategien empfohlen sind und wie sich Agent-Upgrades sinnvoll automatisieren lassen.

Ausgangslage / Problemstellung

Nach einem Upgrade der Wazuh-Zentrale von einer älteren unterstützten Version auf die aktuelle Version zeigen sich folgende Symptome:

  • Agents erscheinen im Manager oder Dashboard als Pending
  • Einige Agents verschwinden vollständig aus der Ansicht
  • Erwartete automatische Reconnects oder Auto-Upgrades bleiben aus

Zusätzlich stellen sich strategische Fragen:

  • Warum werden Agents nach einem Server-Upgrade nicht automatisch aktualisiert?
  • Welche Upgrade-Methoden sind offiziell empfohlen?
  • Gibt es eine dynamische oder automatische Möglichkeit, Agents versionssynchron zu halten?
  • Welche Ansätze existieren für eine Integration von Wazuh mit OpenCTI?

Technische Analyse

Warum Agents nach einem Upgrade nicht Active sind

Wazuh verfolgt bewusst das Designprinzip, Agents nicht automatisch mit dem Server zu upgraden. Der Hintergrund ist betrieblich und sicherheitsrelevant:

  • Agents laufen oft auf kritischen Systemen (Datenbanken, Banken, OT, Healthcare)
  • Ein Auto-Upgrade könnte:
    • Dienste unerwartet neu starten
    • Downtime verursachen
    • regulatorische Vorgaben verletzen

Nach einem Server-Upgrade bleiben Agents daher auf ihrem alten Stand, bis sie explizit aktualisiert werden. Inkompatible Versionen führen dazu, dass Agents:

  • nicht mehr korrekt verbinden
  • als Pending markiert werden
  • nicht mehr vollständig dargestellt werden

Dieses Verhalten ist beabsichtigt und kein Fehler.

Lösung / Best Practices

Empfohlene Upgrade-Methoden für Agents

Wazuh unterstützt mehrere kontrollierte Upgrade-Ansätze:

1. Remote-Upgrade über die Wazuh API
Über die Dev Tools im Dashboard oder direkt per API:

Dokumentation:
https://documentation.wazuh.com/current/user-manual/agent/agent-management/remote-upgrading/index.html

2. Upgrade über das Agent Summary Dashboard
Für kleinere Umgebungen kann das Upgrade direkt über die Weboberfläche durchgeführt werden.

3. CLI-basierte Upgrades mit Automatisierung
Ein bewährter Ansatz ist die Nutzung des agent_upgrade-Tools:

/var/ossec/bin/agent_upgrade -l | awk '$1 ~ /^[0-9]+$/ {print "Starting upgrade on agent " $1; system("/var/ossec/bin/agent_upgrade -a " $1)}'

Wichtige Hinweise:

  • Der Befehl funktioniert nur, wenn alle Quotes korrekt sind (keine typografischen Anführungszeichen)
  • Ein > im Prompt deutet auf ein unvollständiges Kommando hin
  • Bei vielen Agents kann die Ausführung längere Zeit dauern

Der Befehl agent_upgrade -l listet zunächst alle veralteten Agents auf:
https://documentation.wazuh.com/current/user-manual/agent/agent-management/remote-upgrading/upgrading-agent.html#using-the-command-line

Automatisierung per Cronjob

Eine einfache, aber effektive Strategie ist ein periodischer Cronjob, der:

  • veraltete Agents erkennt
  • diese gezielt upgraded

Damit bleibt die Umgebung weitgehend versionssynchron, ohne unkontrollierte Auto-Upgrades.

Lessons Learned / Best Practices

  • Agent-Auto-Upgrades sind bewusst nicht Teil des Wazuh-Designs
  • Server-Upgrades müssen immer durch ein geplantes Agent-Upgrade ergänzt werden
  • Remote-Upgrades setzen aktive, verbundene Agents voraus
  • Großflächige „Upgrade all“-Aktionen bergen Betriebsrisiken
  • CLI- und API-basierte Automatisierung bietet die beste Balance aus Kontrolle und Effizienz
  • OpenCTI-Integrationen sind möglich, aber aktuell Community-getrieben

Fazit

Wenn Agents nach einem Wazuh-Server-Upgrade nicht mehr Active sind, ist das kein Fehler, sondern eine Folge eines sicherheitsbewussten Designs. Ein strukturierter Upgrade-Prozess für Agents – idealerweise automatisiert, aber kontrolliert – ist essenziell für einen stabilen Betrieb. Mit API, CLI und gezielter Automatisierung lassen sich auch große Agent-Flotten sicher und planbar aktualisieren.

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/p1768968323222289