Ruckus-Logs in Wazuh dekodieren: Custom Decoder für ZoneDirector- und SmartZone-Events

Einleitung

Wireless-Infrastruktur erzeugt sicherheitsrelevante Logs zu Access Points, WLANs, Authentifizierungen, Client-Verbindungen und VLAN-Zuordnungen. Für Security Monitoring mit Wazuh sind diese Daten besonders wertvoll, weil sie Hinweise auf neue Clients, fehlgeschlagene Authentifizierungen, verdächtige SSIDs oder ungewöhnliche Client-IP-Zuweisungen liefern können.

Bei Ruckus-Logs zeigt sich jedoch schnell: Nicht jedes Logformat lässt sich mit einem einzigen Decoder sauber abdecken. Besonders ZoneDirector-ähnliche Syslog-Meldungen und strukturierte SmartZone-/hostapd-Events benötigen unterschiedliche Decoder-Strategien.

Ausgangslage / Problemstellung

Im ersten Fall liegen klassische Syslog-Meldungen eines Ruckus ZoneDirector vor:

<134>Mar 06 14:22:15 Ruckus-ZD AP[AA:BB:CC:DD:EE:FF] connected to WLAN "OfficeWiFi" on channel 36 (5GHz)
<134>Mar 06 14:22:20 Ruckus-ZD User[JohnDoe] authenticated successfully via WPA2-PSK
<132>Mar 06 14:23:05 Ruckus-ZD AP[AA:BB:CC:DD:EE:FF] disconnected from WLAN "OfficeWiFi"

Ein erster Decoder versucht, Priorität, Zeitstempel, Host und Nachricht selbst zu extrahieren:

<decoder name="ruckus">
  <type>syslog</type>
  <prematch>&lt;\d+&gt;\w+\s+\d+\s+\d+:\d+:\d+\s+\S+\s+\S+\s+.+</prematch>
  <regex>&lt;(\d+)&gt;(\w+\s+\d+\s+\d+:\d+:\d+)\s+(\S+)\s+(\S+\s+.+)</regex>
  <order>ruckus.priority,ruckus.timestamp,ruckus.host,ruckus.message</order>
</decoder>

Im Decoder-Test wird jedoch kein Treffer angezeigt.

Später kommt ein zweites, strukturierteres Logformat hinzu:

2026 Mar 09 10:45:34 serverhostname->1.2.3.4  Mar  9 15:45:32 hostapd: @@236,clientInfoUpdate,"apMac"="AA:BB:CC:DD:EE:FF","clientMac"="AA:BB:CC:DD:EE:FF","ssid"="OfficeWifi","bssid"="AA:BB:CC:DD:EE:FF","userId"="","wlanId"="1234","iface"="wlan32","tenantUUID"="abcd1234-ab12-ab12-ab12-abcdef123456","apName"="AccessPoint-01-2","clientIP"="1.2.3.4","userName"="92a6713260b5","vlanId"="1224","radio"="a/n/ac","encryption"="None","band"="5g"

Hier matcht der Decoder zwar, exportiert aber keine Felder.

Technische Analyse

Bei Wazuh-Decodern sind drei Punkte entscheidend:

Prematch und Regex müssen zum tatsächlichen Payload passen
Der richtige Regex-Typ muss verwendet werden
Die Felder in <order> müssen korrekt kommasepariert sein

Beim ersten Logformat ist es unnötig und fehleranfällig, den gesamten Syslog-Header selbst zu parsen. Wazuh verarbeitet Syslog-Strukturen bereits vor und stellt den relevanten Loganteil für Decoder bereit. Robuster ist daher ein Parent-Decoder, der nur auf den Hersteller- oder Gerätetyp matcht, und danach mehrere Child-Decoder für konkrete Ereignistypen.

Beim zweiten Logformat ist der Fehler subtiler. Die Regex verwendet PCRE-typische Konstrukte wie [^"]*. Standardmäßig nutzt Wazuh jedoch nicht automatisch PCRE2 für jede Regex. Wird PCRE2 benötigt, muss dies explizit angegeben werden:

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

Zusätzlich müssen die Feldnamen in <order> mit Kommas getrennt werden. Leerzeichen allein reichen nicht aus.

Falsch:

<order>event_code event_type ap_mac client_mac</order>

Richtig:

<order>event_code,event_type,ap_mac,client_mac</order>

Lösung / Best Practices

Für die einfachen Ruckus-ZD-Meldungen ist ein Parent-/Child-Decoder-Ansatz sinnvoll.

<decoder name="ruckus-zd">
  <prematch>Ruckus-ZD</prematch>
</decoder>

Decoder für verbundene Access Points:

<decoder name="ruckus-zd-ap-connected">
  <parent>ruckus-zd</parent>
  <prematch>connected to WLAN</prematch>
  <regex>AP\[(\S+)\] connected to WLAN "([^"]+)" on channel (\d+) \(([^)]+)\)</regex>
  <order>srcmac,ssid,channel,band</order>
</decoder>

Decoder für getrennte Access Points:

<decoder name="ruckus-zd-ap-disconnected">
  <parent>ruckus-zd</parent>
  <prematch>disconnected from WLAN</prematch>
  <regex>AP\[(\S+)\] disconnected from WLAN "([^"]+)"</regex>
  <order>srcmac,ssid</order>
</decoder>

Decoder für erfolgreiche Benutzer-Authentifizierung:

<decoder name="ruckus-zd-user-auth">
  <parent>ruckus-zd</parent>
  <prematch>authenticated successfully</prematch>
  <regex>User\[(\S+)\] authenticated successfully via (\S+)</regex>
  <order>srcuser,auth_method</order>
</decoder>

Für strukturierte SmartZone-/hostapd-Events sollte PCRE2 explizit gesetzt und die <order>-Direktive korrekt formatiert werden:

<decoder name="ruckus-smartzone-structured">
  <prematch>hostapd: @@</prematch>
  <regex type="pcre2">hostapd:[ \t]+@@([0-9]+),([^,]+),.*"apMac"="([^"]*)".*"clientMac"="([^"]*)".*"ssid"="([^"]*)".*"bssid"="([^"]*)".*"wlanId"="([^"]*)".*"iface"="([^"]*)".*"tenantUUID"="([^"]*)".*"apName"="([^"]*)".*"clientIP"="([^"]*)".*"userName"="([^"]*)".*"vlanId"="([^"]*)".*"radio"="([^"]*)".*"encryption"="([^"]*)".*"band"="([^"]*)"</regex>
  <order>event_code,event_type,ap_mac,client_mac,ssid,bssid,wlan_id,iface,tenant_uuid,ap_name,client_ip,user_name,vlan_id,radio,encryption,band</order>
</decoder>

Nach dem Anlegen oder Ändern der Decoder sollte der Wazuh Manager neu gestartet werden:

systemctl restart wazuh-manager

Anschließend sollte mit wazuh-logtest geprüft werden, ob Decoder und Felder korrekt erkannt werden:

/var/ossec/bin/wazuh-logtest

Ein Decoder allein erzeugt noch keinen Alert. Dafür ist zusätzlich eine passende Custom Rule erforderlich, zum Beispiel:

<group name="ruckus,wireless,">
  <rule id="100910" level="3">
    <decoded_as>ruckus-zd-ap-connected</decoded_as>
    <description>Ruckus AP connected to WLAN $(ssid) on channel $(channel) ($(band))</description>
  </rule>

  <rule id="100911" level="3">
    <decoded_as>ruckus-zd-ap-disconnected</decoded_as>
    <description>Ruckus AP disconnected from WLAN $(ssid)</description>
  </rule>

  <rule id="100912" level="5">
    <decoded_as>ruckus-zd-user-auth</decoded_as>
    <description>Ruckus user authenticated successfully via $(auth_method)</description>
  </rule>

  <rule id="100913" level="4">
    <decoded_as>ruckus-smartzone-structured</decoded_as>
    <description>Ruckus SmartZone client update: $(client_mac) on SSID $(ssid), IP $(client_ip)</description>
  </rule>
</group>

Lessons Learned / Best Practices

Bei Netzwerkgeräten ist es selten sinnvoll, alle Varianten mit einer einzigen großen Regex abzudecken. Besser ist ein modularer Decoder-Aufbau:

Parent Decoder:
→ erkennt Hersteller, Produkt oder Logfamilie

Child Decoder:
→ erkennt konkrete Ereignistypen

Rules:
→ bewerten die Ereignisse sicherheitsfachlich

Für Ruckus-Logs bedeutet das:

Ruckus-ZD Syslog:
→ mehrere kleine Child-Decoder für AP connect, AP disconnect, User auth

SmartZone / hostapd:
→ strukturierte Key-Value-Events mit PCRE2 dekodieren

Alerting:
→ nicht im Decoder lösen, sondern über Custom Rules

Besonders wichtig sind diese Stolpersteine:

<order> immer kommasepariert schreiben
PCRE2 explizit mit type="pcre2" aktivieren
Regex nicht unnötig auf den gesamten Syslog-Header ausdehnen
Nach Decoder-Änderungen den Manager neu starten
Decoder und Rules getrennt testen

Sicherheitsfachlich sollten Ruckus-Events nicht nur gesammelt, sondern gezielt ausgewertet werden. Relevante Use Cases sind unter anderem:

Neue oder unbekannte Client-MAC-Adressen
Authentifizierungen auf sensiblen SSIDs
Clients ohne erwartete Verschlüsselung
Ungewöhnliche VLAN-Zuweisungen
AP-Wechsel oder häufige Disconnects
Verbindungen auf nicht freigegebenen Bändern oder Kanälen

Fazit

Ruckus-Logs lassen sich in Wazuh zuverlässig auswerten, wenn Decoder modular aufgebaut und passend zum jeweiligen Logformat geschrieben werden. Für einfache ZoneDirector-Meldungen ist ein Parent-/Child-Decoder-Design am robustesten. Für strukturierte SmartZone-Events sind PCRE2 und eine korrekt kommaseparierte <order>-Direktive entscheidend. Erst durch ergänzende Custom Rules werden die dekodierten Felder zu verwertbaren Security Alerts.