Перейти до вмісту

Адон 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.