crowdsec-manager/docs/ALLOWLIST.md

Allowlist Management

Dokumentation der automatischen Allowlist-Verwaltung im CrowdSec Manager v0.1.0.

---

Funktionsweise

Das Script arbeitet nach dem Desired-State-Prinzip: Du definierst WAS allowgelistet sein soll (Domains/IPs), und das Script sorgt dafür, dass der IST-Zustand in CrowdSec dem SOLL-Zustand entspricht.

Ablauf einer Synchronisation

1. Vorbereitung
   ├── Abhängigkeiten prüfen (dig, curl)
   ├── Lock-File erwerben
   ├── Temporäre Dateien erstellen
   └── CrowdSec Health-Check

2. Datenerfassung
   ├── Aktuelle CrowdSec-Allowlist abrufen → current_ips.txt
   ├── Backup der aktuellen Liste erstellen
   └── DNS-Auflösung aller Einträge → new_ips.txt

3. Synchronisation
   ├── Vergleich: current_ips.txt vs. new_ips.txt
   ├── Bei keinen Änderungen: Frühzeitiger Abbruch (kein Backup, keine Benachrichtigung)
   ├── Neue IPs hinzufügen (in new, nicht in current)
   ├── Veraltete IPs entfernen (in current, nicht in new)
   ├── Backup der vorherigen Liste erstellen
   └── Statistiken aktualisieren

4. Abschluss
   ├── Zusammenfassung ausgeben
   ├── Benachrichtigungen senden
   ├── Lock-File freigeben
   └── Temporäre Dateien aufräumen

---

Kommandozeilen-Optionen

Startmodi (v0.1.0)

Aufruf	Beschreibung
./script.sh	Startet das interaktive Menü (Standard)
./script.sh --sync-allowlist	Führt Allowlist-Sync aus (für Cron)
./script.sh --interactive	Startet das interaktive Menü (explizit)

Wichtig für Cron: Ab v0.2.0 muss --sync-allowlist angegeben werden, da ohne Parameter das interaktive Menü startet.

Alle Optionen

Option	Kurz	Beschreibung
--sync-allowlist		Allowlist-Sync ausführen (nicht-interaktiv, für Cron)
--interactive	-i	Interaktives Menü starten
--config FILE	-c	Eigene Konfigurationsdatei laden
--dry-run	-d	Simuliert alle Aktionen ohne CrowdSec zu ändern
--verbose	-v	Setzt Log-Level auf DEBUG
--quiet	-q	Setzt Log-Level auf ERROR
--list	-l	Zeigt aktuelle CrowdSec-Allowlist an
--flush	-f	Entfernt ALLE vom Script verwalteten Einträge
--test	-t	Testet Config, DNS und CrowdSec-Verbindung
--help	-h	Zeigt Hilfe an
--version	-V	Zeigt Version an

---

Dry-Run Modus

Im Dry-Run Modus werden alle Schritte normal durchgeführt (DNS-Auflösung, Vergleich), aber die CrowdSec-Befehle werden nicht ausgeführt:

./crowdsec-manager.sh --sync-allowlist --dry-run

Ausgabe:

[INFO] [DRY-RUN] Würde hinzufügen: 203.0.113.50
[INFO] [DRY-RUN] Würde entfernen: 198.51.100.20

Auch im interaktiven Menü (Punkt 2) kann ein Dry-Run gestartet werden.

---

Test-Modus

Prüft die gesamte Konfiguration ohne etwas zu ändern:

./crowdsec-manager.sh --test

Ausgabe:

Konfigurationstest:

[OK] Konfigurationsdatei geladen
CrowdSec-Erreichbarkeit... [OK]
DNS-Auflösung... [OK] dig gefunden

Konfigurierte Einträge (3):
  [Domain] example.com -> 93.184.216.34, 2606:2800:220:1:...
  [Domain] cdn.example.com -> 104.16.132.229
  [IP/CIDR] 192.168.1.0/24

Benachrichtigungen:
  Aktiviert:  true
  Desktop:    false
  Ntfy:       true
  Gotify:     false
  E-Mail:     false

---

Flush-Modus

Entfernt alle vom Script verwalteten Einträge aus CrowdSec (identifiziert über ALLOWLIST_REASON):

./crowdsec-manager.sh --flush

Achtung: Manuell mit cscli decisions add erstellte Einträge werden NICHT entfernt.

---

Cron-Integration

Empfohlene Intervalle

Anwendungsfall	Intervall	Cron-Ausdruck
Dynamische DNS (DynDNS)	15 Minuten	*/15 * * * *
Cloud-Dienste / CDN	30 Minuten	*/30 * * * *
Statische Infrastruktur	Stündlich	0 * * * *
Feste IPs	Täglich	0 3 * * *

Einrichtung

crontab -e

Empfohlener Eintrag:

# CrowdSec Manager - alle 30 Minuten
*/30 * * * * /opt/crowdsec-manager/crowdsec-manager.sh --sync-allowlist >> /var/log/crowdsec-manager-cron.log 2>&1

Cron-spezifisches Verhalten

Das Script erkennt automatisch ob es im Terminal oder per Cron läuft:

• Terminal: Farbige Ausgabe
• Cron: Plain-Text Ausgabe (keine Escape-Codes)

---

Exit-Codes

Exit-Code	Bedeutung
0	Erfolgreich
1	Kritischer Fehler (Config fehlt, CrowdSec nicht erreichbar)
2	Teilweise erfolgreich (mit nicht-kritischen Fehlern)

---

Mehrere Konfigurationen

Du kannst mehrere Konfigurationsdateien für verschiedene Allowlists verwenden:

# Webserver-Allowlist
./crowdsec-manager.sh --sync-allowlist --config config/webserver.conf

# Monitoring-Allowlist
./crowdsec-manager.sh --sync-allowlist --config config/monitoring.conf

Jede Konfiguration sollte einen eigenen ALLOWLIST_REASON verwenden:

# webserver.conf
ALLOWLIST_REASON="allowlist-webserver"

# monitoring.conf
ALLOWLIST_REASON="allowlist-monitoring"