JSON-Felder in Wazuh ignorieren oder normalisieren: Konflikte im Index sauber lösen

von

Einleitung

In modernen SIEM-Umgebungen ist die Verarbeitung strukturierter Logs essenziell. Wazuh setzt dabei stark auf JSON-basierte Events, die über Decoder, Filebeat und den Wazuh Indexer verarbeitet werden. Ein häufiges Problem tritt auf, wenn sich die Datenstruktur eines Feldes ändert – etwa wenn ein Feld einmal als String und ein anderes Mal als Objekt geliefert wird. Solche Inkonsistenzen führen schnell zu Mapping-Konflikten im Index und blockieren die Verarbeitung.

Ausgangslage / Problemstellung

Ein JSON-Feld innerhalb der Wazuh-Events enthält inkonsistente Datentypen. In einigen Fällen ist der Wert ein String, in anderen ein Objekt. Dadurch entsteht beim Indexing ein Konflikt, da Elasticsearch-basierte Systeme (inklusive Wazuh Indexer) pro Feld einen festen Datentyp erwarten.

Typische Auswirkungen:

  • Indexierungsfehler in Filebeat oder Wazuh Indexer
  • Events werden verworfen oder nicht gespeichert
  • Fehlermeldungen bezüglich Mapping-Konflikten
  • Inkonsistente Datenbasis im SIEM

Die konkrete Anforderung: Ein bestimmtes JSON-Feld soll entweder ignoriert oder vor der Indexierung entfernt werden, um diese Konflikte zu vermeiden.

Technische Analyse

Die Verarbeitungskette in Wazuh sieht vereinfacht so aus:

  1. Logquelle → Wazuh Agent
  2. Wazuh Manager (Decoding & Rule Engine)
  3. Filebeat (Transport)
  4. Ingest Node Pipeline (Transformation)
  5. Wazuh Indexer (Speicherung)

Der entscheidende Punkt ist: Mapping-Konflikte entstehen nicht im Decoder, sondern beim Indexing im Wazuh Indexer. Das bedeutet, dass klassische Wazuh-Decoder keine geeignete Stelle sind, um Datentyp-Konflikte zu lösen.

Ein Feld kann nicht gleichzeitig als string und object im selben Index existieren. Sobald ein Mapping festgelegt ist, schlägt jede abweichende Struktur fehl.

Deshalb muss die Bereinigung vor dem Indexing erfolgen – idealerweise in der Ingest Pipeline von Filebeat.

Lösung / Best Practices

Entfernen problematischer Felder via Ingest Pipeline

Der stabilste Ansatz besteht darin, das problematische Feld vor der Indexierung vollständig zu entfernen.

Die Standard-Ingest-Pipeline für Wazuh befindet sich typischerweise hier:

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

Vor Änderungen sollte unbedingt ein Backup erstellt werden:

cp /usr/share/filebeat/module/wazuh/alerts/ingest/pipeline.json \
   /usr/share/filebeat/module/wazuh/alerts/ingest/pipeline.json.bak

Anschließend wird die Pipeline bearbeitet. Innerhalb der processors-Sektion kann ein zusätzlicher remove-Prozessor eingefügt werden.

Beispiel:

{
  "remove": {
    "field": "data.problem_field",
    "ignore_missing": true,
    "ignore_failure": true
  }
}

Dieser Block sollte vor bestehenden remove-Einträgen eingefügt werden, etwa vor dem Entfernen des message-Feldes.

Nach der Anpassung muss die Pipeline neu geladen werden:

sudo filebeat setup --pipelines --modules wazuh

Damit wird sichergestellt, dass die Änderungen aktiv sind.

Alternative: Bedingte Verarbeitung (fortgeschritten)

Wenn das Feld nur dann problematisch ist, wenn es ein Objekt ist, könnte theoretisch ein Script-Prozessor genutzt werden, um den Typ zu prüfen und nur in diesem Fall zu entfernen oder umzuwandeln.

Beispiel (konzeptionell):

{
  "script": {
    "source": "if (ctx.data?.problem_field instanceof Map) { ctx.data.remove('problem_field'); }"
  }
}

Diese Methode ist jedoch komplexer, fehleranfälliger und sollte nur eingesetzt werden, wenn der Informationsgehalt des Feldes zwingend benötigt wird.

Warum nicht im Decoder lösen?

Wazuh Decoder arbeiten auf der Parsing-Ebene, bevor die Daten strukturiert im JSON vorliegen. Typkonflikte entstehen jedoch erst beim Mapping im Indexer. Daher ist die Ingest Pipeline die richtige Stelle für solche Anpassungen.

Lessons Learned / Best Practices

  • JSON-Felder müssen konsistente Datentypen haben
  • Mapping-Konflikte entstehen im Indexer, nicht im Wazuh Decoder
  • Ingest Pipelines sind der richtige Ort für Datenbereinigung
  • Problematische Felder besser entfernen als inkonsistent speichern
  • Änderungen an Pipelines immer versionieren und dokumentieren
  • Nach Pipeline-Anpassungen Filebeat-Pipelines neu laden
  • Bei kritischen Feldern kann ein separates Index-Mapping sinnvoll sein

Ein häufiger Fehler ist der Versuch, solche Probleme „im Agent“ oder über Decoder zu lösen – das greift zu kurz und adressiert nicht die eigentliche Ursache.

Fazit

Inkonsistente JSON-Strukturen sind eine häufige Ursache für Indexierungsprobleme in Wazuh. Der zuverlässigste Weg zur Lösung ist die Bereinigung der Daten in der Ingest Pipeline, bevor sie den Wazuh Indexer erreichen. Das gezielte Entfernen problematischer Felder sorgt für stabile Pipelines, vermeidet Mapping-Konflikte und stellt sicher, dass sicherheitsrelevante Events weiterhin verarbeitet werden.

Quellen

https://www.elastic.co/guide/en/elasticsearch/reference/current/ingest-processors.html
https://documentation.wazuh.com/current/user-manual/manager/event-logging.html

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