Scarnox · Blog

Cloudflare Turnstile: cómo funciona y cómo resolverlo (próximamente)

Cloudflare Turnstile es un captcha que normalmente no pide nada al visitante. Ejecuta comprobaciones en el navegador y, en la mayoría de los casos, las supera sin ningún puzzle. Cuando no está seguro, puede mostrar un paso interactivo breve. Entonces el widget escribe un token en el formulario, y el sitio verifica ese token con Cloudflare. El soporte de Scarnox para Turnstile está próximamente. Esta guía explica cómo funciona el widget, por qué a menudo se confunde con otros desafíos y los enfoques generales para trabajos legítimos.

La página incluye un elemento contenedor con la clase cf-turnstile y un atributo data-sitekey. El script de Turnstile se carga, ejecuta sus comprobaciones y añade un input oculto llamado cf-turnstile-response. El valor de ese input es el token. El formulario lo envía junto con el resto de campos, y el backend del sitio lo envía al endpoint de verificación de Cloudflare junto con la clave secreta del sitio.

Como otros widgets de token, la verificación se hace en el servidor. Un formulario que acepta cualquier valor en ese campo sin comprobarlo no está realmente protegido.

Modos y lo que significan para un script

Turnstile puede funcionar en más de un modo. En el modo gestionado, Cloudflare decide si muestra un paso interactivo. En el modo no interactivo, el widget nunca pide nada al visitante y solo muestra un estado. En el modo invisible, no se muestra nada. Para un script, el modo cambia lo que verás en la página, pero el resultado es el mismo: un token en el campo del formulario, verificado en el servidor.

Los tokens son de vida corta y de un solo uso. Envía el formulario poco después de que el widget produzca el token, y no reutilices un token que ya fue verificado.

Por qué bloquea la automatización

Turnstile observa señales del entorno del navegador y el comportamiento de la sesión. Un navegador headless por defecto, un conjunto de funciones del navegador ausente o incoherente, una sesión nueva sin historial y una dirección de red sospechosa pueden empujar la decisión hacia un desafío o un bloqueo. Las señales son de la misma familia que las de otras comprobaciones basadas en puntuación, por eso los enfoques son parecidos.

Enfoques legítimos

Estos son los enfoques que funcionan para un trabajo legítimo:

Usa un navegador real para las páginas que cargan Turnstile. Un perfil de navegador normal con ajustes coherentes tiene menos probabilidades de ser desafiado que una build de automatización sin más. La guía de detección de navegadores headless enumera las señales habituales.
Mantente en la sesión. Conserva las cookies entre las páginas de tu flujo, para que el visitante no parezca nuevo en cada petición.
Regula tus peticiones. Un ritmo constante y parecido al humano reduce los desafíos mucho más que cualquier truco concreto.
Revisa primero las normas del sitio protegido por Cloudflare. Muchos sitios protegidos publican una API o un feed. Compruébalo antes de construir un flujo con navegador. La guía de scraping de sitios protegidos por Cloudflare cubre el enfoque con más profundidad.
Usa claves de prueba en desarrollo. Cloudflare publica claves de sitio de prueba para desarrollo, que producen resultados predecibles sin una comprobación real. Son para tus propias pruebas de integración, no para tráfico de producción.
Pregunta al titular. Si administras el sitio, puedes ajustar la configuración de Turnstile para las rutas que usan tus pruebas automatizadas. Si no, pide una lista de permitidos o una API.

Qué hará un solver de Turnstile

Un solver de Turnstile basado en tokens recibe la sitekey y la URL de la página, produce un token válido para el campo cf-turnstile-response y lo devuelve a tu código. Tu código escribe el token en el formulario y lo envía sin demora. Es el mismo patrón que la integración en vivo de PopularCaptcha, con un tipo de tarea distinto.

Scarnox todavía no resuelve Turnstile en vivo. El único tipo de tarea en vivo hoy es PopularCaptcha, sin proxy. Turnstile está próximamente, y sus detalles de petición estarán en la referencia de la API cuando se publique. No construyas sobre una interfaz supuesta antes de entonces.

Errores habituales

Las integraciones de Turnstile suelen fallar de algunas formas previsibles. La más común es usar un token después de que haya caducado o después de que ya haya sido verificado. Los tokens son de un solo uso, así que un reintento tras un envío de formulario fallido necesita un resultado nuevo del widget, no el valor antiguo. La segunda es una sitekey que pertenece a otro entorno. Una clave de desarrollo en una página de producción, o al revés, produce un fallo de verificación que parece un error de tu código. Comprueba qué clave usa la página antes de depurar cualquier otra cosa.

Otro error frecuente es tratar un paso interactivo como un fallo. En modo gestionado, Turnstile puede mostrar un paso breve a algunos visitantes, y un script que espera un paso silencioso se quedará bloqueado. Diseña el flujo para esperar el resultado del widget y para gestionar el caso en que el widget pida más.

Por último, no fijes el nombre del campo sin comprobarlo en la página real. El input cf-turnstile-response es el estándar, pero un sitio puede envolver el widget de otra manera, y leer el formulario renderizado es más rápido que adivinar.

Scrapea de forma responsable

Hacer scraping de un sitio protegido por Turnstile es un trabajo habitual, y necesita el mismo cuidado que cualquier otro scraping. Revisa el robots.txt y los términos de servicio. Mantén bajo tu ritmo y no recopiles datos personales que no necesites. Cuando un sitio tenga una API, prefiérela. La guía sobre si el web scraping es legal cubre las preguntas principales.

Para prepararte

Crea una cuenta para empezar con crédito de prueba gratis, sin tarjeta. Cuando el soporte de Turnstile se publique, podrás probarlo en tus propias páginas antes de ejecutar nada contra un sitio en vivo.