Seguridad
La página de Seguridad de una clave de sitio decide cuán difícil es el reto y qué peticiones tienen permitido llegar hasta él. Los valores por defecto son un término medio sensato; esta página trata de cuándo apartarse de ellos, y hacia qué lado.
Empieza aquí
La mayoría de sitios deberían dejar los valores por defecto en paz. Echa mano de las perillas de abajo cuando tengas un motivo:
- Estás bajo abuso activo, o el formulario es de alto valor (registros, pagos, restablecimiento de contraseña): sube la protección. Sube la Dificultad, sube el Nivel de ofuscación y activa Bloquear navegadores automatizados. Cambias un poco de cómputo del visitante y algo de CPU del servidor por un muro mucho más alto.
- La velocidad y la conversión importan más, y el riesgo es bajo (una caja de newsletter en una página de marketing): mantén la protección ligera. Deja la Dificultad baja y Retos por solicitud en 1 para que el reto sea ligerísimo en un teléfono barato.
El resto de esta página es cada perilla y hacia qué lado girarla.
Exigir un juego
El control más fuerte aquí es exigir que un visitante juegue un juego para pasar, no solo superar la comprobación silenciosa de fondo. Activa Exigir un juego para verificar, aquí en la página de Seguridad, y todo visitante debe superar uno de los juegos registrados en esta clave. El servidor elige qué juego recibe cada visitante, así que no se puede saltar ni cambiar.
Registras los juegos que una clave puede usar, y ahí es también donde el gate se explica por completo, en la página Juegos y el gate de juego de la clave. No puedes activar el gate hasta que haya al menos un juego registrado. Dejarlo apagado es la opción menos segura: la clave se puede pasar sin jugar un juego.
Modo vista previa
Mientras aún construyes tu integración, el modo vista previa aprueba automáticamente cada verificación en esta clave, así puedes cablear el widget y tu backend de /siteverify sin resolver el reto real cada vez. El widget y cualquier juego exigido se siguen mostrando exactamente como los vería un visitante; solo se fuerza el veredicto a pasar, y cada sesión se marca como vista previa. Deja la protección contra bots de la clave desactivada, así que vuelve a apagarlo antes de salir en vivo. Todos los detalles en Modo vista previa.
Proof of work: Dificultad y Retos por solicitud
El proof of work hace que el navegador resuelva un pequeño puzzle para que el abuso a escala salga caro (ver proof of work).
- Dificultad (1 a 8) fija cuán difícil es cada puzzle. Más alto le cuesta más a un atacante, pero también le cuesta más al dispositivo del visitante, lo que los teléfonos de gama baja sienten en el extremo del rango. Empieza en el valor por defecto y súbelo solo si de verdad ves abuso.
- Retos por solicitud (1 a 500) pide varias resoluciones a la vez, multiplicando el coste. Déjalo en 1 a menos que tengas un motivo concreto para amontonar más.
El navegador resuelve estos puzzles en un Web Worker, así que la Content-Security-Policy de tu página debe permitir blob: para los workers (worker-src blob:); este es obligatorio. Dejar que el solver corra como WebAssembly rápido lleva dos permisos juntos: 'wasm-unsafe-eval' en script-src para que pueda compilar el módulo, y el origen del que cargas el script del widget en connect-src para que pueda descargarlo. Los dos son opcionales: si falta cualquiera de los dos, el solver recae en una implementación más lenta de JavaScript puro dentro del mismo Worker y la verificación sigue funcionando, en silencio. Mira sandboxing de juego para la política completa de la página anfitriona.
Instrumentación: Nivel de ofuscación y Bloquear navegadores automatizados
La instrumentación corre un pequeño programa en el navegador del visitante para comprobar que un navegador real, no un script, resolvió el reto (ver instrumentación). Está activada por defecto y es la única capa que distingue un navegador real de uno automatizado.
- La Instrumentación se puede apagar por clave. Déjala encendida para casi todo sitio. Apágala solo si la página que incrusta tu widget corre una Content-Security-Policy que no puede permitir
'unsafe-eval'(el programa de instrumentación lo necesita, ver abajo). Con ella apagada, la clave ya no puede detectar navegadores automatizados, aunque el proof of work y cualquier juego exigido siguen corriendo, y los dos ajustes de abajo dejan de aplicar. - Nivel de ofuscación (1 a 10) es cuán difícil es de ingeniería inversa el programa en navegador. Más alto es más fuerte pero usa más CPU del servidor. El valor por defecto es el correcto para la mayoría de sitios; súbelo si eres el blanco frecuente y dirigido de un atacante.
- Bloquear navegadores automatizados rechaza de plano los clientes headless y WebDriver detectados. Actívalo on si ninguna automatización legítima toca jamás tu formulario. Déjalo off si esperas bots legítimos (tu propio monitoreo, integraciones de socios, herramientas de accesibilidad), porque también bloqueará esos.
Content-Security-Policy
El programa de instrumentación corre eval en el navegador del visitante, así que la página que incrusta tu widget debe permitir 'unsafe-eval' en su script-src. Este es el único requisito duro de CSP y no tiene fallback: si 'unsafe-eval' está bloqueado, la verificación expira y la consola del navegador muestra [cap] Instrumentation failed. Tienes dos opciones: permitir 'unsafe-eval' en las páginas que alojan el widget, o apagar la Instrumentación (arriba) para quitar el requisito. La lista completa de lo que la CSP de una página anfitriona necesita está en sandboxing de juego.
Headers obligatorios
Puedes exigir que toda petición lleve un header concreto. La mayoría de sitios no lo necesitan; es útil cuando tu propio cliente siempre envía un header sobre el que puedes filtrar, como un filtro extra barato.
Lo que no puedes exigir son los headers que Caputchin elimina por privacidad antes de que una petición llegue siquiera a la verificación. Identifican al visitante, y la postura de Caputchin es no recoger datos por visitante, así que los descarta en la frontera de la plataforma:
| Header eliminado | Por qué se descarta |
|---|---|
cf-connecting-ip | La IP del visitante, puesta por Cloudflare. Nunca cruza la frontera, así que Caputchin ni la almacena ni la comprueba. |
x-forwarded-for | La IP del visitante vista a través de proxies. Mismo motivo. |
x-real-ip | La IP del visitante desde proxies upstream. Mismo motivo. |
user-agent | La cadena User-Agent del visitante, que identifica su navegador y dispositivo. |
sec-ch-ua* (cada client hint Sec-CH-UA: sec-ch-ua, sec-ch-ua-platform, sec-ch-ua-mobile y el resto) | La forma estructurada del User-Agent. Misma frontera de privacidad. |
Exigir uno de estos bloquearía toda petición, porque nunca llega, así que la plataforma rechaza esa configuración en vez de dejarte inutilizar la clave.
Rate limit y origins CORS
- Máximo de solicitudes por segundo limita cuán rápido aceptará peticiones la clave. Súbelo si de verdad tienes mucho tráfico; bájalo para frenar una clave que está siendo aporreada.
- Orígenes CORS es tu allowlist de origins, impuesta en el servidor antes de que el puzzle siquiera corra. Déjala vacía mientras pruebas desde
localhost; antes de salir a producción, añade tus origins reales para que solo tu propio sitio pueda usar la clave.
Véase también
- Modo vista previa para aprobar automáticamente cada verificación mientras construyes y pruebas.
- Juegos y el gate de juego para registrar juegos y exigir uno para verificar.
- Claves de sitio para el resto de una clave.
- Estadística y sesiones para ver si tus ajustes están deteniendo el tráfico correcto.