API¶

SmartBot Protection предоставляет API для управления защитой, настройки правил и параметров проверки, работы со списками, применения конфигурации и получения данных о работе системы.

API используется для интеграции с внешними системами, автоматизированного развёртывания конфигурации и выполнения операций, доступных в Консоли управления.

Общие сведения¶

Все методы доступны по базовому пути /v1/antibot/. Обмен данными выполняется в формате JSON.

Идентификатор клиента

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

Пагинация

Методы получения списков принимают параметры:

• page – номер страницы. По умолчанию 1.
• per_page – количество записей на странице. По умолчанию 25.

Ответ содержит блок meta с номером текущей страницы, размером страницы и общим количеством страниц.

Сортировка и фильтрация по дате

Методы фильтрации принимают параметр order и границы периода:

• created_at_from и created_at_to – для справочников. Формат даты: 2025-10-23.
• occurred_at_from и occurred_at_to либо time_from и time_to – для событий. Формат даты и времени: 2025-10-23T11:00:00.

Поиск

Параметр search_query выполняет поиск по содержимому записей. Поиск применяется начиная с трёх символов.

Групповые операции

Удаление выполняется методами batch_destroy, которые принимают одиночное значение или массив значений. Для некоторых справочников также доступно групповое создание записей.

Ошибки

При неуспешной обработке запроса возвращается объект со списком сообщений в поле errors.

Модель объектов¶

Управление защитой основано на нескольких связанных сущностях.

Защищаемое приложение (client_apps) – ресурс, к которому привязываются параметры защиты. Приложению назначаются наборы параметров токена, поведенческого анализа и накопительной оценки.

Правило (node_rules) – политика, определяющая режим работы и тип проверки. Правило принадлежит приложению, может иметь родительское правило и содержит условие применения.

Условие применения – критерий, по которому правило применяется к запросу. Содержит адрес ресурса и способ сопоставления с ним.

Снимок конфигурации (config_snapshots) – зафиксированное состояние всех правил, готовое к развёртыванию или уже развёрнутое.

Наборы параметров – параметры токена (cookie_settings), накопительной оценки (score_settings) и поведенческого анализа (behavioral_scores). Каждый набор имеет наименование и назначается приложению. Один набор может использоваться несколькими приложениями.

Управление правилами¶

Правила¶

При создании указываются приложение и наименование правила.

Пример запроса:

{
  "node_rule": {
    "client_app_id": 1,
    "title": "",
    "location": "/home",
    "location_operator": "exact"
  }
}

Правило содержит режим работы и тип проверки в блоке настроек, ссылку на родительское правило и условие применения.

Ответ включает идентификатор, состояние правила, дату и время создания и изменения.

Способы сопоставления адреса¶

Адрес, заданный в условии, сопоставляется с адресом запроса одним из трёх способов.

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

Если запрос соответствует нескольким правилам, применяется наиболее специфичное. Точное совпадение имеет приоритет над шаблоном пути, а шаблон пути – над регулярным выражением.

Приложения¶

Список приложений формируется автоматически при подключении защищаемых ресурсов и соответствует обслуживаемым доменам. Вручную приложения не создаются.

API используется для просмотра приложений и назначения наборов параметров.

Для приложения можно изменить назначенные наборы параметров.

Пример запроса:

{
  "client_app": {
    "cookie_setting_id": 1,
    "behavioral_score_id": 2,
    "score_setting_id": 3
  }
}

Идентификаторы наборов возвращаются методами просмотра соответствующих справочников.

Удаление приложения выполняется при отключении защищаемого ресурса.

Развёртывание конфигурации¶

Изменения правил не применяются немедленно. Они накапливаются в снимке конфигурации, который затем целиком развёртывается на ноды. Это исключает ситуацию, когда часть изменений уже действует, а остальные ещё не применены.

Одновременно существуют два снимка:

• Текущий – редактируемое состояние, которое формируется по мере внесения изменений.
• Развёрнутый – состояние конфигурации, действующее на нодах.

Просмотр текущего снимка¶

Метод просмотра текущего снимка поддерживает фильтрацию по типу проверки, режиму работы, приложению и адресу ресурса.

Параметры фильтрации по типу проверки, режиму работы и приложению принимают массивы значений.

Сравнение снимков¶

Метод сравнения возвращает список различий между двумя снимками.

Каждое различие содержит:

• Тип изменения: добавление, удаление или изменение значения.
• Путь к изменённому элементу.
• Предыдущее и новое значения, если значение было изменено.

Пример ответа:

[
  ["~", "node_rules[0].settings.antibot_mode", "monitor", "block"],
  ["~", "node_rules[0].location_operator", "exact", "regex"]
]

Если снимки для сравнения не указаны, сопоставляются текущий и развёрнутый снимки.

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

Развёртывание снимка¶

Метод развёртывания без указания снимка применяет текущую конфигурацию.

Если указан конкретный снимок, развёртывается ранее сохранённое состояние.

Возврат к предыдущей конфигурации¶

Метод назначения текущим переносит выбранный снимок в редактируемое состояние.

Для возврата к предыдущей конфигурации:

1. Выберите ранее развёрнутый снимок.

2. Назначьте его текущим с помощью метода make_current.

3. Повторно разверните конфигурацию методом deploy.

Такой механизм позволяет проверять изменения перед применением, развёртывать конфигурацию целиком, сохранять историю и возвращаться к предыдущим версиям.

Параметры защиты¶

Параметры токена¶

Набор содержит наименование и срок жизни токена.

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

Параметры накопительной оценки¶

Набор определяет изменение накопительной оценки клиента в течение сеанса.

Пример запроса:

{
  "score_setting": {
    "token_score_threshold": 30,
    "token_score_reward_value": 1,
    "token_score_penalty_value": 20,
    "title": ""
  }
}

Параметры набора:

• token_score_threshold – пороговое значение, при достижении которого клиент считается недостоверным.
• token_score_penalty_value – величина, добавляемая при обнаружении отклонения.
• token_score_reward_value – величина, на которую оценка снижается при подтверждении добросовестного поведения.

Соотношение значений определяет строгость защиты. Значительное увеличение оценки при обнаружении отклонения и небольшое снижение при добросовестном поведении приводят к более медленному восстановлению доверия к клиенту.

Параметры поведенческого анализа¶

Набор содержит параметры всех блоков поведенческого анализа:

• Анализ ввода с клавиатуры.
• Анализ движения мыши.
• Анализ кликов.
• Анализ прокрутки.
• Анализ вставки из буфера обмена.
• Анализ отправки форм.
• Анализ последовательностей действий.

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

Можно изменять отдельные параметры или всю группу.

Пример запроса:

{
  "behavioral_score": {
    "click_score_threshold": 0.9,
    "click_window_size": 1500
  }
}

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

Управление списками¶

API предоставляет методы для работы с тремя справочниками.

Известные поисковые роботы (well_known_bots) – записи содержат наименование, маски доменных имён для проверки по обратным DNS-записям и шаблон строки идентификации клиента. Поиск выполняется по всем трём полям. Сортировка доступна по дате создания и наименованию.

Запрещённые отпечатки TLS (ja4_tls_fingerprints) – записи содержат значение отпечатка и причину внесения.

Запрещённые строки идентификации клиента (forbidden_user_agents) – записи содержат шаблон и причину внесения.

Для всех справочников доступны следующие методы:

Удаление записей о поисковых роботах и TLS-отпечатках выполняется по значению, а не по идентификатору. Это связано с наличием общесистемного списка, поверх которого действуют записи клиента.

Поле причины заполняется при создании записи и сохраняется в справочнике. Рекомендуется указывать источник сведений или номер инцидента для последующего анализа.

Экспорт выполняется в форматах CSV и XLSX. Формат задаётся параметром format.

Данные о блокировках¶

Список заблокированных запросов¶

GET /v1/antibot/block_logs/filter

Метод поддерживает фильтрацию по следующим параметрам:

• Адрес источника.
• Адрес ресурса.
• Строка идентификации клиента.
• Основание блокировки.

Все четыре параметра принимают массивы значений, что позволяет формировать сложные выборки одним запросом.

Дополнительно можно задать границы периода и порядок сортировки по времени события.

Каждая запись содержит:

• Время события.
• Основание блокировки и его значение.
• HTTP-метод и адрес запроса.
• Адрес источника.
• Строку идентификации клиента.
• Отпечаток клиентского окружения.
• Отпечаток TLS-соединения.
• Отпечаток HTTP-запроса.

Отпечатки позволяют сопоставлять обращения одного клиента при изменении сетевого адреса. Это используется для анализа распределённых атак.

Экспорт списка выполняется методом:

GET /v1/antibot/block_logs/export

Метод поддерживает тот же состав параметров фильтрации.

Динамика событий¶

GET /v1/antibot/block_event_occurrences

Метод возвращает распределение событий по времени за указанный период с группировкой.

Для каждого интервала возвращаются:

• Количество событий.
• Количество событий блокировки.
• Общее количество запросов.

Распределение оснований¶

GET /v1/antibot/block_event_occurrences/reasons

Метод возвращает распределение оснований блокировки за выбранный период.

Для каждого основания указываются количество событий и его доля.

Также возвращаются итоговые показатели:

• Общее количество событий.
• Количество выявленных автоматизированных клиентов.
• Общее количество запросов.

Сводные показатели¶

GET /v1/antibot/block_event_occurrences/bots_summary

Метод возвращает итоговые значения:

• Количество событий.
• Количество выявленных автоматизированных клиентов.
• Общее количество запросов.

Показатели прохождения проверки¶

GET /v1/antibot/metric_counters

Метод возвращает динамику отдельного показателя за выбранный период.

Показатель задаётся параметром chart_title, период – границами времени.

Совместный анализ показателей позволяет оценить прохождение проверок.

Разница между количеством показов страницы проверки и количеством выданных токенов означает, что часть клиентов не завершает проверку. Для автоматизированных клиентов это ожидаемое поведение. Если проверку не завершают легитимные пользователи, необходимо пересмотреть пороговые значения.

Рост количества незавершённых дополнительных проверок может указывать на избыточную строгость защиты.

Применение в автоматизированных сценариях¶

API можно использовать для автоматизации операций управления и мониторинга SmartBot Protection.

Развёртывание конфигурации из внешней системы

Правила и условия формируются программно. Затем выполняются сравнение с развёрнутой конфигурацией и применение изменений.

Список различий можно передать на согласование до развёртывания.

Перенос настроек между контурами

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

Пополнение списков по событию

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

Плановое изменение строгости

Наборы параметров переключаются по расписанию. Например, можно повысить строгость проверок на период проведения акции.

Экспорт данных во внешние системы

Списки заблокированных запросов и показатели работы системы выгружаются по расписанию для передачи в системы мониторинга и формирования отчётности.

Возврат к предыдущему состоянию

При обнаружении избыточных срабатываний ранее развёрнутый снимок назначается текущим и развёртывается повторно.