Einleitung
E-Mail-Benachrichtigungen gehören zu den ältesten und zugleich kritischsten Alerting-Mechanismen in SIEM-Umgebungen. Wazuh bietet hierfür sowohl eine integrierte E-Mail-Funktion als auch die Möglichkeit, Custom Email Alerts über Integrationen umzusetzen. In der Praxis entsteht dabei häufig Verwirrung: Während das Standard-Alerting eine native Drosselung über <email_maxperhour> unterstützt, fehlt eine vergleichbare Option für Custom Integrations. Dieser Artikel ordnet das Verhalten korrekt ein und zeigt den von Wazuh offiziell vorgesehenen Weg auf.
Ausgangslage / Problemstellung
In einer Wazuh-Umgebung wurden benutzerdefinierte E-Mail-Benachrichtigungen über eine Custom Integration (z. B. ein Python-Skript) eingerichtet. Ziel war es, die Anzahl der versendeten E-Mails pro Stunde zu begrenzen – analog zur bekannten Einstellung:
<email_maxperhour>100</email_maxperhour>
Die Beobachtung: Trotz gesetztem Limit werden weiterhin unbegrenzt E-Mails aus der Custom Integration versendet.
Technische Analyse
Geltungsbereich von <email_maxperhour>
Die Einstellung <email_maxperhour> ist Bestandteil der globalen E-Mail-Konfiguration des Wazuh-Managers und greift ausschließlich für das integrierte E-Mail-Alerting von Wazuh. Dieses Alerting ist direkt an die interne Alert-Engine gekoppelt und wird über die klassischen <alerts>– und <email_alerts>-Optionen gesteuert.
Die offizielle Wazuh-Dokumentation beschreibt <email_maxperhour> explizit als Mechanismus zur Begrenzung der vom internen Maildienst versendeten Benachrichtigungen. Custom Integrations werden in diesem Zusammenhang nicht erwähnt, da sie architektonisch getrennt verarbeitet werden.
Quelle:
Wazuh Dokumentation – Alerts configuration
https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/alerts.html
Architektur von Custom Integrations
Custom Integrations werden über den Integrator des Wazuh-Managers ausgeführt. Eine <integration>-Definition legt fest, welche Alerts (z. B. nach Level, Gruppe oder Regel-ID) an ein externes Skript weitergereicht werden.
Wesentliche Eigenschaften laut offizieller Dokumentation:
- Das Integrationsskript wird für jeden passenden Alert einzeln aufgerufen
- Es existiert keine zentrale Drosselungs- oder Queue-Logik für Integrationen
- Der Integrator übernimmt lediglich das Matching und das Weiterreichen der Alert-Daten
Damit ist klar: Custom Integrations unterliegen nicht dem internen E-Mail-Subsystem und können folglich auch nicht von <email_maxperhour> beeinflusst werden.
Quelle:
Wazuh Dokumentation – Integration configuration
https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/integration.html
Konsequenz für Custom Email Alerts
Jede passende Alert-Instanz führt zur Ausführung des Integrationsskripts. Ohne zusätzliche Logik wird somit auch für jedes Ereignis eine E-Mail versendet. Dieses Verhalten ist beabsichtigt und dokumentiert und stellt keinen Fehler dar.
Lösung / Best Practices
Offiziell empfohlener Ansatz: Rate Limiting im Integrationsskript
Die von Wazuh empfohlene und unterstützte Methode zur Begrenzung von Custom Alerts besteht darin, das Rate Limiting direkt im Integrationsskript umzusetzen. Dies wird auch explizit von Wazuh-Mitarbeitern im Community-Kontext bestätigt und entspricht der Architekturentscheidung des Integrator-Moduls.
Dabei gilt:
- Wazuh stellt keine native Limit-Option für Custom Integrations bereit
- Die Verantwortung für Drosselung, Aggregation oder Verwerfung liegt vollständig beim Skript
Quelle:
Wazuh Dokumentation – Integration configuration
https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/integration.html
Minimal empfohlene Umsetzung (konform zur Dokumentation)
Ohne zusätzliche externe Komponenten oder Datenbanken lässt sich ein einfaches Limit wie folgt umsetzen:
- Persistenter Status in einer lokalen Datei (z. B. Zähler + Zeitfenster)
- Prüfung bei jedem Skriptaufruf:
- Liegt das aktuelle Ereignis noch im selben Zeitfenster?
- Wurde das definierte Maximum erreicht?
- Bei Überschreitung: Kein Versand der E-Mail
Diese Logik liegt vollständig außerhalb von Wazuh und verletzt keine unterstützten Betriebsmodelle, da Integrationsskripte explizit als frei gestaltbar dokumentiert sind.
Ergänzende Maßnahme: Integration-Filter korrekt setzen
Unabhängig vom Rate Limiting empfiehlt Wazuh, die Menge der ausgelösten Integrationen bereits vorab zu reduzieren:
- Einschränkung nach
level - Nutzung von
rule_idodergroup - Trennung mehrerer Integrationen nach Use Case
Dies reduziert Last, vermeidet unnötige Skriptausführungen und ist vollständig in der offiziellen Integration-Konfiguration vorgesehen.
Quelle:
Wazuh Dokumentation – Integration options
https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/integration.html
Lessons Learned / Best Practices
<email_maxperhour>gilt ausschließlich für den integrierten E-Mail-Versand von Wazuh, nicht für Custom Integrations.- Custom Integrations werden ereignisbasiert ohne Drosselung ausgeführt.
- Rate Limiting für Custom Email Alerts ist bewusst Aufgabe des Integrationsskripts.
- Vorfilterung über
<integration>-Optionen ist der erste und wichtigste Schritt zur Alert-Reduktion. - Das beobachtete Verhalten entspricht vollständig der offiziellen Wazuh-Dokumentation und ist kein Konfigurationsfehler.
Fazit
Wazuh trennt klar zwischen internem Alerting und Custom Integrations. Die native E-Mail-Drosselung über <email_maxperhour> schützt ausschließlich den eingebauten Mailversand. Wer benutzerdefinierte E-Mail-Alerts über Integrationen realisiert, muss die Kontrolle über Versandfrequenz und Volumen selbst übernehmen. Dieses Design ist dokumentiert, stabil und erlaubt maximale Flexibilität – erfordert aber ein bewusstes Alert- und Integrationsdesign.
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/p1767334568043149