Получение TLS-отпечатков¶

Отпечаток TLS-соединения (JA4) характеризует клиента независимо от заявленного User-Agent. Библиотеки автоматизации и утилиты могут иметь узнаваемые отпечатки даже при подмене User-Agent.

Отпечаток используется на двух уровнях защиты:

Проверка по чёрному списку отпечатков.
Привязка токена к соединению. Токен, выданный одному клиенту, отклоняется при предъявлении с другим TLS-отпечатком.

Отпечаток вычисляется там, где терминируется TLS-соединение. Способ настройки зависит от места терминации TLS. Все три варианта обеспечивают одинаковый результат.

Вариант 1. Терминация на ноде¶

Если веб-сервер ноды самостоятельно терминирует TLS, включите сбор отпечатков директивой в блоке http:

antibot_fingerprinting on;

Отпечатки собираются для всех SSL-серверов конфигурации.

HTTP/3 не поддерживается. Соединения QUIC обрабатываются без отпечатка.

Вариант 2. Приём соединений без терминации¶

Если терминацию TLS выполнять нельзя, соединения принимаются модулем stream без расшифрования и передаются HTTP-серверам приложений. Отпечаток вычисляется на этапе TLS-рукопожатия, до расшифрования.

Пример конфигурации:

stream {
    server {
        listen 443;
        tls_fingerprint on;
        pass 127.0.0.1:8443;
    }
}

HTTP-серверы в этой схеме слушают порт 8443.

Для работы требуется nginx версии 1.25.5 или выше с модулем ngx_stream_pass_module.

Вариант 3. Терминация до ноды¶

Если TLS терминируется на предшествующем оборудовании – балансировщике, прокси или облачном терминаторе, отпечаток вычисляется на нём и передаётся на ноду в заголовке.

Нода использует полученный отпечаток для проверки по чёрному списку и привязки токена к соединению.

Требования к передаче отпечатка:

Отпечаток должен передаваться при каждом обращении на всех путях трафика, включая программные интерфейсы и страницу проверки.
Балансировщик должен перезаписывать входное значение заголовка. Клиент не должен иметь возможности задать его самостоятельно, иначе отпечаток можно подделать.
Значение должно передаваться без изменений, поскольку сравнение выполняется посимвольно.

Вместе с отпечатком на ноду должен передаваться исходный IP-адрес клиента. Он используется для формирования отпечатка HTTP-запроса и проверки адресов.

Если терминатор выполняет подмену адреса (NAT), передайте исходный адрес в заголовке и настройте на ноде механизм real_ip с помощью директив set_real_ip_from и real_ip_header.

Без этой настройки все клиенты будут определяться по адресу балансировщика, и привязка токена к клиенту потеряет различимость.

Имя заголовка задаётся параметром blacklists.tls.field_map. По умолчанию принимаются заголовки x-ja4-fingerprint и ja4. Подробнее – в Параметрах конфигурации ноды.

Значение вычисляется Lua-модулем haproxy-ja4 и передаётся в заголовке X-JA4-Fingerprint.

Согласованность отпечатка¶

Токен сохраняет TLS-отпечаток в момент выдачи и сверяет его при каждом обращении.

Способ получения отпечатка должен быть единым для всего трафика. Если отпечаток передаётся только на части путей или изменяется при прохождении трафика, запросы блокируются с основанием Токен другого клиента (TLS Fingerprint).

Порядок анализа таких блокировок описан в Мониторинге и анализе заблокированных запросов.

Сравнение выполняется по настраиваемой маске. По умолчанию сопоставляются первые 22 позиции JA4, а нестабильная часть отпечатка игнорируется. Это исключает влияние различий, не связанных с клиентом.

Маска также позволяет использовать разные источники отпечатка, значения которых различаются в отдельных позициях.

Параметр tls_fingerprint_compare описан в Параметрах конфигурации ноды.

Если отпечаток недоступен¶

Отсутствие TLS-отпечатка не приводит к блокировке запроса. Проверки, использующие отпечаток, не выполняются:

Чёрный список TLS-отпечатков не срабатывает.
Токен не привязывается к TLS-соединению.

Остальные уровни защиты продолжают работать.

При отсутствии отпечатка защита частично снижается, поэтому рекомендуется настроить один из описанных способов его получения.

Проверить получение отпечатка можно по журналу ноды и переменной $antibot_check_result. Порядок проверки описан в Журналах и метриках ноды.