Niveau 5 · Maîtriser

Niveau 5

Les outils experts

Jeux de règles Kokiris, assistant RuleForge, révisions, cluster, performance, certificats SSL, assistant IA, comptes, revendeurs et membres, clés API et page API.

6 chapitres · ≈ 80 min · 0/6 terminé

5.1 Les protections Kokiris

Durée 10 minPrérequis niveau 2

Objectifs

• Lire la liste des failles couvertes.
• Activer le jeu de règles de son CMS sur un site.
• Déclarer le chemin du back-office d'une boutique PrestaShop ou Magento.

Kokiris publie des jeux de règles qui corrigent en quelques heures des failles récentes, avant que le site ne soit mis à jour. Le jeu Kokiris Rules s'applique à tous les sites. Les jeux par CMS se choisissent site par site : Kokiris WordPress, Kokiris PrestaShop, Kokiris Magento et Kokiris Joomla.

Protections. Chaque ligne est une faille couverte, avec sa référence CVE et les règles qui la bloquent. La cloche du haut compte les nouvelles.

1. Ouvrez la fiche du site, carte Plugins activés.
2. Cochez le jeu de votre CMS, par exemple Kokiris WordPress pour le site WordPress.
3. Pour Kokiris PrestaShop ou Kokiris Magento, renseignez aussi le Chemin du back-office dans la carte Général : le dossier /admin… renommé à l'installation de PrestaShop, ou le frontName de l'administration Magento.
4. Enregistrez, puis appliquez.

Plugins. Les jeux Kokiris portent un badge et se mettent à jour depuis cette page. Un jeu CMS affiché Désactivé ici peut être actif sur un site : il s'active site par site.

Activer ici, c'est activer partout

Le bouton « Activer » de la page Plugins active le jeu sur tous les sites. Pour un seul site, passez par sa fiche.

PrestaShop et Magento : sans chemin, pas d'exclusions pour l'administration

Les jeux Kokiris PrestaShop et Magento ne reconnaissent le back-office que sous le Chemin du back-office déclaré. Sans lui, les actions de l'administration perdent leurs exclusions, et certaines sont bloquées comme des attaques. Le chemin commence par / ; laissez le champ vide pour les autres CMS.

À retenir

• Un jeu CMS s'active dans la fiche du site, pas dans la page Plugins.
• PrestaShop et Magento : déclarez le chemin du back-office de chaque boutique.
• Mettre à jour un jeu = « Actualiser le registre », « Mettre à jour », puis « Appliquer ».
• Une règle Kokiris en détection seule signale sans bloquer et vaut 0 point (chapitre 2.4).

Vérifiez

Vous voulez activer le jeu Kokiris WordPress sur un seul de vos sites. Où cliquez-vous ?

5.2 RuleForge et règles personnalisées

Durée 15 minPrérequis chapitres 2.3 et 3.1

Objectifs

• Créer une règle sans écrire de syntaxe ModSecurity.
• Savoir quand passer aux règles personnalisées.

RuleForge part de votre besoin, pas de la syntaxe. Il pose une question, « Que souhaitez-vous faire ? », et génère la configuration :

• Bloquer une menace : une IP, un pays, un robot, un motif, ou trop de requêtes.
• Faire confiance : une IP, un chemin ou un paramètre, pour toujours ou jusqu'à une date.
• Le WAF bloque à tort : part d'un blocage récent et propose la bonne portée.
• Renforcer la protection : valider les paramètres attendus, restreindre les méthodes HTTP.

RuleForge. Pour une nouvelle règle, pensez-y en premier.

Quand RuleForge ne couvre pas votre besoin, utilisez Règles perso, comme pour la règle témoin du chapitre 2.3. Pour appliquer les mêmes règles à plusieurs sites, rassemblez-les dans un groupe, page Groupes de règles.

• Une règle que le moteur ne sait pas charger est refusée dès l'enregistrement, avec la raison donnée par le serveur, en anglais.
• Une règle allow sans site arrête toutes les règles suivantes pour les requêtes qu'elle vise : le formulaire vous prévient.
• Un motif s'écrit comme une expression régulière ordinaire : \. désigne un point, union\s+select le mot « union », des espaces, puis « select ». Avec les versions antérieures à octobre 2026, les motifs à antislash ne correspondaient jamais : une ancienne règle de ce type peut se mettre à bloquer, vérifiez ses effets dans les journaux.

Quand la règle agit-elle ?

L'écran final de RuleForge le dit. Un bannissement d'IP est « Actif immédiatement ». Tout le reste est « Enregistré, pas encore actif » : la règle attend dans les modifications en attente, cliquez sur « Appliquer » dans le bandeau. Si votre compte ne peut pas appliquer, l'écran vous dit à qui le demander.

5.3 Révisions, cluster et performance

Durée 10 minRôle administrateur

Objectifs

• Identifier le nœud leader.
• Revenir à une révision précédente.
• Lire l'état des services et alléger l'inspection des fichiers statiques.
• Lire l'usage du mois dans la page Tarification.
• Gérer les certificats SSL d'un nœud.

Selon votre offre, kokiGUARD tourne sur un ou plusieurs nœuds. Avec plusieurs nœuds, un seul, le leader, accepte les modifications : Redis Sentinel le désigne. Le leader construit la révision, l'applique, puis la publie aux autres nœuds.

Gestion du cluster. Leader actuel, nœuds en ligne, et boutons pour choisir un master préféré.

1. Pour revenir en arrière : Révisions, Voir les différences avec la version en service, puis Appliquer sur la révision validée voulue.
2. Pour contrôler les services : Performance montre les requêtes par seconde, les sessions, et l'état de HAProxy, de Coraza et de la liaison entre eux, nœud par nœud.

Performance. Le premier écran à ouvrir si un site ralentit.

Si le moteur d'inspection s'arrête

Si Coraza ne répond plus, vos sites restent joignables : HAProxy laisse passer le trafic sans inspection plutôt que de le couper. La panne n'est pas silencieuse pour autant : Performance montre le serveur coraza-spoa hors service, chaque requête non inspectée est notée en erreur dans le journal de HAProxy, et la supervision de Kokiris est alertée.

Ne pas inspecter les images, polices et vidéos

Sur une boutique, les images, polices et vidéos font souvent la majorité des requêtes. Dans Paramètres, carte Paramètres WAF par défaut, l'option Ne pas inspecter les images, polices et vidéos les laisse passer sans le moteur WAF : moins de charge, des pages plus rapides en plein pic. Elle est prise en compte au prochain Appliquer.

• Seules les requêtes GET et HEAD vers des fichiers comme .jpg, .png, .webp, .svg, .woff2 ou .mp4 sont concernées. Les fichiers .css, .js, .pdf et .map restent inspectés, tout comme un chemin aux caractères inhabituels, des paramètres autres qu'un simple anti-cache (?v=123) ou un segment .php.
• Les bannissements, les limites de débit, le blocage par pays et la vérification JavaScript s'appliquent toujours. Le volume facturé ne change pas.

Suivre l'usage dans Tarification

La page Tarification montre l'Usage courant de votre installation : le nombre de sites, de personnalisations et le volume de requêtes du mois, avec la Grille active, le Palier atteint et le Prix estimé. L'Historique du volume donne les mois précédents, et le Simulateur de prix calcule le prix d'un autre usage.

• Le palier retenu est le plus haut atteint sur l'une des trois mesures.
• Les personnalisations sont vos objets de configuration : règles perso, corrections de faux positifs, règles de trafic de confiance, groupes de règles, profils de bannissement (sauf le profil Default) et pages d'erreur personnalisées.
• Un mois commence et finit à minuit dans le Fuseau de facturation : Paramètres, carte Facturation, Europe/Paris par défaut.
• Avec une grille en mode À la consommation, le volume ne fait pas changer de palier : ce qui dépasse le Volume inclus est facturé au Prix du dépassement (€), par tranche d'Unité (requêtes).
• Les requêtes du panel kokiGUARD lui-même ne sont pas comptées.

Tarification. L'usage du mois en cours. Ici, aucune grille n'est encore active : le palier et le prix estimé restent vides.

Les Grilles tarifaires traduisent votre offre : parlez-en à Kokiris avant d'en modifier une.

Les certificats SSL

Sur un nœud hébergé chez Kokiris, la page Certificats SSL (menu Système, administrateur) gère les certificats Let's Encrypt de vos domaines : leur date d'expiration, l'ajout d'un certificat, sa suppression et le renouvellement.

1. Faites pointer le DNS du domaine vers votre kokiGUARD : Let's Encrypt le vérifie en HTTP.
2. Cliquez sur Ajouter un certificat, saisissez les domaines, un par ligne (le premier nomme le certificat, pas de joker *.), puis Vérifier le DNS.
3. Indiquez l'E-mail du compte Let's Encrypt, puis cliquez sur Créer. L'opération peut prendre plusieurs minutes.

Le certificat est installé et copié sur les autres nœuds aussitôt : il n'y a rien à appliquer. Le renouvellement est automatique, 30 jours avant l'expiration ; Renouveler maintenant le lance tout de suite pour les certificats arrivés à échéance. Sur un nœud qui n'a pas cet outil, la page indique « Certificats indisponibles » : demandez à Kokiris.

Une modification refusée avec l'erreur 409 ?

Le message, en anglais, vient du serveur. « This node is in standby mode » : vous êtes connecté à un nœud qui n'est pas leader, reconnectez-vous par l'adresse principale du panel. S'il parle de « lease » ou de « term », réessayez dans quelques secondes ; si l'erreur persiste, prévenez Kokiris.

5.4 L'assistant IA

Durée 15 minPrérequis chapitre 2.4Rôle opérateur

Objectifs

• Configurer un fournisseur d'IA et choisir les champs qu'il ne verra jamais.
• Faire expliquer un événement, puis laisser l'IA proposer une correction.
• Demander le rapport des dernières 24 heures.
• Poser une question à l'Analyste IA.

L'assistant IA explique, dans la langue du panel, ce que le WAF a vu, et aide à décider. Il fonctionne avec tout service compatible OpenAI : Mistral, DeepSeek, un modèle local via Ollama ou vLLM.

Configurer

1. Dans Paramètres, carte Assistant IA, saisissez l'URL de base de l'API, la clé et le nom du modèle. L'exemple ci-dessous utilise DeepSeek (https://api.deepseek.com/v1, modèle deepseek-flash). Kokiris peut faire ce réglage pour vous.
2. Choisissez le Style des réponses : Technique, Standard ou Pédagogue.
3. Dans Champs masqués pour l'IA, ajoutez un nom de cookie, de paramètre ou d'en-tête par ligne, par exemple un cookie de session maison. Terminez par * pour un préfixe, comme PrestaShop-*.
4. Cliquez sur Enregistrer, puis sur Tester la connexion. Une coche verte confirme.

Assistant IA configuré. La clé ne se relit jamais : elle s'affiche masquée une fois enregistrée. Le champ Champs masqués pour l'IA est vide par défaut.

Ce qui part vers le fournisseur

Le contexte envoyé se limite à la forme des valeurs et aux fragments utiles. Jamais la valeur d'un cookie ni d'un secret (mot de passe, jeton, numéro de carte) : seulement sa forme, du type <b64:44>. Les adresses IP, noms de domaine et e-mails sont remplacés par des pseudonymes, puis remis en clair par kokiGUARD au retour de la réponse. Un champ de la liste Champs masqués pour l'IA ne part qu'en forme, jamais en valeur ; dans une radiographie, le bouton en forme d'œil barré, à côté d'un nom de champ, l'ajoute à cette liste (droit d'écriture sur les paramètres). Enfin, l'IA ne consulte que ce que votre compte a le droit de voir.

Faire expliquer un événement

Dans Journaux, cliquez sur 🤖 sur une ligne. La réponse arrive en direct dans un panneau latéral. Sur une ligne qui regroupe beaucoup de requêtes, l'IA lit les 50 plus récentes, et le titre du panneau le précise.

Explication d'un blocage. L'IA a reconnu la règle témoin comme un test volontaire, et non comme une attaque. Elle explique aussi pourquoi elle ne propose aucune correction.

Laisser l'IA proposer une correction

Quand l'IA conclut à un faux positif que rien ne couvre encore, elle propose une correction, contrôlée par le serveur comme si vous l'aviez saisie. Une carte 📋 la résume et montre la règle générée. Pré-remplir l'exclusion ouvre le formulaire Corriger une règle : vous relisez, vous enregistrez, puis vous appliquez. L'IA n'enregistre jamais rien elle-même, et ce bouton demande le droit d'écrire les faux positifs.

Sur la page Faux positifs, 🤖 Analyser avec l'IA passe en revue la carte Champs qui déclenchent des règles : un verdict par champ (FAUX POSITIF, ATTAQUE ou INCERTAIN) avec sa raison, une carte de correction par famille de champs faux positifs, et une phrase de résumé par groupe de champs. L'IA reçoit les champs par petits lots, l'un après l'autre : l'analyse va toujours au bout. Un champ qu'elle n'a pas pu traiter porte NON ANALYSÉ, avec la raison : réponse trop longue même pour ce champ seul, erreur du fournisseur, ou budget de l'analyse atteint. Une analyse compte pour une seule requête du quota.

Le rapport des dernières 24 heures

Sur le Tableau de bord, le bouton 🤖 Rapport IA (24 h) ouvre un rapport de sécurité dans le même panneau latéral : volume et tendance, attaques notables, IP les plus agressives, règles les plus déclenchées, et deux ou trois recommandations au plus. Il faut le droit de lire le tableau de bord ou les journaux. Un rapport compte pour une requête du quota.

Rapport IA (24 h). Pratique pour un point du lundi matin. Comme toute réponse de l'IA, ses recommandations sont à vérifier avant d'agir.

Interroger l'Analyste IA

La page Analyste IA est une conversation. L'agent consulte lui-même les journaux, les statistiques, la réputation des IP et la configuration des sites, puis répond. Chaque outil utilisé s'affiche au fil de l'eau.

Analyste IA. L'agent a d'abord identifié « la boutique », puis fouillé les journaux et la réputation des IP. Il annonce ses hypothèses : si ce n'est pas le bon site, il suffit de le lui dire.

Vérifiez avant d'agir

Chaque réponse porte la mention « Analyse générée par IA — à vérifier avant d'agir ». L'IA propose, vous décidez. Le quota journalier (200 requêtes par défaut) protège votre budget.

Vérifiez

L'IA voit-elle l'adresse IP réelle d'un visiteur ?

5.5 Comptes, droits et clés API

Durée 10 minPrérequis chapitre 0.2Rôle administrateur ; éditeur pour ses clés API

Objectifs

• Créer un compte au profil Personnalisé.
• Comprendre les comptes revendeur et membre d'un kokiGUARD mutualisé.
• Créer une clé API pour un script, sans lui donner plus que nécessaire.
• Savoir ce qui ferme une session.

Les quatre rôles du chapitre 0.2 vont du Lecteur à l'Admin. Quand aucun ne convient, le profil Personnalisé donne une grille de droits : pour chaque page ou fonction, une case Lecture et une case Écriture, rangées en quatre groupes (Opérations, Configuration, Surveillance, Système).

1. Ouvrez Utilisateurs, puis cliquez sur Nouvel utilisateur.
2. Saisissez le Nom d'utilisateur et le Mot de passe.
3. Dans Profil, choisissez Personnalisé, puis cochez les cases utiles. Pour une agence web qui corrige ses faux positifs : Tableau de bord et Logs en lecture, Faux positifs en lecture et en écriture.
4. Cliquez sur Enregistrer.

Profil Personnalisé. Ce compte voit le tableau de bord et les journaux, et corrige les faux positifs. Rien d'autre n'apparaît dans ses menus.

• Cocher Écriture coche aussi Lecture : on ne modifie pas ce que l'on ne voit pas.
• Sans Révisions et application en écriture, le compte prépare ses corrections, et un éditeur ou Kokiris les applique.
• La ligne Utilisateurs reste réservée aux administrateurs, et le dernier administrateur ne peut pas perdre ses droits.
• Changer les droits ou le mot de passe d'un compte ferme ses sessions : il se reconnecte avec ses nouveaux droits.

Revendeurs et membres : le kokiGUARD mutualisé

Un même kokiGUARD peut protéger les sites de plusieurs clients, par exemple ceux d'une agence et de ses propres clients. Le champ Type de compte de la fenêtre Nouvel utilisateur le permet :

Type	Ce qu'il fait
Standard	Un compte ordinaire, avec un rôle ou une grille Personnalisé, sur tous les sites.
Revendeur	Une grille de droits, jamais un rôle, et une liste de sites : les siens. Il ne voit et ne modifie qu'eux : leurs corrections, leur trafic de confiance, leurs règles perso, leurs plugins, leurs robots, leurs journaux et leur tableau de bord. Un site qu'il ajoute devient le sien. Il crée ses propres comptes membres.
Membre	Un compte créé par un revendeur, sur une partie de ses sites, avec une partie de ses droits. Il ne crée ni compte ni site.

1. Un administrateur ouvre Utilisateurs → Nouvel utilisateur, choisit Revendeur dans Type de compte, coche ses droits puis ses sites, et enregistre.
2. Le revendeur, connecté, ouvre Utilisateurs : il n'y voit que ses membres. Nouvel utilisateur crée un membre, sur les sites et dans les droits qu'il choisit parmi les siens.

Un revendeur et son membre. Les droits s'affichent en pastilles ; le membre ne dépasse jamais ni les droits ni les sites de son revendeur.

Un revendeur ou un membre ne touche jamais à ce qui vaut pour tous les sites de la plateforme :

• pas d'entrée Global (tous les sites), ni de règle sur le catch-all, un joker ou un site système ;
• pas de groupe d'IP nouveau, pas de groupe de règles partagé ;
• pas de bannissement, pas de mode Challenge, pas de radar des menaces : la réputation est commune à tous les sites (chapitre 2.1). Ses règles perso bloquent, mais ne donnent aucun point de réputation ;
• pas de bouton Appliquer : l'hébergeur active l'application automatique (chapitre 2.2) ;
• une adresse de confiance doit porter une condition (chapitre 3.2).

Le site d'un autre compte lui répond comme s'il n'existait pas. Une clé API créée par un revendeur ou un membre prend son type et ses sites. Changer le type ou les sites d'un compte ferme ses sessions, et un site retiré à un revendeur est aussi retiré à ses membres.

Côté Kokiris

Sur une plateforme mutualisée, Kokiris peut aussi router chaque site vers son serveur de production (page Backends, réservée à l'administrateur) et compter les requêtes du mois par revendeur, pour la facturation.

Les clés API

Une clé API donne à un script, par exemple un outil de supervision, des droits précis sans le mot de passe d'un compte.

1. Dans Paramètres, carte Clés API, cliquez sur Nouvelle clé API.
2. Donnez un Nom, choisissez un Profil ou une grille Personnalisé, et une Expiration (jamais si le champ reste vide).
3. Validez avec Nouvelle clé API. La clé ne s'affiche qu'une fois : cliquez sur Copier et rangez-la dans le coffre de votre outil.

Le script envoie la clé dans l'en-tête Authorization. Pour vérifier les droits d'une clé, remplacez l'adresse par celle de votre panel :

terminal · droits d'une clé API

curl -s -H 'Authorization: Bearer kwaf_…' https://panel.example.com/api/v1/auth/me

• Une clé ne dépasse jamais les droits de celui qui la crée : les profils plus larges sont grisés. Si ses droits baissent ensuite, une clé devenue plus large que lui est désactivée.
• Une clé ne peut pas créer d'autre clé.
• Révoquer supprime la clé.

Clés API. Seul le préfixe de chaque clé reste visible. La colonne Dernière utilisation aide à repérer une clé oubliée, à révoquer.

Pour savoir quelle route appeler et quel droit cocher, ouvrez la page API (chapitre 5.6).

À retenir

• Personnalisé = une grille Lecture / Écriture, case par case. Les menus suivent la grille.
• Un revendeur travaille sur ses sites seulement, un membre sur une partie des sites de son revendeur.
• Une clé API ne fait jamais plus que son créateur.
• Changer les droits d'un compte ferme ses sessions.

Vérifiez

Votre agence web doit pouvoir corriger les faux positifs de vos sites, et rien d'autre. Quel profil lui donnez-vous ?

5.6 La page API

Durée 10 minPrérequis chapitre 5.5

Objectifs

• Trouver la route de l'API qui fait ce que vous voulez, et le droit qu'elle demande.
• Essayer une lecture depuis le panel, puis copier la commande curl pour un script.

Tout le panel repose sur une API REST : mêmes routes, mêmes droits. La page API, dans le menu Système, en donne la référence. Elle est ouverte à tout compte connecté.

La page API. L'encadré Démarrer, puis le nombre de routes, de domaines et de routes ouvertes avec vos droits. Un compte Lecteur y lit aussi, à l'étape 1, qu'il doit demander sa clé à un administrateur.

1. L'encadré Démarrer résume la marche à suivre : créer une clé API (chapitre 5.5), la garder dans une variable, puis appeler l'API.
2. Cherchez une route par son chemin, son résumé, sa méthode ou son droit, ou filtrez par Méthodes et par Domaines (hostnames, fail2ban, logs…).
3. Ouvrez la route. En tête, le droit qu'elle demande et si votre compte l'a : « Vous avez ce droit », ou « Droit manquant : write:fail2ban ». Pour un compte revendeur ou membre, une route qui ne vaut pas site par site (bannissements, groupes d'IP, entrées globales…) porte « Refusé à votre compte », quels que soient ses droits. Dessous, ses paramètres, son corps et ses réponses.
4. Cliquez sur Copier la commande curl : elle utilise la variable KOKIGUARD_API_KEY de l'encadré Démarrer.

Essayer une lecture. La requête part avec votre session ; la réponse s'affiche avec son code, sa durée, sa taille et son JSON repliable.

• Essayer ne sert qu'aux lectures (GET). Une écriture (POST, PUT, PATCH, DELETE) ne se lance pas depuis cette page : utilisez sa commande curl, avec une clé qui a le droit demandé.
• Le bouton openapi.json télécharge la description complète de l'API, pour Postman, Insomnia ou un générateur de client.
• Les anciennes pages /docs et /redoc n'existent plus : la page API les remplace.

À retenir

• La page API montre, route par route, le droit demandé et si vous l'avez.
• Essayer = lectures seulement, avec votre session. Pour écrire : curl et une clé API.
• Une clé n'a que les droits cochés à sa création, toujours inclus dans ceux de son créateur.
• Un compte revendeur ou membre voit « Refusé à votre compte » sur les routes qui ne valent pas site par site.

Vérifiez

Vous voulez bannir une adresse depuis un script, avec la route POST /api/v1/fail2ban/ban. Comment la testez-vous ?

Ce que vous savez maintenant

• Lire la liste des protections Kokiris, activer le jeu de votre CMS sur un site et, pour PrestaShop ou Magento, déclarer le chemin du back-office.
• Créer une règle avec RuleForge, et savoir quand passer aux règles personnalisées.
• Comparer et réappliquer une révision, identifier le nœud leader, lire la page Performance et l'usage du mois.
• Faire expliquer un événement par l'IA, la laisser proposer une correction, et savoir ce qu'elle voit.
• Gérer les certificats SSL d'un nœud.
• Créer un compte au profil Personnalisé, un revendeur et ses membres, et une clé API limitée.
• Trouver une route dans la page API, le droit qu'elle demande, et l'essayer ou la copier en curl.