Что такое Cloudflare Turnstile: режимы, токен и проверка

what is cloudflare turnstile - What Is Cloudflare Turnstile? Modes, Token and Verification

Что такое Cloudflare Turnstile? Это альтернатива CAPTCHA от Cloudflare. Вместо картинок с загадками она проверяет посетителя тестами, которые выполняются в фоне, а когда посетитель проходит проверку, страница получает токен, который сервер сайта затем проверяет через Cloudflare. В этом руководстве разобраны три режима виджета, токен и его ограничения, принцип проверки и то, как отличить виджет от полностраничной проверки.

Что видит посетитель: три режима виджета

Cloudflare описывает три режима в документации виджета Cloudflare. Владелец сайта выбирает один из них при создании виджета.

РежимЧто видит посетитель
Managed modeCloudflare выбирает между неинтерактивной проверкой и флажком, поэтому флажок появляется только тогда, когда нужна дополнительная проверка
Non-interactive modeВиджет с индикатором загрузки, пока идут проверки, и посетителя никогда не просят ничего делать
Invisible modeНичего нет: ни виджета, ни индикатора, а проверки выполняются в фоне

Ни один из трёх режимов не просит посетителя читать искажённый текст или выбирать картинки. По данным обзора Cloudflare, сайту не обязательно пропускать свой трафик через Cloudflare, чтобы использовать виджет, но его владельцу нужен аккаунт Cloudflare, чтобы его создать.

Что Cloudflare Turnstile даёт странице? Токен

Для разработчика всё сводится к полю формы cf-turnstile-response, вызову проверки на сервере и, если вы автоматизируете сайт с Turnstile, токену, который нужно подставить самостоятельно. Если виджет находится внутри формы, Cloudflare сообщает, что он добавляет скрытое поле с именем cf-turnstile-response, и оно уходит на сервер вместе с остальными полями. Виджет можно отрисовать неявно: тогда он ищет в разметке элемент с классом cf-turnstile. Можно отрисовать его и явно, вызовом turnstile.render() из скрипта страницы. Страница с явной отрисовкой может также передать callback, и в документации API CapSkip сказано выполнить этот callback с полученным токеном, если страница его определяет.

Токен живёт недолго. В руководстве по серверной валидации сказано, что каждый токен действителен 300 секунд и предназначен для одного использования, а Cloudflare отслеживает его погашение по всей своей сети с задержкой. Поэтому токен, запрошенный в начале длинного скрипта, может оказаться потраченным или устаревшим к моменту отправки формы.

Как сервер проверяет токен

Само получение поля ничего не доказывает. Cloudflare называет серверную валидацию обязательной: сайт отправляет POST-запросом токен и свой секретный ключ на endpoint siteverify, то есть на https://challenges.cloudflare.com/turnstile/v0/siteverify, и читает ответ в формате JSON. Документированные значения приведены ниже.

НаправлениеЗначениеЗначение
Отправляетсяsecret (обязательно)Секретный ключ виджета
Отправляетсяresponse (обязательно)Токен из поля формы
Отправляетсяremoteip (необязательно)IP-адрес посетителя
Отправляетсяidempotency_key (необязательно)UUID, который вы создаёте, чтобы повтор той же проверки был безопасен
ВозвращаетсяsuccessПрошла ли проверка
Возвращаетсяchallenge_ts, hostnameКогда проверка была пройдена и где она была показана
Возвращаетсяerror-codesСписок, например missing-input-response или timeout-or-duplicate
Возвращаетсяaction, cdataПользовательские значения, которые страница задала для виджета

Cloudflare перечисляет семь кодов ошибок, и два из них важны здесь. Код missing-input-response означает, что токен до Cloudflare не дошёл, а timeout-or-duplicate означает, что токен истёк или уже был проверен. В документированном ответе нет оценки: результат только один, проверка пройдена или нет, плюс значения action и cdata, которые задала ваша страница, чтобы сервер мог их проверить. Это моё прочтение документированных полей, а не заявление Cloudflare о том, что он никогда не возвращает.

Виджет или страница проверки: какой это Turnstile?

Виджет и полностраничная проверка относятся к разным вещам. Виджет является элементом в уже загруженной странице. Страница проверки показывается Cloudflare вместо сайта, до того как придёт какое-либо содержимое. В документации Cloudflare о clearance сказано, что прохождение такой проверки устанавливает cookie cf_clearance, привязанное к посетителю и устройству. Там же сказано, что виджет с включённым pre-clearance может выдавать это cookie, тогда как по умолчанию виджет выдаёт одноразовый токен. Эта таблица поможет понять, с чем вы имеете дело.

Что вы видитеЧто это такоеЧто от вас нужно CapSkip
Окно или индикатор внутри формы и поле cf-turnstile-response в HTMLВиджет в режиме managed или non-interactivesitekey и полный адрес страницы. Токен подставляется в поле
Форма, которая не работает без токена, но на экране нет окнаВиджет в режиме invisible или виджет, который не отрисовалсяТе же два значения. Найдите sitekey в разметке или в вызове render
Целая страница с надписью "Just a moment" до загрузки сайтаПолностраничная проверкаДва пути в CapSkip. Запрос токена Turnstile с action, data и pagedata, если страница передаёт их в turnstile.render, или запрос cookie cf_clearance, описанный ниже

Получение токена Turnstile из CapSkip

CapSkip работает на вашем ПК с Windows, отвечает по адресу 127.0.0.1:8080 в формате запросов 2captcha и не берёт плату за каждое решение на лицензионной копии. На странице распознавание Cloudflare Turnstile описан сам продукт, а в разделе Документация API перечислены параметры, использованные здесь. Если скрипт работает на другой машине, переключите CapSkip в Server mode и укажите адрес этого ПК как хост, как объясняет раздел Настройки подключения в руководстве по установке. При запуске Server mode CapSkip открывает порт для всех адресов, поэтому, чтобы оставить доступ только для ожидаемых машин, добавьте для остальных блокирующее правило Windows Firewall.

Вот запрос виджета вручную. Метод называется turnstile, а в документации API обязательными значениями названы sitekey и pageurl. Каждый вызов занимает одну строку curl.exe, которую PowerShell выполняет как написано. В cmd пропускайте строки, которые начинаются с решётки.

# 1. Submit the task. CapSkip answers with a task id.
curl.exe -s -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=YOUR_SITEKEY&pageurl=https://example.com/contact&json=1" http://127.0.0.1:8080/in.php
# {"status":1,"request":"12345"}

# 2. Poll with that id until the token is ready.
curl.exe -s "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
# {"status":0,"request":"CAPCHA_NOT_READY"} means poll again shortly.
# {"status":1,"request":"TOKEN","userAgent":"Mozilla/5.0 ..."}

То же задание через Python SDK сводится к одному вызову. Он отправляет задание, опрашивает результат и возвращает словарь, значение code которого является токеном для поля cf-turnstile-response.

# python -m pip install capskip
from capskip import CapSkip

# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)

result = solver.turnstile("YOUR_SITEKEY", "https://example.com/contact")

print(result["code"])  # the token for the cf-turnstile-response field
print(result.get("userAgent"))  # the User-Agent to send with it

В документации API сказано, что CapSkip решает Turnstile с определённым User-Agent браузера и что при отправке токена нужно передать тот же. В ответе JSON он указан как userAgent, а в текстовом режиме приходит в заголовке ответа X-Turnstile-User-Agent. SDK запрашивает ответ JSON, поэтому берите значение из результата и ставьте его в запрос, который несёт токен.

Запрос для страницы проверки

Для страницы проверки документация API просит передать ещё три значения, которые вы читаете из аргументов, передаваемых страницей в turnstile.render(). Отправляйте те, которые страница задаёт, и не отправляйте пустые. В документации есть короткий скрипт, который переопределяет эту функцию и выводит аргументы.

Значение запросаГде страница его хранит
actionАтрибут data-action или action в вызове render
dataЗначение cData в вызове render или атрибут data-cdata
pagedataЗначение chlPageData в вызове render
# python -m pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)

# action, data and pagedata come from the page's turnstile.render call.
result = solver.turnstile(
    "YOUR_SITEKEY",
    "https://example.com/protected",
    action="managed",
    data="YOUR_CDATA",
    pagedata="YOUR_CHLPAGEDATA",
)
print(result["code"], result.get("userAgent"))

Значение managed для action скопировано из примера запроса в документации API, поэтому используйте то action, которое задаёт ваша страница.

Путь через cookie даёт отдельный запрос. В документации API он указан в разделе Cloudflare Challenge (cf_clearance) для полной страницы с надписью "Just a moment". Он работает только через JSON API createTask, выключен, пока вы не включите Return cf_clearance cookies в настройках Cloudflare, и каждый запрос должен указывать прокси, который вы будете использовать потом. В Python SDK для него нет вызова, поэтому вот запрос в том виде, как его пишет документация API, отправленный через PowerShell. Значение proxy взято из документации как заглушка.

# Submit the cookie task. A proxy is required.
$body = '{"clientKey":"YOUR_API_KEY","task":{"type":"AntiCloudflareTask","websiteURL":"https://www.example.com/","proxy":"203.0.113.10:8080:login:password"}}'
$task = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/createTask -ContentType "application/json" -Body $body

# Poll every few seconds while the status is processing.
$ask = @{ clientKey = "YOUR_API_KEY"; taskId = $task.taskId } | ConvertTo-Json
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/getTaskResult -ContentType "application/json" -Body $ask
} while ($result.status -eq "processing")

$result.solution.cookies.cf_clearance
$result.solution.userAgent

Запрос cookie используйте, когда после проверки хотите загружать сайт обычными HTTP-запросами. Документация API описывает этот случай для скрипта или инструмента без собственного браузера и советует отправлять cookie через тот же прокси и с тем же User-Agent. Запрос токена подходит для страницы, которая вызывает turnstile.render() и имеет callback или поле, принимающее токен. Такое сопоставление для запроса токена является выводом из двух разделов документации, а не их утверждением.

Повторное использование cookie в Python разобрано в материале как повторно использовать cookie cf_clearance. Запрос токена в коде смотрите в материале Руководство по Node.js. Версия для PHP описана в руководстве по решению Turnstile на PHP, а версия для C# описана в руководстве по странице проверки на C#.

Что я запускал и чего это не показывает

Я запускал все четыре блока кода против имитации, которая изображает CapSkip, на Python 3.11.7, 3.13.7 и 3.14.0 с capskip 1.7.0, а два блока PowerShell в Windows PowerShell 5.1. Я не отправлял ни одного задания в настоящее приложение, поэтому здесь ничего не показано о том, как отвечает настоящая страница Turnstile и что настоящее приложение возвращает для виджета.

Проверка на имитацииРезультат
Вызов виджета в PythonОдно задание с методом turnstile, sitekey и адресом страницы, а токен и User-Agent вернулись в результате
Вызов для страницы проверки в PythonТо же задание также несло action, data и pagedata ровно в том виде, как они были переданы
Оба блока Python, вставленные в один файлОба задания были отправлены и прочитаны обратно
Путь через cookie в PowerShellИмитация увидела тип AntiCloudflareTask, адрес страницы и прокси. Один раз она ответила processing, затем выдала cookie и User-Agent, которые блок вывел
Отправка через curl.exe, затем опросПервый опрос показал, что задание не готово, а второй вернул токен

FAQ

Сколько живёт токен Turnstile?

Cloudflare называет 300 секунд, и токены предназначены для одного использования. Запрашивайте токен у CapSkip прямо перед отправкой формы.

Совпадает ли Turnstile с проверкой Cloudflare перед загрузкой сайта?

Нет. Виджет живёт внутри страницы и выдаёт токен. Полностраничная проверка заменяет страницу и заканчивается cookie cf_clearance. Таблица выше показывает, как их различить.

Можно ли увидеть виджет Turnstile, прежде чем писать код?

Да. Откройте демонстрационную страницу Turnstile и посмотрите, как работает виджет и какое поле он заполняет.

Можно ли обращаться к сервису с другого ПК?

Да, через Server mode. Укажите в качестве host адрес ПК, на котором работает CapSkip, и добавьте блокирующее правило Windows Firewall для любого адреса, которому доступ не нужен. Сервис по-прежнему работает на вашем собственном оборудовании с Windows.

Коротко

Если коротко, что такое Cloudflare Turnstile? Это токен в cf-turnstile-response, который сайт проверяет через Cloudflare, и отдельная полностраничная проверка, которая заканчивается cookie. Чтобы подставить токен или cookie из собственного кода, можно использовать локальный обход капчи на вашем ПК, например CapSkip, с фиксированной лицензией и без платы за каждое решение.