Die Stärke von CrowdSec liegt nicht nur in der großen Community und den zahlreichen bereits vorhandenen Collections. Das System ist von Grund auf modular aufgebaut und kann nahezu beliebig erweitert werden.

Ob selbst entwickelte Webanwendungen, proprietäre Dienste oder spezielle Logformate – mit eigenen Parsern und Szenarien lassen sich nahezu beliebige Sicherheitsereignisse erkennen und automatisch verarbeiten.

Dieser Artikel richtet sich an fortgeschrittene Administratoren, die CrowdSec individuell erweitern möchten.

Wie verarbeitet CrowdSec Logdateien?

Bevor ein Angriff erkannt werden kann, durchlaufen Logeinträge mehrere Verarbeitungsschritte.

Der Datenfluss sieht vereinfacht folgendermaßen aus:

Logdatei
    │
    ▼
Acquisition
    │
    ▼
Parser
    │
    ▼
Enrichment
    │
    ▼
Szenario
    │
    ▼
Alert
    │
    ▼
Decision
    │
    ▼
Bouncer

Jede Stufe erfüllt eine klar definierte Aufgabe.

Parser und Szenarien – der Unterschied

Obwohl beide Komponenten zusammenarbeiten, erfüllen sie unterschiedliche Aufgaben.

Parser

Parser lesen Rohdaten aus Logdateien und strukturieren diese.

Beispiele:

• IP-Adresse extrahieren
• Zeitstempel erkennen
• Benutzername auslesen
• HTTP-Statuscode übernehmen
• User-Agent speichern
• URL ermitteln

Szenarien

Szenarien analysieren die von den Parsern gelieferten Informationen.

Beispiele:

• mehr als zehn Loginversuche
• mehrere 404-Fehler
• SQL-Injection-Muster
• Portscanner erkennen
• ungewöhnlich viele API-Aufrufe

Parser sammeln Daten – Szenarien bewerten sie.

Aufbau eines Parsers

Parser werden als YAML-Dateien definiert.

Ein einfaches Grundgerüst sieht beispielsweise so aus:

name: custom-app-parser
description: Parser für eine eigene Anwendung

filter: "evt.Parsed.program == 'customapp'"

onsuccess: next_stage

pattern_syntax:
  IP: '(?P<source_ip>\d+\.\d+\.\d+\.\d+)'

nodes:
  - grok:
      pattern: "%{IP}"

Der Parser beschreibt, welche Logeinträge verarbeitet werden und welche Informationen daraus extrahiert werden sollen.

YAML verstehen

CrowdSec verwendet YAML für nahezu sämtliche Konfigurationen.

Die Syntax wirkt zunächst ungewohnt, ist jedoch übersichtlich aufgebaut.

Beispiel:

name: my-parser

description: Eigener Parser

filter: "evt.Line.Labels.type == 'custom'"

Wichtige Eigenschaften:

• Einrückungen erfolgen ausschließlich mit Leerzeichen.
• Tabs sollten vermieden werden.
• Schlüssel und Werte werden durch Doppelpunkte getrennt.
• Listen beginnen mit einem Bindestrich.

Schon kleine Einrückungsfehler können dazu führen, dass Parser nicht geladen werden.

Reguläre Ausdrücke (Regex)

Viele Parser verwenden reguläre Ausdrücke oder Grok-Muster.

Beispielsweise:

2026-07-20 10:30:15 Login failed from 203.0.113.25

Ein passender Ausdruck könnte lauten:

(?P<ip>\d+\.\d+\.\d+\.\d+)

Dadurch wird die IP-Adresse aus dem Logeintrag extrahiert und für die weitere Verarbeitung verfügbar gemacht.

Grok-Muster verwenden

Statt komplexe reguläre Ausdrücke selbst zu schreiben, können Grok-Muster verwendet werden.

Beispiel:

nodes:
  - grok:
      pattern: "%{IP:source_ip}"

Dadurch bleibt die Konfiguration wesentlich übersichtlicher.

Parser speichern

Eigene Parser werden üblicherweise im Verzeichnis

/etc/crowdsec/parsers/

abgelegt.

Zur besseren Übersicht empfiehlt sich ein eigenes Unterverzeichnis.

Beispielsweise:

/etc/crowdsec/parsers/s02-enrich/

oder

/etc/crowdsec/parsers/custom/

Dadurch bleiben eigene Erweiterungen auch nach Updates leichter wartbar.

Parser testen

Nach dem Erstellen sollte jeder Parser ausführlich getestet werden.

CrowdSec bietet hierfür den Befehl:

sudo cscli explain --file test.log

Die Ausgabe zeigt unter anderem:

• erkannte Parser
• extrahierte Felder
• erfolgreiche Verarbeitung
• übersprungene Parser

Dadurch lassen sich Fehler schnell finden.

Eigene Szenarien entwickeln

Szenarien entscheiden, wann CrowdSec einen Angriff erkennt.

Ein einfaches Beispiel:

type: leaky

name: custom-bruteforce

description: Mehrfache Loginfehler

filter: "evt.Meta.service == 'customapp'"

capacity: 5

leakspeed: 1m

blackhole: 5m

Dieses Szenario erkennt fünf Ereignisse innerhalb einer Minute.

Wichtige Parameter

Typische Einstellungen eines Szenarios:

capacity

Wie viele Ereignisse zulässig sind.

leakspeed

Zeitraum, in dem die Ereignisse auftreten dürfen.

blackhole

Verhindert wiederholte Auslösungen unmittelbar hintereinander.

filter

Legt fest, welche Ereignisse berücksichtigt werden.

Szenarien speichern

Eigene Szenarien befinden sich normalerweise unter:

/etc/crowdsec/scenarios/

Auch hier empfiehlt sich eine saubere Trennung zwischen Standard- und eigenen Dateien.

Szenarien testen

Nach Änderungen kann überprüft werden, ob das Szenario korrekt geladen wurde.

sudo cscli scenarios list

Eigene Szenarien erscheinen anschließend in der Übersicht.

Debugging

Nicht jeder Parser funktioniert sofort.

Typische Hilfsmittel:

sudo journalctl -u crowdsec -f

oder

sudo cscli explain --file test.log

Besonders hilfreich sind:

• Parser wurde geladen?
• Filter greift?
• Felder korrekt erkannt?
• Szenario ausgelöst?
• Alert erstellt?

Testdaten verwenden

Eigene Parser sollten niemals ausschließlich mit Live-Daten entwickelt werden.

Empfehlenswert sind kleine Testdateien.

Beispiel:

2026-07-20 10:15:11 LOGIN FAILED user=admin ip=203.0.113.15

2026-07-20 10:15:14 LOGIN FAILED user=admin ip=203.0.113.15

2026-07-20 10:15:18 LOGIN FAILED user=admin ip=203.0.113.15

Mit solchen Testdateien lassen sich Änderungen reproduzierbar überprüfen.

Typische Fehler

Die häufigsten Probleme sind:

• falsche Einrückungen in YAML
• Tabs statt Leerzeichen
• fehlerhafte Regex
• falscher Filter
• Parser wird nie aufgerufen
• Szenario erkennt keine Ereignisse
• falscher Dateipfad
• Tippfehler in Feldnamen

Gerade YAML reagiert sehr empfindlich auf Formatierungsfehler.

Best Practices

Für eigene Parser und Szenarien haben sich folgende Empfehlungen bewährt:

• eigene Dateien niemals in Standardkonfigurationen ändern
• sprechende Namen vergeben
• Parser klein und übersichtlich halten
• Testdaten verwenden
• Änderungen dokumentieren
• Versionsverwaltung (z. B. Git) nutzen
• nach jedem Update Funktion prüfen
• bestehende Community-Parser als Vorlage verwenden

Einsatzmöglichkeiten

Eigene Parser eignen sich unter anderem für:

• selbst entwickelte Webanwendungen
• REST-APIs
• VPN-Lösungen
• Datenbankserver
• IoT-Geräte
• Mailserver
• Proxy-Server
• Industrieanwendungen
• proprietäre Software

Damit lässt sich CrowdSec weit über klassische Linux-Dienste hinaus einsetzen.

Mit eigenen Parsern und Szenarien lässt sich CrowdSec exakt an die Anforderungen einer individuellen IT-Umgebung anpassen. Parser strukturieren Logdaten und extrahieren relevante Informationen, während Szenarien diese Daten analysieren und bei verdächtigen Mustern automatisch Alerts und Decisions auslösen. Durch den modularen Aufbau, die Verwendung von YAML und umfangreiche Test- und Debugging-Werkzeuge können auch komplexe Anwendungen zuverlässig überwacht werden. Wer regelmäßig mit speziellen Diensten oder Eigenentwicklungen arbeitet, erweitert CrowdSec auf diese Weise zu einer leistungsfähigen, maßgeschneiderten Sicherheitsplattform.