Einleitung
In komplexeren Wazuh-Deployments ist es üblich, Alerts logisch zu trennen – etwa nach Kunden, Organisationseinheiten oder Sicherheitszonen. Technisch wird dies häufig über Ingest-Pipelines im Wazuh Indexer umgesetzt, die Alerts anhand von Metadaten in unterschiedliche Indizes routen.
Ein zentrales, aber oft übersehenes Detail dabei sind die zugrunde liegenden Index-Templates. Werden diese nicht korrekt berücksichtigt, drohen Mapping-Konflikte, fehlerhafte Feldtypen und im schlimmsten Fall der Verlust von SIEM-Funktionalität.
Dieser Artikel beleuchtet einen realistischen Fehlerfall und zeigt, wie sich benutzerdefinierte Index-Namen sauber und dauerhaft in die Wazuh-Architektur integrieren lassen.
Ausgangslage / Problemstellung
In der betrachteten Umgebung wurde eine Ingest-Pipeline konfiguriert, die Wazuh-Alerts anhand des Feldes agent.labels.group in verschiedene Tagesindizes schreibt. Abhängig vom Gruppenwert wurden Index-Präfixe wie:
cybowatch-alerts-4.x-nie-*cybowatch-alerts-4.x-ttg-*cybowatch-alerts-*
verwendet.
Kurz nach Einführung dieser Split-Routing-Logik kam es zu Indexierungsfehlern. Konkret meldete der Indexer Typkonflikte bei Feldern wie manager.name. Neue Alerts konnten nicht mehr zuverlässig gespeichert werden, obwohl die Pipeline technisch korrekt funktionierte.
Technische Analyse
Die Ursache liegt im Zusammenspiel zwischen Index-Namen, Index-Templates und der dynamischen Feldzuweisung des Wazuh Indexers (OpenSearch/Elasticsearch).
Wazuh liefert standardmäßig ein umfassendes Index-Template aus, das unter anderem:
- feste Datentypen für zentrale Felder definiert,
- dynamische Mappings einschränkt,
- Kompatibilität mit Wazuh-Dashboards sicherstellt.
Dieses Template ist jedoch nur auf bestimmte Index-Patterns beschränkt, in der Regel:
wazuh-alerts-4.x-*wazuh-archives-4.x-*
Durch die Einführung neuer Präfixe (cybowatch-*) lagen die neu erzeugten Indizes außerhalb dieses Gültigkeitsbereichs. Der Indexer erstellte sie daher ohne Wazuh-spezifisches Template und vergab Feldtypen dynamisch. Sobald ein Feld – etwa manager.name – unterschiedlich interpretiert wurde, kam es zu einem Mapping-Konflikt.
Ein zentraler Architekturpunkt:
Index-Templates greifen ausschließlich beim Erstellen eines neuen Index. Bereits existierende Indizes behalten ihr fehlerhaftes Mapping dauerhaft.
Lösung / Best Practices
Um Split-Routing stabil umzusetzen, gibt es zwei valide Lösungsansätze. Einer davon ist klar zu bevorzugen.
Variante 1: Index-Namen unter das bestehende Wazuh-Schema legen (empfohlen)
Die einfachste und robusteste Lösung besteht darin, benutzerdefinierte Indizes so zu benennen, dass sie weiterhin vom offiziellen Wazuh-Template erfasst werden. Bewährt hat sich folgendes Muster:
wazuh-alerts-4.x-cybowatch-nie-YYYY.MM.DDwazuh-alerts-4.x-cybowatch-ttg-YYYY.MM.DDwazuh-alerts-4.x-cybowatch-YYYY.MM.DD
Der individuelle Teil des Namens wird direkt nach -4.x- eingefügt, während das grundlegende Pattern erhalten bleibt.
Vorteile dieser Vorgehensweise:
- Keine Template-Anpassung notwendig
- Vollständige Kompatibilität mit Wazuh-Dashboards
- Update-sicher bei zukünftigen Wazuh-Versionen
- Geringerer Betriebs- und Wartungsaufwand
Variante 2: Wazuh-Index-Template erweitern
Alternativ kann das offizielle Wazuh-Template angepasst werden, indem zusätzliche index_patterns (z. B. cybowatch-*) aufgenommen werden. Anschließend muss das Template neu geladen werden, bevor neue Indizes entstehen.
Dabei sind mehrere Punkte zu beachten:
- Änderungen wirken nur auf neu erzeugte Indizes
- Bestehende Indizes mit falschem Mapping müssen reindiziert werden
- Template-Anpassungen müssen bei Updates geprüft und ggf. erneut angewendet werden
Diese Variante ist technisch korrekt, sollte jedoch nur gewählt werden, wenn feste Namenskonventionen die erste Lösung ausschließen.
Lessons Learned / Best Practices
- Eigene Index-Namen dürfen niemals losgelöst von den Wazuh-Templates betrachtet werden.
- Split-Routing sollte bevorzugt innerhalb des bestehenden
wazuh-alerts-*-Schemas erfolgen. - Mapping-Konflikte sind fast immer ein Symptom fehlender oder falsch angewendeter Templates.
- Änderungen an Templates erfordern ein bewusstes Index-Lifecycle-Management inklusive Reindexing.
- Neue Pipelines sollten stets mit der Erzeugung eines frischen Index getestet werden.
Fazit
Das Aufteilen von Wazuh-Alerts auf mehrere Indizes ist ein leistungsfähiges Mittel zur Strukturierung und Skalierung von SIEM-Umgebungen. Entscheidend für den stabilen Betrieb ist jedoch die konsequente Einhaltung der Wazuh-Index-Architektur.
Wer benutzerdefinierte Index-Namen unter das bestehende Template-Schema integriert, vermeidet Mapping-Probleme, reduziert Betriebsrisiken und stellt langfristige Kompatibilität sicher.
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/C0A933R8E/p1768642409173679