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

Аддон BotBlocker: 5 шагов от примера до ZIP

Большинство плагинов безопасности WordPress предлагают готовый набор функций: бери что дают. BotBlocker Security идёт другим путём и публикует контракт аддонов: манифест, валидатор и рабочий пример. Владелец сайта может добавить проверку, о которой команда плагина не думала.

Код: BotBlocker-Add-on-Developer-Kit, лицензия GPL-3.0.

У гибкости есть цена. Аддон работает до фаервола или рядом с ним, и ошибка, которая в обычном плагине была бы просто багом, здесь становится дырой в защите. Контракт нужен для того, чтобы такие ошибки находились до загрузки ZIP на боевой сайт.

Аддон botblocker это небольшой плагин WordPress с манифестом bbcs-addon.json. В манифесте указаны слаг, версия, требования, настройки, необязательные способности и функции рантайма, которые нужны аддону.

Базовая линия: BotBlocker 1.7.5 и выше, WordPress 5.9 и выше, PHP 7.4 и выше. Текущий контракт это Add-on API v2, всё ниже относится к нему.

Шаг 1. Скопировать пример и переименовать всё

В комплекте три примера: канонический, продвинутый с перехватом решений по трафику и минимальный с внешней капчей.

Начинать нужно с канонического. Скопируйте папку, затем переименуйте саму папку, слаг в манифесте, корневой PHP-файл, текстовый домен, префикс функций, имя опции, хендлы ассетов и CSS-классы. Забытый префикс из примера приводит к тому, что через год два аддона борются за одну опцию.

Шаг 2. Поведение в одном файле, настройки в другом

Работу несут два файла: поведение и экран администратора.

Поведение живёт в основном файле. Настройки живут в файле настроек, в одном массиве опций вида vendor_addon_settings. Санитайзер объявлен в манифесте, и использовать нужно именно его, а не вторую копию, написанную позже.

Данные о посетителе и запросе берутся из документированного объекта ядра, а не из $_SERVER в разных местах кода. Это правило важно: ядро нормализует заголовки прокси и результаты проверок, а чтение суперглобала напрямую возвращает ровно ту проблему подмены, ради которой и ставится фаервол.

Шаг 3. Решить, нужен ли контракт трафика

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

Аддон, который принимает решения о трафике, подключается раньше, через pre-run контракт. В манифесте в списке функций появляется traffic_decision_provider, а раздел рантайма называет pre-run файл, который выставляет маркер готовности и колбэк регистрации.

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

Если задачу решает обычный хук после проверки, используйте хук.

Шаг 4. Проверить папку исходников

В комплекте есть validate-addon.php. Он проверяет манифест, конфликты имён, соответствие санитайзера и отсутствующие файлы до упаковки.

Запускайте его на каждое изменение. Валидатор быстрее установки на стенд и ловит тот класс ошибок, который даёт белый экран при активации.

Шаг 5. Упаковать одну папку, а не набор файлов

ZIP должен содержать ровно одну корневую папку, имя которой совпадает со слагом. BotBlocker проверит архив, установит аддон в каталог рантайма внутри uploads и оставит выключенным до активации администратором.

В Windows не используйте Compress-Archive: он пишет обратные слэши, WordPress их не нормализует, и на Linux-хостинге файлы распакуются с обратными слэшами в именах. Установка падает с ошибкой, в которой про архивы нет ни слова.

Берите package-addon.ps1 из комплекта или zip -r в Linux, затем прогоните валидатор уже по ZIP.

Что лежит в комплекте

Документ о контракте рантайма, справочник API v2, описание данных запроса и объекта ядра, справочник настроек и паттерны интерфейса, руководство по трафику и редиректам, жизненный цикл и стандарт качества кода, правила упаковки и тестирования, матрица совместимости и список известных пробелов в контракте ядра.

Начинайте с контракта рантайма. Он короткий и объясняет порядок загрузки, а именно оттуда растёт большинство обращений «аддон ничего не делает».

Публичный комплект распространяется по GPL-3.0 и лежит на GitHub: BotBlocker Add-on Developer Kit. Сам плагин есть на WordPress.org, хаб документации на botblocker.top/docs.

Про безопасность плагинов: Plugin Handbook.