Niveau 2 · Protéger
Vous activez le WAF sur un site, vous appliquez la configuration, puis vous vérifiez avec une règle témoin qu'une règle est réellement active. Les exemples utilisent un site WordPress. Pendant la phase de training, Kokiris fait ces réglages pour vous : ce niveau vous apprend à les comprendre et à les refaire.
2.1 Activer le WAF et choisir un mode
- Activer le WAF sur un site.
- Choisir entre Détecter, Bloquer, Challenge et Bannir.
1Détecter
Le WAF analyse et journalise tout, mais ne bloque rien.
Le mode de la phase de training : on repère les faux positifs sans gêner les visiteurs.
2Bloquer
Les requêtes dont le score atteint le seuil reçoivent une page 403.
À la fin du training, quand Kokiris a validé que les journaux sont propres.
3Challenge
Bloque comme Bloquer, et ajoute des points de réputation à l'IP. Au seuil du profil, l'IP doit résoudre un challenge dans son navigateur au lieu d'être bannie.
Quand un ban serait trop brutal : clients derrière une même adresse, robots qu'on veut ralentir sans couper des humains (chapitre 4.5).
4Bannir
Bloque, et ajoute des points de réputation à l'IP. Au-delà d'un seuil, Fail2Ban la bannit.
Ensuite, sur un site stabilisé, avec l'accord de Kokiris.
Détecter, c'est la caméra qui filme sans intervenir. Bloquer, c'est le vigile qui refuse l'entrée. Challenge, c'est le vigile qui, à force de refus, demande à l'insistant de montrer patte blanche avant de revenir. Bannir, c'est le vigile qui refuse l'entrée et retient le visage : la prochaine fois, la porte reste fermée un moment.
- Dans Sites, cliquez sur ✏️ Modifier sur la ligne du site.
- Dans la carte Général, section Chaîne de protection, cochez WAF activé.
- Choisissez Détecter, puis cliquez sur Enregistrer les modifications en bas de la page. Les quatre modes forment une chaîne : la carte du mode choisi et celles qu'il comprend s'affichent en couleur.
La fiche du site. WAF activé, mode Détecter. Cochez la case Protéger aussi sous Alias pour que l'alias www. hérite des mêmes réglages. Le champ Chemin du back-office ne sert qu'aux boutiques PrestaShop et Magento (chapitre 5.1).
Le site est enregistré, mais le WAF ne l'applique pas encore. C'est l'objet du chapitre suivant.
Avec un compte revendeur ou membre (chapitre 5.5), les cartes Challenge et Bannir sont grisées, avec le message « Protection par bannissement mutualisée, opérée par l'hébergeur » : un ban vaut pour tous les sites de la plateforme, donc l'hébergeur seul le pilote. Un site que vous créez démarre en Bloquer, et un site déjà en Bannir le reste.
Vous mettez en ligne un nouveau site aujourd'hui. Quel mode choisissez-vous en premier ?
2.2 Appliquer une modification
- Comprendre pourquoi une modification n'est pas active tout de suite.
- Appliquer, puis revenir en arrière si besoin.
Chaque modification est d'abord enregistrée comme « en attente ». Vous pouvez ainsi préparer plusieurs changements et les appliquer en une seule fois, au moment choisi.
- Repérez le bandeau en haut de l'écran : Appliquer, Annuler et le lien voir.
- Cliquez sur voir pour relire la liste des changements dans Révisions.
- Cliquez sur Appliquer.
Des modifications attendent. Le bandeau reste visible tant que vous n'avez ni appliqué ni annulé.
Ce qui se passe quand vous cliquez sur Appliquer
- kokiGUARD construit une nouvelle révision de la configuration et la valide hors ligne.
- Il prend un instantané de la configuration en service.
- Il installe la nouvelle configuration, redémarre Coraza, puis recharge HAProxy sans couper les connexions.
- En cas d'échec, il remet automatiquement l'instantané en place. Le message d'échec donne la révision remise en place.
- Les autres nœuds du cluster récupèrent la même révision.
Le bouton Appliquer n'apparaît que pour un compte qui a le droit d'appliquer (rôle éditeur, ou ligne Révisions et application cochée en écriture). Sans ce droit, vos modifications attendent qu'un éditeur ou Kokiris les applique.
L'application automatique
Si l'option Appliquer automatiquement les modifications en attente est cochée (Paramètres, carte Actions système, administrateur), vous n'avez plus à cliquer :
- le leader applique lui-même quand les modifications en attente n'ont pas changé depuis 90 secondes, et au plus tard 5 minutes après la première. Une série de modifications ne fait donc qu'un seul rechargement ;
- il passe par les mêmes contrôles qu'Appliquer : validation, instantané, restauration en cas d'échec ;
- le bandeau devient « Modifications en attente — application automatique », avec l'heure du dernier Appliquer ;
- un échec s'affiche dans un bandeau pour les comptes qui peuvent appliquer, et va au journal d'audit. Aucun nouvel essai n'est fait avant votre prochaine modification.
Un compte revendeur ou membre n'a jamais le bouton Appliquer : sur une plateforme mutualisée, l'hébergeur active l'application automatique, et ces comptes voient « application automatique » à sa place.
Un Appliquer vide les compteurs de HAProxy : limites de débit, file d'attente, détection des scanners. L'attente de 90 secondes regroupe vos modifications pour éviter des rechargements en rafale.
Révisions. Chaque application laisse une révision validée, que vous pouvez comparer ou réappliquer.
- Enregistrer prépare. Appliquer met en service.
- Une application ratée se répare seule : l'instantané précédent est restauré.
Vous avez enregistré trois modifications sur trois sites différents. Combien de fois devez-vous cliquer sur « Appliquer » ?
2.3 Vérifier avec une règle témoin
- Créer une règle personnalisée inoffensive.
- Prouver avec curl qu'une règle est inactive, puis active.
- Reconnaître une réponse bloquée par kokiGUARD.
Une règle témoin bloque une requête que personne n'envoie par hasard. Elle ne gêne donc aucun visiteur, et elle vous donne un test fiable à rejouer après chaque changement.
C'est la sirène d'alerte testée le premier mercredi du mois à midi : on vérifie que l'alarme fonctionne, sans qu'il y ait d'incendie.
- Ouvrez Règles perso, puis cliquez sur + Ajouter une règle.
- Remplissez : Nom de la règle Règle témoin kokiGUARD, Site votre site, Variables
ARGS:kokiguard-test, Opérateur@streq, Valeur de l'opérateurbloque-moi, Actionsdeny, Sévérité Critique. - Cliquez sur Enregistrer. N'appliquez pas encore.
La règle témoin. Elle refuse toute requête dont le paramètre kokiguard-test vaut exactement bloque-moi.
Test 1 : règle enregistrée mais pas appliquée
curl -s -o /dev/null -w '%{http_code}\n' 'https://www.votre-site.fr/?kokiguard-test=bloque-moi'
200
Remplacez www.votre-site.fr par l'adresse de votre site. La requête passe : la règle existe dans le panel, mais pas encore dans le WAF.
Test 2 : après « Appliquer »
curl -s -D - -o /dev/null 'https://www.votre-site.fr/?kokiguard-test=bloque-moi'
HTTP/2 403
x-waf-action: blocked
cache-control: no-cache
content-length: 3157
content-type: text/html; charset=UTF-8
alt-svc: h3=":443"; ma=60
Deux signes prouvent que c'est kokiGUARD qui bloque : le code 403 et l'en-tête x-waf-action: blocked.
Test 3 : une requête normale passe toujours
curl -s -o /dev/null -w '%{http_code}\n' 'https://www.votre-site.fr/?kokiguard-test=bonjour'
200
Ce que voit un visiteur bloqué. Une page 403 en français ou en anglais (bouton 🌐 en bas à droite), avec le nom du site et un identifiant de requête à communiquer au support. Le même identifiant figure dans l'en-tête X-Request-ID, dans les journaux de kokiGUARD et dans ceux de HAProxy.
Dans Paramètres, carte Pages d'erreur, le bouton ⬆️ Téléverser remplace la page de Blocage WAF (403), de Limite de débit (429), d'Erreur WAF (500) ou du Challenge de preuve de travail par votre fichier HTML, de 14 Ko au plus (rôle éditeur). Un téléversement, comme une réinitialisation, crée une modification en attente : la nouvelle page est servie après Appliquer. Écrivez %% pour chaque % de la page, dans le texte comme dans le CSS (width: 100%%) : un % seul fait refuser le fichier. Pour afficher le nom du site et l'identifiant de requête, reprenez %[var(txn.host)] et %[var(txn.coraza.id)] de la page par défaut. 📄 Aperçu montre le rendu final, et 🔄 Réinitialiser remet la page d'origine. Une mise à jour de kokiGUARD ne remplace jamais une page que vous avez personnalisée.
Sous la liste, Logo de la page de challenge place votre logo (SVG, PNG ou WebP de 12 Ko au plus) sur la page du challenge par défaut (chapitre 4.5). Il apparaît après Appliquer.
Pages d'erreur. Les quatre pages servies par défaut. Après un téléversement, le badge change et le bouton 🔄 Réinitialiser apparaît.
L'action deny bloque tout de suite, sans passer par le score d'anomalie. Réservez-la aux cas certains, comme cette règle témoin. Les règles du CRS, elles, respectent le mode du site.
Vous venez d'enregistrer une règle et curl renvoie encore 200. Quelle est la cause la plus probable ?
2.4 Lire les journaux
- Retrouver une requête bloquée.
- Lire un score d'anomalie et l'issue d'une requête.
- Ouvrir la radiographie d'une requête.
La page Journaux montre chaque requête inspectée, sur tous les nœuds du cluster. En mode Détecter, c'est ici que vous voyez ce qui aurait été bloqué.
Journaux WAF. Des robots y cherchent des fichiers sensibles (/proc/self, /composer.lock) ou testent des injections. Sur l'espace pro, en mode Détecter, l'issue est le code rendu par le site (ici 404) : la requête n'a pas été bloquée.
Lire le score et l'issue
Chaque règle qui réagit ajoute des points selon sa sévérité : critique 5, erreur 4, avertissement 3, notice 2. Quand le total atteint le seuil du site (5 par défaut), la requête est bloquée en mode Bloquer ou Bannir.
Certaines règles des jeux Kokiris sont en détection seule : elles signalent une requête douteuse sans jamais la bloquer. Elles valent 0 point, au score comme pour le bannissement : leur ligne apparaît dans les journaux avec un score de 0.
Un contrôle à l'aéroport : chaque indice suspect ajoute des points. À 5 points, on ouvre la valise. En mode Détecter, on note et on laisse passer ; en mode Bloquer, on ne laisse pas passer.
À côté du score, une pastille donne ce qui est vraiment arrivé à la requête. Le tableau de bord affiche la même pastille.
| Pastille | Signification |
|---|---|
| BLOQUÉE | kokiGUARD a bloqué la requête : elle n'a pas atteint le site. |
Un code HTTP : 200, 302, 404… | La requête est passée, et le site a répondu ce code. C'est ce que vous voyez en mode Détecter. |
| passée | La requête est passée, mais son code HTTP n'est plus connu. |
| ↩ réponse | Une règle a réagi à la réponse du site, par exemple une page d'erreur qui en dit trop, et pas à la requête du visiteur. |
| Corps trop grand · refusé (413) | Le corps de la requête dépassait la taille que kokiGUARD inspecte : il a été refusé. Aussi « · passé » ou « · upload » quand il a été laissé passer (chapitre 3.3). Pas de score : ce n'est pas une attaque. |
À côté de chaque adresse IP, un badge donne son AS : le réseau qui l'annonce sur Internet, par exemple un hébergeur, un opérateur mobile ou un fournisseur de cloud. Un clic sur le badge ouvre ce réseau dans le radar des menaces (chapitre 4.2).
- Filtrez sur votre site et votre IP pour retrouver vos tests.
- Passez en vue Regroupés pour voir les motifs répétés, ou restez en Chronologie pour voir chaque requête.
- Cliquez sur une ligne pour voir les règles déclenchées et leurs points, puis sur 🔍 Détails : la fenêtre Détails du journal montre la règle, le côté (requête ou réponse) et les en-têtes.
- Pour retrouver une requête précise, collez dans Rechercher par Request ID l'identifiant affiché sur la page de blocage (voir Que faire si…).
La radiographie d'une requête
Pour une requête récente, le bouton 🔬 Radiographie de la fenêtre Détails du journal rassemble sur un seul écran tout ce que kokiGUARD sait d'elle :
- l'issue : BLOQUÉE ou PASSÉE, avec le code HTTP du site quand il est connu, le nom du site et son mode ;
- le score d'anomalie face au seuil du site. En mode Détecter, une ligne prévient quand la requête aurait été bloquée en mode blocage ;
- la requête reconstituée : chaque champ qui a fait réagir une règle est marqué du numéro de cette règle, et le fragment en cause est surligné quand il figure tel quel dans la valeur. Les cookies n'apparaissent que par leur nom et leur longueur, jamais par leur valeur ;
- Ce qui a déclenché : chaque règle, avec son champ, son fragment et son côté (requête ou réponse) ;
- Ce champ sur 24 h : le nombre de détections, d'IP différentes, et la part de l'IP la plus active. De quoi voir si le champ gêne beaucoup de visiteurs ou une seule source ;
- Corrections actives : la correction qui couvre déjà ce champ, s'il y en a une.
Radiographie d'une requête bloquée. Le champ en cause porte le numéro de la règle qui a réagi, et le fragment est surligné. Les statistiques sur 24 h disent si ce champ gêne beaucoup de visiteurs ou une seule source.
Si la requête est légitime, Corriger ce faux positif ouvre le formulaire de correction déjà rempli avec le champ en cause et les règles qui ont réagi sur lui (chapitre 3.1).
- Les journaux sont votre source de vérité, surtout en mode Détecter.
- Score ≥ seuil du site = requête bloquée (hors mode Détecter). La pastille dit ce qui s'est vraiment passé.
- La radiographie montre le champ et le fragment exacts qui ont fait réagir le WAF.
Sur une requête, deux règles d'avertissement (3 points chacune) ont réagi. Le site est en mode Bloquer, avec le seuil par défaut. Que se passe-t-il ?
- Activer le WAF sur un site et choisir entre Détecter, Bloquer, Challenge et Bannir.
- Faire la différence entre enregistrer et appliquer, revenir en arrière avec les révisions, et reconnaître l'application automatique.
- Prouver avec une règle témoin et curl qu'une règle est active.
- Lire un score d'anomalie et l'issue d'une requête dans les journaux, puis ouvrir sa radiographie.