Wazuh-Regeln für UniFi CEF-Logs: Warum Decoder funktionieren, aber Child Rules nicht auslösen

von

Einleitung

UniFi kann System- und Sicherheitsereignisse im Common Event Format an ein SIEM senden. In Wazuh lassen sich diese CEF-Logs mit Custom Decodern und Regeln auswerten, um beispielsweise VPN-Verbindungen, Admin-Logins oder Konfigurationsänderungen sichtbar zu machen. Häufig funktioniert dabei zunächst das Decoding, während die darauf aufbauenden Regeln nicht auslösen. Die Ursache liegt meist in einer Abweichung zwischen Decoder-Name, extrahierten Feldnamen und den Feldern, auf die Regeln verweisen.

Ausgangslage / Problemstellung

Für UniFi-CEF-Logs wurde ein eigener Decoder erstellt:

<decoder name="Ubiquiti-Custom">
  <program_name>CEF</program_name>
</decoder>

Die Regelbasis verweist jedoch auf einen anderen Decoder-Namen:

<rule id="100100" level="5">
  <decoded_as>ubiquiti-cef</decoded_as>
  <description>Ubiquiti CEF Event Detected</description>
</rule>

Zusätzlich verwenden die Child Rules ein Feld namens event_name:

<field name="event_name">VPN Client Connected</field>

Dieses Feld wird im gezeigten Decoder aber nicht extrahiert. Dadurch kann die Parent Rule nicht zuverlässig greifen, und die Child Rules matchen ebenfalls nicht.

Technische Analyse

In Wazuh muss <decoded_as> exakt dem Namen der Decoder-Familie entsprechen. Wenn der Decoder Ubiquiti-Custom heißt, muss die Parent Rule ebenfalls darauf verweisen:

<decoded_as>Ubiquiti-Custom</decoded_as>

UniFi exportiert CEF-Logs im Format:

CEF:Version|Device Vendor|Device Product|Device Version|Device Event Class ID|Name|Severity|Extension

Ein Beispiel für ein UniFi-Admin-Event ist:

CEF:0|Ubiquiti|UniFi Network|9.3.33|544|Admin Accessed UniFi Network|1|UNIFIcategory=System UNIFIsubCategory=Admin UNIFIhost=Office UDM Pro UNIFIaccessMethod=web src=105.5.138.59

Der Event-Name steht dabei im sechsten pipe-getrennten Header-Feld, also hier:

Admin Accessed UniFi Network

Wenn dieser Wert nicht als Feld, etwa event_name, extrahiert wird, kann eine Regel mit <field name="event_name">...</field> nicht auslösen. Als pragmatischer Start kann stattdessen <match> auf den Rohlog-Inhalt verwendet werden:

<match>\|Admin Accessed UniFi Network\|</match>

Das ist weniger elegant als ein sauber extrahiertes Feld, funktioniert aber schnell und stabil für erste Use Cases.

Lösung / Best Practices

Die Parent Rule sollte zuerst korrigiert werden:

<group name="ubiquiti,cef,">

  <rule id="100100" level="5">
    <decoded_as>Ubiquiti-Custom</decoded_as>
    <description>Ubiquiti CEF Event Detected</description>
  </rule>

  <rule id="100101" level="6">
    <if_sid>100100</if_sid>
    <match>\|VPN Client Connected\|</match>
    <description>UniFi VPN Client Connected</description>
  </rule>

  <rule id="100102" level="4">
    <if_sid>100100</if_sid>
    <match>\|VPN Client Disconnected\|</match>
    <description>UniFi VPN Client Disconnected</description>
  </rule>

  <rule id="100103" level="7">
    <if_sid>100100</if_sid>
    <match>\|Admin Accessed UniFi Network\|</match>
    <description>UniFi Admin Login</description>
  </rule>

  <rule id="100104" level="8">
    <if_sid>100100</if_sid>
    <match>\|Admin Made Config Changes\|</match>
    <description>UniFi Admin Configuration Changed</description>
  </rule>

</group>

Langfristig ist es besser, den CEF-Header sauber zu decodieren und den Event-Namen explizit als Feld zu speichern. Dann können Regeln wieder gezielt mit <field> arbeiten:

<decoder name="Ubiquiti-Custom">
  <program_name>CEF</program_name>
</decoder>

<decoder name="Ubiquiti-Custom-header">
  <parent>Ubiquiti-Custom</parent>
  <regex>^CEF:(\d+)\|([^|]+)\|([^|]+)\|([^|]+)\|([^|]+)\|([^|]+)\|([^|]+)\|</regex>
  <order>cef_version,device_vendor,device_product,device_version,event_code,event_name,severity</order>
</decoder>

Danach sind Regeln mit Feldvergleich möglich:

<rule id="100103" level="7">
  <if_sid>100100</if_sid>
  <field name="event_name">Admin Accessed UniFi Network</field>
  <description>UniFi Admin Login</description>
</rule>

Nach jeder Änderung müssen Manager und Regeln neu geladen werden:

systemctl restart wazuh-manager

Die Analyse sollte anschließend mit wazuh-logtest erfolgen:

/var/ossec/bin/wazuh-logtest

Dort lässt sich prüfen, ob erst der Decoder Ubiquiti-Custom erkannt wird und anschließend die erwartete Regel-ID auslöst.

Lessons Learned / Best Practices

Bei Custom Rules muss der Wert in <decoded_as> exakt zum Decoder-Namen passen. Schon unterschiedliche Groß-/Kleinschreibung oder ein abweichender Name verhindern, dass die Parent Rule matched.

Regeln mit <field> funktionieren nur auf Feldern, die der Decoder tatsächlich erzeugt. Wenn event_name nicht im Decoder-Output erscheint, kann keine Regel darauf matchen.

UniFi CEF-Logs bestehen aus einem festen CEF-Header und einer variablen Extension mit vielen möglichen key=value-Feldern wie UNIFIcategory, UNIFIsubCategory, UNIFIhost, UNIFIaccessMethod, src oder msg. Für produktive Umgebungen sollte daher eine Decoder-Familie aufgebaut werden, die zuerst den CEF-Header zuverlässig extrahiert und anschließend relevante Extension-Felder als optionale Sibling Decoder verarbeitet.

Fazit

Wenn UniFi-CEF-Decoder in Wazuh funktionieren, aber Regeln nicht auslösen, liegt die Ursache meist nicht im Dashboard, sondern in der Regel-Logik. Der wichtigste Fix ist der korrekte <decoded_as>-Wert. Danach müssen die Child Rules entweder auf vorhandene Felder verweisen oder über <match> direkt auf den CEF-Event-Namen prüfen. Für eine robuste Integration empfiehlt sich ein sauberer CEF-Header-Decoder mit explizitem event_name-Feld.

Quellen

UniFi Dokumentation: System Logs & SIEM Integration
https://help.ui.com/hc/en-us/articles/33349041044119-UniFi-System-Logs-SIEM-Integration

Wazuh Dokumentation: Rules XML Syntax
https://documentation.wazuh.com/current/user-manual/ruleset/ruleset-xml-syntax/rules.html

Wazuh Dokumentation: Decoders XML Syntax
https://documentation.wazuh.com/current/user-manual/ruleset/ruleset-xml-syntax/decoders.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/C07CNG3M11N/p1771619871855019