iskwaf2x — Web Application Firewall для MODX Revolution 2.x

Автор: Иван Сергеевич К. (ivan@iskwaf.ru)
Сайт: iskwaf.ru | iskwaf.com

iskwaf2x — компонент для MODX Revolution 2.x, реализующий базовый WAF (Web Application Firewall) для защиты вашего сайта от угроз, ботов и подозрительной активности. Предоставляет гибкие правила, ведёт логи, поддерживает систему отчетов и геолокацию по IP. Поддерживает собственную числовую CAPTCHA и различные режимы логирования и проверки.

Основные возможности

  • Гибкие многоуровневые правила:
    • IP-адрес/CIDR (приоритет точного IP над подсетью)
    • User-Agent: contains, exact, regex
    • Referrer: contains, exact, regex
    • Request URI: contains, exact, regex, starts_with (с учетом или без query string)
  • Действия по правилам: Block (403), CAPTCHA, Allow
  • Локальная CAPTCHA: Числовая, 6 цифр, проверка 3 первых/последних, хранение результата в сессии
  • Опциональные режимы проверки WAF:
    • Проверка на каждый запрос (по умолчанию)
    • Проверка один раз за сессию
  • Система логирования: Режимы `full`, `triggered`, `off`, автоматическая очистка (через CRON), отображение пропусков из-за режима "один раз за сессию"
  • Геоанализ IP: IP2Location LITE (страна, город, ASN, ISP) через отдельную CRON-задачу
  • Отчеты: Суточные агрегаты событий, с топами по IP, правилам, поисковым ботам, гео
  • Интерфейс управления (CMP): Вкладки для логов (с гео), каждого типа правил, отчетов; управление, (де)активация, удаление

Установка

  1. Загрузите архив iskwaf2x-x.y.z.transport.zip через "Установщик дополнений" (Extras → Installer) в MODX 2.x.
  2. Установите пакет iskwaf2x.
  3. Доступ к CMP появится в меню как "iskwaf2x".

Конфигурация

После установки настройте системные параметры, создайте страницу CAPTCHA, подготовьте окружение GeoIP.

1. Системные настройки

Найдите их в "Система" → "Системные настройки" и выберите пространство iskwaf2x.

Ключ Описание Возможные значения/Действие
iskwaf2x_captcha_resource_id ID ресурса MODX для страницы CAPTCHA. Создайте новый ресурс, некэшируемый, вызовите [[!iskwaf2xCaptcha]].
Укажите его ID здесь.
iskwaf2x_option_log Режим логирования WAF.
  • full — все запросы (по умолчанию)
  • triggered — только события, вызвавшие правила
  • off — логирование отключено
iskwaf2x_waf_check_mode Режим проверки правил.
  • on_every_request — проверка на каждый запрос (по умолчанию)
  • once_per_session — только один раз за сессию
iskwaf2x_log_retention_days Сколько дней хранить логи Число (например, 7 или 30)
iskwaf2x_ip2location_download_token Токен для скачивания баз IP2Location Зарегистрируйтесь на lite.ip2location.com, получите токен и укажите его
iskwaf2x_ip_analysis_limit_per_run Максимум IP для анализа за запуск CRON-скрипта Число, по умолчанию 5000
iskwaf2x_ip_analysis_update_interval Через сколько дней обновлять гео для IP Число, по умолчанию 30

2. Страница CAPTCHA

Создайте некэшируемый ресурс, вставьте
[[!iskwaf2xCaptcha? &tpl=`iskwaf2xCaptchaFormTpl`]]
Параметр &tpl опционален.

3. Настройка GeoIP (IP2Location)

  1. Зарегистрируйтесь на lite.ip2location.com, получите токен, укажите его в iskwaf2x_ip2location_download_token
  2. PHP-библиотека должна лежать в
    core/components/iskwaf2x/lib/ip2location/src/
  3. Создайте и откройте на запись папки:
    core/components/iskwaf2x/tmp_db_download/
    core/components/iskwaf2x/geoip_db/
  4. Запустите CRON-скрипт ip2location_download.php для первой загрузки баз

4. CRON-задачи

Скачивание/обновление баз GeoIP:
  • Скрипт: core/components/iskwaf2x/elements/cron/ip2location_download.php
  • Периодичность: 1 раз в месяц
  • Пример: /usr/bin/php /путь_до_сайта/core/components/iskwaf2x/elements/cron/ip2location_download.php
Анализ IP из логов и заполнение GeoIP:
  • Скрипт: core/components/iskwaf2x/elements/cron/analyze_ip2location_details.php
  • Периодичность: раз в несколько часов или раз в сутки
Очистка старых логов:
  • Скрипт: core/components/iskwaf2x/elements/cron/clear_log.php
  • Периодичность: раз в сутки

Использование (CMP)

  • Откройте пункт меню iskwaf2x в админке.
  • Доступны вкладки: Логи (с отображением страны/города), IP-правила, User-Agent, Referrer, URI, Отчеты.
  • Создавайте, редактируйте, активируйте, удаляйте правила и просматривайте логи/отчёты.

Типы правил

IP-правила

  • Поля: IP/CIDR, Тип действия, Описание, Активно
  • Точное совпадение IP важнее CIDR. Приоритет у самой узкой сети.
Примеры:
  • Одиночный IPv4: 192.168.1.100
  • IPv4 CIDR: 10.0.0.0/8
  • IPv6 CIDR: 2001:db8::/32

User-Agent правила

  • Поля: Паттерн, Тип паттерна ('contains', 'exact', 'regex'), Действие, Описание, Активно
Примеры:
  • Тип: contains, паттерн: AhrefsBot
  • Тип: regex, паттерн: /^EvilCorp Crawler\/[0-9\.]+/i

Referrer правила

  • Поля: Паттерн, Тип паттерна ('contains', 'exact', 'regex'), Действие, Описание, Активно
Примеры:
  • Тип: contains, паттерн: spam-site.com
  • Тип: regex, паттерн: /^https?:\/\/([\w-]+\.)*spammerdomain\.com/i

Request URI правила

  • Поля: Паттерн, Тип паттерна ('contains', 'exact', 'regex', 'starts_with'), Учитывать Query String, Действие, Описание, Активно
Примеры:
  • Тип: exact, Query String: нет, паттерн: /wp-login.php
  • Тип: starts_with, Query String: нет, паттерн: /admin-backup/
  • Тип: contains, Query String: да, паттерн: eval(

Система CAPTCHA

Локальная капча: 6 цифр, ввод 3 из них. Вызывается как [[!iskwaf2xCaptcha? &tpl=`iskwaf2xCaptchaFormTpl`]]. Результат хранится в сессии.

Система отчетов

Суточные агрегаты (iskwaf2x_report_daily): события WAF, блокировки, CAPTCHA, разрешения, типы правил, поисковые боты, топ N IP и правил (JSON). Генерируются CRON-скриптом.

В продукте используются геоданные IP2Location LITE — https://lite.ip2location.com.

This product includes IP2Location LITE data available from https://lite.ip2location.com.

Важные замечания

Обратите внимание

  • Порядок правил: IP → User-Agent → Referrer → URI. Первое сработавшее — определяет действие.
  • Регулярки: используйте ограничители (например, /badbot/i)
  • IP клиента: по умолчанию $_SERVER['REMOTE_ADDR']. За прокси — адаптируйте.
  • Производительность: большое число правил или режим full могут замедлять сайт
  • Проверяйте логи! Возможны ложные срабатывания

Отказ от ответственности

iskwaf2x — это базовый WAF, не заменяет корпоративные решения и не гарантирует полную защиту. Используйте на свой страх и риск. Делайте резервные копии сайта!