O Bot Protection nunca age sozinho: o seu servidor executa a action da resposta. O modo decide qual é essa ação.
Monitor mode
Toda conta nova começa aqui. A action de toda resposta é allow, então ninguém é parado, e intended_action diz o que o block mode faria. A visão geral do painel mostra quantas decisões o block mode teria bloqueado ou mandado para challenge. Coloque a chamada, faça o deploy e acompanhe por alguns dias.
Block mode
Ele pode ser ligado quando um dos seus domínios estiver protegido: a primeira decisão do seu servidor sobre um visitante das suas páginas que não seja um bot o adiciona, e a página de challenge só manda os visitantes de volta para um domínio protegido. Com o block mode ligado, o seu último domínio protegido não pode ser removido. Na sua própria máquina, ele pode ser ligado assim que a tag rodar numa página em localhost: até um dos seus domínios estar protegido, a página de challenge só manda de volta os visitantes nessa máquina. Você também pode adicionar um domínio à mão na página de Set-up.
Ligue-o no card Modo da página Configuração; ele vale a partir da próxima requisição. A action passa a ser a que você definiu para a classe do visitante:
| Classe | Ação padrão | Significa |
|---|---|---|
| human high | allow | uma pessoa, com prova de fora da sessão |
| human | allow | uma pessoa confirmada pelo seu próprio feedback |
| unknown | allow | evidência insuficiente para qualquer lado; a maioria das primeiras visitas |
| bot | challenge | automação, pelo que o cliente faz |
| bot high | block | automação, com evidência forte |
Você pode mudar a ação de qualquer classe no mesmo card. Voltar ao monitor mode é igualmente rápido.
O que cada ação significa para o seu código
allow: siga como se o Bot Protection não estivesse lá.challenge: peça uma prova a mais antes de seguir: o seu CAPTCHA, uma verificação por email ou telefone, um caminho mais lento. Se não tiver nenhum, siga.block: recuse a ação. Responda com a mesma mensagem de quando um cadastro falha, para um bot não aprender nada.
O block mode nunca impede uma página de carregar. O Bot Protection julga só as ações sobre as quais o seu servidor pergunta (um cadastro, um login, um checkout), então um bot bloqueado ainda vê o seu site; o que ele não consegue concluir é a ação.
A página de desafio
Sem uma verificação sua, mande o visitante desafiado para a nossa. No block mode, uma resposta cuja action é challenge traz challenge.url: redirecione o navegador para lá, com &r= e o endereço para onde voltar, em um dos seus domínios. A página faz o navegador resolver uma pequena prova de trabalho, de poucos segundos no máximo, e o manda de volta a esse endereço com kz_token acrescentado. O middleware guarda esse token no cookie _kz, e pelos próximos 30 minutos o challenge dessa sessão é allow, com challenge.passed verdadeiro.
Os SDKs fazem isso por você: em um carregamento de página (GET) sem onChallenge, protect, withKorzen e o Protect do Go mandam o visitante para lá e, quando ele volta, guardam o kz_token e o mandam para o mesmo endereço sem ele. Eles só aceitam o token de um navegador que eles mesmos mandaram à página, então um link com o token de outra pessoa não planta nada. Um envio de formulário ou uma chamada de API sob desafio é recusado com 403: desafie a página que mostra o formulário, e a aprovação deixa o envio passar. Um hook seu manda o visitante com challengeRedirect(d, returnTo) (em Go, korzen.SendToChallenge), que marca o navegador do mesmo jeito. O endereço de volta é o que o visitante pediu, com o host e o esquema de X-Forwarded-Host e X-Forwarded-Proto quando seu proxy os define, ou senão de Host. Atrás de um proxy que repassa Host: localhost e nenhum dos dois, como o nginx faz por padrão, dê a publicURL (em Go, PublicURL) a origem do seu site, como https://shop.example. A página só manda um visitante de volta para localhost quando a tag também viu a página do visitante em localhost e o IP da decisão era loopback ou um endereço privado (um app no Docker na sua máquina vê o da bridge, como 172.17.0.1). Atrás de um proxy, a página de um visitante fica no seu domínio, então a página nunca o manda para localhost.
Um navegador sem JavaScript espera no lugar: alguns segundos, mais para um desafio mais difícil, e a página segue sozinha e dá a mesma aprovação. Não há volta que pule a página. A prova de trabalho, ou a espera, faz cada sessão automatizada pagar pelo seu cadastro; sozinha, ela não detém um bot determinado.
Uma ação que precisa do tag
Um script que copia um navegador e envia cada requisição de um endereço novo nunca roda a sua página, então ele é unknown, não bot, como uma pessoa cujo bloqueador de anúncios barra o tag. Numa ação em que isso não basta, como entrar numa fila, um cadastro ou um checkout, envie "require_token": true com a decisão (a opção requireToken dos SDKs, em Go RequireToken). Sem um token válido do tag, a resposta é challenge com token_required true, qualquer que seja a classe; a classe em si não muda, e em monitor mode ela é o intended_action. Um token faz a ação uma vez por hora por sessão, gasto pelo envio do formulário, nunca pelo carregamento da página que o mostra: até três tentativas em dois minutos são a mesma tentativa (um cartão recusado, um erro de digitação), e uma posterior é respondida como se não houvesse token, então um navegador é um lugar na fila. A opção dos SDKs o envia só nos envios.
Um visitante enviado à página de desafio a partir dessa ação não tem espera sem JavaScript: a página pede a prova de trabalho e que o nosso tag rode nela, e isso dá um token novo para a ação: um script que resolve a prova de trabalho sem rodar o nosso tag não passa. Quem está com o JavaScript desligado não passa, então envie require_token só nas ações que precisam dele. Um envio de formulário sob challenge recebe o 403 dos SDKs: para mandar o visitante à página, faça isso em onChallenge com challengeRedirect(d, returnTo) para a página do formulário (em Go, korzen.SendToChallenge). Quando o Bot Protection está fora do ar ou lento, o seu servidor continua deixando o visitante passar.
require_token encarece tomar uma ação sem uma visita de verdade: o navegador do visitante precisa rodar o nosso tag na sua página (ou na página de desafio) e ganhar um token preso a esse navegador e a essa rede, gasto uma vez. Não é um CAPTCHA nem uma prova de que há uma pessoa: um bot bem financiado que imita um navegador ainda consegue ganhar tokens, devagar e com custo, e a nossa classificação e a detecção de fazendas julgam essas sessões como qualquer outra.
Pausar
O botão de proteção na página Configuração pausa tudo sem deploy: toda resposta é allow, nada é registrado nem cobrado.