Wazuh E-Mail-Alerts nach Agent-Gruppen filtern: Warum event_location nicht passt und welche Ansätze wirklich funktionieren

von

Einleitung

E-Mail-Alerts sind in Wazuh ein bewährter „Last Mile“-Kanal für kritische Events – besonders, wenn ein SOC nicht permanent im Dashboard arbeitet oder bestimmte Betriebsgruppen (z. B. Business Units) eigene Benachrichtigungswege brauchen. Häufig lautet die Anforderung: „Sende Alerts nur für Agent-Gruppe X an Empfänger A und nur für Gruppe Y an Empfänger B.“
Genau hier stößt das klassische Manager-basierte <email_alerts>-Routing schnell an eine harte Grenze: Wazuh kann zwar nach Severity, Rule-Group/Rule-ID und Event Location filtern – aber nicht nativ nach Agent-Gruppen.

Ausgangslage / Problemstellung

Es existieren zwei <email_alerts>-Blöcke in ossec.conf, die E-Mails abhängig von event_location an unterschiedliche Empfänger schicken sollen:

  • TS-BU → ABC@gmail.com
  • EA-BU → Help@gmail.com

Der Ansatz scheitert, weil event_location nur bestimmte Werte akzeptiert und „TS-BU/EA-BU“ als Agent-Gruppen (nicht Agent-Name/Hostname/IP/Logfile) nicht matchen können. Die Folge: Keine oder unerwartete Benachrichtigung.

Wazuh dokumentiert explizit, dass event_location nur Agent-Name, Hostname, IP-Adresse oder Logfile unterstützt.

Technische Analyse

1) event_location ist kein Gruppenfilter

Die Manager-Funktion „Email alert based on event location“ prüft die Location des Events, nicht die Agent-Gruppenzugehörigkeit. Zulässige Werte sind Agent/Host/IP/Datei – Gruppen sind nicht Teil dieser Matching-Logik.

2) Warum Gruppen im Manager-Alerting nicht „einfach“ gehen

Agent-Gruppen in Wazuh sind primär ein Mechanismus für zentrale Konfigurationsverteilung (Group-based config via agent.conf). Die Rule Engine ist historisch nicht „gruppenbewusst“ – das wurde auch als Feature-Request diskutiert.

3) Was stattdessen zuverlässig funktioniert

Für „Routing nach organisatorischer Zugehörigkeit“ braucht es ein Feld im Alert, das wirklich filterbar ist, z. B.:

  • Agent Labels (z. B. agent.labels.bu = TS-BU)
    Labels sind ausdrücklich dafür gedacht, Alert-Daten um eigene Metadaten zu erweitern.
  • Danach entweder:
    • Manager-seitig per Integrator (Custom Script) routen, oder
    • Indexer-seitig per OpenSearch Alerting/Notifications (Query-Monitore) routen.

Lösung / Best Practices

Im Betrieb haben sich zwei Muster etabliert – je nach Anforderung an Wartbarkeit, Skalierung und Zustelllogik.

Option 1: Group-/BU-Routing per Agent Labels + Wazuh Integrator (Manager-seitig, sehr flexibel)

Wann sinnvoll: Wenn Routing-Logik komplex ist (mehrere Empfängerregeln, Template-Logik, Escalation, eigene SMTP-Mechanik), oder wenn ihr die Zustellung nicht vom Indexer abhängig machen wollt.

  1. Labels pro Gruppe setzen (zentral via agent.conf)
    Für die Gruppe TS-BU z. B. in der Gruppen-Konfiguration:
<labels>
  <label key="bu">TS-BU</label>
</labels>

Für EA-BU entsprechend bu=EA-BU.
Wazuh beschreibt Labels als Mechanismus, Alert-Informationen um benutzerdefinierte Daten zu erweitern.

  1. Custom Integration über den Integrator
    Der Integrator ist genau dafür da, Alerts an externe Tools/APIs oder eigene Skripte zu übergeben.

Best-Practice-Pattern:

  • Integrator triggert ein Skript bei Alerts ab einem bestimmten Level / Rule-ID / Rule-Group
  • Skript liest das Alert-JSON (inkl. agent.labels.bu)
  • Skript entscheidet Empfänger:
  • Skript versendet E-Mail (SMTP) oder übergibt an MTA/Relay

Vorteile:

  • Echtzeitnah (ohne Query-Scheduling)
  • Voll kontrollierbares Routing/Format
  • Unabhängig von Dashboards/Alerting-Plugins

Nachteile:

  • Eigenentwicklung und Pflege des Skripts
  • SMTP/Secrets müssen sauber betrieben werden

Option 2: Group-/BU-Routing über OpenSearch Alerting + Notifications (Indexer-seitig, „SIEM-typisch“)

Wann sinnvoll: Wenn ihr ohnehin über den Indexer arbeitet und routingfähige Alerts über Queries bauen wollt (und ggf. zusätzliche Filter wie Rule-Level, MITRE, Data Source, Compliance).

OpenSearch Alerting arbeitet mit Monitoren, die periodisch Queries ausführen (z. B. „alle Alerts der letzten Minute“), und löst bei Treffern Aktionen über Notifications aus.

  1. Voraussetzung: Alerts sind im Indexer
    Wazuh schreibt Alerts lokal u. a. nach alerts.json und leitet sie standardmäßig in den Indexer weiter (typischer Wazuh-Stack).
  2. Notification Channel (E-Mail) anlegen
    In OpenSearch Dashboards über Notifications einen E-Mail-Channel/Sender konfigurieren (oder per API). Das Notifications-Plugin ist die zentrale Stelle für Ausgabekanäle.
  3. Pro BU einen Monitor (Per query)
  • Index: typischerweise wazuh-alerts-4.x-* (abhängig von eurem Stack)
  • Filter:
    • Zeitfenster: @timestamp now-1m..now
    • agent.labels.bu = TS-BU
    • optional: rule.level >= 9 oder konkrete rule.id/rule.groups

Die Monitor-Logik „per query“ ist Standard im Alerting-Plugin.

Vorteile:

  • Kein eigenes Script nötig
  • Sehr gute Filterbarkeit (Query-DSL)
  • Routing über mehrere Channels/Empfängergruppen

Nachteile:

  • Polling-Charakter (z. B. minütlich)
  • Abhängig von Alerting/Notifications-Setup
  • Feldnamen müssen konsistent im Index ankommen (Labels vorher sauber ausrollen)

Warum „Dashboard-Level Filtering“ allein keine Lösung ist

Dashboard/Discover-Filter regeln Sichtbarkeit für Nutzer, nicht Manager-seitiges E-Mail-Routing. Wenn das Ziel „E-Mails nach BU“ ist, braucht ihr ein routingfähiges Feld im Alert und eine serverseitige Benachrichtigungslogik (Integrator oder Indexer Alerting).

Lessons Learned / Best Practices

  • event_location nur verwenden, wenn ihr wirklich nach Agent-Name/Host/IP/Logfile routen wollt – nicht als Gruppenersatz.
  • Agent-Gruppen sind kein Routing-Primitive der Rule Engine – sie sind primär für zentrale Konfiguration gedacht.
  • Labels sind der saubere Weg, um Organisations- oder Betriebszugehörigkeit in Alerts zu tragen (agent.labels.*).
  • Für E-Mail-Routing nach Gruppen:
    • Integrator wählen, wenn ihr maximale Kontrolle/Custom Logik braucht.
    • OpenSearch Alerting/Notifications wählen, wenn ihr Query-basiertes SIEM-Alerting mit Channels nutzen wollt.

Fazit

Group-basierte E-Mail-Alerts lassen sich mit den klassischen <email_alerts>-Mechanismen des Wazuh Managers nicht sauber umsetzen, weil event_location keine Gruppen kennt. Der praxistaugliche Best-Practice-Weg ist: Gruppenzugehörigkeit als Label in den Alerts verankern und anschließend entweder managerseitig über den Integrator oder indexerseitig über OpenSearch Alerting/Notifications zu routen. Damit wird aus einer „unmatchbaren“ Konfiguration ein robustes, skalierbares Alert-Routing.

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