Aide-mémoire
Les signaux HTTP, le vocabulaire, les étapes de la mise en service et la commande kokiguard, à garder sous la main.
R.2 Reconnaître une réponse de kokiGUARD
| Situation | Code | Signal visible par le client |
|---|---|---|
| Bloqué par une règle | 403 | En-tête x-waf-action: blocked et page de blocage avec un identifiant, repris par l'en-tête X-Request-ID |
| Bloqué par pays | 403 | En-tête X-Geo-Blocked: 1 |
| Robot bloqué | 403 | En-tête X-Bot-Blocked : le nom du robot, ou impostor pour un usurpateur |
| Challenge demandé | 403 | Page du challenge sur une page web, qu'un navigateur résout seul ; 403 sans page pour un autre type de requête |
| Corps plus grand que la taille inspectée | 413 | En-tête x-waf-action: body-too-large |
| Limite de débit dépassée | 429 | En-tête retry-after: 60 |
| File d'attente pleine | 429 | En-tête retry-after: 10 et page d'attente |
| Mode maintenance | 503 | Page de maintenance |
| Vérification JavaScript | 200 | Page de calcul à la place du site ; un navigateur passe seul |
| IP bannie | — | Connexion coupée ou délai dépassé, selon la méthode de bannissement |
| Site en mode Détecter | 200 | Aucun signal : regardez les journaux |
R.3 Glossaire
| Terme | Définition |
|---|---|
| WAF | Pare-feu applicatif web. Il lit le contenu des requêtes HTTP, là où un pare-feu réseau ne voit que des adresses et des ports. |
| AS | Système autonome : le réseau (hébergeur, opérateur, fournisseur de cloud) qui annonce une adresse IP sur Internet. Badge à côté de chaque adresse, onglet du radar des menaces. |
| CRS | OWASP Core Rule Set : le jeu de règles libre de référence, utilisé par kokiGUARD via le moteur Coraza. |
| Score d'anomalie | Total des points ajoutés par les règles qui réagissent à une requête. Au-delà du seuil du site, la requête est bloquée. |
| Paranoïa (PL) | Niveau de sévérité des règles, de 1 à 4. Plus il est haut, plus il détecte, et plus il produit de faux positifs. Réglé avec Kokiris. |
| Phase de training | Période de mise en service où Kokiris ajoute tous vos sites en mode Détecter, corrige les faux positifs et ajuste la configuration, avant le passage en Bloquer puis en Bannir. |
| Faux positif | Requête légitime prise pour une attaque. Se corrige avec la portée la plus étroite possible, sur une ou plusieurs règles et un ou plusieurs champs. |
| Radiographie | Vue complète d'une requête récente : son issue et son code HTTP, son score, la requête reconstituée avec ce qui a déclenché, les statistiques du champ sur 24 h et la correction qui le couvre déjà. |
| Trafic de confiance | Trafic exempté d'inspection (« Ne pas inspecter ») ou forcé à l'inspection (« Toujours inspecter »). |
| Groupe d'IP | Liste nommée d'adresses (IP ou CIDR), réutilisable par les règles de chemin du trafic de confiance, en « Ne pas inspecter » ou « Accès réservé » (403 pour les autres adresses). |
| Réputation | Points cumulés par une IP en mode Bannir ou Challenge, qui décident de son bannissement ou de son challenge. |
| Challenge | Calcul (preuve de travail) qu'un navigateur fait seul en moins d'une seconde, et qu'un script simple ne fait pas. Remplace le ban en mode Challenge, et sert d'action envers un robot. |
| Robot vérifié, usurpateur | Un robot vérifié a le User-Agent d'un robot connu et une adresse dans les plages publiées par son éditeur. Un usurpateur a ce User-Agent, mais une adresse hors de ces plages. |
| Condition | Critère sur la requête (en-tête, paramètre, cookie…) qui limite une correction ou une entrée de confiance aux requêtes qui le remplissent. |
| Corps trop grand | Requête dont le corps dépasse la taille que kokiGUARD inspecte : refusée en 413 ou laissée passer, selon le site. |
| Application automatique | Réglage qui fait appliquer les modifications en attente par le leader, quand elles n'ont pas changé depuis 90 secondes. |
| Prison | File de bannissement Fail2Ban, avec sa durée : 10 min, 6 h, 24 h ou permanente. |
| Révision | Version complète et validée de la configuration, que l'on peut comparer et réappliquer. |
| Chemin du back-office | Dossier de l'administration d'une boutique PrestaShop ou Magento, déclaré dans la fiche du site. Les jeux Kokiris ne reconnaissent le back-office que sous ce chemin. |
| Profil Personnalisé | Grille de droits Lecture / Écriture, page par page, pour un compte ou une clé API. Les menus suivent la grille. |
| Revendeur, membre | Comptes d'un kokiGUARD mutualisé, limités à leurs sites. Le revendeur crée ses membres, dans ses droits et parmi ses sites. |
| Clé API | Accès d'un script au panel, sans mot de passe. Ses droits ne dépassent jamais ceux de son créateur. |
| Leader | Nœud du cluster qui accepte les modifications et les diffuse aux autres. |
| Détection des scanners | Compte, par adresse, les réponses d'erreur des sites. Au-delà du seuil, l'adresse apparaît dans les journaux (« Scan · N/min ») et, en mode Bannir, elle est bannie de tous les sites. |
| Règle en détection seule | Règle d'un jeu Kokiris qui signale sans bloquer : 0 point, au score comme pour le bannissement. |
| Règle témoin | Règle inoffensive qui bloque une requête connue, pour vérifier que le WAF applique bien les règles. |
R.4 Les étapes de la mise en service
Pour suivre l'avancement avec Kokiris. Les cases se cochent pour vous aider ; elles restent dans ce navigateur.
R.5 kokiguard (shell)
Pour les administrateurs qui ont un accès root à un nœud kokiGUARD, en général chez Kokiris. Sans accès shell, faites la même chose dans le panel : Gestion du cluster (chapitre 5.3) et Fail2Ban (chapitre 4.1).
| Commande | Effet |
|---|---|
kokiguard status | Le cluster vu par ce nœud : leader (★), terme, et pour chaque nœud son rôle, son état et la révision appliquée. |
kokiguard ban <ip|cidr> [--jail <prison>] | Bannit une adresse ou un réseau sur tout le cluster, par le leader : le ban est dans l'historique et le journal d'audit. Prison par défaut : waf-ban-10m. |
kokiguard unban <ip|cidr> | Retire l'adresse de toutes les prisons, sur tout le cluster. |
kokiguard check | Contrôle de santé de ce nœud, en lecture seule : services, API, haproxy -c, Redis, bans, détection des scanners, version, disques. Code de sortie Icinga : 0 OK, 1 WARNING, 2 CRITICAL, 3 UNKNOWN. |
kokiguard update | Met à jour ce nœud et ses nœuds distants. Rien n'est fait si la version publiée est déjà installée. En cluster, lancez-la sur le nœud qui déploie le cluster (node-1). |
kokiguard help <commande> | Le détail d'une commande et de ses options. |
terminal · root sur un nœud
kokiguard status
kokiguard ban 203.0.113.0/24 --jail waf-ban-24h
kokiguard unban 203.0.113.0/24
--local : seulement en secours
kokiguard ban --local et kokiguard unban --local passent par Fail2Ban sur ce nœud seulement, quand l'API ou le leader ne répond pas. Les autres nœuds ne sont pas prévenus, et l'action n'est ni dans l'historique ni dans le journal d'audit. Dès que l'API répond, refaites l'action sans --local.
Installation, réparation, bascule du leader et reprise d'urgence : voir le guide d'installation INSTALL.md du dépôt kokiGUARD.