CrowdSec arbeitet zuverlässig und stabil. Treten dennoch Probleme auf, liegt die Ursache häufig nicht bei CrowdSec selbst, sondern bei fehlerhaften Logquellen, Berechtigungen oder einer unvollständigen Konfiguration.
Mit einer strukturierten Vorgehensweise lassen sich die meisten Fehler innerhalb weniger Minuten finden.
In diesem Artikel betrachten wir die häufigsten Probleme aus der Praxis.
Systematisch vorgehen
Bei jeder Fehlersuche empfiehlt sich dieselbe Reihenfolge.
Dienst läuft? ↓ Logs werden gelesen? ↓ Parser arbeitet? ↓ Szenario ausgelöst? ↓ Decision erzeugt? ↓ Bouncer blockiert?
Erst wenn jeder Schritt funktioniert, kann CrowdSec korrekt arbeiten.
Läuft CrowdSec überhaupt?
Prüfen Sie zunächst den Dienst.
sudo systemctl status crowdsec
Falls Docker verwendet wird:
docker compose ps
Der Dienst sollte den Status active (running) besitzen.
Version prüfen
sudo cscli version
oder
docker compose exec crowdsec cscli version
Veraltete Installationen sollten zunächst aktualisiert werden.
Problem: Logs werden nicht erkannt
Dies ist einer der häufigsten Fehler.
Prüfen Sie zunächst:
sudo cscli metrics
Wichtige Informationen:
- gelesene Logzeilen
- aktive Parser
- verarbeitete Ereignisse
Stehen überall Nullen, werden keine Logs verarbeitet.
Acquisition-Dateien prüfen
Kontrollieren Sie:
ls /etc/crowdsec/acquis.d/
oder
cat /etc/crowdsec/acquis.yaml
Achten Sie besonders auf:
- richtige Dateipfade
- korrekte Labels
- YAML-Formatierung
Existiert die Logdatei?
ls -l /var/log/nginx/
oder
ls -l /var/log/apache2/
Fehlt die Datei, kann CrowdSec sie selbstverständlich nicht lesen.
Werden überhaupt Logeinträge geschrieben?
Prüfen Sie:
tail -f /var/log/nginx/access.log
oder
tail -f /var/log/apache2/access.log
Bleibt die Ausgabe leer, liegt das Problem nicht bei CrowdSec.
Parserfehler
Werden Logzeilen gelesen, aber keine Events erzeugt, liegt die Ursache häufig beim Parser.
Hilfreich ist:
sudo cscli explain --file test.log
Die Ausgabe zeigt:
- erkannte Parser
- übersprungene Parser
- extrahierte Felder
- erkannte Szenarien
Eigene Parser überprüfen
Kontrollieren Sie:
- YAML-Einrückungen
- Regex
- Grok-Muster
- Filter
- Feldnamen
Bereits kleine Tippfehler verhindern die Verarbeitung.
Parserliste anzeigen
sudo cscli parsers list
Dort erkennen Sie:
- installierte Parser
- eigene Parser
- Versionen
Szenarien werden nicht ausgelöst
Prüfen Sie:
sudo cscli scenarios list
Anschließend:
sudo cscli alerts list
Keine Alerts bedeuten:
- Parser liefert keine Daten
- Filter passt nicht
- Angriff erfüllt die Bedingungen nicht
Keine Decisions vorhanden
sudo cscli decisions list
Sind keine Decisions vorhanden, wurde entweder kein Angriff erkannt oder das Szenario erzeugt keine Sperre.
Bouncer funktioniert nicht
Ein häufiger Fehler.
Prüfen Sie zunächst:
sudo cscli bouncers list
Kontrollieren Sie:
- letzter Kontakt
- API-Key
- Status
API-Schlüssel prüfen
Wurde der richtige Schlüssel verwendet?
Gegebenenfalls einen neuen erzeugen:
sudo cscli bouncers add nginx
Danach den Schlüssel im Bouncer aktualisieren.
Local API prüfen
sudo cscli machines list
Die Local API sollte erreichbar sein.
API-Probleme
Typische Ursachen:
- falscher Port
- Firewall blockiert
- Docker-Netzwerk
- DNS
- Reverse Proxy
Standardmäßig verwendet die Local API Port 8080.
Erreichbarkeit testen
curl http://127.0.0.1:8080
Je nach Konfiguration sollte eine Antwort erfolgen.
Docker-Probleme
Innerhalb des Containers:
docker compose exec crowdsec cscli metrics
Zusätzlich:
docker compose logs crowdsec
Fehlende Volumes gehören zu den häufigsten Ursachen.
Berechtigungen
Kann CrowdSec Logdateien lesen?
Prüfen Sie:
ls -l /var/log/
Gegebenenfalls:
sudo usermod -aG adm crowdsec
Danach:
sudo systemctl restart crowdsec
AppArmor
In manchen Fällen verhindert AppArmor den Zugriff.
Prüfen Sie:
sudo aa-status
Die meisten Standardinstallationen funktionieren jedoch problemlos.
Firewall-Probleme
Wird zwar eine Decision erzeugt, erfolgt aber keine Sperre, liegt die Ursache häufig beim Bouncer oder der Firewall.
Prüfen Sie:
sudo cscli decisions list
Anschließend:
sudo nft list ruleset
oder
sudo iptables -L
Je nach verwendetem Firewall-Bouncer sollten entsprechende Regeln vorhanden sein.
Reverse Proxy
Ein häufiger Fehler:
CrowdSec erkennt nur interne Docker-IP-Adressen.
Prüfen Sie:
- X-Forwarded-For
- X-Real-IP
- Trusted Proxy
- Real-IP-Konfiguration
Andernfalls wird möglicherweise der Reverse Proxy selbst gesperrt.
Maschinenstatus prüfen
sudo cscli machines list
Kontrollieren Sie:
- Name
- Version
- letzter Kontakt
Dashboard funktioniert nicht
Prüfen Sie:
- Container läuft
- Port erreichbar
- HTTPS
- Reverse Proxy
- Login
Bei Docker:
docker compose logs dashboard
Performanceprobleme
Hilfreiche Werkzeuge:
top htop sudo cscli metrics
Sehr große Logdateien oder fehlerhafte Parser verursachen häufig unnötige Last.
Debugging
Die wichtigste Informationsquelle bleibt das Journal.
sudo journalctl -u crowdsec -f
Dort erscheinen:
- Parserfehler
- YAML-Fehler
- Datenbankfehler
- API-Probleme
- Ladefehler
Konfiguration testen
Vor Änderungen empfiehlt sich:
crowdsec -t
Syntaxfehler werden sofort angezeigt.
Hub aktualisieren
sudo cscli hub update
Anschließend:
sudo cscli hub upgrade
Veraltete Parser verursachen gelegentlich Probleme.
Häufige Docker-Fehler
- Log-Volumes fehlen
- Docker-Socket nicht eingebunden
- falsche Acquisition-Datei
- Containername falsch
- internes Netzwerk fehlt
- Local API nicht erreichbar
Typische YAML-Fehler
Die häufigsten Ursachen:
- Tabs verwendet
- falsche Einrückungen
- Doppelpunkte vergessen
- ungültige Listen
- Tippfehler
Ein YAML-Validator hilft häufig weiter.
Checkliste
Vor einer umfangreichen Fehlersuche sollte folgende Liste abgearbeitet werden:
- läuft CrowdSec?
- existieren Logdateien?
- werden Logs gelesen?
- funktionieren Parser?
- werden Alerts erzeugt?
- entstehen Decisions?
- arbeitet der Bouncer?
- funktioniert die Firewall?
- stimmt die Reverse-Proxy-Konfiguration?
- sind API und Dashboard erreichbar?
Mit dieser Reihenfolge lassen sich die meisten Probleme schnell eingrenzen.
Best Practices
Für eine stabile CrowdSec-Installation haben sich folgende Maßnahmen bewährt:
- CrowdSec regelmäßig aktualisieren
- Hub-Komponenten aktuell halten
- Logrotation aktivieren
- Parser testen
- Konfiguration dokumentieren
- Änderungen zunächst in einer Testumgebung prüfen
- Dashboard absichern
- Metriken regelmäßig kontrollieren
- Logquellen überwachen
- Debugging-Werkzeuge kennen und nutzen
Die meisten Probleme mit CrowdSec lassen sich auf wenige Ursachen zurückführen: fehlende oder falsch eingebundene Logdateien, Parserfehler, Berechtigungsprobleme oder eine unvollständige Bouncer-Konfiguration. Mit einem systematischen Vorgehen – vom Dienststatus über die Logaufnahme bis hin zu Alerts, Decisions und Bouncer – lassen sich Fehler schnell eingrenzen und beheben. Werkzeuge wie cscli metrics, cscli explain, journalctl und crowdsec -t gehören dabei zur Grundausstattung jedes Administrators und ermöglichen eine zielgerichtete Analyse selbst komplexer Installationen.
