Migration von Wazuh 4.x auf Wazuh 5.x: Architekturänderungen, Konfigurationsmigration und neue Verwaltung von Erkennungsregeln

Einleitung

Mit Wazuh 5.x vollzieht die Plattform einen grundlegenden Architekturwechsel. Administratoren, die von einer bestehenden Wazuh-4.x-Umgebung migrieren möchten, müssen sich darauf einstellen, dass die Migration nicht mit einem klassischen Versionsupgrade vergleichbar ist. Stattdessen werden Konfiguration, Regelverwaltung und Teile der Datenanalyse neu organisiert. Dieser Artikel erläutert die wichtigsten Unterschiede zwischen Wazuh 4.x und 5.x, beschreibt den empfohlenen Migrationspfad und zeigt auf, welche Auswirkungen die Änderungen auf den täglichen Betrieb haben.

Ausgangslage / Problemstellung

Viele Administratoren gehen davon aus, dass sich eine bestehende Wazuh-4.x-Installation ähnlich wie frühere Versionen direkt aktualisieren lässt. Bei Wazuh 5.x ist dies jedoch nicht der Fall.

Zu den häufigsten Fragestellungen gehören:

Gibt es einen direkten Upgradepfad von Wazuh 4.x auf 5.x?
Können bestehende ossec.conf-Konfigurationen übernommen werden?
Werden benutzerdefinierte Regeln weiterhin als XML-Dateien verwaltet?
Erfolgt die Regelverwaltung ausschließlich über das Webinterface?

Gerade Umgebungen mit umfangreichen Custom Rules, Decodern oder individuellen Integrationen müssen diese Änderungen frühzeitig berücksichtigen, um einen reibungslosen Umstieg sicherzustellen.

Technische Analyse

Kein In-Place-Upgrade

Wazuh 5.x unterstützt keinen direkten In-Place-Upgradepfad von einer bestehenden 4.x-Installation.

Stattdessen empfiehlt das Projekt ausdrücklich, eine vollständig neue Wazuh-5.x-Umgebung bereitzustellen und anschließend die unterstützten Konfigurationen sowie Sicherheitsrichtlinien manuell zu übernehmen. Dadurch lassen sich auch grundlegende Architekturänderungen sauber berücksichtigen.

Dieser Ansatz reduziert das Risiko, veraltete oder inkompatible Einstellungen in die neue Plattform zu übernehmen.

Neue Manager-Konfiguration

Eine der sichtbarsten Änderungen betrifft die Manager-Konfiguration.

Während unter Wazuh 4.x die zentrale Konfigurationsdatei üblicherweise

/var/ossec/etc/ossec.conf

war, verwendet Wazuh 5.x eine neue Struktur mit der Datei

/var/wazuh-manager/etc/wazuh-manager.conf

Dabei wurden zahlreiche Konfigurationsparameter überarbeitet oder neu strukturiert. Ein einfaches Kopieren der bisherigen ossec.conf ist daher nicht vorgesehen und kann zu Fehlfunktionen oder nicht unterstützten Konfigurationen führen.

Stattdessen sollten Administratoren die bestehende Konfiguration analysieren und nur die weiterhin unterstützten Einstellungen gezielt in die neue Konfiguration übernehmen.

Neue Verwaltung von Regeln und Decodern

Eine der größten funktionalen Änderungen betrifft die Erkennungslogik.

Während Wazuh 4.x benutzerdefinierte Regeln überwiegend als XML-Dateien verwaltete, setzt Wazuh 5.x auf eine modernisierte Architektur:

Custom Rules verwenden das YAML-Format.
Die Verwaltung erfolgt über den Bereich Security Analytics im Wazuh Dashboard.
Regeln durchlaufen einen definierten Workflow:
1. Draft
2. Test
3. Custom
4. Erstellung eines Detectors

Bestehende XML-Regeln können daher nicht einfach übernommen werden. Individuelle Erkennungslogik muss in das neue Format übertragen und anschließend getestet werden.

Verwaltung nicht ausschließlich über das Dashboard

Obwohl die grafische Oberfläche einen zentralen Bestandteil der neuen Verwaltung darstellt, ist sie nicht die einzige Möglichkeit.

Der integrierte Content Manager stellt zusätzlich APIs bereit, mit denen sich unter anderem folgende Inhalte automatisiert verwalten lassen:

Custom Rules
Decoder
Integrationen
KVDB-Inhalte

Dadurch können bestehende Automatisierungsprozesse und Infrastructure-as-Code-Ansätze auch unter Wazuh 5.x weiter genutzt oder neu aufgebaut werden.

Lösung / Best Practices

Für eine erfolgreiche Migration empfiehlt sich folgendes Vorgehen:

Eine separate Wazuh-5.x-Testumgebung bereitstellen.
Die bestehende 4.x-Konfiguration analysieren und dokumentieren.
Keine Dateien direkt übernehmen, insbesondere nicht die alte ossec.conf.
Manager-Konfiguration anhand der neuen Architektur neu erstellen.
Sämtliche Custom Rules und Decoder auf das neue YAML-Format migrieren.
Jede Regel im Draft- und Test-Workflow validieren.
Anschließend Detectoren erstellen und produktiv schalten.
APIs des Content Managers nutzen, wenn Regeln oder Integrationen automatisiert verwaltet werden sollen.
Erst nach erfolgreicher Validierung die Produktionsumgebung migrieren.

Insbesondere produktive SIEM-Umgebungen profitieren davon, die Migration als Neuimplementierung mit strukturierten Tests zu behandeln und nicht als klassisches Versionsupgrade.

Lessons Learned / Best Practices

Die Migration auf Wazuh 5.x ist in erster Linie eine Architekturmigration und weniger ein gewöhnliches Software-Upgrade.

Folgende Empfehlungen haben sich bewährt:

Frühzeitig eine Testumgebung aufbauen.
Vorhandene Regeln und Decoder inventarisieren.
Eigene XML-Regeln rechtzeitig in YAML überführen.
Alte Konfigurationsdateien nicht unverändert übernehmen.
Den neuen Workflow für Detection Rules vollständig testen.
Automatisierungen künftig über die Content-Manager-APIs berücksichtigen.
Vor der Produktivmigration sämtliche Detection- und Alarmierungsprozesse validieren.

Gerade umfangreiche Enterprise-Installationen sollten ausreichend Zeit für Tests und Qualitätssicherung einplanen, da sich zentrale Komponenten der Plattform verändert haben.

Fazit

Wazuh 5.x bringt tiefgreifende Änderungen an Architektur, Konfigurationsverwaltung und Detection Engine mit sich. Ein direktes Upgrade von Wazuh 4.x ist nicht vorgesehen. Stattdessen sollte eine neue Umgebung aufgebaut und die vorhandene Konfiguration gezielt migriert werden. Besonders die Umstellung von XML- auf YAML-basierte Regeln sowie die neue Verwaltung über Security Analytics und die Content-Manager-APIs erfordern eine sorgfältige Planung. Wer den Umstieg zunächst in einer Testumgebung durchführt und die neuen Workflows konsequent nutzt, schafft eine stabile Grundlage für den späteren Produktivbetrieb.