Aller au contenu

CrowdSec

Mise à jour : 2026-10-19 | Non relu intégralement

CrowdSec est à la fois un IDS (système de détection d'intrusion) et un IPS (système de prévention d'intrusion). Il lit en continu les journaux de vos services, reconnaît les comportements malveillants (brute-force, scans, exploitation de failles...) et bannit automatiquement les adresses qui attaquent.

Analogie : CrowdSec est un vigile qui relit en permanence les enregistrements des caméras (les journaux). Quand il repère un comportement suspect, il donne la consigne au videur (le bouncer) de ne plus laisser entrer la personne. Et il partage le signalement avec les vigiles des autres établissements.

Ce partage est la force de CrowdSec : chaque installation signale les adresses qui l'attaquent, et reçoit en retour une liste d'adresses reconnues comme malveillantes par la communauté.

Systèmes visés

Debian 12 et 13, Ubuntu 22.04 et suivantes, avec le dépôt officiel de CrowdSec.

Comment ça marche

Journaux (fichiers, journald, conteneurs Docker...)
        │
        ▼
  Acquisition ────► quelles sources lire, avec quel type
        │
        ▼
  Parsers ────────► découper et normaliser chaque ligne (en plusieurs étapes)
        │
        ▼
  Scénarios ──────► reconnaître un comportement (ex. 5 échecs SSH en 10 s)
        │
        ▼
  Profils ────────► transformer l'alerte en décision (ex. bannir 4 h)
        │
        ▼
  Bouncer ────────► appliquer la décision (pare-feu, serveur web...)
Le vocabulaire de CrowdSec
  • Acquisition : la déclaration des sources à lire (un fichier, journald, un conteneur Docker...), avec un label type qui indique comment les interpréter.
  • Parsers : ils découpent chaque ligne de journal pour en extraire les informations utiles (adresse IP, utilisateur, URL...). Ils travaillent en étapes (stages) successives : s00-raw lit le format brut, s01-parse interprète le contenu propre au service, s02-enrich ajoute du contexte.
  • Enrichers : des parsers de l'étape s02-enrich qui ajoutent du contexte (pays de l'adresse, réseau...). Les listes blanches se placent aussi à cette étape.
  • Scénarios : ils décrivent un comportement malveillant. La plupart fonctionnent comme un seau percé : chaque événement suspect ajoute une goutte, le seau fuit à vitesse constante, et s'il déborde, une alerte est levée.
  • Profils : ils décident quoi faire d'une alerte (bannir, combien de temps, notifier).
  • Décisions : le résultat appliqué, en général un bannissement d'adresse pour une durée donnée.
  • Bouncers : les composants qui appliquent les décisions. Sans bouncer, CrowdSec détecte mais ne bloque rien.
  • Collections : des lots prêts à l'emploi de parsers et de scénarios pour un service donné (SSH, Nginx, Traefik...).
  • Hub : le catalogue en ligne des collections, parsers et scénarios, maintenus par CrowdSec et la communauté.
  • LAPI (API locale) : le cœur de votre installation, qui stocke les décisions et que les bouncers interrogent.
  • CAPI (API centrale) : le service de CrowdSec qui reçoit les signalements de la communauté et distribue la liste de blocage partagée.

Choisir son bouncer

Il existe deux grandes familles de bouncers :

  • le bouncer pare-feu, qui bloque l'adresse au niveau du système, sur tous les ports;
  • les bouncers applicatifs (plugin Traefik, module Nginx...), qui bloquent seulement au niveau du service web, par exemple en renvoyant une page "403".

Ce tutoriel utilise le bouncer pare-feu. C'est le choix que je fais en production, pour trois raisons :

  • le blocage intervient avant que le service web ne traite la requête;
  • il protège tous les services de la machine, pas seulement le web;
  • la configuration reste identique sur tous les serveurs, avec ou sans reverse proxy.

1. Installer CrowdSec

En root :

apt update && apt full-upgrade -y
apt install -y curl
curl -s https://install.crowdsec.net -o install-crowdsec.sh
less install-crowdsec.sh    # facultatif : lire le script avant de l'exécuter
sh install-crowdsec.sh
apt install -y crowdsec

Le script ajoute le dépôt officiel de CrowdSec et sa clé de signature. Le télécharger dans un fichier plutôt que de l'exécuter directement (curl ... | sh) permet de vérifier ce qu'il fait.

Deux services, deux rôles

L'installation crée le service crowdsec (détection : lecture des journaux, scénarios, API locale). Le blocage est assuré par un second service, le bouncer, installé à l'étape 2. Tant que celui-ci n'est pas en place, CrowdSec voit les attaques mais ne bloque rien.

À l'installation, CrowdSec détecte les services présents (SSH, Nginx...) et installe les collections correspondantes. Vérifiez :

systemctl status crowdsec
cscli collections list
Le port 8080 est déjà utilisé ?

L'API locale écoute par défaut sur 127.0.0.1:8080. Si un autre service utilise déjà ce port, changez-le dans trois fichiers. Exemple avec le port 6660 :

/etc/crowdsec/config.yaml :

api:
  server:
    listen_uri: 127.0.0.1:6660

/etc/crowdsec/local_api_credentials.yaml :

url: http://127.0.0.1:6660

/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml (une fois le bouncer installé) :

api_url: http://127.0.0.1:6660/

Puis :

systemctl restart crowdsec
systemctl restart crowdsec-firewall-bouncer

Complétion de la commande cscli

La complétion permet d'obtenir les commandes et options disponibles avec la touche Tab :

apt install -y bash-completion
cscli completion bash > /etc/bash_completion.d/cscli
source /etc/bash_completion.d/cscli

Testez en tapant cscli puis Tab. Les prochains terminaux l'auront automatiquement.

2. Installer le bouncer pare-feu

Le bouncer existe en deux paquets, selon l'outil qui gère le pare-feu :

# Recommandé si Docker est présent sur la machine
apt install -y crowdsec-firewall-bouncer-iptables

# Ou, sans Docker, sur un système récent
apt install -y crowdsec-firewall-bouncer-nftables

Le paquet s'enregistre automatiquement auprès de l'API locale. Vérifiez :

systemctl status crowdsec-firewall-bouncer
cscli bouncers list

cscli bouncers list doit afficher le bouncer, avec une date de dernière connexion récente.

Docker : le bouncer doit aussi protéger les conteneurs

Les ports publiés par Docker ne passent pas par la chaîne INPUT du pare-feu, que le bouncer protège par défaut. Sans réglage, une adresse bannie peut continuer à atteindre vos conteneurs.

Dans /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml :

Bouncer iptables, décommentez la chaîne DOCKER-USER, évaluée avant les règles générées par Docker :

iptables_chains:
  - INPUT          # trafic entrant vers l'hôte (SSH, web...)
  - DOCKER-USER    # trafic entrant vers les conteneurs Docker
#  - FORWARD       # trafic routé par l'hôte (rarement utile ici)

Bouncer nftables, ajoutez l'accroche forward :

nftables_hooks:
  - input
  - forward

Vérifiez les noms exacts des clés dans votre fichier, puis : systemctl restart crowdsec-firewall-bouncer.

Contrôlez ensuite que la règle est bien présente, y compris après un redémarrage du serveur (Docker et le bouncer démarrent dans un ordre qui peut varier) :

iptables -L DOCKER-USER -n | grep -i crowdsec

3. Protéger son propre accès

Avant tout test, assurez-vous qu'un faux positif ne pourra jamais couper votre accès d'administration. Placez votre réseau d'administration (VPN, adresse fixe du bureau...) en liste blanche, dans un fichier à vous, /etc/crowdsec/parsers/s02-enrich/mes-whitelists.yaml :

name: perso/whitelist-admin
description: "Ne jamais bannir le réseau d'administration"
whitelist:
  reason: "réseau d'administration"
  cidr:
    - "100.64.0.0/10"   # remplacez par la plage de votre VPN
  ip:
    - "203.0.113.10"    # remplacez par une adresse fixe de confiance
systemctl reload crowdsec
  • Les événements venant de ces adresses sont écartés dès l'analyse : ils ne déclenchent aucune alerte.
  • Créez toujours votre propre fichier. Un fichier fourni par le hub, une fois modifié, est considéré comme altéré et n'est plus mis à jour.
  • Vérifiez que la liste est prise en compte : cscli parsers list doit afficher perso/whitelist-admin.
Alternative : les allowlists

Les versions récentes (1.6.8 et suivantes) proposent des listes d'autorisation gérées en ligne de commande. La différence avec la liste blanche ci-dessus : la whitelist écarte les événements à l'analyse, l'allowlist empêche toute décision, y compris celles venant de la liste communautaire. Les deux se complètent :

cscli allowlists create admin -d "Réseau d'administration"
cscli allowlists add admin 100.64.0.0/10 203.0.113.10
cscli allowlists inspect admin
cscli allowlists remove admin 203.0.113.10

4. Vérifier ce qui est surveillé

Les sources lues

Les sources sont déclarées dans /etc/crowdsec/acquis.d/, un fichier YAML par service (par exemple setup.linux.yaml et setup.sshd.yaml, créés à l'installation). La commande clé est :

cscli metrics

La section Acquisition Metrics liste chaque source, avec le nombre de lignes lues et analysées. Une source absente, ou dont les lignes lues restent à zéro, signale un problème d'acquisition.

Exemples d'acquisition :

# SSH via journald (Debian 12 et 13 n'ont plus de /var/log/auth.log par défaut)
source: journalctl
journalctl_filter:
  - "_SYSTEMD_UNIT=ssh.service"
labels:
  type: syslog
# Journaux système classiques (Ubuntu, ou Debian avec rsyslog)
filenames:
  - /var/log/auth.log
  - /var/log/syslog
  - /var/log/kern.log
labels:
  type: syslog
# Nginx
filenames:
  - /var/log/nginx/access.log
  - /var/log/nginx/error.log
labels:
  type: nginx
# Traefik (journaux d'accès au format JSON)
filenames:
  - /var/log/traefik/access.log
labels:
  type: traefik
# HAProxy
filenames:
  - /var/log/haproxy.log
labels:
  type: haproxy
# Journaux d'un conteneur Docker, lus directement
source: docker
container_name:
  - nom-du-conteneur
labels:
  type: authentik   # le type attendu par la collection du service

Après toute modification :

systemctl restart crowdsec
cscli metrics

Les collections installées

La détection automatique n'est pas exhaustive : complétez selon vos services.

Collection Rôle
crowdsecurity/linux Journaux système (installée par défaut)
crowdsecurity/sshd Brute-force SSH
crowdsecurity/nginx Accès suspects sur Nginx
crowdsecurity/traefik Accès suspects sur Traefik
crowdsecurity/http-cve Tentatives d'exploitation de failles web connues (CVE)
crowdsecurity/base-http-scenarios Comportements web suspects (scans, brute-force...)
crowdsecurity/nextcloud Brute-force sur Nextcloud
cscli collections install crowdsecurity/sshd crowdsecurity/http-cve crowdsecurity/base-http-scenarios
systemctl reload crowdsec
Nextcloud : éviter les faux positifs

L'usage normal de Nextcloud (synchronisation, aperçus) génère beaucoup de requêtes qui peuvent ressembler à un scan. Installez le parser qui les écarte :

cscli parsers install crowdsecurity/nextcloud-whitelist
systemctl reload crowdsec

5. Régler la durée de bannissement

Par défaut, une décision bannit l'adresse pendant 4 heures. Le réglage se trouve dans /etc/crowdsec/profiles.yaml, qui contient deux profils : default_ip_remediation (une adresse) et default_range_remediation (une plage d'adresses). Modifiez la durée dans les deux :

decisions:
  - type: ban
    duration: 24h
systemctl reload crowdsec

Le bon réglage dépend du service : une durée longue décourage les attaquants, une durée courte limite la gêne si un utilisateur légitime est banni par erreur.

6. Recevoir les alertes par mail

1) Configurer le serveur SMTP dans /etc/crowdsec/notifications/email.yaml. Le fichier contient déjà un modèle de message en HTML (format) : ne modifiez que les paramètres de connexion.

type: email
name: email_default

# Regrouper les alertes arrivées dans les 30 secondes en un seul mail
group_wait: 30s

smtp_host: mail.domaine.fr
smtp_port: 587
smtp_username: alertes@domaine.fr
smtp_password: "<MOT_DE_PASSE_APPLICATION>"
auth_type: login               # login, plain, crammd5 ou none
encryption_type: starttls      # starttls (port 587), ssltls (port 465) ou none

sender_name: "CrowdSec"
sender_email: alertes@domaine.fr
email_subject: "[CrowdSec] Adresse bannie"
receiver_emails:
  - admin@domaine.fr

Ce fichier contient un mot de passe : vérifiez qu'il n'est lisible que par root (chmod 600), et utilisez un mot de passe d'application dédié.

2) Activer la notification dans /etc/crowdsec/profiles.yaml : dans chacun des deux profils, décommentez :

notifications:
  - email_default

3) Tester puis appliquer :

cscli notifications test email_default
systemctl restart crowdsec

Chaque mail indique l'adresse bannie (avec des liens vers Whois et la base de réputation CrowdSec CTI), la durée du bannissement et le scénario déclencheur.

7. Console CrowdSec (optionnel)

La console web de CrowdSec offre un tableau de bord de vos installations et permet de s'abonner à des listes de blocage supplémentaires.

1) Créez un compte sur app.crowdsec.net et validez-le. 2) Dans Security Engines, cliquez sur Add Security Engine et copiez la clé d'enrôlement. 3) Sur le serveur :

```sh
cscli console enroll --name "$(hostname)" VOTRE-CLE
```

4) Acceptez l'enrôlement dans la console, puis : systemctl restart crowdsec. 5) Option : permettre de gérer les décisions depuis la console avec cscli console enable console_management.

Ce qui est partagé avec CrowdSec

Par défaut, chaque installation envoie à CrowdSec les adresses qui l'ont attaquée et le scénario déclenché : c'est ce qui alimente la liste communautaire dont vous bénéficiez. L'option -e context à l'enrôlement partage en plus des détails sur chaque alerte : activez-la seulement si vous en avez besoin dans la console.

8. Tester

Test sans risque

Avec une adresse de documentation, jamais la vôtre :

cscli decisions add --ip 198.51.100.7 --duration 5m --reason "test"
cscli decisions list
iptables -L INPUT -n | grep -i crowdsec      # ou : nft list table ip crowdsec
cscli decisions delete --ip 198.51.100.7

Test réel

Depuis une machine extérieure (et uniquement contre votre propre serveur), lancez un scanner de vulnérabilités web :

curl -I https://votresite.fr
nikto -h https://votresite.fr

Sur le serveur :

cscli alerts list
cscli decisions list

L'adresse de la machine de test doit apparaître. Relancez curl depuis cette machine : avec le bouncer pare-feu, la connexion n'aboutit plus et finit par expirer. Vous n'obtenez pas de page "403" : le pare-feu ignore simplement les paquets. Pensez à lever le bannissement ensuite : cscli decisions delete --ip ADRESSE.

9. Gérer les décisions et les alertes

# Adresses actuellement bannies
cscli decisions list

# Lever un bannissement
cscli decisions delete --ip 1.2.3.4

# Lever tous les bannissements (y compris ceux de la liste communautaire)
cscli decisions delete --all

# Historique des alertes, puis détail d'une alerte
cscli alerts list
cscli alerts inspect -d 42

10. Comprendre et ajuster un scénario

Extrait du scénario de brute-force SSH :

type: leaky
name: crowdsecurity/ssh-bf
description: "Detect ssh bruteforce"
filter: "evt.Meta.log_type == 'ssh_failed-auth'"
groupby: evt.Meta.source_ip
capacity: 5
leakspeed: "10s"
blackhole: 1m

C'est le seau percé :

  • filter : seuls les échecs d'authentification SSH remplissent le seau;
  • groupby : un seau par adresse IP;
  • capacity: 5 : le seau déborde au-delà de 5 événements;
  • leakspeed: 10s : il se vide d'une goutte toutes les 10 secondes;
  • blackhole: 1m : après un débordement, la même adresse ne redéclenche pas d'alerte pendant 1 minute.

Pour adapter un scénario, ne modifiez pas le fichier fourni par le hub (il ne serait plus mis à jour). Copiez-le dans /etc/crowdsec/scenarios/ sous un autre nom (et un autre name:), modifiez la copie, puis systemctl reload crowdsec.

Tester un scénario sans bannir

Le mode simulation enregistre les alertes d'un scénario sans appliquer de décision :

cscli simulation enable crowdsecurity/ssh-bf
cscli simulation status
cscli simulation disable crowdsecurity/ssh-bf

11. Maintenance

# Mettre à jour le catalogue et les éléments installés (parsers, scénarios...)
cscli hub update
cscli hub upgrade
systemctl reload crowdsec

CrowdSec et le bouncer se mettent à jour avec le système (apt update && apt full-upgrade). Après chaque mise à jour, vérifiez :

systemctl status crowdsec crowdsec-firewall-bouncer
cscli metrics

12. Diagnostic

# État de l'API locale et de la connexion à l'API centrale
cscli lapi status
cscli capi status

# Le bouncer interroge-t-il bien l'API ?
cscli bouncers list

# Journaux
journalctl -u crowdsec -n 50
journalctl -u crowdsec-firewall-bouncer -n 50
tail -f /var/log/crowdsec.log
tail -f /var/log/crowdsec-firewall-bouncer.log

Voir les adresses bannies dans le pare-feu :

# Bouncer iptables : lister les ensembles d'adresses, puis afficher l'un d'eux
ipset list -n | grep -i crowdsec
ipset list crowdsec-blacklists

# Bouncer nftables
nft list table ip crowdsec

Les noms des ensembles peuvent varier selon la version du bouncer : utilisez d'abord la commande qui les liste.

Problèmes fréquents :

  • Une source n'apparaît pas dans cscli metrics : vérifiez le chemin du fichier, ses permissions, et que le fichier d'acquisition se termine bien par .yaml.
  • Des lignes lues mais pas analysées : le type du label ne correspond à aucun parser installé. Installez la collection du service.
  • Des attaques détectées mais pas bloquées sur des conteneurs : il manque la chaîne DOCKER-USER (voir l'encadré Docker de l'étape 2).

Références