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, optional erst nach einer Mindestdauer.
• 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.

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.
• 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.
• Rohalarm zuerst, die Analyse ersetzt oder ergänzt die Nachricht per Edit.
• Befehle für Allowlist-User: /status, /problems, /host <name>, /explain <service>, /ask <frage> in Telegram, mit ! statt / in Element.
• Ruhigstellen:
  • mute: der Bot meldet einen Service für eine Dauer nicht mehr. Checkmk bleibt unberührt.
  • downtime: setzt eine echte Downtime in Checkmk. Nur nach Bestätigung, nur für Allowlist-User, mit einstellbarer Maximaldauer. Standardmäßig aus.

Agent für Fragen

• /ask und /explain 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.

Web-UI

• Anmeldung mit lokalen Nutzern (Argon2), optional TOTP. Rollen admin und viewer.
• Einstellungen mit Verbindungstest: Checkmk, Ollama, Telegram, später Matrix.
• Setup-Assistent beim ersten Start, Dashboard mit Live-Status, Alarmverlauf, Audit-Log, Benutzerverwaltung.
• Geplant: Prompts mit Versionierung, Rollback und Testbereich; Routing und Stummschaltungen.
• 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	geplant
Phase 5: Befehle, mute/downtime, Agent-Loop	geplant
Phase 6: Prompt-Versionierung, Testbereich, Retention	geplant
Phase 7: Deployment (setup-lxc.sh, Caddy, systemd, Checkmk-Agent)	geplant
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.

Schnellstart (manuell, bis das Setup-Skript existiert)

Voraussetzung: Python 3.11+, Zugriff auf Checkmk 2.3+ (Automation-User mit Lese-Rolle) 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.