Что такое hCaptcha: токен, siteverify и Enterprise

hCaptcha представляет собой проверку на ботов, которую ставят перед формой. Посетитель проходит задание в виджете, после чего виджет добавляет токен с именем h-captcha-response в форму. Ваш сервер отправляет этот токен в hCaptcha, чтобы убедиться, что он настоящий. Так что же такое hCaptcha для разработчика? Это виджет, токен и один вызов проверки, и именно с этим вы имеете дело, если скрипту нужно пройти такую проверку. В этом руководстве разобрано, как её распознать, что проверяет сервер, что означает каждая ошибка и что отправляет скрипт.
Чтобы разобраться в самой идее CAPTCHA, прочитайте материал что такое CAPTCHA и зачем она нужна сайтам. Этот материал посвящён только hCaptcha.
Как распознать hCaptcha на странице
Руководство разработчика hCaptcha показывает виджет как элемент класса h-captcha с атрибутом data-sitekey. Страница CapSkip для hCaptcha называет sitekey публичным UUID. Если виджет создаёт скрипт, sitekey является параметром hcaptcha.render(), который описан в руководстве по конфигурации. После успешного прохождения задания, как сказано в руководстве, hCaptcha добавляет в отправку формы поле h-captcha-response с токеном.
Итак, его выдают три признака: элемент с классом h-captcha, sitekey и поле формы h-captcha-response после прохождения задания. В документации API CapSkip добавлено, что форма может нести второе поле с именем g-recaptcha-response, которое нужно заполнить тем же токеном.
Флажок, невидимый режим и аккаунты Enterprise
Флажок и невидимый режим являются двумя режимами виджета. Enterprise представляет собой уровень аккаунта, который может использовать любой из них, и он меняет содержимое ответа сервера при проверке. CapSkip использует один метод для всех них.
- Флажок. Посетитель ставит галочку и, по данным документации CapSkip, иногда отвечает на задание с картинками.
- Невидимый режим. В руководстве по невидимому режиму сказано, что для элемента нужно задать data-size равным invisible, после чего виджет отрисовывается в фоне и показывается, только когда нужна проверка. Ваша страница запускает его через hcaptcha.execute(), а токен приходит в вашу функцию callback.
- Enterprise. В ответе проверки появляются два поля, score и score_reason, которые в руководстве hCaptcha помечены как только для Enterprise. У задания в CapSkip нет параметра score. Единственный связанный переключатель называется High score mode для hCaptcha, о нём говорится в разделе FAQ ниже.
Некоторые сайты Enterprise также передают виджету значение rqdata через hcaptcha.setData() до его запуска. В публичной документации hCaptcha оно не описано, поэтому всё, что здесь сказано о нём, опирается на документацию CapSkip: сайт выдаёт одно значение на каждое задание, и оно быстро устаревает, поэтому скрипту нужно новое для каждого задания.
Что сервер делает с токеном
Сервер отправляет токен POST-запросом на https://api.hcaptcha.com/siteverify в виде тела формы в кодировке URL, и руководство предупреждает, что JSON отправлять нельзя. Обязательны два поля: секрет аккаунта и токен, они отправляются как secret и response. Руководство рекомендует remoteip (адрес пользователя) и называет sitekey необязательным: он позволяет указать, какой sitekey вы ожидаете. В ответе JSON есть success, challenge_ts, hostname и error-codes.
Токены одноразовые. Единственный срок жизни, который называет руководство, это значение по умолчанию 120 секунд, указанное в описании одного из кодов ошибок. В документации CapSkip указано около двух минут. Запрашивайте токен прямо перед отправкой.
Ошибки siteverify и что проверить
Эти коды взяты из таблицы ошибок в руководстве hCaptcha. Скрипт обычно видит только отклонённую форму. Последний столбец отражает моё понимание того, что стоит проверить, это не текст hCaptcha.
| Код ошибки | Что говорит руководство | Что проверить |
|---|---|---|
missing-input-response | Параметр токена отсутствует. | В отправке формы не было поля h-captcha-response, или сайт читает другое имя. |
invalid-input-response | Токен недействителен или имеет неверный формат. | Значение было обрезано, изменено или дважды закодировано на пути в форму. |
expired-input-response | Срок токена истёк (по умолчанию 120 с). | Между решением и отправкой прошло слишком много времени. Решите и сразу отправляйте. |
already-seen-response | Токен уже проверялся один раз. | Токен использовали повторно или повторили отправку формы со старым токеном. Каждый раз запрашивайте новый. |
sitekey-secret-mismatch | Значение sitekey не зарегистрировано для указанного секрета. | Проблема в конфигурации сайта на стороне сервера, а не в том, что отправляет скрипт. |
invalid-input-secret | Секретный ключ недействителен или имеет неверный формат. | Это тоже на стороне сервера, в коде владельца сайта. |
Сравнение с reCAPTCHA и Turnstile
Все три кладут в форму один токен и проверяют его на сервере, поэтому различия сводятся к именам и числам. reCAPTCHA использует g-recaptcha-response, а в руководстве Google по проверке сказано, что токен действителен две минуты и проверяется один раз. Turnstile использует cf-turnstile-response, а Руководство Cloudflare по серверной валидации называет 300 секунд и одно использование. В Python SDK CapSkip вызовы называются hcaptcha(), recaptcha() и turnstile(), это взято из исходного кода версии 1.7.0.
Как выглядит запрос к CapSkip
CapSkip работает на вашем ПК с Windows и понимает формат запросов 2captcha, поэтому задание hCaptcha сводится к двум HTTP-вызовам. Обе команды curl.exe ниже запускаются как написано и в PowerShell, и в cmd. Первая отправляет задание и отвечает id задания. Вторая опрашивает по этому id, а CAPCHA_NOT_READY означает, что нужно подождать несколько секунд и спросить снова. Поле data добавляйте, только если страница задаёт rqdata. Ключ имеет значение, только если в CapSkip включена API Key Validation.
curl.exe -X POST -d "key=YOUR_API_KEY&method=hcaptcha&sitekey=YOUR_SITEKEY&pageurl=https://example.com/login&json=1" http://127.0.0.1:8080/in.php curl.exe "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
То же задание через Python SDK сводится к одному вызову, который отправляет задание, опрашивает и возвращает результат. Параметры: invisible, data (rqdata для Enterprise), userAgent и proxy. CapSkip использует переданный вами userAgent, только если он совпадает с браузером, которым он решает. Результат содержит токен как code и token, значение respKey и User-Agent, с которым получен токен.
# pip install capskip
from capskip import CapSkip
# The key matters only when API Key Validation is on in CapSkip.
solver = CapSkip(apiKey="YOUR_API_KEY", host="127.0.0.1", port=8080)
# For an Enterprise rqdata add data=RQDATA; for an invisible widget
# add invisible=1. Neither is needed for a plain checkbox.
result = solver.hcaptcha(
sitekey="YOUR_SITEKEY",
url="https://example.com/login",
)
# The token goes in h-captcha-response, sent with this User-Agent.
print(result["code"][:12], result["userAgent"])Оба блока запускались против имитации CapSkip, а не настоящего приложения, и каждый отправил method=hcaptcha с указанными sitekey и адресом страницы. Настоящего решения не было, поэтому здесь нет утверждений о времени решения или проценте успеха. Полные скрипты и все параметры есть на странице CapSkip для решения hCaptcha, а метод указан в разделе Документация по API CapSkip.
- hCaptcha на Python с помощью SDK capskip
- hCaptcha Enterprise на Node.js со свежим rqdata
- hCaptcha на C# с HCaptchaAsync
Запуск CapSkip на сервере
Если скрипт работает на другой машине, переключите CapSkip в Server mode и укажите в настройке host эту машину. На этот счёт настройки подключения в руководстве по установке описывают оба режима, а Server mode требует запуска CapSkip от имени администратора, при этом машина остаётся ПК с Windows, который вы контролируете. Проверьте, какие адреса могут достучаться до порта, и добавьте блокирующее правило Windows Firewall для тех, которым это не нужно. Решение происходит на этой машине, поэтому hCaptcha видит её сеть, так что привяжите к заданию прокси, если это важно для сайта.
Часто задаваемые вопросы
Совпадает ли hCaptcha с reCAPTCHA?
Нет. Это отдельные сервисы со своими виджетами, именами полей и хостами проверки. Скрипт должен отправить правильное поле и запросить у CapSkip правильный метод.
Как понять, что сайт использует hCaptcha Enterprise?
Не всегда по фронтенду. В документации CapSkip сказано, что некоторые сайты Enterprise передают значение rqdata в hcaptcha.setData() до запуска виджета. Если вы видите этот вызов, отправьте значение как параметр data, новое для каждого задания. Если нет, решайте как обычно и пробуйте High score mode, если сайт отказывается принимать токены.
Почему форма отклоняет токен, который вернул CapSkip?
В документации CapSkip перечислены обычные причины: токен старый или уже использован, sitekey не совпадает со страницей или User-Agent отличается от указанного в ответе. Для строгих сайтов добавлена настройка High score mode для hCaptcha в разделе Settings, Captcha types, которой нужен Google Chrome на ПК с CapSkip.
Можно ли запустить CapSkip на сервере для заданий hCaptcha?
Да. Используйте Server mode на машине с Windows, которую вы контролируете, и направьте скрипт на её адрес.
Коротко
hCaptcha представляет собой виджет, который заканчивается одним одноразовым токеном, проверяемым один раз по адресу siteverify hCaptcha. Если токен нужен вашему скрипту, локальный сервис распознавания капчи на вашем ПК с Windows охватывает случаи с флажком, невидимым режимом и Enterprise одним методом и без платы за каждое решение.
