Wazuh Telegram-Benachrichtigungen mit OpenSearch Alerting einrichten

Ein Sicherheitsdashboard hilft nur, wenn jemand hineinschaut. Für dringende Ereignisse möchte ich deshalb eine Nachricht auf dem Handy bekommen. In meiner Wazuh-Installation funktioniert das über OpenSearch Notifications und Alerting: Ein Benachrichtigungskanal spricht die Telegram-Bot-API an, Monitore bestimmen den Anlass und die Häufigkeit.

Ich nutze denselben Telegram-Bot wie für Zabbix, weil ich nicht für jedes System einen eigenen Bot pflegen möchte. Die Regeln und Nachrichten bleiben getrennt, damit sofort erkennbar ist, welches System meldet. Für diese Anleitung brauchst du einen funktionierenden Wazuh-Indexer mit den entsprechenden OpenSearch-Funktionen und administrative Rechte zum Einrichten des Kanals.

Bot und Zielchat vorbereiten

Lege bei Telegram über den offiziellen BotFather einen Bot an oder verwende deinen bestehenden Monitoring-Bot. Öffne den Zielchat und starte den Bot. Du brauchst den Bot-Token und die numerische Chat-ID. Bei Gruppen kann die Chat-ID negativ sein; speichere sie als Zeichenfolge.

Die Details zum Bot und der API beschreibt Telegram. Mit der Methode getUpdates lässt sich bei einem neuen Bot eine empfangene Chat-Nachricht zuordnen. Bei einem vorhandenen Bot können Polling oder ein bestehender Webhook die Updates bereits verarbeiten. Ändere dessen Webhook deshalb nicht für eine schnelle ID-Abfrage.

Für das Senden lautet der Endpunkt:

https://api.telegram.org/bot<BOT_TOKEN>/sendMessage

Der Token ist ein Zugangsschlüssel. Ein Screenshot dieser fertigen URL wäre daher ein veröffentlichtes Geheimnis. Die Artikelbilder zeigen nur Monitore und Betriebsstatus.

Einen Webhook-Kanal anlegen

Öffne im Dashboard Notifications und lege einen Kanal vom Typ Custom webhook an. Verwende den Telegram-Endpunkt, HTTPS und POST. Setze als Header Content-Type: application/json. Beschränke den Zugang zu dieser Konfiguration auf die Administratoren, die den Bot tatsächlich verwalten sollen. OpenSearch Notifications

Telegram erwartet für eine einfache Textnachricht einen JSON-Body:

{
  "chat_id": "<CHAT_ID>",
  "text": "Wazuh: Verbindungstest",
  "disable_notification": false
}

Wähle für den Anfang keinen parse_mode. So werden Unterstriche, Paketnamen und andere Sonderzeichen nicht versehentlich als Formatierungsbefehle interpretiert. Die Pflichtfelder sind in der sendMessage-Dokumentation beschrieben.

Warum der eingebaute Kanaltest scheitern kann

Ein wichtiger Stolperstein: Die generische OpenSearch-Testnachricht hat nicht automatisch den JSON-Aufbau, den Telegram verlangt. Ein Fehler beim eingebauten Kanaltest beweist daher noch nicht, dass Token, Netzverbindung oder Chat-ID falsch sind.

Teste zuerst eine Nachricht mit einem bekannten gültigen Telegram-Body. Kontrolliere sowohl die HTTP-Antwort als auch das Telegram-Feld ok und den tatsächlichen Eingang im Chat. Danach testest du die Nachrichtenvorlage des Monitors. Der erfolgreiche direkte Test ersetzt diesen zweiten Test nicht.

Den ersten Monitor erstellen

Öffne Alerting → Monitors → Create monitor. Für einen einfachen Start genügt ein Query-level monitor, der alle fünf Minuten wazuh-alerts-* abfragt. Weiter unten findest du eine komplette, deaktivierte Monitor-Vorlage mit Platzhaltern; passe Kanal-ID und Chat-ID an, bevor du sie verwendest.

Die Abfrage filtert die letzten fünf Minuten nach rule.level >= 12. Paket-CVE-Ereignisse werden aus diesem dringenden Ereignisstrom ausgeschlossen, weil eine Inventaraktualisierung sehr viele Befunde gleichzeitig erzeugen kann. Sie gehören in einen eigenen Befundbericht. Prüfe in deinen Daten, ob dafür wie bei mir die Gruppe vulnerability-detector verwendet wird.

{
  "size": 0,
  "track_total_hits": true,
  "query": {
    "bool": {
      "filter": [
        {"range": {"timestamp": {"gte": "now-5m", "lte": "now"}}},
        {"range": {"rule.level": {"gte": 12}}}
      ],
      "must_not": [{"term": {"rule.groups": "vulnerability-detector"}}]
    }
  }
}

Als Trigger-Bedingung dient ctx.results[0].hits.total.value > 0. Die Aktion verwendet deinen Notifications-Kanal und eine JSON-Nachricht, die die Trefferzahl enthält. Im Query-level-Starter ist eine Wiederholungsgrenze von 60 Minuten bewusst einfach gehalten: Sie gilt für die Aktion insgesamt. Ein neues Problem kann dadurch innerhalb dieses Fensters ebenfalls keine weitere Nachricht auslösen.

Für meine produktive dringende Alarmierung verwende ich deshalb einen Bucket-level monitor mit Gruppen nach System und Regel. Dadurch lassen sich Wiederholungen pro betroffenem System und Regel begrenzen. Beachte außerdem das Abfragefenster: Eine spätere erneute Aktivierung nach einer ereignisfreien Zeit ist nicht dasselbe wie eine technische Doppelzustellung. OpenSearch Alerting API

Vorlage: der komplette Starter-Monitor

Die Vorlage ist absichtlich deaktiviert ("enabled": false). Mit unveränderten Platzhaltern verschickt sie nichts.

{
  "type": "monitor",
  "name": "Wazuh Serie · Ereignisse ab Level 12",
  "monitor_type": "query_level_monitor",
  "enabled": false,
  "schedule": {"period": {"interval": 5, "unit": "MINUTES"}},
  "inputs": [{"search": {
    "indices": ["wazuh-alerts-*"],
    "query": {
      "size": 0,
      "track_total_hits": true,
      "query": {"bool": {
        "filter": [
          {"range": {"timestamp": {"gte": "now-5m", "lte": "now"}}},
          {"range": {"rule.level": {"gte": 12}}}
        ],
        "must_not": [{"term": {"rule.groups": "vulnerability-detector"}}]
      }}
    }
  }}],
  "triggers": [{
    "name": "Mindestens ein Ereignis",
    "severity": "1",
    "condition": {"script": {"source": "ctx.results[0].hits.total.value > 0", "lang": "painless"}},
    "actions": [{
      "name": "Telegram Zusammenfassung",
      "destination_id": "HIER_NOTIFICATIONS_CHANNEL_ID_EINTRAGEN",
      "message_template": {
        "lang": "mustache",
        "source": "{\"chat_id\":\"HIER_CHAT_ID_EINTRAGEN\",\"text\":\"Wazuh: {{ctx.results.0.hits.total.value}} Ereignisse ab Level 12 in den letzten 5 Minuten. Bitte Dashboard prüfen.\",\"disable_notification\":false}"
      },
      "throttle_enabled": true,
      "throttle": {"value": 60, "unit": "MINUTES"}
    }]
  }]
}

Meine fünf Monitore

Der tägliche Bericht kommt bei mir um 09:00 Uhr. Stelle die Zeitzone im Monitor ausdrücklich ein, in Deutschland zum Beispiel Europe/Berlin, statt lokale Uhrzeit und UTC zu vermischen.

Der Offline-Monitor verwendet regelmäßig erhobene Agentenstatusdaten. Bei meinem 15-Minuten-Abzug und einem Grenzwert von 25 Minuten kann die Erkennung ungefähr 25 bis 40 Minuten dauern. Wer kürzere Reaktionszeiten will, muss auch den Statusabzug entsprechend häufiger erstellen.

Funktion und Wiederherstellung prüfen

Bei einem Testagenten prüfe ich nacheinander: direkte Telegram-Nachricht, Monitor-Abfrage, Aktion, Drosselung und Wiederherstellung. Ich schalte dafür nicht absichtlich einen produktiven Mail- oder Datenbankserver aus. Ein Monitor-Dry-Run hilft beim Prüfen der Abfrage, beweist aber noch keine erfolgreiche Zustellung.

Ein eigener Alarm zum Stillstand der Datenstrecke ist ebenfalls hilfreich. Komplett schweigende Systeme sehen sonst leicht nach einer ruhigen Nacht aus.

Den Totalausfall des Indexers kann sein eigener Monitor nicht zuverlässig melden. Deshalb prüft Zabbix Wazuh unabhängig und verwendet den bereits eingerichteten Telegram-Weg. Die Grundlagen dafür stehen im Zabbix-Telegram-Artikel.