Accueil » Formations » Administration sécurité » Introduction à CrowdSec

Introduction à CrowdSec

CrowdSec est un moteur open source de détection et de remédiation des comportements malveillants. Il lit les journaux de vos serveurs, y reconnaît des attaques (force brute SSH, scans web, tentatives d’exploitation) et fait bloquer les adresses fautives par des composants placés au plus près du trafic : pare-feu, serveur web, reverse proxy. Sa particularité est collaborative : chaque instance peut partager les adresses qu’elle a détectées et recevoir en retour une liste d’adresses signalées par la communauté. Ce cours s’adresse aux administrateurs, techniciens et responsables sécurité de PME qui veulent protéger des serveurs exposés sur Internet sans déployer un SOC complet. Les commandes présentées correspondent à la branche 1.8 du Security Engine (version 1.8.0 publiée fin août 2026), installée sur Ubuntu Server 24.04 LTS depuis le dépôt officiel de l’éditeur.

Cadre d’usage : les attaques simulées dans les travaux pratiques (échecs de connexion SSH en rafale, requêtes de test HTTP) se font uniquement dans un laboratoire isolé, sur des machines qui vous appartiennent. Ne lancez jamais ces tests contre un système dont vous n’avez pas la responsabilité.

1. Pourquoi CrowdSec : de fail2ban à l’IPS collaboratif

Pendant des années, la protection de base d’un serveur Linux exposé reposait sur fail2ban : un démon lit un fichier de journal, compte les échecs d’authentification par adresse IP et ajoute une règle de pare-feu au-delà d’un seuil. Le principe est efficace mais montre vite ses limites dès qu’on gère plusieurs serveurs : chaque machine apprend seule, les règles sont locales, la détection se limite à des expressions régulières sur des lignes isolées et il n’existe aucune vision d’ensemble.

CrowdSec reprend l’idée et la réorganise en trois rôles distincts : détecter à partir des journaux, décider d’une sanction dans une base centrale, appliquer cette sanction là où elle est la plus utile. Le projet est développé en Go par un éditeur français, publié sous licence MIT et accompagné d’un hub public de règles de détection maintenues par l’éditeur et la communauté.

Concrètement, CrowdSec répond à trois besoins fréquents en PME :

  • Arrêter le bruit de fond d’Internet. Un serveur SSH ou un site web exposé reçoit en permanence des tentatives automatisées. CrowdSec les reconnaît et coupe l’accès aux sources les plus agressives.
  • Mutualiser la défense de plusieurs serveurs. Une adresse bannie après une attaque sur un serveur peut être bloquée immédiatement sur tous les autres.
  • Bénéficier du renseignement collectif. Les adresses signalées par des milliers d’autres instances sont bloquées avant même d’avoir attaqué vos machines.

Bonne pratique : CrowdSec ne remplace ni les mises à jour, ni un pare-feu bien configuré, ni l’authentification par clé SSH. C’est une couche supplémentaire qui réduit l’exposition et la charge, pas une excuse pour laisser un service vulnérable en ligne.

2. Architecture : Log Processor, Local API et composants de remédiation

CrowdSec sépare clairement la détection de la sanction. Trois briques coopèrent :

  • Le Log Processor (agent) lit les journaux, les analyse et produit des alertes lorsqu’un comportement correspond à un scénario.
  • La Local API (LAPI) reçoit les alertes, les transforme en décisions (bannir telle adresse pendant quatre heures, par exemple) selon des profils, et les stocke dans une base de données (SQLite par défaut, MySQL ou PostgreSQL pour les déploiements plus importants). Elle écoute par défaut sur 127.0.0.1:8080.
  • Les composants de remédiation (bouncers) interrogent régulièrement la LAPI, récupèrent les décisions en cours et les appliquent : règle nftables ou iptables, réponse 403 ou captcha sur un serveur web, blocage sur un reverse proxy.

On peut se représenter le schéma ainsi : à gauche, les journaux (auth.log, journal systemd, journaux Nginx) entrent dans le Log Processor ; au centre, la LAPI et sa base de décisions ; à droite, plusieurs bouncers qui tirent les décisions et agissent sur le trafic. Une liaison sortante relie enfin la LAPI à la Central API (CAPI) de l’éditeur pour le partage communautaire.

Sur une installation simple, le Log Processor et la LAPI tournent dans le même service crowdsec, sur la même machine que le bouncer. Dans une architecture plus large, une LAPI centrale reçoit les alertes de plusieurs agents et sert les décisions à tous les bouncers du parc : une attaque détectée sur un serveur protège alors immédiatement les autres.

Cette séparation a une conséquence pratique importante : la détection ne bloque jamais rien par elle-même. Si aucun bouncer n’est installé, CrowdSec produit des alertes et des décisions, mais aucun paquet n’est filtré. C’est la première chose à vérifier lorsqu’un administrateur pense « CrowdSec ne bloque pas ».

3. Le pipeline de détection : acquisition, parseurs, scénarios

Le traitement d’une ligne de journal suit toujours le même chemin.

  1. Acquisition. Les sources sont déclarées dans /etc/crowdsec/acquis.yaml ou dans des fichiers séparés du dossier /etc/crowdsec/acquis.d/. Chaque source précise son type (file, journalctl, docker, syslog…) et une étiquette labels.type qui indique quel parseur doit lire les lignes.
  2. Parsing. Les parseurs transforment une ligne brute en événement structuré : adresse source, utilisateur, chemin HTTP, code de retour. Ils sont organisés en étapes : s00-raw (format du journal, syslog par exemple), s01-parse (application : sshd, nginx) et s02-enrich (enrichissements : géolocalisation, date, listes blanches).
  3. Scénarios. Les événements alimentent des scénarios qui décrivent un comportement malveillant. La plupart reposent sur le modèle du seau percé (leaky bucket) : chaque événement ajoute une goutte dans un seau propre à une adresse source, le seau fuit à vitesse constante, et une alerte est levée lorsqu’il déborde.

Le scénario crowdsecurity/ssh-bf illustre bien ce modèle : le seau a une capacité de 5 événements et se vide d’une goutte toutes les 10 secondes. Quelques échecs d’authentification espacés ne déclenchent rien ; une rafale d’échecs depuis la même adresse fait déborder le seau et produit une alerte. Un délai de « blackhole » d’une minute évite ensuite de lever des alertes en boucle pour la même source.

Cette approche comportementale est plus robuste qu’un simple comptage : des scénarios différents détectent la force brute lente (ssh-slow-bf), l’énumération de comptes, le parcours systématique d’un site web (http-crawl-non_statics) ou la recherche de fichiers sensibles (http-sensitive-files).

4. Le hub : collections, parseurs et scénarios prêts à l’emploi

Personne n’écrit ses parseurs et scénarios en partant de zéro : le hub CrowdSec en publie des centaines, versionnés et testés. Ils sont regroupés en collections qui correspondent à un service. Quelques exemples :

  • crowdsecurity/linux : parseur syslog, enrichissements GeoIP et date, et la collection crowdsecurity/sshd ;
  • crowdsecurity/sshd : parseurs des journaux SSH et scénarios ssh-bf, ssh-slow-bf, ssh-time-based-bf, ssh-cve-2024-6387, ssh-refused-conn et ssh-generic-test ;
  • crowdsecurity/nginx : parseur des journaux Nginx et collection crowdsecurity/base-http-scenarios (exploration de site, chemins sensibles, injections SQL et XSS, user-agents malveillants…).

Lors de l’installation, CrowdSec détecte les services présents (SSH, Nginx, Apache…) et installe les collections correspondantes. Pour un service ajouté plus tard, on installe la collection avec cscli collections install et on déclare la source de journaux dans l’acquisition. Le hub se met à jour en deux temps : cscli hub update rafraîchit l’index des éléments disponibles, cscli hub upgrade met à jour les éléments installés.

Un élément modifié localement est dit tainted (altéré) : il n’est plus mis à jour automatiquement. C’est un garde-fou utile, mais aussi un piège : un scénario modifié à la main il y a deux ans ne bénéficie plus des corrections de l’éditeur. Préférez les fichiers locaux séparés (whitelists, profils, fichiers .local) aux modifications directes des éléments du hub.

5. Décisions et remédiation : ban, captcha et bouncers

Une décision associe une portée (une adresse IP, une plage, parfois un nom d’utilisateur), un type de sanction et une durée. Le type le plus courant est ban ; d’autres types comme captcha existent, à condition que le bouncer sache les appliquer. Par défaut, une alerte sur une adresse IP produit un bannissement de quatre heures.

Le choix du bouncer dépend de l’endroit où l’on veut agir :

  • Bouncer pare-feu (crowdsec-firewall-bouncer-nftables ou -iptables) : il alimente un ensemble d’adresses dans nftables ou iptables. Tout le trafic de l’adresse bannie est coupé, quel que soit le service. C’est le choix par défaut sur un serveur Linux.
  • Bouncers applicatifs (Nginx, reverse proxy comme Traefik, HAProxy…) : ils interviennent au niveau HTTP et peuvent présenter un captcha plutôt que de couper brutalement l’accès, ce qui limite l’impact d’un faux positif sur un visiteur légitime.
  • Intégrations d’équipements : des composants existent pour des pare-feu comme pfSense ou OPNsense, ce qui permet de bloquer en périphérie du réseau plutôt que sur chaque serveur.

Les bouncers fonctionnent en mode « pull » : ils interrogent la LAPI à intervalle régulier et ne récupèrent que les changements (nouvelles décisions, décisions expirées). Chaque bouncer s’authentifie avec une clé d’API créée par cscli bouncers add ; lorsqu’un bouncer est installé par paquet sur la même machine que la LAPI, cette clé est générée et configurée automatiquement.

Bonne pratique : combinez les niveaux. Le bouncer pare-feu coupe les scanners et les attaques de force brute ; un bouncer HTTP avec captcha traite les comportements web ambigus. Un seul niveau de remédiation, c’est soit trop brutal, soit trop permissif.

6. Le réseau collaboratif : CAPI, signaux et blocklist communautaire

Lorsqu’une alerte est levée, la LAPI peut transmettre un signal à la Central API de l’éditeur : l’adresse source, le scénario déclenché et l’horodatage. Les journaux eux-mêmes ne quittent pas votre serveur. Les signaux de toutes les instances sont croisés pour écarter les faux positifs et les tentatives d’empoisonnement, puis une blocklist communautaire est redistribuée aux instances participantes.

Ces décisions d’origine CAPI s’ajoutent à vos décisions locales et sont appliquées par les mêmes bouncers. On les distingue avec cscli decisions list -a, qui inclut les décisions reçues de la Central API. La commande cscli capi status vérifie que l’instance est bien enregistrée et joint l’API centrale.

La console web de l’éditeur complète le dispositif : en y inscrivant un moteur avec cscli console enroll, on visualise les alertes de tout le parc, on s’abonne à des blocklists supplémentaires et on gère plusieurs instances depuis une interface unique. L’inscription est facultative ; la détection et le blocage locaux fonctionnent sans elle.

Point d’attention RGPD : une adresse IP est une donnée personnelle. Le partage des signaux est documenté par l’éditeur et peut être désactivé, mais vous perdez alors la blocklist communautaire. Mentionnez ce traitement dans votre registre et faites valider le choix par la direction.

7. Installation et organisation des fichiers

Sur Debian et Ubuntu, l’éditeur fournit un dépôt de paquets. Un script ajoute ce dépôt, puis l’installation se fait avec apt :

curl -s https://install.crowdsec.net | sudo sh
sudo apt install crowdsec

Le paquet installe le service crowdsec, détecte les services présents, installe les collections adaptées, déclare les sources de journaux correspondantes et enregistre l’instance auprès de la Central API. Il n’installe aucun bouncer : c’est une étape séparée.

sudo apt install crowdsec-firewall-bouncer-nftables

Les fichiers essentiels sont regroupés sous /etc/crowdsec/ :

  • config.yaml : configuration principale (chemins, base de données, adresse d’écoute de la LAPI) ;
  • acquis.yaml et acquis.d/ : sources de journaux ;
  • profiles.yaml : règles de transformation des alertes en décisions ;
  • parsers/, scenarios/, collections/ : éléments installés depuis le hub ;
  • notifications/ : configuration des greffons de notification (e-mail, Slack, webhook…) ;
  • bouncers/crowdsec-firewall-bouncer.yaml : configuration du bouncer pare-feu (adresse de la LAPI dans api_url, clé dans api_key, mode nftables ou iptables dans mode).

Pour les fichiers livrés par les paquets, privilégiez les surcharges .local (par exemple profiles.yaml.local ou crowdsec-firewall-bouncer.yaml.local) : vos réglages ne seront pas écrasés lors d’une mise à jour.

8. Piloter CrowdSec avec cscli

cscli est l’outil en ligne de commande qui pilote toute l’instance. Il s’exécute avec les droits root et s’organise en sous-commandes par objet :

sudo cscli metrics                       # activité : sources lues, parseurs, scénarios, bouncers
sudo cscli hub list                      # éléments installés et leur état
sudo cscli collections list              # collections installées
sudo cscli alerts list                   # alertes levées
sudo cscli decisions list                # décisions locales en cours
sudo cscli bouncers list                 # bouncers enregistrés et dernière connexion
sudo cscli machines list                 # agents enregistrés auprès de la LAPI

Quelques commandes reviennent constamment en exploitation :

  • cscli metrics show acquisition parsers vérifie que les journaux sont bien lus et analysés : un fichier lu mais jamais parsé signale une erreur d’étiquette type dans l’acquisition ;
  • cscli alerts inspect <id> -d affiche le détail d’une alerte avec les événements qui l’ont déclenchée ;
  • cscli decisions add et cscli decisions delete ajoutent ou retirent une décision manuellement, par exemple pour bannir une adresse repérée lors d’un incident ou lever un faux positif ;
  • cscli explain fait passer une ligne de journal dans le pipeline et montre parseur par parseur ce qui a été reconnu.

Après toute modification de configuration (acquisition, profils, whitelists), rechargez ou redémarrez le service, puis contrôlez les métriques : c’est le moyen le plus rapide de détecter une source muette.

9. Réduire les faux positifs : whitelists, allowlists et simulation

Un outil qui bannit automatiquement doit être réglé avec soin : bloquer la passerelle de l’entreprise, l’outil de supervision ou le prestataire d’infogérance peut provoquer une coupure plus gênante qu’une attaque. CrowdSec propose trois mécanismes complémentaires.

Les whitelists de parsing sont des parseurs de l’étape s02-enrich, placés dans /etc/crowdsec/parsers/s02-enrich/. Elles écartent des événements avant qu’ils n’atteignent les scénarios, selon une adresse (ip), une plage (cidr) ou une expression portant sur l’événement (par exemple, ignorer les requêtes GET /health d’une sonde de supervision). Le parseur crowdsecurity/whitelists, installé par défaut, écarte ainsi les adresses de bouclage et les plages privées : par défaut, une attaque venant de votre propre réseau local ne déclenche aucune alerte.

name: azur/whitelist-supervision
description: "Ne jamais sanctionner le serveur de supervision"
whitelist:
  reason: "Supervision interne"
  ip:
    - "192.0.2.50"

Les allowlists centralisées sont gérées par la LAPI avec cscli allowlists. Elles ne s’appliquent qu’aux adresses et plages, mais agissent partout : alertes locales ignorées, adresses retirées des blocklists, décisions manuelles refusées (sauf option --bypass-allowlist), contournement du WAF. Chaque entrée peut recevoir une date d’expiration, ce qui est idéal pour un audit ou un test d’intrusion autorisé.

sudo cscli allowlists create partenaires -d "Adresses de confiance"
sudo cscli allowlists add partenaires 198.51.100.10 -e 7d -d "Audit externe"
sudo cscli allowlists inspect partenaires

Le mode simulation, enfin, permet d’activer un scénario sans conséquence : les alertes sont levées et les décisions enregistrées, mais marquées comme simulées et ignorées par les bouncers. C’est la bonne façon d’introduire un nouveau scénario en production et d’observer ce qu’il aurait bloqué pendant quelques jours.

Attention : une whitelist empêche les nouvelles décisions, elle ne supprime pas celles qui existent. Après l’ajout d’une exception, retirez la décision en cours avec cscli decisions delete --ip <adresse>.

10. Profils et notifications

Le fichier /etc/crowdsec/profiles.yaml décide de ce que devient une alerte. Chaque profil comporte des filtres (à quelles alertes il s’applique), des décisions (type et durée), d’éventuelles notifications et une instruction on_success: break qui arrête l’évaluation des profils suivants. Le profil par défaut, default_ip_remediation, bannit pendant quatre heures toute adresse IP à l’origine d’une alerte qui demande une remédiation.

Deux réglages sont fréquemment utiles :

  • La durée progressive avec duration_expr : l’expression Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4) allonge le bannissement de quatre heures à chaque récidive de la même adresse.
  • Les notifications : un profil peut appeler un ou plusieurs greffons (e-mail, Slack, Teams via webhook HTTP, Splunk…) configurés dans /etc/crowdsec/notifications/. La commande cscli notifications test envoie un message d’essai sans attendre une vraie attaque.

Méfiez-vous des notifications trop bavardes : sur un serveur exposé, des dizaines d’alertes par jour sont normales. Réservez l’envoi de messages aux scénarios significatifs (tentative d’exploitation, alerte sur un serveur interne) ou à un récapitulatif, et laissez le reste dans la console ou le SIEM.

11. Déploiement multi-serveurs et WAF (AppSec)

Dès que le parc compte plusieurs serveurs, une LAPI centrale devient intéressante. Le principe est simple :

  1. sur le serveur central, la LAPI écoute sur une adresse joignable par les autres machines (paramètre api.server.listen_uri de config.yaml) ;
  2. sur chaque serveur, l’agent est installé avec sa LAPI locale désactivée, puis enregistré auprès de la LAPI centrale avec cscli lapi register ;
  3. l’administrateur valide chaque agent sur le serveur central avec cscli machines validate (ou configure un jeton d’enregistrement automatique limité à des plages d’adresses) ;
  4. les bouncers de chaque serveur sont configurés avec l’adresse de la LAPI centrale et une clé créée par cscli bouncers add.

Une attaque détectée sur un serveur produit alors une décision centrale, appliquée en quelques secondes par tous les bouncers du parc. La LAPI devient un composant critique : filtrez son port d’écoute aux seuls serveurs du parc, chiffrez les échanges en TLS hors laboratoire et sauvegardez sa base.

CrowdSec propose aussi un composant AppSec, un pare-feu applicatif (WAF) qui inspecte les requêtes HTTP transmises par un bouncer compatible (Nginx, Traefik…) et bloque en temps réel les tentatives d’exploitation de vulnérabilités connues grâce à des règles de « virtual patching ». La version 1.8 y ajoute une détection de robots par défi et empreinte navigateur, désactivée par défaut. Ce composant dépasse le cadre de ce cours d’introduction, mais il s’appuie sur les mêmes notions : LAPI, bouncers, décisions et allowlists.

Positionnement : CrowdSec analyse des journaux et des requêtes applicatives. Il complète une sonde réseau comme Suricata, qui inspecte les paquets, et un SIEM qui corrèle l’ensemble des sources. Il peut d’ailleurs lire les alertes d’autres outils grâce aux collections correspondantes du hub.

12. Synthèse et check-list d’exploitation

CrowdSec transforme les journaux de vos serveurs en décisions de blocage partagées. Sa mise en œuvre repose sur quelques choix structurants : les sources à lire, les collections adaptées aux services, le ou les bouncers qui appliqueront les sanctions, et une politique d’exceptions claire. Les huit travaux pratiques qui suivent parcourent ce cycle dans un laboratoire : installation, prise en main de cscli, blocage d’une attaque SSH, protection d’un serveur web, gestion des décisions, profils et notifications, mise au point des parseurs, puis architecture multi-serveurs.

Check-list d’exploitation

  1. Au moins un bouncer installé et visible dans cscli bouncers list.
  2. Toutes les sources de journaux lues et parsées dans cscli metrics show acquisition parsers.
  3. Adresses d’administration, de supervision et de sauvegarde déclarées en whitelist ou en allowlist.
  4. cscli hub update puis cscli hub upgrade planifiés, et paquets CrowdSec tenus à jour.
  5. Nouveaux scénarios introduits en mode simulation avant activation.
  6. Procédure écrite pour lever un faux positif (cscli decisions delete) et pour bannir manuellement une adresse lors d’un incident.

Évaluation : Introduction à CrowdSec

Répondez aux questions puis vérifiez votre score. Une seule bonne réponse par question.

1. Dans l’architecture CrowdSec, quel composant applique concrètement le blocage d’une adresse ?
2. Sur une installation par défaut, pourquoi une rafale d’échecs SSH venant de 10.0.2.20 ne déclenche-t-elle aucune alerte ?
3. Dans un scénario de type seau percé (leaky bucket), que se passe-t-il lorsque le seau d’une adresse déborde ?
4. Quelle commande permet de vérifier que les journaux sont bien lus puis analysés par les parseurs ?
5. Quelle est la durée par défaut d’un bannissement créé par le profil default_ip_remediation ?
6. Vous ajoutez en whitelist une adresse déjà bannie. Que se passe-t-il ?
7. À quoi sert le mode simulation d’un scénario ?
8. Dans une architecture multi-serveurs, quelle commande, exécutée sur la LAPI centrale, autorise un agent qui vient de s’enregistrer ?

Pour aller plus loin sur le blog : CrowdSec : l’IPS collaboratif et open source qui mutualise la défense des serveurs · Falco : détecter les menaces en temps réel sur Linux, conteneurs et Kubernetes

Défiler vers le haut