TL;DR — Résumé Rapide

Guide complet CrowdSec : installation, bouncers, scénarios personnalisés, listes communautaires et protection Nginx+SSH sur vos serveurs Linux.

Chaque serveur connecté à Internet est constamment attaqué : scanners SSH, crawlers de vulnérabilités web, bots de credential-stuffing et abuseurs d’API génèrent des millions de requêtes malveillantes chaque heure. CrowdSec est un système de prévention des intrusions moderne et open-source qui va au-delà de la simple surveillance de logs sur un seul serveur : il analyse vos journaux localement, détecte les patterns d’attaque grâce à des scénarios comportementaux et partage anonymement les IPs d’attaquants avec une communauté mondiale pour construire des listes de blocage collaboratives. Ce guide couvre la configuration complète de CrowdSec : architecture, installation sur Debian/Ubuntu et RHEL/Rocky, collections, bouncers, scénarios personnalisés, listes blanches, déploiement multi-serveurs et un parcours complet de durcissement en production protégeant Nginx et SSH.

Prérequis

Avant de commencer, assurez-vous de disposer de :

  • Un serveur Linux sous Ubuntu 20.04/22.04/24.04, Debian 11/12 ou RHEL/Rocky/AlmaLinux 8/9
  • Un accès root ou sudo
  • systemd comme système d’init
  • iptables, nftables ou firewalld disponibles pour le bouncer pare-feu
  • Une familiarité de base avec les fichiers de configuration YAML

Fonctionnement de CrowdSec

CrowdSec sépare la détection des menaces de leur application en trois couches :

1. Agent (détection) L’agent CrowdSec lit les logs depuis des fichiers, journald, Docker, Kafka ou syslog. Les logs traversent un pipeline de parsing en plusieurs étapes : S00-raw normalise le texte brut, S01-parse extrait les champs structurés (IP, timestamp, méthode HTTP, chemin) et S02-enrich ajoute les données GeoIP et CTI. Les événements analysés alimentent des scénarios — des machines à états YAML qui implémentent une logique leaky-bucket, trigger ou compteur pour identifier les patterns d’attaque.

2. API Locale (coordination) L’API Locale (LAPI) reçoit les décisions de l’agent, les stocke dans SQLite ou PostgreSQL et les distribue aux bouncers. Dans une configuration multi-machines, un serveur exécute la LAPI tandis que tous les autres agents et bouncers s’y connectent en HTTPS.

3. API Centrale (intelligence communautaire) Lors de l’inscription de votre instance, l’API Centrale sur api.crowdsec.net envoie des listes de blocage communautaires à votre LAPI et reçoit de votre part des rapports anonymisés d’IPs. Cela transforme chaque déploiement CrowdSec en capteur alimentant le réseau mondial de threat intelligence.

4. Bouncers (application) Les bouncers interrogent la LAPI pour obtenir les décisions actives et les appliquent : le bouncer pare-feu ajoute des règles iptables/nftables, le bouncer Nginx émet des réponses HTTP 403 ou des challenges CAPTCHA, et le bouncer Cloudflare crée des règles de pare-feu en bordure via l’API Cloudflare.

Installation

Ubuntu / Debian

curl -s https://install.crowdsec.net | sudo bash
sudo apt install crowdsec -y
sudo systemctl enable --now crowdsec
sudo systemctl status crowdsec

RHEL / Rocky / AlmaLinux

curl -s https://install.crowdsec.net | sudo bash
sudo dnf install crowdsec -y
sudo systemctl enable --now crowdsec

Docker

services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    restart: unless-stopped
    environment:
      COLLECTIONS: "crowdsecurity/linux crowdsecurity/nginx crowdsecurity/sshd"
    volumes:
      - /var/log:/var/log:ro
      - crowdsec_data:/var/lib/crowdsec/data
      - crowdsec_config:/etc/crowdsec
    ports:
      - "8080:8080"

volumes:
  crowdsec_data:
  crowdsec_config:

Kubernetes (Helm)

helm repo add crowdsec https://crowdsecurity.github.io/helm-charts
helm repo update
helm install crowdsec crowdsec/crowdsec \
  --set agent.acquisition[0].namespace=default \
  --set agent.acquisition[0].podName="*" \
  --set agent.acquisition[0].program=nginx

Installation des Collections

Les collections regroupent parsers et scénarios pour un service spécifique. Installez-les avec cscli :

# Collection Linux de base (auth, syslog)
sudo cscli collections install crowdsecurity/linux

# Détection de brute-force SSH
sudo cscli collections install crowdsecurity/sshd

# Détection d'attaques Nginx
sudo cscli collections install crowdsecurity/nginx

# Apache
sudo cscli collections install crowdsecurity/apache2

# WordPress
sudo cscli collections install crowdsecurity/wordpress

# Recharger après installation de nouvelles collections
sudo systemctl reload crowdsec

Listez le contenu installé du hub :

sudo cscli hub list
sudo cscli collections list
sudo cscli scenarios list
sudo cscli parsers list

Acquisition des Logs

CrowdSec découvre les sources de logs via /etc/crowdsec/acquis.yaml. Plusieurs méthodes sont supportées :

Source fichier

filenames:
  - /var/log/nginx/access.log
  - /var/log/nginx/error.log
labels:
  type: nginx
# --- (next source)
filenames:
  - /var/log/auth.log
labels:
  type: syslog

journald / systemd

source: journalctl
journalctl_filter:
  - "_SYSTEMD_UNIT=sshd.service"
labels:
  type: syslog

Conteneurs Docker

source: docker
container_name:
  - nginx
  - myapp
labels:
  type: nginx

Après modification de acquis.yaml, redémarrez l’agent :

sudo systemctl restart crowdsec

Scénarios et Parsers

Types de scénario

TypeDescriptionCas d’usage
leakybucketCompte les événements dans une fenêtre glissante ; le débordement déclenche une décisionBrute-force (N échecs en T secondes)
triggerUn seul événement déclenche immédiatementÉvénements critiques uniques
counterCompte les valeurs distinctes (ex. : URLs scannées)Scanners, énumérateurs

Exemple de scénario personnalisé

Créez /etc/crowdsec/scenarios/myapp-bruteforce.yaml :

type: leakybucket
name: myapp/bruteforce
description: "Détecter le brute-force sur l'endpoint de login de myapp"
filter: "evt.Meta.service == 'myapp' && evt.Meta.log_type == 'auth_failed'"
groupby: "evt.Meta.source_ip"
distinct: "evt.Meta.username"
capacity: 5
leakspeed: "10s"
blackhole: "5m"
labels:
  service: myapp
  type: bruteforce
  remediation: true

Champs clés :

ChampSignification
capacityRemplissage maximum du seau avant débordement
leakspeedVitesse de vidange du seau
blackholeDélai minimum entre débordements répétés pour le même IP
groupbyCritère de regroupement des événements (généralement l’IP source)
distinctCompte les valeurs distinctes pour éviter l’évasion multi-utilisateurs
remediation: trueLe débordement génère une décision de blocage

Installation et Configuration des Bouncers

Bouncer pare-feu (iptables/nftables)

# Backend iptables
sudo apt install crowdsec-firewall-bouncer-iptables -y

# Backend nftables
sudo apt install crowdsec-firewall-bouncer-nftables -y

sudo systemctl enable --now crowdsec-firewall-bouncer

Vérifiez l’enregistrement :

sudo cscli bouncers list

Bouncer Nginx

sudo apt install crowdsec-nginx-bouncer -y

Configuration dans /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf :

API_KEY=<auto-généré>
API_URL=http://localhost:8080
MODE=ban          # ban | captcha | throttle
CAPTCHA_SITE_KEY=<clé-recaptcha-v2>
CAPTCHA_SECRET_KEY=<secret-recaptcha-v2>
CAPTCHA_GRACE_TIME=1800

Bouncer Cloudflare

sudo apt install crowdsec-cloudflare-bouncer -y
sudo crowdsec-cloudflare-bouncer -g <CF_API_TOKEN> -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml
sudo systemctl enable --now crowdsec-cloudflare-bouncer

Référence cscli

# Décisions
sudo cscli decisions list                    # Tous les blocages actifs
sudo cscli decisions add -i 203.0.113.42     # Blocage manuel
sudo cscli decisions add -r 10.0.0.0/8 -t ban -d 1h  # Bloquer un CIDR
sudo cscli decisions delete -i 203.0.113.42  # Supprimer un blocage

# Alertes
sudo cscli alerts list                       # Scénarios déclenchés récemment
sudo cscli alerts inspect <id>               # Contexte complet de l'alerte

# Gestion du hub
sudo cscli hub list
sudo cscli hub update
sudo cscli collections upgrade crowdsecurity/nginx

# Gestion des machines (multi-serveur)
sudo cscli machines list
sudo cscli machines add agent-web-02 --auto

# Gestion des bouncers
sudo cscli bouncers list
sudo cscli bouncers add mon-bouncer

# Métriques
sudo cscli metrics

Listes de Blocage Communautaires et API Centrale

Inscrivez-vous à l’API Centrale pour débloquer les listes communautaires :

sudo cscli console enroll <votre-token-de-app.crowdsec.net>
sudo systemctl restart crowdsec

Les listes communautaires incluent :

  • Liste de réputation d’IPs CrowdSec — IPs détectés attaquant des déploiements CrowdSec dans le monde entier
  • Firehol Level 1 — IPs malveillants connus
  • Noeuds de sortie Tor — optionnel, pour bloquer le trafic anonyme
  • Listes proxy/VPN — IPs de sortie de fournisseurs cloud utilisés par les bots

Chaque décision de l’API Centrale porte un type : ban (blocage dur), captcha (challenge CAPTCHA) ou throttle (limitation de débit).

Listes Blanches

Liste blanche de parser (pré-scénario)

Créez /etc/crowdsec/parsers/s02-enrich/whitelist.yaml :

name: maentreprise/whitelists
description: "IPs bureau et monitoring"
whitelist:
  reason: "IPs internes et de confiance"
  ip:
    - "192.168.1.0/24"
    - "10.0.0.0/8"
  cidr:
    - "172.16.0.0/12"

Liste blanche post-débordement

name: maentreprise/postoverflow-whitelist
description: "Autoriser le monitoring synthétique depuis des IPs connus"
whitelist:
  reason: "Monitoring de disponibilité"
  expression:
    - "evt.Overflow.Alert.Source.IP in ['203.0.113.100', '203.0.113.101']"

Configuration Multi-Serveur

Serveur LAPI

# /etc/crowdsec/config.yaml
api:
  server:
    listen_uri: 0.0.0.0:8080
    tls:
      cert_file: /etc/crowdsec/ssl/cert.pem
      key_file: /etc/crowdsec/ssl/key.pem

Enregistrement des agents supplémentaires

Sur chaque serveur supplémentaire :

sudo apt install crowdsec -y
sudo cscli lapi register -u https://serveur-lapi:8080
# Sur le serveur LAPI, valider :
sudo cscli machines validate <machine-id>

Bouncer connecté à une LAPI distante

# /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
api_url: https://serveur-lapi:8080
api_key: <clé-bouncer-du-serveur-lapi>

Supervision : Prometheus et Grafana

CrowdSec expose des métriques Prometheus à http://localhost:6060/metrics. Importez le dashboard Grafana officiel (ID 14584) pour une vue visuelle de :

  • Décisions émises par heure
  • Services les plus attaqués
  • Taux de correspondance des parsers
  • Fréquence de débordement des scénarios

Vérification rapide en ligne de commande :

sudo cscli metrics

CrowdSec vs Alternatives

OutilMécanismeLangageMulti-serveurIntelligence CommunautaireBouncers
CrowdSecScénarios comportementauxGoLAPI natifOui (API Centrale)Pare-feu, Nginx, CF, personnalisé
Fail2BanRegex de logsPythonSync manuelNoniptables, nftables, firewalld
SuricataIDS/IPS réseauCMode clusterAbonnements de règlesNFQueue
OSSEC/WazuhHIDS + analyse de logsCManager-agentRègles Wazuh cloudRéponse active
ModSecurityWAF (couche HTTP)CProxy inverseOWASP CRSModule Nginx/Apache
Cloudflare WAFPare-feu de bordureN/ACDN mondialIntel de menaces CFBordure CF uniquement

Déploiement en Production : Nginx + SSH

Étape 1 — Installer CrowdSec et les collections :

curl -s https://install.crowdsec.net | sudo bash
sudo apt install crowdsec -y
sudo cscli collections install crowdsecurity/linux \
  crowdsecurity/sshd \
  crowdsecurity/nginx

Étape 2 — Configurer l’acquisition des logs dans /etc/crowdsec/acquis.yaml :

filenames:
  - /var/log/nginx/access.log
  - /var/log/nginx/error.log
labels:
  type: nginx
# --- (next source)
source: journalctl
journalctl_filter:
  - "_SYSTEMD_UNIT=sshd.service"
labels:
  type: syslog

Étape 3 — Installer le bouncer pare-feu :

sudo apt install crowdsec-firewall-bouncer-nftables -y
sudo systemctl enable --now crowdsec-firewall-bouncer

Étape 4 — Liste blanche des IPs de confiance :

# /etc/crowdsec/parsers/s02-enrich/whitelist.yaml
name: monserveur/whitelist
description: "IPs de confiance"
whitelist:
  reason: "Bureau et VPN"
  ip:
    - "192.168.1.0/24"

Étape 5 — S’inscrire à l’API Centrale :

sudo cscli console enroll <token-de-app.crowdsec.net>
sudo systemctl restart crowdsec

Étape 6 — Vérifier que la protection est active :

sudo cscli decisions list
sudo cscli metrics
sudo cscli bouncers list

Cas Particuliers et Avertissements

  • Faux positifs des équilibreurs de charge : Si tout le trafic arrive via un proxy inverse, CrowdSec ne voit que l’IP du proxy. Configurez le parsing de X-Forwarded-For ou ajoutez l’IP du proxy à la liste blanche.
  • Logs Docker : Les logs Docker nécessitent le type d’acquisition source: docker. Monter /var/log ne fonctionne pas pour les conteneurs écrivant en stdout/stderr.
  • Lacunes de couverture des parsers : Vérifiez sudo cscli metrics pour des valeurs élevées de unparsed — elles indiquent des lignes de log sans parser installé.
  • Clés API des bouncers : Si vous régénérez les clés (ex. après réinstallation de la LAPI), mettez à jour le fichier de configuration de chaque bouncer et redémarrez le service.

Résumé

CrowdSec fournit un système de prévention des intrusions en couches et alimenté par la communauté qui s’adapte d’un simple VPS à une flotte multi-datacenter :

  • L’agent analyse les logs à travers un pipeline de parsers par étapes et évalue les événements avec des scénarios YAML de type leaky-bucket, trigger et compteur
  • L’API Locale coordonne les décisions et connecte bouncers et agents dans les déploiements multi-serveurs
  • Les bouncers appliquent les décisions au niveau pare-feu (iptables/nftables), application (Nginx) ou CDN (Cloudflare)
  • cscli gère collections, décisions, alertes, machines, bouncers et métriques depuis la ligne de commande
  • Les listes de blocage communautaires via l’API Centrale ajoutent une threat intelligence mondiale sans configuration supplémentaire
  • Les scénarios et listes blanches personnalisés permettent d’affiner précisément la protection

Articles Connexes