crowdsec-manager/docs/NOTIFICATIONS.md

Benachrichtigungen

Dokumentation des Benachrichtigungssystems im CrowdSec Manager v0.1.0.

---

Übersicht

Das Benachrichtigungssystem ist modular aufgebaut. Vier Kanäle können gleichzeitig aktiv sein:

                    ┌── Desktop (notify-send)
                    ├── Ntfy (HTTP POST)
should_notify? ─────┤
                    ├── Gotify (HTTP POST / JSON)
                    └── E-Mail (SMTP via curl / mail)

---

Allgemeine Konfiguration

Benachrichtigungen aktivieren

NOTIFY_ENABLED=true

Benachrichtigungs-Bedingungen

NOTIFY_ON="changes"

Wert	Bedingung
always	Nach jeder Ausführung
changes	Wenn IPs hinzugefügt, entfernt oder Fehler aufgetreten sind
errors	Nur bei Fehlern

Benachrichtigungs-Inhalt

Jede Benachrichtigung enthält:

=== CrowdSec Manager Report ===
Status: OK
Zeitpunkt: 2026-03-11 14:30:00
---
Domains aufgelöst: 5
IPs gesamt: 12
Hinzugefügt: 3
Entfernt: 1
Unverändert: 8
Fehler: 0

Bei Fehlern werden zusätzliche Details angehängt:

Details:
  WARN: Keine Auflösung für broken-domain.com
  ERROR: Konnte 203.0.113.50 nicht hinzufügen: ...

---

Desktop-Benachrichtigung (notify-send)

Verwendet notify-send für Desktop-Notifications auf Linux.

NOTIFY_DESKTOP_ENABLED=true

Voraussetzungen:

• notify-send muss installiert sein (Teil von libnotify-bin auf Debian/Ubuntu)
• Desktop-Session muss aktiv sein

Verhalten:

• Bei Fehlern: Urgency wird auf critical gesetzt
• Ansonsten: normal

---

Ntfy

Ntfy ist ein Open-Source Benachrichtigungsdienst. Du kannst die öffentliche Instanz oder eine eigene nutzen.

Konfiguration

NOTIFY_NTFY_ENABLED=true
NOTIFY_NTFY_URL="https://ntfy.sh"           # oder eigene Instanz
NOTIFY_NTFY_TOPIC="mein-crowdsec"            # Dein Topic
NOTIFY_NTFY_PRIORITY="default"               # low, default, high, urgent
NOTIFY_NTFY_TOKEN="tk_xxxxxxxx"              # Access Token (optional)
NOTIFY_NTFY_TAGS="shield,white_check_mark"   # Emoji-Tags

Prioritäten

• Bei Fehlern wird automatisch high verwendet
• Ansonsten der konfigurierte Wert

Tags

• Bei Fehlern werden automatisch warning,shield verwendet
• Ansonsten der konfigurierte Wert

Voraussetzungen

• curl muss installiert sein
• Ntfy-Server muss erreichbar sein

Ntfy-App

Du kannst die Ntfy-App auf Android/iOS installieren und das Topic abonnieren, um Push-Benachrichtigungen zu erhalten.

---

Gotify

Gotify ist ein Self-Hosted Push-Benachrichtigungsdienst.

Konfiguration

NOTIFY_GOTIFY_ENABLED=true
NOTIFY_GOTIFY_URL="https://gotify.meinedomain.de"   # Gotify-Server URL
NOTIFY_GOTIFY_TOKEN="AbCdEf12345"                    # App-Token
NOTIFY_GOTIFY_PRIORITY=5                             # Priorität (0-10)

Einrichtung in Gotify

1. Melde dich in deinem Gotify-Webinterface an
2. Erstelle eine neue Application (z.B. "CrowdSec Manager")
3. Kopiere den generierten Token
4. Trage URL und Token in die Config ein

Prioritäten

Bereich	Bedeutung
0	Minimale Priorität
1-3	Niedrig
4-7	Normal
8-10	Hoch

• Konfigurierte Priorität wird als Standard verwendet
• Bei Fehlern wird automatisch Priorität 8 (hoch) gesetzt

Voraussetzungen

• curl muss installiert sein
• Gotify-Server muss erreichbar sein
• Für JSON-Escaping wird python3 bevorzugt (Fallback: sed)

---

E-Mail

E-Mails werden bevorzugt über SMTP mit curl gesendet. Fallback ist der mail-Befehl.

Konfiguration

NOTIFY_EMAIL_ENABLED=true
NOTIFY_EMAIL_TO="admin@example.com"
NOTIFY_EMAIL_FROM="crowdsec@meinserver.de"
NOTIFY_EMAIL_SUBJECT="CrowdSec Manager Report"
NOTIFY_EMAIL_SMTP_SERVER="smtp.example.com"
NOTIFY_EMAIL_SMTP_PORT="587"          # 587 für STARTTLS, 465 für SSL
NOTIFY_EMAIL_SMTP_USER="mailuser"
NOTIFY_EMAIL_SMTP_PASS="mailpass"
NOTIFY_EMAIL_SMTP_TLS=true

SMTP-Ports

Port	Protokoll	SMTP_TLS
587	STARTTLS	true (verwendet smtps://)
465	Implicit TLS/SSL	true
25	Unverschlüsselt	false

Fallback

Wenn curl nicht verfügbar ist, wird versucht den mail-Befehl zu verwenden. Dieser muss auf dem System konfiguriert sein (z.B. mit Postfix/Sendmail).

Voraussetzungen

• curl (bevorzugt) oder mail
• SMTP-Server muss erreichbar sein

---

Sicherheitshinweise

• Tokens und Passwörter werden in der Konfigurationsdatei gespeichert. Stelle sicher, dass die Datei nur von berechtigten Benutzern lesbar ist:

  chmod 600 config/crowdsec-manager.conf
  

• Keine sensiblen Daten (Passwörter, Tokens) werden in der Log-Ausgabe angezeigt
• Verwende eigene/selbst gehostete Instanzen (Ntfy, Gotify) für erhöhte Sicherheit