Установка и настройка

Быстрый старт

BotOff проверяет каждую отправку формы: браузер посетителя незаметно решает небольшую задачу и получает одноразовый токен, а ваш сервер проверяет этот токен у себя, без запросов в интернет. Если токена нет или он поддельный — форма не доходит до сайта.

Выберите свой вариант:

Требования

• PHP 7.4 или новее. Расширение sodium желательно (оно есть почти везде); без него задача станет проще для ботов, но всё будет работать.
• Возможность записывать файлы в каталог над корнем сайта (туда кладётся конфиг с ключом и журнал).
• Для модуля Битрикса — MySQL или MariaDB и сайт в UTF-8.
• Ни Composer, ни SSH, ни cron не нужны. Подходит обычный виртуальный хостинг.

Скачать

Проверить, что архив скачался целиком:

# Linux, macOS
sha256sum botoff-php-*.zip

# Windows (PowerShell)
Get-FileHash botoff-php-*.zip -Algorithm SHA256

1С-Битрикс

1. Распакуйте архив в /local/modules/ Должна получиться папка /local/modules/botoff.captcha/ (в ней include.php, install/, lib/). Залить можно по FTP или через файловый менеджер хостинга.
2. Установите модуль Админка → Marketplace → Установленные решения → в строке «BotOff — защита форм от ботов» нажмите Установить.
3. Всё Модуль сразу начинает проверять формы в режиме наблюдения: ничего не блокирует, только записывает. Виджет на страницы вставляется сам.

Что модуль создаёт при установке

Где что найти в админке

• Настройки → BotOff → Отчёт — сколько отправок прошло и сколько было бы отклонено, по каким причинам и на каких адресах.
• Настройки → Настройки модулей → BotOff — режим, адреса форм, исключения.

Настройки модуля

Пример поля «Какая форма на каком адресе» (такие строки стоят по умолчанию):

/auth/ => login
/login/ => login
/personal/register/ => signup
/personal/order/make/ => order

Пример поля «Не проверять адреса»:

/ajax/calc.php
/local/ajax/
/api/

Если виджет вставляете сами

Когда автоматическая вставка выключена, добавьте в шаблон сайта перед </body>:

<?php
if (\Bitrix\Main\Loader::includeModule('botoff.captcha')) {
    // false — без привязки в HTML: безопасно для композитного кеша
    echo \BotOff\Bitrix\Settings::boot()->scriptTag('/botoff', null, false);
}
?>

Композитный сайт и HTML-кеш

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

Обновление

Залейте новую версию поверх папки /local/modules/botoff.captcha/. Настройки и журнал сохраняются. Файлы виджета в /botoff/ обновятся при переустановке модуля, либо скопируйте их из install/public/botoff/ вручную.

Любой сайт на PHP

1. Залейте папку botoff/ в корень сайта Из архива PHP-пакета. Должно получиться https://ваш-сайт/botoff/index.php.
2. Включите автозащиту форм Нужно, чтобы файл botoff/guard.php выполнялся перед каждым запросом. Выберите способ, который подходит вашему хостингу (ниже).
3. Вставьте тег виджета в общий шаблон страниц, перед </body>.
4. Проверьте, что всё на месте, и неделю понаблюдайте.

Шаг 2. Автозащита: три способа

Способ А — .htaccess (Apache с PHP как модулем). Добавьте строку в .htaccess в корне сайта, путь — полный, от корня сервера:

php_value auto_prepend_file "/home/user/site.ru/public_html/botoff/guard.php"

Способ Б — .user.ini (PHP-FPM, nginx, большинство виртуальных хостингов). Создайте файл .user.ini в корне сайта:

auto_prepend_file = /home/user/site.ru/public_html/botoff/guard.php

Способ В — строка в коде. Если у сайта одна точка входа (index.php), подключите защиту первой строкой:

<?php
require __DIR__ . '/botoff/guard.php';
// ... дальше ваш код как был

Шаг 3. Тег виджета

Простой вариант — статический тег:

<script src="/botoff/botoff.js" data-endpoint="/botoff" defer></script>

Лучше — через PHP: тогда токен привяжется к сессии посетителя, а виджет узнает, какая форма на каком адресе (routes из конфига):

<?php
require_once $_SERVER['DOCUMENT_ROOT'] . '/botoff/bootstrap.php';
echo \BotOff\BotOff::boot()->scriptTag('/botoff');
?>

Шаг 4. Проверка

Откройте в браузере https://ваш-сайт/botoff/index.php?r=health. Должно быть:

{"ok":true,"v":"0.1.7","alg":"argon2id-v1","network":"up"}

alg = argon2id-v1 — sodium есть, всё отлично. sha256-v1 — sodium выключен: попросите хостинг включить расширение, защита станет сильнее.

При первом запросе BotOff сам создаст на уровень выше корня сайта:

/home/user/site.ru/
├── botoff-config.php      ← ключ и настройки (никому не передавайте)
├── botoff-data/           ← журнал и служебные файлы
└── public_html/
    └── botoff/            ← то, что вы залили

Если у вас nginx без Apache

Файл .htaccess в папке botoff/ закрывает служебные файлы только на Apache. Для nginx добавьте в конфиг сайта:

location ~ ^/botoff/(src/|bootstrap\.php|guard\.php|report\.php|config\.example\.php) {
    return 404;
}

Для Caddy:

@botoff_internal path /botoff/src/* /botoff/bootstrap.php /botoff/guard.php /botoff/report.php /botoff/config.example.php
respond @botoff_internal 404

WordPress

Отдельный плагин ещё в работе, а пока ставится PHP-пакет — так же надёжно.

1. Залейте botoff/ в корень WordPress (рядом с wp-config.php).
2. Автозащита — способ Б (.user.ini) из раздела выше, или первой строкой в wp-config.php:
   wp-config.php, в самом начале

   <?php
   require __DIR__ . '/botoff/guard.php';

   Копировать
3. Виджет — в functions.php вашей темы (лучше дочерней):
   functions.php

   $botoff_widget = function () {
       require_once ABSPATH . 'botoff/bootstrap.php';
       echo \BotOff\BotOff::boot()->scriptTag('/botoff');
   };
   add_action('wp_footer', $botoff_widget);     // все страницы сайта
   add_action('login_footer', $botoff_widget);  // wp-login.php: у неё свой шаблон без wp_footer

   Копировать

Комментарии, вход (wp-login.php), регистрация и обычные формы защищаются сразу. Чтобы вход проверялся строже, добавьте в конфиг:

'routes' => [
    '#^/wp-login\.php#' => 'login',
    '#^/wp-comments-post\.php#' => 'comment',
],

Кабинет: отчёт, проверка сайта, настройки, оповещения

Кабинет на botoff.app/account работает для любого сайта — с Битриксом и без. Вход по коду из письма, пароля нет.

1. Добавьте сайт и подтвердите его. Файлом в корне, файлом в папке botoff/ (он уже лежит в архиве из кабинета) или записью в DNS.
2. Впишите ключи сайта. Битрикс: Настройки → Настройки модулей → BotOff → «Сеть BotOff». PHP-пакет: ключи уже в архиве из кабинета, либо две строки site_key и site_secret в конфиге.
3. Готово. Сайт раз в 10 минут присылает сводку: адреса форм, итоги проверок, тип клиента и имена полей — без IP-адресов и того, что вводят посетители.

Что есть в кабинете

• Отчёт — тот же, что в админке Битрикса: график, кто ломится, почему отклонено, живые подсказки «этот адрес стоит защищать», «а это похоже на вебхук — не проверять». Кнопки применяют настройку на сайте сами.
• Проверка сайта — смотрит сайт снаружи, как посетитель: движок, формы, куда скрипты отправляют данные. Только чтение, формы не отправляются.
• Настройки защиты — для сайтов без админки: режим, JSON-адреса, исключения, адрес → действие. Сайт забирает их со сводкой, проверяя подпись ключом сайта. Если botoff.app недоступен — работает на последних полученных.
• Оповещения — письмо об атаке (порог выбираете сами), если сайт перестал выходить на связь, недельная сводка. Отписка в один клик из любого письма.
• Архив для сайта — PHP-пакет с вписанными ключами и файлом подтверждения. Последний шаг — открыть https://ваш-сайт/botoff/?r=setup: там строка для автозащиты с точным путём под ваш сервер и кнопка «Копировать».

Какие формы защищаются

Автозащита проверяет запросы POST с телом формы (application/x-www-form-urlencoded или multipart/form-data). Не проверяются:

• GET-запросы (поиск, фильтры);
• JSON-запросы — у API обычно своя авторизация;
• адреса из списка исключений.

Виджет сам находит на странице все формы с method="post", в том числе появившиеся позже (модальные окна), и добавляет в них два скрытых поля: botoff-token и поле-ловушку botoff-hp. До вашего кода эти поля не доходят — защита их убирает.

Действия и строгость

У каждой формы есть «действие». Токен выдаётся под конкретное действие: токен от формы обратной связи не подойдёт для входа. Действие задаёт строгость:

Пока сайт не подключён к сети узлов BotOff (как сейчас у всех — сеть в разработке), все проверки локальные и все профили работают.

Как указать действие

По адресу — в конфиге (routes) или в настройках модуля Битрикса. Виджет получит ту же таблицу и сам выдаст токен с нужным действием:

'routes' => [
    '#^/auth/#' => 'login',
    '#^/register/#' => 'signup',
    '#^/cart/checkout#' => 'order',
],

Атрибутом формы — если адресов несколько или удобнее в HTML. Атрибут главнее таблицы, но сервер ждёт действие по таблице — они должны совпадать:

<form method="post" action="/auth/" data-botoff-action="login">

Отключить защиту для конкретной формы (виджет её не тронет; на сервере добавьте адрес в исключения):

<form method="post" action="/subscribe" data-botoff="off">

Режим наблюдения и включение защиты

После установки BotOff ничего не блокирует: проверяет каждую форму и записывает, что было бы отклонено. Так вы увидите, не задевает ли защита что-то своё — например, AJAX-запрос, который отправляется без формы.

Где смотреть

• Битрикс — Настройки → BotOff → Отчёт. У каждого адреса — последний отказ: какие поля пришли, каким клиентом и откуда. Кнопка «В исключения» рядом.
• PHP-пакет — консольный отчёт по журналу (нужен SSH):
  консоль

  php botoff/report.php 7

  Копировать
  Без SSH скачайте по FTP файл botoff-data/decisions.log — по строке JSON на каждую проверку.

Как читать

• Отказы honeypot, replayed, отправки без браузера (curl, python) — это боты, всё правильно.
• На адресе все отправки отклонены с missing_token, и это ваша форма — значит, она отправляется не через <form>: исключите адрес или передавайте токен.
• wrong_action — действие формы не совпало с таблицей routes. Поправьте таблицу или атрибут.

Включить защиту

Битрикс — кнопка «Включить защиту» в отчёте. PHP-пакет — в конфиге:

'mode' => 'enforce',

Посетитель, не прошедший проверку, увидит страницу «Не получилось отправить форму» с кнопкой вернуться. AJAX-запрос с заголовком Accept: application/json получит ответ 403:

{"error":"botoff_rejected","message":"Не удалось подтвердить, что запрос отправил человек. Обновите страницу и попробуйте ещё раз."}

Как BotOff ловит ботов

Одной проверки мало: бот подделает то, что проверяют. Поэтому BotOff сверяет несколько слоёв и поднимает цену для тех, кто не сходится. Человек ничего этого не замечает.

Фильтр содержимого: живой спам, который капча не видит

Капча отличает человека от программы, но не может остановить человека, которому платят за рассылку. Для этого — фильтр содержимого. Он работает только на сервере сайта: значения полей никуда не уходят и не записываются, в отчёт попадает лишь название правила.

Где настроить: Битрикс — Настройки → Настройки модулей → BotOff → «Фильтр содержимого». PHP-пакет — кабинет → сайт → «Настройки защиты», или ключи max_links, stop_words, deny_ips и другие в конфиге (справочник ниже).

Страны и файрвол на уровне сайта

Файрвол срабатывает на любом запросе к сайту, раньше самого сайта. Страна определяется на вашем сервере по свободной базе DB-IP: файл скачивается с botoff.app, только если вы указали страны, и обновляется раз в месяц.

Где настроить: Битрикс — вкладка «Файрвол» в настройках модуля. PHP-пакет — «Настройки защиты» в кабинете, или ключи firewall, deny_countries, challenge_countries в конфиге.

Страна по IP: «IP Geolocation by DB-IP» (db-ip.com), лицензия CC BY 4.0.

AJAX и одностраничные сайты

Обычно ничего делать не нужно. Виджет сам добавляет токен в заголовок X-BotOff-Token у запросов fetch и XMLHttpRequest (а значит, и jQuery, axios, BX.ajax), если это POST на ваш же сайт с телом формы (FormData, URLSearchParams, строка a=1&b=2) и адрес не в исключениях. GET-запросы, чужие домены и счётчики аналитики виджет не трогает.

JSON-запросы проверяются только на адресах, которые вы перечислили, — в Битриксе поле «Проверять и JSON-запросы на адресах», в конфиге:

'protect_json' => ['#^/ajax/api\.php#', '#^/api/order#'],

Виджет получит этот список и сам добавит токен в такие запросы.

Если нужен ручной контроль

Передать токен самому — например, когда запрос уходит на другой ваш домен:

const token = await BotOff.getToken('feedback');
await fetch('/ajax/feedback.php', {
  method: 'POST',
  headers: { 'X-BotOff-Token': token },
  body: new FormData(form),
});

BotOff.getToken('order').then(function (token) {
  $.ajax({
    url: '/ajax/order.php',
    method: 'POST',
    headers: { 'X-BotOff-Token': token },
    data: $(form).serialize(),
  });
});

const token = await BotOff.getToken('login');
await axios.post('/api/login', formData, { headers: { 'X-BotOff-Token': token } });

Чтобы токен был готов заранее (без паузы при отправке), прогрейте его, когда пользователь начал заполнять форму:

input.addEventListener('focus', () => BotOff.prefetch('login'), { once: true });

Для React, Vue и других SPA, где формы создаются скриптом и отправляются через fetch, можно выключить автоматический поиск форм и брать токен вручную:

<script src="/botoff/botoff.js" data-endpoint="/botoff" data-auto="off" defer></script>

Проверка в своём коде

Если автозащита вам не подходит или нужно проверить обработчик, который она не видит (JSON, REST), проверяйте токен сами:

<?php
require_once $_SERVER['DOCUMENT_ROOT'] . '/botoff/bootstrap.php';

$check = \BotOff\BotOff::boot()->verify('login');   // токен берётся из поля botoff-token или заголовка X-BotOff-Token
if (!$check['ok']) {
    http_response_code(403);
    exit('Проверка не пройдена: ' . $check['error']);
}
// ... дальше обычная обработка формы

Токен можно передать явно — например, из JSON-тела:

$data = json_decode(file_get_contents('php://input'), true);
$check = \BotOff\BotOff::boot()->verify('feedback', $data['botoffToken'] ?? '');

Что возвращает verify():

// прошёл
['ok' => true, 'risk' => 10, 'mode' => 'lite', 'reasons' => ['lite'], 'action' => 'login', 'iat' => 1792332000]

// не прошёл
['ok' => false, 'error' => 'replayed']
['ok' => false, 'error' => 'risk_too_high', 'risk' => 85, 'reasons' => ['lite', 'automation'], ...]

Битрикс: в обработчике, который в исключениях

Модуль и так проверяет все формы до компонентов. Ручная проверка нужна для адресов из списка «Не проверять» — например, своего AJAX-обработчика с JSON:

use Bitrix\Main\Loader;

if (Loader::includeModule('botoff.captcha')) {
    $check = \BotOff\Bitrix\Settings::boot()->verify('order');
    if (!$check['ok']) {
        $this->arResult['ERRORS'][] = 'Не удалось подтвердить, что вы не робот. Обновите страницу.';
        return;
    }
}

Laravel: middleware

// app/Http/Middleware/BotOffCheck.php
public function handle($request, Closure $next, string $action = 'form')
{
    require_once public_path('botoff/bootstrap.php');
    $check = \BotOff\BotOff::boot(base_path('botoff-config.php'))->verify($action, $request->input('botoff-token') ?? $request->header('X-BotOff-Token'));
    abort_unless($check['ok'], 403, 'Проверка не пройдена');
    return $next($request);
}

// routes/web.php
Route::post('/login', [AuthController::class, 'login'])->middleware('botoff:login');

Переезд с reCAPTCHA и Яндекс SmartCaptcha

Проще всего — убрать старую капчу и поставить автозащиту: формы будут проверяться без правок обработчиков. Если хотите оставить свой код проверки, BotOff отвечает в том же формате, что и они.

1. Уберите старый виджет со страниц (скрипт recaptcha/api.js или smartcaptcha.yandexcloud.net и блок капчи в форме) и поставьте тег BotOff.
2. Узнайте локальный секрет — один раз, из консоли или временного скрипта:
   консоль, из корня сайта

   php -r 'require "botoff/bootstrap.php"; echo \BotOff\BotOff::boot()->localSecret(), "\n";'

   Копировать
3. Поменяйте адрес проверки, секрет и имя поля в обработчике:

   	Было	Стало
   Адрес	https://www.google.com/recaptcha/api/siteverify https://smartcaptcha.yandexcloud.net/validate	https://ваш-сайт/botoff/index.php?r=siteverify
   Секрет	ключ из консоли Google / Яндекса	результат шага 2
   Поле с токеном	g-recaptcha-response / smart-token	botoff-token

$resp = file_get_contents('https://site.ru/botoff/index.php?r=siteverify', false, stream_context_create(['http' => [
    'method' => 'POST',
    'header' => 'Content-Type: application/x-www-form-urlencoded',
    'content' => http_build_query([
        'secret' => BOTOFF_SECRET,
        'response' => $_POST['botoff-token'] ?? '',
        'remoteip' => $_SERVER['REMOTE_ADDR'],
    ]),
]]));
$r = json_decode($resp, true);
if (!$r['success']) { /* отказ */ }

Ответ подходит и под проверку reCAPTCHA (success, score), и под SmartCaptcha (status):

{"success":true,"status":"ok","challenge_ts":"2026-10-18T12:00:10Z","hostname":"site.ru","action":"form","score":0.9,"error-codes":[]}

Все настройки

Если сайт подключён к кабинету и там сохранены настройки, то mode, routes, exclude, protect_json, require_token, lite_rate и ip_header берутся из кабинета, а файл нужен только для ключей. Конфиг — обычный PHP-файл, который возвращает массив: botoff-config.php на уровень выше корня сайта (в Битриксе им управляет модуль). Создаётся сам при первом запуске; указывать нужно только то, что меняете. Другой путь к конфигу задаётся переменной окружения BOTOFF_CONFIG или аргументом BotOff::boot('/путь/к/конфигу.php').

Пример конфига интернет-магазина за Cloudflare:

<?php
return [
    'lite_key' => '…останется тот, что создался…',
    'mode' => 'enforce',
    'origins' => ['https://shop.ru', 'https://www.shop.ru'],
    'ip_header' => 'HTTP_CF_CONNECTING_IP',
    'routes' => [
        '#^/login#' => 'login',
        '#^/register#' => 'signup',
        '#^/checkout#' => 'order',
        '#^/reviews/add#' => 'review',
    ],
    // свои исключения + стандартные (иначе стандартные пропадут)
    'exclude' => array_merge(\BotOff\Config::defaultExclude(), [
        '#^/api/#',
        '#^/ajax/calc\.php#',
    ]),
];

Справочник виджета

Атрибуты тега <script>

Атрибуты форм

JavaScript

Пока токен получается, у формы есть класс botoff-pending и aria-busy="true" — можно показать индикатор:

form.botoff-pending button[type=submit] { opacity: .6; pointer-events: none; }

Коды ошибок

Вопросы

Для защиты форм сайта от автоматизированных отправок (ботов) используется сервис BotOff. Сервис не собирает и не хранит персональные данные посетителей: проверка выполняется в браузере, а сайт получает только одноразовую оценку риска.

Удаление

Битрикс

Marketplace → Установленные решения → BotOff → Удалить. Можно оставить журнал в базе (галочка). Модуль уберёт обработчики, агент, папку /botoff/, конфиг и служебные данные. Затем удалите /local/modules/botoff.captcha/.

PHP-пакет

1. Уберите строку auto_prepend_file (или require в коде) и подождите 5 минут, если это был .user.ini.
2. Уберите тег виджета из шаблона.
3. Удалите папку botoff/, файл botoff-config.php и папку botoff-data/.