Wazuh Decoder für UniFi CEF-Logs: Feld-Splitting, Formatabweichungen und Decoder-Konflikte sauber lösen

Einleitung

CEF (Common Event Format) ist ein etabliertes Log-Format mit einem festen Header (Version|Vendor|Product|…) und einer variablen Extension als Key-Value-Liste. Genau diese Mischung sorgt in Wazuh häufig für zwei typische Probleme: Decoder „catcht“ nicht zuverlässig (wegen leicht abweichender CEF-Header-Darstellung) oder Decoder kollidiert mit anderen CEF-Decodern (weil die Prematches zu generisch sind). CEF selbst ist als Header+Extension definiert, wobei die Extension aus Key-Value-Paaren besteht. OpenText+2OpenText+2

Dieser Beitrag zeigt anhand von Ubiquiti UniFi CEF-Logs, wie man Decoder so baut, dass sie (1) den CEF-Header robust parsen, (2) wichtige Extension-Felder extrahieren und (3) keine Konflikte mit anderen CEF-Quellen (z. B. Imperva/Incapsula) erzeugen.

Ausgangslage / Problemstellung

Es liegen UniFi-Logs im CEF-Format vor, u. a. in dieser Form:

Der ursprüngliche Decoder verwendete:

einen sehr schmalen prematch auf CEF:0|Ubiquiti|UniFi Network (ohne Berücksichtigung von Leerzeichen nach CEF:),
Regex-Platzhalter wie (\.) / (\.+) (praktisch „Punkt(e)“, nicht „beliebige Zeichen“),
und erzeugte in der weiteren Iteration Konflikte mit einem anderen CEF-Decoder (Imperva), weil die Erkennung nicht sauber voneinander getrennt war.

Technische Analyse

1) CEF ist nicht immer „CEF:0|…“ – Whitespace und Syslog-Header verändern das Matching

Viele Geräte/Forwarder liefern CEF nicht als reinen String CEF:0|…, sondern mit einem Präfix (Timestamp/Hostname) und teilweise als CEF: 0|… (mit Leerzeichen). In Wazuh werden bei syslog-artigem Header in der Pre-Decoding-Phase Felder wie timestamp, hostname und program_name extrahiert. Wazuh Dokumentation+1

Wenn Wazuh in Phase 1 program_name: 'CEF' erkennt, ist <program_name>CEF</program_name> als Filter oft zuverlässiger als ein prematch, der „am String-Anfang“ erwartet wird.

2) Regex-Syntax: `(\.)` matcht einen Punkt – nicht „beliebige Zeichen“

In Wazuh-Decodern ist die Feldextraktion über <regex> + <order> definiert; Regex erfordert dabei zwingend prematch oder program_name (im Decoder selbst oder beim Parent). Wazuh Dokumentation+1

(\.) bedeutet: „matche genau einen Punkt“. Für „bis zum nächsten Pipe“ ist bei CEF-Headern stattdessen sinnvoll:

([^|]*) (alles außer |, auch leer möglich) oder
(.+?) (nicht-gierig, wenn man sauber begrenzt)

3) Decoder-Konflikte: „CEF“ ist kein Vendor – Prematch muss die Quelle eindeutig machen

Wenn mehrere Produkte CEF liefern, ist ein Decoder-Parent wie <program_name>CEF</program_name> allein zu breit. Dann „konkurrieren“ CEF-Decodersets. Sauber wird es, wenn der Parent zusätzlich über prematch auf Vendor/Product einschränkt (z. B. |Ubiquiti|UniFi Network| vs. |Incapsula|SIEMintegration|). Das reduziert Überschneidungen drastisch.

4) Extension-Felder: `\S+` reicht nicht, wenn Values Leerzeichen enthalten

Im Beispiel ist UNIFIwifiName=Switch-up Workers ein Value mit Leerzeichen. Ein Regex UNIFIwifiName=(\S+) würde nur Switch-up erfassen. Für solche Felder braucht man entweder:

ein Pattern, das bis zum nächsten KEY= läuft (Lookahead), oder
eine konservative Extraktion über mehrere spezialisierte Kinderdecoder (für Felder ohne Spaces) und separate Behandlung der „problematischen“ Keys.

Für Lookaheads ist es oft sinnvoll, PCRE2 zu nutzen (<regex type="pcre2">). Wazuh unterstützt unterschiedliche Regex-Typen inkl. PCRE2. Stack Overflow+1

Lösung / Best Practices

1) Parent-Decoder: program_name + eindeutiger prematch auf Vendor/Product

Damit UniFi nicht Imperva „in die Quere kommt“, sollte der Parent sowohl program_name als auch Vendor/Product enthalten:

<decoder name="cef-ubiquiti-unifi">
  <program_name>CEF</program_name>
  <prematch>\|\s*Ubiquiti\|\s*UniFi Network\|</prematch>
</decoder>

\s* toleriert Whitespace.
Der prematch ist bewusst so gewählt, dass er Imperva (Incapsula|SIEMintegration) nicht treffen kann.

2) CEF-Header robust parsen (Version, EventID, Name, Severity)

Ein robuster Child-Decoder, der Whitespace nach CEF: toleriert und sauber an Pipes trennt:

<decoder name="cef-ubiquiti-unifi-header">
  <parent>cef-ubiquiti-unifi</parent>
  <regex>CEF:\s*0\|Ubiquiti\|UniFi Network\|([^|]*)\|([^|]*)\|([^|]*)\|([^|]*)\|</regex>
  <order>ubiquiti.version,ubiquiti.event_id,ubiquiti.name,ubiquiti.severity</order>
</decoder>

Damit vermeidet man die typischen Fehler durch (\.) und stellt sicher, dass der Decoder unabhängig vom Präfix (Timestamp/Hostname) greift.

3) Extension-Felder extrahieren: erst „sichere“ Keys, dann Sonderfälle

Für Felder ohne Leerzeichen ist (\S+) oder IP-Regex okay:

<decoder name="cef-ubiquiti-unifi-kv-category">
  <parent>cef-ubiquiti-unifi</parent>
  <regex>UNIFIcategory=(\S+)</regex>
  <order>unifi.category</order>
</decoder>

<decoder name="cef-ubiquiti-unifi-kv-subcategory">
  <parent>cef-ubiquiti-unifi</parent>
  <regex>UNIFIsubCategory=(\S+)</regex>
  <order>unifi.subcategory</order>
</decoder>

<decoder name="cef-ubiquiti-unifi-kv-clientip">
  <parent>cef-ubiquiti-unifi</parent>
  <regex>UNIFIclientIp=(\d{1,3}(?:\.\d{1,3}){3})</regex>
  <order>srcip</order>
</decoder>

Für Keys mit Leerzeichen im Value (z. B. UNIFIwifiName=Switch-up Workers) empfiehlt sich PCRE2 mit Lookahead „bis zum nächsten KEY=“:

<decoder name="cef-ubiquiti-unifi-kv-wifiname">
  <parent>cef-ubiquiti-unifi</parent>
  <regex type="pcre2">UNIFIwifiName=(.*?)(?=\s+\w+=|$)</regex>
  <order>unifi.wifi_name</order>
</decoder>

Wichtig: Das Lookahead (?=\s+\w+=|$) ist bewusst generisch (nächster Key= oder Zeilenende). PCRE2-Unterstützung ist in Wazuh-Decodern relevant, wenn man solche Konstrukte nutzen möchte. wazuh-documentation-49-master.readthedocs.io+1

4) Konflikte vermeiden: Eindeutige Decoder-Namen und eindeutige Parent-Prematches

Auch wenn Wazuh Decoder-Hierarchien unterstützt, sollte man in Custom-Decodern:

eindeutige name-Werte wählen (nicht mehrfach ubiquiti-decoder-child verwenden),
pro Produkt/Vendor einen klaren Parent bauen,
und nicht auf „CEF allgemein“ matchen, wenn mehrere CEF-Quellen existieren.

5) Testen mit `wazuh-logtest` und danach Manager neu laden

Wazuh empfiehlt zum Debugging den Einsatz von wazuh-logtest, um Decoding (Phase 1/2) nachvollziehbar zu prüfen. Wazuh Dokumentation+2Wazuh Dokumentation+2 Für produktive Alert-Generierung müssen Decoder-Änderungen anschließend durch Neustart/Reload des Managers wirksam werden (je nach Setup/Workflow). Wazuh Dokumentation

Lessons Learned / Best Practices

Program Name nutzen, aber nie allein: <program_name>CEF</program_name> ist stabil, muss aber mit Vendor/Product im prematch kombiniert werden, um Konflikte zu vermeiden. Wazuh Dokumentation+1
CEF-Header immer mit [^|]* trennen: Das ist für Pipe-separierte Header deutlich robuster als „irgendwas mit Punkt“. OpenText+1
Key-Value-Extension ist trickreich: Values können Leerzeichen enthalten; dafür PCRE2-Lookaheads einsetzen oder Felder selektiv extrahieren. CEF ist explizit als Header + Extension mit Key-Value-Paaren definiert. OpenText+2Delinea Dokumentationsbibliothek+2
Regelmäßig mit echten Logs testen: Kleine Formatabweichungen wie CEF: 0| statt CEF:0| sind in der Praxis normal und entscheiden über „matcht“ vs. „matcht nicht“.

Fazit

UniFi-CEF-Decoding in Wazuh scheitert selten an „CEF an sich“, sondern an Details: Whitespace, syslogartige Präfixe, falsche Regex-Platzhalter und zu generische Prematches, die mit anderen CEF-Decodern kollidieren. Mit einem klaren Parent pro Vendor/Product, einem robusten Header-Regex und gezielter Extension-Feldextraktion (inkl. PCRE2 für Values mit Leerzeichen) wird das Decoding stabil, konfliktfrei und langfristig wartbar.

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

Quelle

Dieser Artikel stammt aus dem Wazuh-Blog von m.a.x. it (veröffentlicht am 28. Januar 2026).

Unterstützung von m.a.x. it

Bei Einführung, Betrieb und Feintuning von Wazuh (SIEM) unterstützt Sie m.a.x. it mit SIEM-Services auf Open-Source-Basis.

Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen

Anonym

Suche

Wazuh Decoder für UniFi CEF-Logs: Feld-Splitting, Formatabweichungen und Decoder-Konflikte sauber lösen

Namensräume

Mehr

Seitenaktionen

Inhaltsverzeichnis

Einleitung

Ausgangslage / Problemstellung

Technische Analyse

1) CEF ist nicht immer „CEF:0|…“ – Whitespace und Syslog-Header verändern das Matching

2) Regex-Syntax: `(\.)` matcht einen Punkt – nicht „beliebige Zeichen“

3) Decoder-Konflikte: „CEF“ ist kein Vendor – Prematch muss die Quelle eindeutig machen

4) Extension-Felder: `\S+` reicht nicht, wenn Values Leerzeichen enthalten

Lösung / Best Practices

1) Parent-Decoder: program_name + eindeutiger prematch auf Vendor/Product

2) CEF-Header robust parsen (Version, EventID, Name, Severity)

3) Extension-Felder extrahieren: erst „sichere“ Keys, dann Sonderfälle

4) Konflikte vermeiden: Eindeutige Decoder-Namen und eindeutige Parent-Prematches

5) Testen mit `wazuh-logtest` und danach Manager neu laden

Lessons Learned / Best Practices

Fazit

Quelle

Unterstützung von m.a.x. it

Navigation

Navigation

m.a.x. it

Kategorien

Wikiwerkzeuge

Wikiwerkzeuge

Anonym

Suche

Wazuh Decoder für UniFi CEF-Logs: Feld-Splitting, Formatabweichungen und Decoder-Konflikte sauber lösen

Einleitung

Ausgangslage / Problemstellung

Technische Analyse

1) CEF ist nicht immer „CEF:0|…“ – Whitespace und Syslog-Header verändern das Matching

2) Regex-Syntax: (\.) matcht einen Punkt – nicht „beliebige Zeichen“

3) Decoder-Konflikte: „CEF“ ist kein Vendor – Prematch muss die Quelle eindeutig machen

4) Extension-Felder: \S+ reicht nicht, wenn Values Leerzeichen enthalten

Lösung / Best Practices

1) Parent-Decoder: program_name + eindeutiger prematch auf Vendor/Product

2) CEF-Header robust parsen (Version, EventID, Name, Severity)

3) Extension-Felder extrahieren: erst „sichere“ Keys, dann Sonderfälle

4) Konflikte vermeiden: Eindeutige Decoder-Namen und eindeutige Parent-Prematches

5) Testen mit wazuh-logtest und danach Manager neu laden

Lessons Learned / Best Practices

Fazit

Quelle

Unterstützung von m.a.x. it

Navigation

Wikiwerkzeuge

Seitenwerkzeuge

Kategorien

2) Regex-Syntax: `(\.)` matcht einen Punkt – nicht „beliebige Zeichen“

4) Extension-Felder: `\S+` reicht nicht, wenn Values Leerzeichen enthalten

5) Testen mit `wazuh-logtest` und danach Manager neu laden