Bot Protection nunca actúa por sí solo: tu servidor ejecuta la action de la respuesta. El modo decide cuál es esa acción.
Monitor mode
Toda cuenta nueva empieza aquí. La action de cada respuesta es allow, así que no se frena a nadie, e intended_action dice lo que haría el block mode. La vista general del panel cuenta cuántas decisiones el block mode habría bloqueado o enviado a un challenge. Añade la llamada, haz el deploy y obsérvalo unos días.
Block mode
Se puede activar cuando uno de tus dominios está protegido: la primera decisión de tu servidor sobre un visitante de tus páginas que no sea un bot lo añade, y la página de challenge solo devuelve a los visitantes a un dominio protegido. Con el block mode activado, tu último dominio protegido no se puede quitar. En tu propia máquina se puede activar en cuanto la tag se ejecute en una página en localhost: hasta que uno de tus dominios esté protegido, la página de challenge solo devuelve a los visitantes de esa máquina. También puedes añadir un dominio a mano en la página de Set-up.
Actívalo en la tarjeta Modo de la página Configuración; se aplica desde la próxima solicitud. La action pasa a ser la que definiste para la clase del visitante:
| Clase | Acción por defecto | Significa |
|---|---|---|
| human high | allow | una persona, con pruebas ajenas a la sesión |
| human | allow | una persona confirmada por tu propio feedback |
| unknown | allow | no hay evidencia suficiente en ningún sentido; la mayoría de las primeras visitas |
| bot | challenge | automatización, por lo que hace el cliente |
| bot high | block | automatización, con evidencia fuerte |
Puedes cambiar la acción de cualquier clase en la misma tarjeta. Volver al monitor mode es igual de rápido.
Qué significa cada acción para tu código
allow: sigue como si Bot Protection no estuviera.challenge: pide más antes de seguir: tu CAPTCHA, una verificación por email o teléfono, un camino más lento. Si no tienes ninguno, sigue.block: rechaza la acción. Responde con el mismo mensaje que muestra un registro fallido, para que un bot no aprenda nada.
El block mode nunca impide que una página cargue. Bot Protection solo juzga las acciones por las que pregunta tu servidor (un registro, un inicio de sesión, un checkout), así que un bot bloqueado sigue viendo tu sitio; lo que no puede completar es la acción.
La página de desafío
Si no tienes una verificación propia, envía al visitante desafiado a la nuestra. En block mode, una respuesta cuya action es challenge trae challenge.url: redirige el navegador allí, con &r= y la dirección a la que volver, en uno de tus dominios. La página hace que el navegador resuelva una pequeña prueba de trabajo, unos segundos como mucho, y luego lo devuelve a esa dirección con kz_token añadido. El middleware guarda ese token en la cookie _kz, y durante los 30 minutos siguientes el challenge de esa sesión es allow, con challenge.passed a true.
Los SDK lo hacen por ti: en una carga de página (GET) sin onChallenge, protect, withKorzen y el Protect de Go envían al visitante allí y, cuando vuelve, guardan kz_token y lo envían a la misma dirección sin él. Solo aceptan el token de un navegador que ellos enviaron a la página, así que un enlace con el token de otra persona no planta nada. El envío de un formulario o una llamada a la API bajo desafío se rechaza con 403: desafía la página que muestra el formulario, y su pase deja pasar el envío. Un hook tuyo envía al visitante con challengeRedirect(d, returnTo) (en Go, korzen.SendToChallenge), que marca el navegador de la misma forma. La dirección de vuelta es la que pidió el visitante, con el host y el esquema de X-Forwarded-Host y X-Forwarded-Proto cuando tu proxy los pone, y si no, de Host. Detrás de un proxy que reenvía Host: localhost y ninguno de los dos, como hace nginx por defecto, da a publicURL (en Go, PublicURL) el origen de tu sitio, como https://shop.example. La página devuelve a un visitante a localhost solo cuando el tag también vio la página del visitante en localhost y la IP de la decisión era loopback o una dirección privada (una app en Docker en tu máquina ve la del bridge, como 172.17.0.1). Detrás de un proxy, la página de un visitante está en tu dominio, así que la página nunca lo envía a localhost.
Un navegador sin JavaScript espera en su lugar: unos segundos, más para un desafío más difícil, y la página sigue sola y da el mismo pase. No hay vuelta que se salte la página. La prueba de trabajo, o la espera, hace que cada sesión automatizada pague por su registro; por sí sola, no detiene a un bot decidido.
Una acción que necesita el tag
Un script que copia un navegador y envía cada petición desde una dirección nueva nunca ejecuta tu página, así que es unknown, no bot, como una persona cuyo bloqueador de anuncios frena el tag. En una acción donde eso no basta, como entrar en una cola, un registro o un checkout, envía "require_token": true con la decisión (la opción requireToken de los SDKs, en Go RequireToken). Sin un token válido del tag, la respuesta es challenge con token_required true, sea cual sea la clase; la clase en sí no cambia, y en monitor mode es el intended_action. Un token hace la acción una vez por hora por sesión, gastado por el envío del formulario, nunca por la carga de la página que lo muestra: hasta tres intentos en dos minutos son el mismo intento (una tarjeta rechazada, una errata), y uno posterior se responde como si no hubiera token, así que un navegador es un lugar en la cola. La opción de los SDKs lo envía solo con los envíos.
Un visitante enviado a la página de desafío desde esa acción no tiene espera sin JavaScript: la página pide la prueba de trabajo y que nuestro tag se ejecute en ella, y eso da un token nuevo para la acción: un script que resuelve la prueba de trabajo sin ejecutar nuestro tag no pasa. Quien tiene JavaScript desactivado no puede pasarla, así que envía require_token solo en las acciones que lo necesitan. Un envío de formulario bajo challenge recibe el 403 de los SDKs: para mandar al visitante a la página, hazlo en onChallenge con challengeRedirect(d, returnTo) hacia la página del formulario (en Go, korzen.SendToChallenge). Cuando Bot Protection está caído o lento, tu servidor sigue dejando pasar al visitante.
require_token encarece tomar una acción sin una visita real: el navegador del visitante tiene que ejecutar nuestro tag en tu página (o en la página de desafío) y ganar un token atado a ese navegador y a esa red, que se gasta una vez. No es un CAPTCHA ni una prueba de que hay una persona: un bot bien financiado que imita un navegador todavía puede ganar tokens, despacio y con un coste, y nuestra clasificación y la detección de granjas juzgan esas sesiones como cualquier otra.
Pausar
El interruptor de protección en la página Configuración pausa todo sin deploy: cada respuesta es allow, nada se registra ni se cobra.