Wazuh Mapping-Chaos durch Custom Index Template: Warum sich Feldtypen unerwartet ändern und wie man es richtig löst

von

Einleitung

Die Anpassung von Feldtypen im Wazuh Indexer ist ein häufiger Anwendungsfall, insbesondere wenn numerische Auswertungen oder Aggregationen benötigt werden. Ein klassisches Beispiel ist die Umwandlung eines Feldes wie data.count von string zu integer, um es in Dashboards oder für Metriken nutzbar zu machen. Was auf den ersten Blick wie eine einfache Mapping-Anpassung erscheint, kann jedoch unerwartete Seiteneffekte verursachen – bis hin zur Veränderung bestehender Standardfelder wie rule.id. Dieser Beitrag zeigt, warum das passiert und wie sich solche Probleme sauber und nachhaltig lösen lassen.

Ausgangslage / Problemstellung

Zur Umwandlung des Feldtyps wurde ein eigenes Index Template mit hoher Priorität erstellt:

PUT _index_template/wazuh_custom_count
{
  "index_patterns": [
    "wazuh-alerts-4.x-*",
    "wazuh-archives-4.x-*"
  ],
  "template": {
    "mappings": {
      "properties": {
        "data": {
          "properties": {
            "count": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "priority": 500
}

Das gewünschte Ergebnis wurde teilweise erreicht: data.count wurde korrekt als Integer erkannt. Gleichzeitig trat jedoch ein unerwarteter Effekt auf:

  • Standardfelder wie rule.id, die zuvor als keyword definiert waren, wurden plötzlich als text + keyword gemappt.

Die zentrale Frage: Warum beeinflusst ein einzelnes Feldmapping plötzlich das gesamte Index-Schema?

Technische Analyse

1. Priorität von Index Templates überschreibt Wazuh-Defaults

Wazuh liefert standardmäßig eigene Index Templates mit, die alle Felder und deren Typen exakt definieren. Diese Templates stellen sicher, dass Felder wie rule.id, agent.id oder data.srcip konsistent gemappt werden.

Durch die Verwendung eines Custom Templates mit einer hohen Priorität (priority: 500) wird dieses Template bevorzugt angewendet. Das Problem dabei: Das Custom Template definiert nur ein einziges Feld (data.count), während alle anderen Felder fehlen.

Das Verhalten des Indexers ist in diesem Fall erwartbar:

  • Für definierte Felder wird das Custom Mapping verwendet
  • Für alle anderen Felder greift Dynamic Mapping

2. Dynamic Mapping verändert Feldtypen

Wenn ein Feld nicht explizit im Template definiert ist, entscheidet der Indexer selbst über den Typ. Für Strings bedeutet das:

  • Standardmäßig werden sie als text + keyword gemappt

Das erklärt den beobachteten Effekt:

FeldVorherNachher
rule.idkeywordtext + keyword

Dieser Effekt ist kein Bug, sondern das Ergebnis eines unvollständigen Templates, das die Wazuh-Defaults verdrängt.

3. Warum Templates nicht für kleine Änderungen geeignet sind

Index Templates sind dafür gedacht, komplette Mappings zu definieren, nicht einzelne Felder selektiv zu überschreiben. Sobald ein Template greift, übernimmt es die Kontrolle über das gesamte Mapping-Verhalten des Indexes.

Das macht sie ungeeignet für punktuelle Anpassungen wie:

  • Umwandlung einzelner Felder
  • kleine Schema-Korrekturen
  • nachträgliche Typanpassungen

Wazuh selbst empfiehlt für solche Anwendungsfälle andere Mechanismen wie Ingest Pipelines oder Reindexing-Prozesse.

Lösung / Best Practices

1. Custom Template entfernen

Der erste Schritt ist das Entfernen des problematischen Templates:

DELETE _index_template/wazuh_custom_count

Damit greifen wieder die Standard-Templates von Wazuh und stellen die korrekten Feldtypen wieder her.

2. Feldtyp über Ingest Pipeline konvertieren

Die empfohlene Methode zur Typanpassung ist die Verwendung einer Ingest Pipeline. Diese konvertiert Felder vor der Indexierung, ohne das Mapping zu überschreiben.

Für wazuh-alerts:

Datei:

/usr/share/filebeat/module/wazuh/alerts/ingest/pipeline.json

Ergänzung im processors-Block:

{
  "convert": {
    "field": "data.count",
    "type": "integer",
    "ignore_missing": true,
    "ignore_failure": true
  }
}

Anschließend:

filebeat setup --pipelines
systemctl restart filebeat

Für wazuh-archives muss die gleiche Anpassung in der entsprechenden Pipeline erfolgen.

Der Vorteil dieses Ansatzes:

  • keine Beeinflussung anderer Felder
  • kompatibel mit Wazuh-Standardtemplates
  • stabil bei Updates

3. Bestehende Indizes korrigieren (Reindexing)

Bereits existierende Indizes behalten ihr altes Mapping. Um diese zu korrigieren, ist ein Reindexing notwendig. Wazuh beschreibt diesen Prozess als Standardverfahren zur nachträglichen Mapping-Korrektur.

Dabei werden:

  • alte Indizes gelesen
  • Daten neu geschrieben (mit neuer Pipeline)
  • korrekt gemappte Felder erzeugt

Wichtig: Reindexing sollte geplant erfolgen, da es Ressourcen verbraucht und produktive Systeme beeinflussen kann.

4. Erweiterte Use Cases: Custom Metrics (EPS)

Im erweiterten Beispiel wurde zusätzlich ein eigener Metrik-Workflow implementiert:

  • Analyse von wazuh-analysisd.state
  • Generierung eigener Felder wie data.eps und data.eps_total
  • Speicherung als JSON-Log
  • Verarbeitung über Decoder und Rules
  • Typkonvertierung via Pipeline

Dieser Ansatz zeigt eine Best Practice für eigene Telemetrie-Daten:

  • Datenerhebung außerhalb von Wazuh
  • strukturierte Übergabe als JSON
  • Integration über bestehende Pipeline-Mechanismen

Dabei ist zu beachten, dass insbesondere wazuh-archives bei aktivierter Vollprotokollierung schnell große Datenmengen erzeugt und entsprechend Storage-Planung erfordert.

Lessons Learned / Best Practices

Der wichtigste Lerneffekt ist: Index Templates sind kein geeignetes Werkzeug für punktuelle Feldänderungen.

Stattdessen gilt:

  • Templates nur verwenden, wenn vollständige Kontrolle über das Mapping gewünscht ist
  • Für einzelne Feldanpassungen immer Ingest Pipelines nutzen
  • Dynamic Mapping bewusst vermeiden, wenn Konsistenz wichtig ist

Weitere Best Practices:

  • Änderungen immer zuerst in Testumgebungen validieren
  • Mapping-Konflikte frühzeitig erkennen (Index Pattern → Refresh)
  • Reindexing als festen Bestandteil von Schemaänderungen einplanen
  • eigene Metriken strukturiert und getrennt von Standarddaten erfassen

Ein häufiger Fehler ist es, die Auswirkungen von Template-Prioritäten zu unterschätzen. Bereits ein kleines Template kann das gesamte Mapping-Verhalten verändern.

Fazit

Die Umwandlung eines einzelnen Feldes wie data.count kann weitreichende Auswirkungen auf das gesamte Wazuh-Datenmodell haben, wenn sie über ein Index Template umgesetzt wird. Der Grund liegt in der Prioritätslogik und dem Fallback auf Dynamic Mapping. Die saubere und stabile Lösung besteht darin, Feldtypen über Ingest Pipelines zu konvertieren und bestehende Indizes bei Bedarf zu reindizieren. Wer diese Trennung beachtet, vermeidet Mapping-Konflikte und erhält ein konsistentes, auswertbares Datenmodell im Wazuh Indexer.

Quellenverweis

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/C07BZJY86G3/p1773126069298269