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

Что такое Cloudflare Turnstile? Это альтернатива CAPTCHA от Cloudflare. Вместо картинок с загадками она проверяет посетителя тестами, которые выполняются в фоне, а когда посетитель проходит проверку, страница получает токен, который сервер сайта затем проверяет через Cloudflare. В этом руководстве разобраны три режима виджета, токен и его ограничения, принцип проверки и то, как отличить виджет от полностраничной проверки.
Что видит посетитель: три режима виджета
Cloudflare описывает три режима в документации виджета Cloudflare. Владелец сайта выбирает один из них при создании виджета.
| Режим | Что видит посетитель |
|---|---|
| Managed mode | Cloudflare выбирает между неинтерактивной проверкой и флажком, поэтому флажок появляется только тогда, когда нужна дополнительная проверка |
| 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-interactive | sitekey и полный адрес страницы. Токен подставляется в поле |
| Форма, которая не работает без токена, но на экране нет окна | Виджет в режиме 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, с фиксированной лицензией и без платы за каждое решение.
