Bot Protection grijpt nooit zelf in: je server voert de action uit die het antwoordt. De modus bepaalt wat die actie is.
Monitor mode
Elk nieuw account begint hier. De action van elk antwoord is allow, dus niemand wordt tegengehouden, en intended_action zegt wat block mode zou doen. Het overzicht in het dashboard telt hoeveel beslissingen block mode zou hebben geblokkeerd en met een challenge zou hebben beantwoord. Zet de call erin, deploy, en kijk een paar dagen mee.
Block mode
Het kan aan zodra een van je domeinen beschermd is: de eerste beslissing van je server over een bezoeker van je pagina's die geen bot is, voegt het toe, en de challenge-pagina stuurt bezoekers alleen terug naar een beschermd domein. Zolang block mode aan staat, kan je laatste beschermde domein niet worden verwijderd. Op je eigen machine kan het aan zodra de tag op een pagina op localhost draaide: tot een van je domeinen beschermd is, stuurt de challenge-pagina dan alleen bezoekers op die machine terug. Je kunt een domein ook met de hand toevoegen op de Set-up-pagina.
Zet het aan in de kaart Modus op de pagina Set-up; het geldt vanaf de volgende request. De action is dan de actie die je voor de klasse van de bezoeker hebt ingesteld:
| Klasse | Standaardactie | Betekent |
|---|---|---|
| human high | allow | een mens, met bewijs van buiten de sessie |
| human | allow | een mens voor wie je eigen feedback instond |
| unknown | allow | niet genoeg bewijs, de ene of de andere kant op; de meeste eerste bezoeken |
| bot | challenge | automatisering, op basis van wat de client doet |
| bot high | block | automatisering, met sterk bewijs |
In dezelfde kaart kun je de actie van elke klasse aanpassen. Terug naar monitor mode gaat net zo snel.
Wat elke actie betekent voor je code
allow: ga door alsof Bot Protection er niet is.challenge: vraag om meer voordat je doorgaat: je CAPTCHA, een controle per e-mail of telefoon, een tragere route. Heb je niets daarvan, ga dan door.block: weiger de actie. Antwoord met dezelfde melding als bij een mislukte registratie, zodat een bot niets leert.
Block mode houdt nooit een pagina tegen bij het laden. Bot Protection beoordeelt alleen de acties waarnaar je server vraagt (een registratie, een login, een checkout), dus een geblokkeerde bot ziet je site nog; wat hij niet kan afronden, is de actie.
De challengepagina
Heb je geen eigen controle, stuur een uitgedaagde bezoeker dan naar de onze. In block mode bevat een antwoord met action challenge het veld challenge.url: stuur de browser daarheen, met &r= en het adres om naar terug te keren, op een van je domeinen. De pagina laat de browser een kleine proof of work oplossen, hooguit een paar seconden, en stuurt hem dan terug naar dat adres met kz_token erbij. De middleware bewaart dat token als de cookie _kz, en de volgende 30 minuten is de challenge van die sessie allow, met challenge.passed op true.
De SDK's doen het voor je: bij het laden van een pagina (GET) zonder onChallenge sturen protect, withKorzen en Protect in Go de bezoeker daarheen, en als hij terugkomt bewaren ze kz_token en sturen ze hem door naar hetzelfde adres zonder. Ze nemen het token alleen aan van een browser die ze zelf naar de pagina stuurden, dus een link met het token van iemand anders plant niets. Een verstuurd formulier of een API-call met een challenge wordt geweigerd met 403: daag de pagina uit die het formulier toont, en de pass laat het formulier door. Een eigen hook stuurt de bezoeker met challengeRedirect(d, returnTo) (in Go korzen.SendToChallenge), die de browser op dezelfde manier markeert. Het adres om naar terug te keren is het adres dat de bezoeker opvroeg, met host en schema uit X-Forwarded-Host en X-Forwarded-Proto als je proxy die zet, anders uit Host. Achter een proxy die Host: localhost doorgeeft en geen van beide, zoals nginx standaard doet, geef je publicURL (in Go PublicURL) de origin van je site, zoals https://shop.example. De pagina stuurt een bezoeker alleen terug naar localhost als de tag de pagina van de bezoeker ook op localhost zag en het IP van de beslissing loopback of een privéadres was (een app in Docker op je eigen machine ziet dat van de bridge, zoals 172.17.0.1). Achter een proxy staat de pagina van een bezoeker op je domein, dus stuurt de pagina hem nooit naar localhost.
Een browser zonder JavaScript wacht in plaats daarvan: een paar seconden, langer bij een moeilijkere puzzel, en dan gaat de pagina vanzelf verder en geeft dezelfde pass. Er is geen weg terug die de pagina overslaat. De proof of work, of het wachten, laat elke geautomatiseerde sessie betalen voor zijn aanmelding; op zichzelf houdt hij een vastberaden bot niet tegen.
Een actie die de tag nodig heeft
Een script dat een browser nadoet en elk verzoek vanaf een nieuw adres stuurt, voert je pagina nooit uit, dus is het unknown, geen bot, net als iemand wiens adblocker de tag tegenhoudt. Bij een actie waar dat niet genoeg is, zoals in een wachtrij gaan, een aanmelding of een checkout, stuur je "require_token": true mee met de beslissing (de optie requireToken van de SDK's, in Go RequireToken). Zonder geldige token van de tag is het antwoord challenge met token_required true, welke klasse ook; de klasse zelf verandert niet, en in monitor mode is het de intended_action. Een token doet de actie één keer per uur per sessie, besteed door het versturen van het formulier, nooit door het laden van de pagina die het toont: tot drie pogingen binnen twee minuten zijn dezelfde poging (een geweigerde kaart, een typfout), en een latere krijgt het antwoord als zonder token, dus één browser is één plek in de wachtrij. De optie van de SDK's stuurt het alleen bij het versturen.
Een bezoeker die vanaf zo'n actie naar de challengepagina gaat, heeft zonder JavaScript geen wachttijd: de pagina vraagt de proof of work en dat onze tag erop draait, en dat geeft een nieuwe token voor de actie: een script dat de proof of work oplost zonder onze tag uit te voeren, komt er niet door. Wie JavaScript uit heeft staan, komt er niet door, dus stuur require_token alleen bij de acties die het nodig hebben. Een formulierpost onder challenge krijgt de 403 van de SDK's: om de bezoeker in plaats daarvan naar de pagina te sturen, doe je dat in onChallenge met challengeRedirect(d, returnTo) naar de pagina van het formulier (in Go korzen.SendToChallenge). Als Bot Protection uitvalt of traag is, laat je server de bezoeker nog steeds door.
require_token maakt een actie zonder echt bezoek duurder: de browser van de bezoeker moet onze tag op je pagina (of op de challengepagina) uitvoeren en een token verdienen dat aan die browser en dat netwerk vastzit en één keer wordt uitgegeven. Het is geen CAPTCHA en geen bewijs van een persoon: een goed gefinancierde bot die een browser nadoet, kan nog steeds tokens verdienen, langzaam en tegen kosten, en onze classificatie en farmdetectie beoordelen die sessies zoals elke andere.
Pauzeren
Met de beschermingsschakelaar op de Set-up-pagina pauzeer je alles zonder deploy: elk antwoord is allow, en er wordt niets vastgelegd of gefactureerd.