Wazuh Decoder XML Syntax Error (1113): PCRE2, Duplicate Names und Caching-Probleme bei Fail2ban-Decodern

Einleitung

Die Erstellung eigener Decoder gehört zu den zentralen Erweiterungsmöglichkeiten von Wazuh. Gerade bei Tools wie Fail2ban ist eine saubere Log-Parsing-Logik essenziell, um sicherheitsrelevante Ereignisse wie gebannte IP-Adressen korrekt zu erkennen und weiterzuverarbeiten. In der Praxis treten dabei jedoch häufig XML-Syntaxfehler oder unerwartetes Decoder-Verhalten auf, obwohl die regulären Ausdrücke scheinbar korrekt sind. Dieser Beitrag zeigt typische Fehlerquellen anhand eines realen Fail2ban-Decoder-Setups und erklärt, wie sich diese systematisch beheben lassen.

Ausgangslage / Problemstellung

Beim Versuch, einen einfachen Fail2ban-Decoder über die Wazuh GUI zu speichern, tritt folgender Fehler auf:

Error: Could not upload decoder (1113) - XML syntax error

Obwohl der Decoder syntaktisch korrekt erscheint und sogar Beispiel-Decoder aus der Dokumentation funktionieren, schlägt das Speichern fehl. Nach Anpassungen (z. B. PCRE2-Syntax) funktioniert der Decoder zunächst, jedoch treten weitere Probleme auf:

Einzelne Decoder greifen nicht wie erwartet
Regex funktioniert in externen Tools (z. B. regex101), aber nicht in Wazuh
Änderungen führen erneut zu XML-Fehlern
Verhalten ist inkonsistent (z. B. nach Neustarts plötzlich funktional)

Technische Analyse

1. Fehlende PCRE2-Deklaration

Wazuh verwendet standardmäßig keine PCRE2-Regex-Engine, selbst wenn der Regex syntaktisch korrekt ist. Wird ein PCRE2-kompatibler Ausdruck verwendet, muss dies explizit angegeben werden:

<regex type="pcre2">...</regex>

Ohne diese Angabe interpretiert Wazuh den Ausdruck mit einer anderen Engine, was zu Parsing-Fehlern oder unerwartetem Verhalten führen kann. Wazuh dokumentiert die Nutzung von PCRE2 explizit als optionalen, aber notwendigen Parameter bei entsprechenden Regex-Mustern.

2. XML-Syntaxfehler durch doppelte Decoder-Namen

Ein kritischer Fehler im späteren Verlauf war die Definition von zwei Decodern mit identischem Namen:

<decoder name="fail2ban-found">...</decoder>
<decoder name="fail2ban-found">...</decoder>

Dies führt zu einem XML-Syntaxfehler (1113), da Decoder-Namen eindeutig sein müssen oder bewusst als sogenannte „Sibling Decoders“ eingesetzt werden – jedoch nur unter bestimmten Bedingungen.

Wazuh unterstützt sogenannte Sibling Decoders, bei denen mehrere Decoder denselben Namen verwenden, um unterschiedliche Teile eines Logs zu extrahieren. Diese müssen jedoch logisch zusammenpassen und dürfen sich nicht gegenseitig überschreiben oder widersprechen.

3. Decoder-Reihenfolge und Matching-Logik

Wazuh verarbeitet Decoder hierarchisch:

Ein Parent-Decoder (z. B. fail2ban) definiert ein allgemeines Matching (prematch)
Child-Decoder extrahieren spezifische Felder basierend auf Regex

Wenn mehrere Child-Decoder existieren, entscheidet die Kombination aus:

prematch
regex
Decoder-Reihenfolge

welcher Decoder greift.

Ein häufiges Problem: Zwei Decoder mit unterschiedlichen Namen, aber ohne unterscheidendes prematch, konkurrieren um dasselbe Log. In diesem Fall wird oft nur der erste passende Decoder angewendet.

4. Unterschied zwischen regex101 und Wazuh

Ein klassischer Stolperstein ist die Annahme, dass ein Regex, der in regex101 funktioniert, automatisch auch in Wazuh funktioniert. Unterschiede ergeben sich durch:

verwendete Regex-Engine
Kontext (vollständige Zeile vs. Teilstring nach Pre-Decoding)
implizite Vorverarbeitung (z. B. Entfernen von Timestamp und Program Name)

In Wazuh wird der Decoder auf den bereits „bereinigten“ Log angewendet, nicht auf die originale Logzeile.

5. Caching und Reload-Verhalten

Ein besonders tückischer Punkt ist das beobachtete Verhalten, dass Decoder nach mehreren Neustarts plötzlich funktionieren. Ursache ist häufig:

internes Caching von Konfigurationen
nicht korrekt neu geladene Decoder-Dateien
GUI-Upload-Probleme

Gerade in Docker-Umgebungen kann es zusätzlich zu Verzögerungen beim Reload kommen.

Lösung / Best Practices

1. Saubere Trennung der Decoder

Ein stabiler Ansatz für Fail2ban ist die klare Trennung nach Event-Typ:

<decoder name="fail2ban">
  <prematch type="pcre2">^\s*\[\d+\]:\s*(INFO|NOTICE)\s*\[[^\]]+\]\s+(Found|Ban|Unban|Restore Ban)\b</prematch>
</decoder><decoder name="fail2ban-found">
  <parent>fail2ban</parent>
  <regex type="pcre2">Found\s+([0-9]{1,3}(\.[0-9]{1,3}){3})</regex>
  <order>fail2ban_ip</order>
</decoder><decoder name="fail2ban-ban">
  <parent>fail2ban</parent>
  <regex type="pcre2">Ban\s+([0-9]{1,3}(\.[0-9]{1,3}){3})</regex>
  <order>srcip</order>
</decoder>

Wichtig ist hier:

Eindeutige Namen für unterschiedliche Log-Typen
Klare Regex-Abgrenzung (Found vs. Ban)
Kein unnötig komplexer Regex

2. Alternativ: Sibling Decoder bewusst einsetzen

Wenn bewusst mehrere Decoder denselben Namen verwenden sollen:

müssen sie unterschiedliche Teile extrahieren
dürfen sich nicht gegenseitig blockieren
sollten keine vollständige Konkurrenz darstellen

Dieser Ansatz ist sinnvoll bei optionalen Feldern, weniger bei klar unterscheidbaren Logtypen wie „Found“ und „Ban“.

3. XML-Validierung vor dem Upload

Viele Fehler lassen sich vermeiden durch:

lokale XML-Validierung
Vermeidung von Copy-Paste-Artefakten
saubere Struktur ohne doppelte Namen

Der Fehlercode 1113 ist fast immer ein Hinweis auf strukturelle Probleme im XML, nicht auf Regex.

4. Wazuh-logtest als Referenz verwenden

Tests sollten immer mit wazuh-logtest erfolgen, da dies exakt die interne Verarbeitung simuliert:

zeigt Pre-Decoding
zeigt angewendeten Decoder
zeigt extrahierte Felder

Das ist deutlich zuverlässiger als externe Regex-Tools.

5. Neustarts gezielt einsetzen

Nach Änderungen:

Wazuh Manager neu starten
bei Docker ggf. Container neu starten
GUI-Cache berücksichtigen

Wenn ein Decoder trotz korrekter Syntax nicht greift, ist ein Reload oft notwendig.

Lessons Learned / Best Practices

Die häufigsten Ursachen für Decoder-Probleme sind nicht komplexe Regex-Fehler, sondern strukturelle Missverständnisse:

PCRE2 muss explizit aktiviert werden
Decoder-Namen sind nicht beliebig wiederverwendbar
Wazuh verarbeitet Logs anders als externe Tools
GUI-Fehler können durch Backend-Caching verstärkt werden

Ein besonders wichtiger Punkt ist die Trennung von Logtypen. Statt einen „Super-Regex“ zu bauen, ist es robuster, mehrere einfache Decoder mit klarer Zuständigkeit zu definieren.

Für produktive Umgebungen empfiehlt sich außerdem:

Versionierung von Decoder-Dateien
Tests mit realen Logs
klare Namenskonventionen für Decoder
Minimierung von Regex-Komplexität

Fazit

Der XML-Syntaxfehler (1113) bei Wazuh-Decodern ist meist kein tatsächlicher Regex-Fehler, sondern ein strukturelles Problem im Decoder-Setup. In Kombination mit nicht aktivierter PCRE2-Unterstützung, doppelten Decoder-Namen und Caching-Effekten entsteht ein schwer nachvollziehbares Fehlerbild. Wer jedoch die Trennung zwischen Parent-, Child- und Sibling-Decodern versteht und konsequent einfache, klar abgegrenzte Regex-Patterns verwendet, erhält eine stabile und wartbare Parsing-Logik für Fail2ban und vergleichbare Logquellen.

Quellenverweis