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 (leer = Standard, 0 = aus für diese Regel, sonst der kleinste Wert), sonst die Standard-Erinnerung in Stunden (Alarmierung, Werkseinstellung 0 = aus). Bestätigte Probleme bekommen keine Erinnerung. 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 = Standard aus "Alarmierung", 0 = aus für diese Regel) und laut/leise (leise: Telegram ohne Benachrichtigung, Matrix als m.notice). Mehrere passende Regeln: die kleinste Verzögerung gilt, beim Erinnerungsintervall schaltet eine ausdrückliche 0 die Erinnerung aus, sonst gilt der kleinste Wert größer 0 (ohne Wert in allen Regeln der Standard), 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).

Betriebsrobustheit (Phase 6c)

• Baseline beim Erstlauf: Ist der Zustandsspeicher leer und die Baseline noch nicht gesetzt, zeichnet der erste erfolgreiche Abruf alle offenen Probleme still auf (sie gelten als gemeldet, damit spätere Recoveries ankommen) und sendet eine einzige Zusammenfassung ohne KI an die Standardziele: Anzahl je Status inklusive Host-Problemen und die 10 kritischsten (Hosts zuerst, dann CRIT, UNKNOWN, WARN). Plugin-Output steht nie darin. Der Button "Baseline neu setzen" (Alarmierung, nur Admins, mit Audit-Eintrag) fordert dasselbe für den nächsten erfolgreichen Abruf an.
• Bestätigte Probleme (Acknowledged in Checkmk): kein neues Problem-Alarm, im Verlauf "unterdrückt (bestätigt)". Verschlechtert sich der Status gegenüber dem Stand bei Beginn der Bestätigung (Reihenfolge CRIT vor UNKNOWN vor WARN), gilt das Problem wieder als unbestätigt und wird gemeldet. Wird die Bestätigung aufgehoben, wird nichts nachgeholt. Stummschaltung, Downtime und Verzögerung wirken wie bisher; Recovery kommt weiter nur, wenn das Problem gemeldet wurde.
• Host-Alarme: Hosts, die nicht UP sind, werden mitabgefragt und als eigener Alarm gemeldet ("Host DOWN", "Host UNREACH", Recovery "Host wieder UP nach ..."). Intern ist der Service-Name Host, DOWN entspricht Status 2 und UNREACH Status 3 (für den Mindest-Schweregrad in Regeln); eine Regel mit Service-Muster Host trifft nur Host-Alarme. Die Host-Verzögerung (Alarmierung, Standard 0) ist unabhängig von Regel- und Standard-Verzögerung; Regel-Verzögerungen gelten nicht für Hosts. Solange ein Host nicht UP ist (auch in der Wartezeit), werden Service-Alarme dieses Hosts mit Grund "Host down" unterdrückt und nicht als gemeldet gezählt; bestehen sie nach der Rückkehr des Hosts weiter, greift die normale Verzögerung. Stummschaltung, Downtime und Bestätigung funktionieren für Hosts wie für Services. Das Dashboard zeigt Host-Probleme zuerst.
• Checkmk nicht erreichbar: Nach 3 aufeinanderfolgenden fehlgeschlagenen Abrufen kommt genau eine Systemmeldung an die Standardziele ("Checkmk nicht erreichbar seit HH:MM" bei Transportfehler, Timeout oder HTTP 5xx, "Antwort von Checkmk unerwartet seit HH:MM: ..." bei HTTP 4xx, ungültiger oder unerwarteter Antwort), beim ersten Erfolg danach "Checkmk wieder erreichbar nach ...". Die Meldung enthält nur einen kurzen Grund ohne Antwortinhalt und Secrets, läuft ohne KI und umgeht Verzögerung, Regeln und Stummschaltungen. Währenddessen gibt es keine Recoveries. Im Verlauf steht sie als Art system (Host checkbot, Service Checkmk-Verbindung).
• Sendelimit: höchstens N Nachrichten pro Minute und Ziel (Alarmierung, Standard 15, 1 bis 60, gleitendes Fenster je Backend und Ziel). Der Überschuss wird nicht einzeln gesendet, sondern als höchstens eine Sammelmeldung pro Minute und Ziel ("N weitere Alarme in der letzten Minute, siehe Verlauf", mit Link, wenn die Basis-URL gesetzt ist). Die betroffenen Einträge stehen im Verlauf als "unterdrückt (im Sammelhinweis)", die KI wird dafür nicht aufgerufen. KI-Nachträge zählen nicht gegen das Limit, Erinnerungen und Systemmeldungen schon; Systemmeldungen werden aber nie blockiert.
• Datenschutz je Backend: Telegram und Matrix haben die Einstellung "Inhalt der Alarmnachrichten": voll (Standard) oder kurz (Host, Service, Status und Verlaufszeile, ohne Plugin-Output und ohne KI-Text). Für kurz-Ziele wird keine KI-Analyse nachgereicht. Eine Überschreibung pro einzelnem Ziel gibt es nicht, weil Ziele in Regeln als freie Zeilen stehen; der Modus gilt je Backend.
• Link zur Oberfläche: Mit gesetzter "Basis-URL dieser Oberfläche" (Alarmierung, ohne abschließenden Schrägstrich gespeichert) enthält jede Alarmnachricht einen Link "Details" auf /alerts#alert-<id> (Telegram als URL-Button in der Button-Reihe, Matrix als Zeile im Text). Lehnt Telegram die URL ab (z. B. localhost), wird die Nachricht ohne Link-Button gesendet. Leer = kein Link.

API-Selbsttest (Phase 6d)

• Prüft rein lesend, ob Checkmk wie erwartet antwortet: /version, Service-Abfrage, Host-Abfrage, Downtime-Abruf. Jeder Teilcheck meldet ok, abweichend (z. B. optionale Spalte fehlt, Fallback auf GET statt POST oder auf query statt downtime_type, Downtimes aus scheduled_downtime_depth abgeleitet) oder fehler (Pflichtspalte fehlt, Checkmk nicht erreichbar oder Antwort unerwartet), nie mit Antwortinhalt im Text.
• Läuft kurz nach dem Start, danach täglich um 04:00 Uhr lokaler Zeit und markiert einen Lauf zusätzlich als Versionswechsel, wenn sich versions.checkmk gegenüber dem letzten Lauf geändert hat. Button "Selbsttest jetzt ausführen" (UI /selftest, nur Admins, höchstens 1x pro 30 s, Audit-Eintrag selftest.run).
• Ergebnis auf /selftest (für alle Rollen lesbar): Status je Teilcheck, Checkmk-Version, Zeitpunkt des letzten Laufs. Teilcheck checkmk_api in /health liest nur den letzten gespeicherten Lauf (kein eigener API-Aufruf); "noch nicht gelaufen" zählt wie "nicht konfiguriert".
• Chat-Meldung (Art system, wie die Checkmk-Ausfallmeldung) bei Wechsel auf abweichend/fehler, bei Rückkehr zu ok und bei Versionswechsel, nie bei gleichem Ergebnis zum Vorlauf. Schalter selftest.enabled (Zeitplan) und selftest.notify (Chat-Meldung) unter "Selbsttest-Einstellungen", beide Standard an.

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, Host-Verzögerung, Recovery-Schalter, Standard-Erinnerung, Bündelungsfenster, KI-Analysen pro Minute, Sendelimit, Basis-URL, Baseline-Button) 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 6c: Baseline, Bestätigungen, Host-Alarme, Ausfallmeldung, Sendelimit, Datenschutz je Backend, UI-Link; atomare Migrationen; Erinnerung je Regel	Code geschrieben, ungetestet
Phase 6d: API-Selbsttest (Version, Service-/Host-Abfrage, Downtime-Abruf, Fallbacks, /health-Teilcheck checkmk_api, UI /selftest)	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. Das gilt ebenso für den Host-Abruf (POST /domain-types/host/collections/all mit den Spalten name, state, plugin_output, last_state_change, scheduled_downtime_depth, acknowledged) und die Service-Spalte acknowledged.

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. Für den ersten Lauf im Test-LXC gibt es deploy/first-run.sh (Dev-venv, Import- und Template-Prüfung, vollständiger pytest-Lauf, Archiv ohne Secrets), siehe deploy/README.md.
• Migrationen laufen je Migration in einer Transaktion mit Rollback; schlägt eine fehl, bleibt die Datenbank beim letzten vollständigen Stand und der Start bricht mit einer Fehlermeldung ab.
• Der Plan und alle Entwurfsentscheidungen stehen in CLAUDE.md.
• Code-Kommentare nur bei echtem WHY, Konstanten statt Magic Strings.