checkbot/README.md

checkbot

Bot für Checkmk. Er liest den Zustand per REST-API, lässt Probleme von einem externen Ollama analysieren und meldet sie in Telegram und/oder Element (Matrix). Betrieb und Einstellungen laufen über eine deutsche Web-UI. Gedacht für einen Debian-LXC.

Stand: Entwicklung. Der Code ist geschrieben, aber noch nicht ausgeführt oder gegen eine echte Checkmk-, Ollama- oder Telegram-Instanz getestet. Die Statusspalte unten sagt, was woran ist.

Was der Bot kann

Alarme melden

• Fragt Checkmk alle 30 s ab (einstellbar) und erkennt neue Probleme, Statuswechsel (WARN/CRIT/UNKNOWN), Recoveries und Flapping.
• Meldet nur Hard-States und erst nach einer Verzögerung (siehe unten).
• Respektiert Downtimes: Services in Downtime lösen keine Nachricht aus und erscheinen im Verlauf als "unterdrückt".
• Bündelt Alarme eines Hosts zu einer Nachricht und begrenzt den Durchsatz, damit eine Alarmflut den Chat und Ollama nicht überrollt.
• Fällt Ollama aus, kommt der Rohalarm trotzdem sofort. Die Analyse wird nachgereicht oder als "KI nicht verfügbar" markiert.

Verzögerung, Delta, Erinnerungen und Recovery

• Verzögerung: Ein Problem wird erst gemeldet, wenn sein jetziger Zustand seit der Standard-Verzögerung (Alarmierung, Werkseinstellung 15 min, 0 = sofort) besteht; eine Regel kann das überschreiben, auch mit 0. Die Zeit zählt ab der letzten Statusänderung in Checkmk, eine Verschlechterung startet sie neu. Wird das Problem vorher wieder OK, gibt es weder Alarm noch Recovery. Mute und Downtime wirken auch in der Wartezeit; was bei Ablauf der Verzögerung unterdrückt ist, wird nicht nachgeholt. Die frühere Einstellung poll.min_duration gibt es nicht mehr, ein vorhandener Altwert wird ignoriert.
• Delta in der Nachricht: WARN → CRIT, seit 18:05 (vorher WARN seit 2 h), bei Recovery wieder OK nach 3 h 12 min (zuletzt CRIT), bei Erinnerungen weiter CRIT seit 4 h: <Output>. Zeiten in der lokalen Zeit des Prozesses.
• Erinnerungen: nur für offene CRIT-Probleme, die gemeldet wurden und weiter CRIT sind, nicht bei Mute, Downtime oder Flapping. Intervall aus den passenden Regeln (kleinstes), sonst die Standard-Erinnerung in Stunden (Alarmierung, Werkseinstellung 0 = aus). Gemessen ab der letzten Meldung bzw. Erinnerung, der Zeitpunkt ist in der Datenbank gespeichert (kein Doppelversand nach Neustart). Erinnerungen laufen ohne KI durch dasselbe Routing wie Alarme und stehen im Verlauf als Art reminder.
• Recovery: Schalter "Recovery-Meldungen senden" (Alarmierung, Werkseinstellung an) und pro Regel über die Alarmarten. Eine Recovery wird nur gesendet, wenn das Problem vorher tatsächlich gemeldet wurde; sonst (oder bei ausgeschaltetem Schalter) steht sie unterdrückt im Verlauf.

KI-Analyse

• Pro Problem kurze Analyse auf Deutsch (max. 8 Zeilen): Zusammenfassung, wahrscheinliche Ursache, nächster Prüfschritt.
• Kontext: Host, Service, Plugin-Output, letzte Statuswechsel, Downtime-Info.
• Ein KI-Hinweis der Regel steht als Abschnitt "Zusatzkontext des Administrators" im Nutzer-Prompt vor dem Datenblock (bereinigt, gekürzt, ohne Begrenzer). Der feste Schutzhinweis im System-Prompt bleibt unverändert.
• Plugin-Output gilt als nicht vertrauenswürdig. Er wird abgegrenzt, gekürzt und bereinigt, und die KI kann nichts auslösen.

Chat (Telegram und Element)

• Beide Backends parallel, einzeln abschaltbar.

• Matrix läuft direkt über die Client-Server-API (httpx, kein matrix-nio, keine E2EE-Abhängigkeiten). Der Alarmraum muss unverschlüsselt sein, der Bot-User braucht einen Access-Token und muss dem Raum beigetreten sein. Die Analyse kommt per m.replace-Edit.

• Regeln (UI /routing, in der Navigation "Regeln"): Host-/Service-Glob, optional "Ausgabe enthält" (Teilstring, keine Regex), Mindest-Schweregrad, Alarmarten und Ziele (Backend plus Chat-ID bzw. Raum-ID). Regeln gelten von oben nach unten, jede passende fügt ihre Ziele hinzu, optional mit Stopp nach Treffer. "Standardziele" in einer Regel fügt die Standardziele aller aktivierten Backends zu den expliziten Zielen hinzu. Eine passende Regel ganz ohne Ziele und ohne Standardziele sendet bewusst nichts. Passt keine Regel, gehen Alarme an die Standardziele. Alarme eines Hosts mit gleicher Zielmenge und gleicher Lautstärke werden zu einer Nachricht gebündelt.

• Weitere Regeloptionen: Verzögerung in Minuten (leer = Standard), KI an/aus, KI-Hinweis (max. 800 Zeichen), Erinnerung bei CRIT in Stunden (leer oder 0 = keine) und laut/leise (leise: Telegram ohne Benachrichtigung, Matrix als m.notice). Mehrere passende Regeln: die kleinste Verzögerung und das kleinste Erinnerungsintervall gelten, KI ist aus, sobald eine passende Regel sie ausschaltet, laut gilt, sobald eine passende Regel laut ist, KI-Hinweise werden in Regelreihenfolge zusammengefügt (insgesamt max. 1200 Zeichen).

• Vorinstallierte Regel "ZFS Zpool" (einmalig beim ersten Start angelegt, danach editier- und löschbar, eine gelöschte Regel kommt nicht zurück): Service *zpool* ab WARN, Standardziele, Verzögerung 0, KI mit Hinweis auf typische Prüfschritte, Erinnerung bei CRIT alle 4 h.

• Stummschaltung (UI /mutes): Host-/Service-Glob mit Ablauf (30 min bis 24 h oder freie Minuten) und Grund. Passende Probleme, Flapping und Recoveries werden nicht gemeldet und im Verlauf als unterdrückt (Stummschaltung) geführt. Abgelaufene Stummschaltungen räumt der Bot selbst auf.

• Der Versand läuft über eine Warteschlange (max. 1000 Events, bei Überlauf wird das älteste verworfen), ein langsames Chat-Backend bremst den Poller nicht.

• Rohalarm zuerst, die Analyse ersetzt oder ergänzt die Nachricht per Edit.

• Befehle für Allowlist-User (Telegram mit /, Element mit !):

  Befehl	Wirkung
  help, status, problems	Hilfe, Zähler, Liste der Probleme
  host <name>	Services eines Hosts
  explain <host> <service>	KI-Analyse über den Agenten
  ask <frage>	freie Frage an den Agenten
  mute <host> [service] <dauer> [grund]	Bot-lokale Stummschaltung
  downtime <host> <service> <dauer> [kommentar]	Checkmk-Downtime, nur nach Bestätigung
  confirm <code>, cancel <code>	Downtime bestätigen oder abbrechen (vor allem für Element)

  Dauer: 30m, 2h, 1d, 1h30m oder 90 (Minuten). Als Antwort auf eine Alarmnachricht genügt /mute 2h bzw. !mute 2h, der Bot ordnet die Nachricht über den Verlauf dem Host und Service zu. Enthält die Nachricht mehrere Services, nennt der Bot den Befehl mit expliziten Angaben.

• Telegram: Der Bot liest per getUpdates (Long-Polling, Offset persistent) mit Nachrichten und Button-Klicks. Beim allerersten Start wird der Rückstand ignoriert. Antworten kommen als Reply auf die Befehlsnachricht.

• Element: Der Bot liest per /sync nur den konfigurierten Raum. Beim ersten Start wird nur das Sync-Token geholt (keine Historie), das Token liegt danach in der Datenbank. Eigene Nachrichten, Edits und Reply-Zitate werden ignoriert bzw. entfernt.

• Alarm-Buttons (Telegram, nur mit gefüllter Allowlist): "2 h stumm" und "Tiefenanalyse", dazu "Downtime 2 h" wenn die Downtime-Funktion aktiv ist. Sie erscheinen bei Einzelalarmen, nicht bei gebündelten Nachrichten und nicht bei Recoveries. In Element steht stattdessen der Hinweis "Antwort mit !mute 2h zum Stummschalten".

• Ruhigstellen:

  • mute: der Bot meldet einen Service für eine Dauer nicht mehr (maximal 7 Tage). Checkmk bleibt unberührt.
  • downtime: setzt eine echte Service-Downtime in Checkmk und ist die einzige Schreibaktion des Bots. Absicherung:
    1. Standardmäßig aus, Schalter in der UI unter "Downtime".
    2. Eigener Checkmk-User und eigenes Secret (verschlüsselt gespeichert), getrennt vom Lese-User.
    3. Maximaldauer einstellbar (Standard 24 h, harte Obergrenze 168 h), längere Anfragen werden abgelehnt.
    4. Der Bot zeigt Host, Service, Dauer und Kommentar und wartet 120 s auf die Bestätigung durch denselben Absender (Telegram: Buttons, Element: !confirm <code>). Der Code ist zufällig und nur einmal gültig.
    5. Nur Allowlist-User, Agent und KI haben keinen Zugriff.
    6. Anfrage, Bestätigung, Abbruch, Ablauf, Ablehnung und Checkmk-Fehler stehen im Audit-Log (Sender, Backend, Host, Service, Dauer).

Agent für Fragen

• /ask, /explain und der Alarm-Button "Tiefenanalyse" nutzen einen Tool-Loop mit fünf festen Lese-Tools (get_service_status, get_host_services, get_state_history, get_downtimes, get_problems).
• Maximal 6 Schritte und 90 s pro Anfrage. Jeder Tool-Aufruf steht im Audit-Log (agent.tool).
• Agent-Ansicht (UI /agent, nur Admins): Liste der letzten Läufe mit Zeit, Absender, Befehl, Frage, Schrittzahl und Ergebnis. Die Detailseite zeigt pro Lauf Frage, Antwort und jeden Schritt (Tool, Argumente, gekürztes Ergebnis, Dauer, Fehler) sowie den Abbruchgrund. Tokens und Secrets werden vor dem Speichern maskiert.

Prompt-Verwaltung

• Zwei Prompts: alert (Alarm-Analyse) und agent (Agent). Jede Änderung ist eine neue, fortlaufend nummerierte Version mit Zeit, Nutzer und Notiz. Version 1 ist der eingebaute Standardtext (oder ein früher in der Einstellung prompt.alert_system gesetzter Text, der einmalig übernommen wird).
• Neue Versionen sind zuerst Entwürfe. "Aktivieren" macht eine Version wirksam, das Aktivieren einer älteren Version ist der Rollback. Der Bot liest den aktiven Text bei jedem Aufruf frisch, ein Neustart ist nicht nötig. Fällt die Datenbank beim Lesen aus, gilt der Standardtext.
• Der feste Schutzhinweis gegen Prompt Injection wird immer hinter den Text gehängt. Er ist in der UI sichtbar, aber nicht editierbar. Der Text darf nicht leer sein, höchstens 4000 Zeichen haben und keine Datenblock-Begrenzer (<daten>, </daten>) enthalten, Steuerzeichen werden entfernt.
• Admins bearbeiten, Viewer lesen. Aktivieren und Anlegen stehen im Audit-Log (Prompt, Versionen, Nutzer, ohne Textinhalt).
• Testbereich (nur Admins, höchstens 6 Läufe pro Minute und Nutzer): Entwurf oder gespeicherte Version gegen einen der letzten 50 Alarme oder einen Freitext-Alarm (vorbelegt mit dem ZFS-Zpool-Beispiel) laufen lassen. Aufgerufen wird Ollama mit dem Alarm-Modell wie im Betrieb, aber ohne Versand in Telegram oder Element und ohne Einträge in Alarmen oder Zustellungen. Angezeigt werden Ergebnis, Dauer und Fehler (ohne Secrets). Für den Agenten-Prompt läuft eine Frage durch den Agent-Loop mit den Lese-Tools. Der Lauf wird nicht in der Agent-Läufe-Liste gespeichert, seine Tool-Aufrufe stehen im Audit-Log (Nutzer test:<name>).

Aufbewahrung

• Einstellbar unter "Aufbewahrung" (ganze Tage, Minimum 1, damit nichts versehentlich ausgeschaltet wird): Alarmverlauf samt Zustellungen 90, Agenten-Läufe 90, Statusverlauf 30, Audit-Log 365, abgelaufene Stummschaltungen 7 Tage nach Ablauf.
• Der Bot räumt einmal nach dem Start (kurz verzögert) und danach einmal pro Kalendertag nach 03:00 Uhr lokaler Zeit auf, in Batches zu 1000 Zeilen mit Pausen. Aktuelle Service-Zustände und der Listener-Zustand bleiben unberührt. Nach dem Lauf folgt PRAGMA wal_checkpoint(TRUNCATE), ein VACUUM gibt es bewusst nicht.
• Die gelöschten Zeilenzahlen stehen im Journal (INFO) und als ein Audit-Eintrag retention.run. Die Einstellungsseite zeigt den letzten Lauf mit Zählern und hat den Button "Jetzt aufräumen" (nur Admins).

Web-UI

• Anmeldung mit lokalen Nutzern (Argon2), optional TOTP. Rollen admin und viewer.
• Einstellungen mit Verbindungstest: Checkmk, Ollama, Telegram, Matrix, Checkmk Downtime. Dazu die Bereiche Alarmierung (Abfrageintervall, Standard-Verzögerung, Recovery-Schalter, Standard-Erinnerung, Bündelungsfenster, KI-Analysen pro Minute) und Aufbewahrung.
• Setup-Assistent beim ersten Start, Dashboard mit Live-Status, Alarmverlauf, Audit-Log, Benutzerverwaltung.
• Regeln und Stummschaltungen (Admins bearbeiten, Viewer sehen). Das Dashboard zeigt bei offenen Problemen den Meldestatus: "gemeldet", "wartet noch N min" oder "unterdrückt (Grund)".
• Prompts (UI /prompts), siehe unten. Aufbewahrung (UI /settings/retention), siehe unten.
• Tokens und Secrets liegen verschlüsselt in der Datenbank und werden in der UI nie wieder angezeigt.

Architektur

Checkmk (REST-API)  <----  Poller  ---->  Alarm-Pipeline  ---->  Telegram / Element
                                                |
                                                +---->  Ollama (extern)

Web-UI (FastAPI, Jinja2)  ----  SQLite (Einstellungen, Verlauf, Audit, Nutzer)

• Der Bot hört nur mit der UI (hinter Caddy mit HTTPS). Alarme kommen per Polling herein, es gibt keinen offenen Alarm-Port.
• Ausgehend: Checkmk, Ollama, Telegram, Matrix.

Status

Bereich	Stand
Phase 1: Secret-Verschlüsselung, SQLite, Checkmk- und Ollama-Client, /health	Code geschrieben, ungetestet
Phase 2: Login, Rollen, TOTP, Einstellungen mit Verbindungstest, Audit, CLI	Code geschrieben, ungetestet
Phase 3: Poller, Alarm-Pipeline, Telegram, Alarmverlauf	Code geschrieben, ungetestet
Phase 4: Matrix-Adapter, Routing, Stummschaltung in der UI	Code geschrieben, ungetestet
Phase 5: Befehle, mute/downtime, Agent-Loop, Listener, Agent-Ansicht	Code geschrieben, ungetestet
Phase 6: Prompt-Versionierung mit Rollback und Testbereich, Retention	Code geschrieben, ungetestet
Phase 6b: Regeln (Ausgabefilter, Verzögerung, KI-Hinweis, Erinnerung, laut/leise), Delta, Erinnerungen, Recovery-Schalter, Zpool-Standardregel	Code geschrieben, ungetestet
Phase 7: Deployment (setup-lxc.sh, Caddy, systemd, Backup, Checkmk-Local-Check)	Dateien geschrieben, nicht auf einem System ausprobiert
Phase 8: Integrationstests	geplant

Die Checkmk-Spaltennamen und der Downtime-Endpunkt sind Annahmen aus der Dokumentation und noch nicht an einer echten Instanz geprüft.

Deployment

Betrieb im Debian-LXC (Proxmox) mit Caddy, systemd, täglichem Backup und Checkmk-Local-Check: siehe deploy/README.md. Einstieg: sudo deploy/setup-lxc.sh aus einem Checkout, Updates mit sudo deploy/update.sh.

Schnellstart (manuell, ohne Setup-Skript)

Voraussetzung: Python 3.11+, Zugriff auf Checkmk 2.5 (Automation-User mit Lese-Rolle; entwickelt nach dem API-Stand von 2.3, gegen 2.5 noch zu prüfen) und auf einen Ollama-Host.

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

export CHECKBOT_CONFIG_DIR=./etc CHECKBOT_DB=./checkbot.db CHECKBOT_SECURE_COOKIES=0
.venv/bin/python -m app.cli gen-keys
.venv/bin/python -m app.cli create-admin
.venv/bin/uvicorn app.main:create_app --factory --host 127.0.0.1 --port 8080

Danach http://127.0.0.1:8080 öffnen, anmelden und im Setup Checkmk und Ollama eintragen.

CHECKBOT_SECURE_COOKIES=0 gehört nur in lokale Tests ohne HTTPS. Im Betrieb läuft die UI hinter Caddy mit HTTPS.

Dateien und Umgebungsvariablen

Variable	Standard	Bedeutung
CHECKBOT_CONFIG_DIR	/etc/checkbot	enthält master.key und session.secret (chmod 600)
CHECKBOT_DB	/var/lib/checkbot/checkbot.db	SQLite-Datenbank
CHECKBOT_BIND_HOST	127.0.0.1	Bind-Adresse
CHECKBOT_BIND_PORT	8080	Port
CHECKBOT_SECURE_COOKIES	1	Session-Cookie nur über HTTPS

Alles andere (Checkmk, Ollama, Chat-Backends, Limits) wird in der UI gesetzt.

CLI

Befehl	Zweck
python -m app.cli gen-keys	legt master.key und session.secret an, überschreibt nichts
python -m app.cli create-admin [name]	legt den ersten Admin an
python -m app.cli set-password <name>	setzt ein Passwort zurück

Geht master.key verloren, sind alle in der Datenbank gespeicherten Secrets unbrauchbar. Sichere die Datei getrennt von der Datenbank.

Sicherheit

• Der Bot liest Checkmk standardmäßig nur. Die einzige Schreibaktion ist die optionale Downtime, mit eigenem Checkmk-User, Bestätigung und Audit-Eintrag.
• KI und Agent haben keine Schreib-Tools.
• CSRF-Schutz, Sicherheits-Header mit strenger CSP, Rate-Limit beim Login, Sitzungen werden beim Passwortwechsel ungültig.
• Das Audit-Log enthält nie Secret-Werte.

Entwicklung

• Tests: pip install -r requirements-dev.txt, dann pytest.
• Der Plan und alle Entwurfsentscheidungen stehen in CLAUDE.md.
• Code-Kommentare nur bei echtem WHY, Konstanten statt Magic Strings.