Bot Protection n'agit jamais seul : votre serveur applique l'action qu'il répond. Le mode détermine quelle est cette action.
Mode monitor
Chaque nouveau compte commence ici. L'action de chaque réponse est allow, donc personne n'est arrêté, et intended_action indique ce que ferait le mode block. La vue d'ensemble du tableau de bord compte combien de décisions le mode block aurait bloquées ou soumises à un challenge. Ajoutez l'appel, déployez, et observez quelques jours.
Mode block
Il s'active dès qu'un de vos domaines est protégé : la première décision de votre serveur sur un visiteur de vos pages qui n'est pas un bot l'ajoute, et la page de challenge ne renvoie les visiteurs que vers un domaine protégé. Tant que le mode block est actif, votre dernier domaine protégé ne peut pas être retiré. Sur votre propre machine, il s'active dès que le tag a tourné sur une page en localhost : tant qu'aucun de vos domaines n'est protégé, la page de challenge ne renvoie alors que les visiteurs de cette machine. Vous pouvez aussi ajouter un domaine à la main sur la page Set-up.
Activez-le dans la carte Mode de la page Configuration : il s'applique dès la requête suivante. L'action est alors celle que vous avez choisie pour la classe du visiteur :
| Classe | Action par défaut | Signifie |
|---|---|---|
| human high | allow | une personne, avec une preuve extérieure à la session |
| human | allow | une personne dont votre propre feedback se porte garant |
| unknown | allow | pas assez d'éléments dans un sens ou dans l'autre ; la plupart des premières visites |
| bot | challenge | de l'automatisation, d'après ce que fait le client |
| bot high | block | de l'automatisation, avec de fortes preuves |
Vous pouvez changer l'action de n'importe quelle classe dans la même carte. Revenir au mode monitor est tout aussi rapide.
Ce que chaque action signifie pour votre code
allow: continuez comme si Bot Protection n'était pas là.challenge: demandez davantage avant de continuer : votre CAPTCHA, une vérification par e-mail ou téléphone, un chemin plus lent. Sans rien de tout cela, continuez.block: refusez l'action. Répondez avec le même message qu'une inscription échouée, pour qu'un bot n'apprenne rien.
Le mode block n'empêche jamais une page de se charger. Bot Protection juge seulement les actions sur lesquelles votre serveur l'interroge (une inscription, une connexion, un checkout) : un bot bloqué voit donc toujours votre site ; ce qu'il ne peut pas mener à bien, c'est l'action.
La page de challenge
Sans vérification à vous, envoyez le visiteur challengé vers la nôtre. En mode block, une réponse dont l'action est challenge porte challenge.url : redirigez-y le navigateur, avec &r= et l'adresse où revenir, sur l'un de vos domaines. La page fait résoudre au navigateur une petite preuve de travail, quelques secondes au plus, puis le renvoie à cette adresse avec kz_token ajouté. Le middleware garde ce token dans le cookie _kz, et pendant les 30 minutes suivantes le challenge de cette session devient allow, avec challenge.passed à true.
Les SDK s'en chargent : sur un chargement de page (GET) sans onChallenge, protect, withKorzen et le Protect de Go y envoient le visiteur, puis à son retour gardent kz_token et le renvoient à la même adresse sans lui. Ils n'acceptent le token que d'un navigateur qu'ils ont eux-mêmes envoyé à la page : un lien portant le token de quelqu'un d'autre n'implante rien. L'envoi d'un formulaire ou un appel d'API en challenge est refusé avec 403 : challengez la page qui affiche le formulaire, et son pass laisse passer l'envoi. Un hook à vous envoie le visiteur avec challengeRedirect(d, returnTo) (en Go, korzen.SendToChallenge), qui marque le navigateur de la même façon. L'adresse de retour est celle que le visiteur a demandée, avec l'hôte et le schéma de X-Forwarded-Host et X-Forwarded-Proto quand votre proxy les pose, sinon ceux de Host. Derrière un proxy qui transmet Host: localhost et aucun des deux, comme nginx par défaut, donnez à publicURL (en Go, PublicURL) l'origine de votre site, par exemple https://shop.example. La page ne renvoie un visiteur vers localhost que si le tag a vu la page du visiteur sur localhost aussi et que l'IP de la décision était en loopback ou une adresse privée (une app dans Docker sur votre machine voit celle du bridge, comme 172.17.0.1). Derrière un proxy, la page d'un visiteur est sur votre domaine : la page ne l'envoie donc jamais vers localhost.
Un navigateur sans JavaScript attend à la place : quelques secondes, plus pour un puzzle plus difficile, puis la page continue d'elle-même et donne le même pass. Aucun retour ne saute la page. La preuve de travail, ou l'attente, fait payer chaque session automatisée pour son inscription ; seule, elle n'arrête pas un bot déterminé.
Une action qui demande le tag
Un script qui imite un navigateur et envoie chaque requête depuis une nouvelle adresse n'exécute jamais votre page : il est donc unknown, pas bot, comme une personne dont le bloqueur de publicités arrête le tag. Sur une action où cela ne suffit pas, comme rejoindre une file, une inscription ou un checkout, envoyez "require_token": true avec la décision (l'option requireToken des SDK, en Go RequireToken). Sans token valide du tag, la réponse est challenge avec token_required à true, quelle que soit la classe ; la classe elle-même ne change pas, et en monitor mode c'est l'intended_action. Un token fait l'action une fois par heure et par session, dépensé par l'envoi du formulaire, jamais par le chargement de la page qui l'affiche : jusqu'à trois essais en deux minutes sont le même essai (une carte refusée, une faute de frappe), et un essai plus tard reçoit la réponse donnée sans token ; un navigateur, c'est donc une place dans la file. L'option des SDK ne l'envoie qu'avec les envois.
Un visiteur envoyé à la page de challenge depuis une telle action n'a pas d'attente sans JavaScript : la page demande la preuve de travail et que notre tag s'y exécute, et cela donne un nouveau token pour l'action : un script qui résout la preuve de travail sans exécuter notre tag ne passe pas. Les personnes qui ont désactivé JavaScript ne passent pas ; n'envoyez donc require_token que sur les actions qui en ont besoin. Un envoi de formulaire sous challenge reçoit le 403 des SDK : pour envoyer plutôt le visiteur vers la page, faites-le dans onChallenge avec challengeRedirect(d, returnTo) vers la page du formulaire (en Go, korzen.SendToChallenge). Quand Bot Protection est en panne ou lent, votre serveur laisse toujours passer le visiteur.
require_token rend plus coûteux de faire une action sans vraie visite : le navigateur du visiteur doit exécuter notre tag sur votre page (ou sur la page de challenge) et gagner un token lié à ce navigateur et à ce réseau, dépensé une fois. Ce n'est ni un CAPTCHA ni la preuve d'une personne : un bot bien financé qui imite un navigateur peut encore gagner des tokens, lentement et à un coût, et notre classification et la détection des fermes jugent ces sessions comme toutes les autres.
Mettre en pause
L'interrupteur de protection de la page Configuration met tout en pause sans déploiement : chaque réponse est allow, rien n'est enregistré ni facturé.