crowdsec-manager/README.md

CrowdSec Manager

Automatische Verwaltung einer CrowdSec-Allowlist und interaktive CrowdSec-Administration über ein Menü.

Übersicht

Der CrowdSec Manager ist ein Bash-Script, das:

• Domains und Subdomains automatisch zu IPv4/IPv6-Adressen auflöst
• Die aufgelösten IPs in eine CrowdSec-Allowlist einträgt
• Veraltete Einträge automatisch entfernt wenn sich IPs ändern
• Per Cron regelmäßig ausgeführt werden kann (automatischer Sync)
• Ein interaktives Menü für die CrowdSec-Administration bereitstellt
• Benachrichtigungen über Änderungen senden kann (Desktop, Ntfy, Gotify, E-Mail)

Features

• Interaktives Menü als Standard-Modus (für manuelle Verwaltung)
• CrowdSec Admin-Funktionen: Decisions, Alerts, Bouncers, Machines, Metriken, IP-Info
• Gotify als zusätzlicher Benachrichtigungskanal
• --sync-allowlist-Flag für automatischen Cron-Betrieb
• Eigene cscli-Befehle direkt aus dem Menü ausführen

Features

Feature	Beschreibung
Interaktives Menü	Grafische Administration von CrowdSec via Menü
DNS-Auflösung	Automatische Auflösung von Domains zu IPv4 und IPv6
CIDR-Support	Ganze Subnetze können allowgelistet werden
Auto-Cleanup	Entfernt IPs die nicht mehr zu konfigurierten Domains gehören
Decisions verwalten	Anzeigen, Suchen, Hinzufügen, Entfernen von Decisions
Alerts verwalten	Anzeigen, Inspizieren, Löschen von Alerts
IP-Info	Komplett-Check einer IP (rDNS, Decisions, Alerts, Details)
Flexible CrowdSec-Anbindung	Unterstützt direkte Installation, Docker, Podman, etc.
Benachrichtigungen	Desktop, Ntfy, Gotify, E-Mail
Logging	Konfigurierbares Log-Level mit Log-Rotation
Dry-Run	Testmodus ohne tatsächliche Änderungen
Lock-File	Verhindert parallele Ausführung
Backup	Sichert den Zustand vor Änderungen
Cron-fähig	Optimiert für automatische Ausführung mit --sync-allowlist

Schnellstart

1. Repository klonen

git clone https://git.techniverse.net/scriptos/crowdsec-manager.git
cd crowdsec-manager
chmod +x crowdsec-manager.sh

2. Abhängigkeiten installieren

# Debian / Ubuntu
sudo apt install -y dnsutils curl

# RHEL / CentOS / Fedora
sudo dnf install -y bind-utils curl

3. Konfiguration anpassen

nano config/crowdsec-manager.conf

Mindestens anpassen:

• CSCLI_CMD – Der Befehl um CrowdSec CLI aufzurufen
• ALLOWLIST_ENTRIES – Die Domains/IPs für die Allowlist

4. Testen & Verwenden

# Konfiguration prüfen
./crowdsec-manager.sh --test

# Interaktives Menü starten (Standard)
./crowdsec-manager.sh

# Allowlist-Sync (für Cron)
./crowdsec-manager.sh --sync-allowlist

# Testlauf ohne Änderungen
./crowdsec-manager.sh --sync-allowlist --dry-run

5. Cron einrichten

crontab -e

*/30 * * * * /opt/crowdsec-manager/crowdsec-manager.sh --sync-allowlist >> /var/log/crowdsec-manager-cron.log 2>&1

Wichtig: --sync-allowlist muss angegeben werden, da ohne Parameter das interaktive Menü startet.

Interaktives Menü

╔═══════════════════════════════════════════════════════╗
║                CrowdSec Manager v0.1.0                ║
╚═══════════════════════════════════════════════════════╝

── ALLOWLIST MANAGEMENT ──
  1) Allowlist synchronisieren       2) Dry-Run
  3) Allowlist anzeigen              4) Config testen
  5) Flush (alle Einträge entfernen)

── DECISIONS ──
 10) Alle anzeigen    11) Suchen    12) Hinzufügen    13) Entfernen

── ALERTS ──
 20) Alle anzeigen    21) Inspizieren    22) Löschen

── INFORMATIONEN ──
 30) IP-Info (Komplett)   31) Metriken      32) Status
 33) Bouncers             34) Machines      35) Parsers
 36) Scenarios            37) Collections

── ERWEITERT ──
 40) Eigener cscli-Befehl    0) Beenden

Konfiguration

Die gesamte Konfiguration erfolgt über: config/crowdsec-manager.conf

CrowdSec Basisbefehl

# Direkt installiert
CSCLI_CMD="cscli"

# Docker
CSCLI_CMD="docker exec crowdsec cscli"

# Docker Compose
CSCLI_CMD="docker compose exec crowdsec cscli"

Domains & IPs

ALLOWLIST_ENTRIES=(
    "example.com"           # Domain (wird aufgelöst)
    "cdn.example.com"
    "203.0.113.50"          # Einzelne IP
    "10.0.0.0/8"            # CIDR-Bereich
    "2001:db8::1"           # IPv6
)

Benachrichtigungen

NOTIFY_ENABLED=true
NOTIFY_ON="changes"          # always | changes | errors

# Ntfy
NOTIFY_NTFY_ENABLED=true
NOTIFY_NTFY_URL="https://ntfy.sh"
NOTIFY_NTFY_TOPIC="mein-crowdsec"

# Gotify
NOTIFY_GOTIFY_ENABLED=true
NOTIFY_GOTIFY_URL="https://gotify.meinedomain.de"
NOTIFY_GOTIFY_TOKEN="AbCdEf12345"
NOTIFY_GOTIFY_PRIORITY=5

# E-Mail
NOTIFY_EMAIL_ENABLED=true
NOTIFY_EMAIL_TO="admin@example.com"
NOTIFY_EMAIL_SMTP_SERVER="smtp.example.com"

Verwendung (CLI)

Verwendung:
  crowdsec-manager.sh [OPTIONEN]

Modi:
  (ohne Optionen)          Startet das interaktive Menü
  --sync-allowlist         Allowlist synchronisieren (für Cron)

Optionen:
  -c, --config FILE        Konfigurationsdatei angeben
  -d, --dry-run            Testlauf ohne Änderungen
  -v, --verbose            Ausführliche Ausgabe (DEBUG)
  -q, --quiet              Minimale Ausgabe (nur ERROR)
  -l, --list               Aktuelle Allowlist anzeigen
  -f, --flush              Alle verwalteten Einträge entfernen
  -t, --test               Konfiguration testen
  -i, --interactive        Interaktives Menü starten
      --sync-allowlist     Allowlist-Sync ausführen (nicht-interaktiv)
  -h, --help               Hilfe anzeigen
  -V, --version            Version anzeigen

Ablaufdiagramm (Allowlist-Sync)

┌─────────────────────────┐
│  Script: --sync-allowlist│
└────────────┬────────────┘
             │
     ┌───────▼────────┐
     │  Config laden   │
     │  Lock erwerben  │
     │  Health-Check   │
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │ Aktuelle Liste  │
     │ abrufen         │
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │ DNS-Auflösung   │
     │ aller Einträge  │
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │ Vergleich &     │
     │ Synchronisation │
     │ (nur bei Änd.)  │
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │ Backup, Report  │
     │ & Notifications │
     │ (nur bei Änd.)  │
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │ Lock lösen      │
     │ Aufräumen       │
     └─────────────────┘

Abhängigkeiten

Paket	Erforderlich	Zweck
bash (≥ 4.0)	✅	Script-Ausführung
dig (dnsutils / bind-utils)	✅	DNS-Auflösung
curl	⚡	Ntfy-, Gotify- und E-Mail-Benachrichtigungen
python3	⚡	JSON-Escaping für Gotify (Fallback: sed)
notify-send	⚡	Desktop-Benachrichtigungen
mail	⚡	E-Mail-Fallback

✅ = Erforderlich | ⚡ = Optional (je nach Konfiguration)

Dateien & Struktur

crowdsec-manager/
├── crowdsec-manager.sh   # Hauptscript
├── config/
│   └── crowdsec-manager.conf        # Konfigurationsdatei
├── examples/
│   └── crontab.example                # Crontab-Beispiele
├── docs/
│   ├── DOCUMENTATION.md               # Dokumentationsindex
│   ├── CONFIGURATION.md               # Konfigurationsreferenz
│   ├── ALLOWLIST.md                   # Allowlist-Verwaltung & Cron
│   ├── ADMIN.md                       # Interaktives Menü & Admin
│   ├── NOTIFICATIONS.md               # Benachrichtigungssystem
│   └── TROUBLESHOOTING.md             # Fehlerbehebung & FAQ
├── README.md                          # Diese Datei
├── LICENSE                            # MIT Lizenz
└── .gitignore

Dokumentation

Die detaillierte Dokumentation ist aufgeteilt in:

Dokument	Beschreibung
docs/CONFIGURATION.md	Alle Konfigurationsoptionen
docs/ALLOWLIST.md	Allowlist-Verwaltung, CLI, Cron
docs/ADMIN.md	Interaktives Menü & Administration
docs/NOTIFICATIONS.md	Ntfy, Gotify, E-Mail, Desktop
docs/TROUBLESHOOTING.md	Fehlerbehebung & FAQ

Lizenz

MIT License – siehe LICENSE Datei.

Beitragen

Pull Requests und Issues sind willkommen! Bitte stelle sicher, dass deine Änderungen die bestehende Funktionalität nicht brechen.