IskWaf - Web Application Firewall для MODX 3

Автор: Иван Сергеевич К. (ivan@iskwaf.ru)
Сайт на русском языке: iskwaf.ru
Сайт на английском языке: iskwaf.com

IskWaf — это компонент для MODX Revolution 3.x, представляющий собой простой, но гибкий межсетевой экран уровня веб-приложения (WAF). Он предназначен для обеспечения базовой защиты вашего сайта от некоторых распространенных угроз, нежелательных ботов и подозрительной активности путем применения набора настраиваемых правил. Компонент также включает подробное логирование, систему отчетов, возможность определения геолокации IP-адресов и опциональные режимы проверки WAF для оптимизации производительности.

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

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

Установка

  1. Загрузите пакет компонента через "Установщик" (Extras -> Installer) в менеджере MODX.
  2. Найдите пакет "IskWaf" и нажмите "Установить".
  3. Следуйте инструкциям на экране.

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

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

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

Найдите их в разделе "Система" (значок шестеренки) -> "Системные настройки", выбрав пространство имен iskwaf.

Ключ Описание Возможные значения/Действие
iskwaf_iskwaf_captcha_resource_id ID ресурса MODX для отображения страницы CAPTCHA. Создайте новый ресурс MODX (например, с alias captcha-verify), убедитесь, что он не кэшируемый. В поле "Содержимое ресурса" поместите вызов сниппета [[!IskWafCaptcha]]. Укажите ID этого ресурса здесь.
iskwaf_iskwaf_option_log Режим логирования WAF.
  • full: (По умолчанию) Логируются все запросы (сработавшие правила + обычные визиты, включая те, где правила были пропущены из-за сессионной проверки).
  • triggered: Логируются только запросы, вызвавшие срабатывание правила. Опционально может логировать факт пропуска правил из-за сессионной проверки (см. код плагина).
  • off: Логирование отключено (но правила продолжают действовать).
iskwaf_waf_check_mode Режим проверки правил WAF.
  • on_every_request: (По умолчанию) Правила WAF проверяются при каждом запросе.
  • once_per_session: Правила WAF проверяются для пользователя только один раз за сессию. Если проверка пройдена, последующие запросы в той же сессии не проходят полную проверку WAF (но логи посещений могут вестись согласно настройке iskwaf_iskwaf_option_log).
iskwaf_iskwaf_log_retention_days Количество дней хранения записей в логе iskwaf_logs. Старые записи удаляются CRON-скриптом. Число (например, 7, 30). По умолчанию в скрипте: 7.
iskwaf_ip2location_download_token Ваш персональный токен для скачивания баз данных с сайта IP2Location. Получите токен после регистрации на lite.ip2location.com и введите его здесь.
iskwaf_ip_analysis_limit_per_run Максимальное количество новых/устаревших IP для анализа за один запуск CRON-скрипта analyze_ip2location_details.php. Число. По умолчанию в скрипте: 500.
iskwaf_ip_analysis_update_interval Периодичность в днях для обновления информации по IP, уже существующему в таблице деталей. Число. По умолчанию в скрипте: 30.
Автоматическое управление правилами и блокировка по странам
iskwaf_iskwaf_blocked_countries Блокируемые страны Укажите двухбуквенные коды стран (ISO 3166-1 alpha-2) через запятую. Трафик из этих стран будет блокироваться, за исключением доверенных ботов. Пример: CN,RU,KP
iskwaf_iskwaf_auto_allow_as_names Разрешенные имена компаний (AS Name) Имена компаний (ASN), чьи подсети будут автоматически разрешены. Разделитель - вертикальная черта (|). Пример: GOOGLE|Yandex|Microsoft
iskwaf_iskwaf_auto_allow_as_numbers Разрешенные номера AS (ASN) Номера автономных систем (ASN), чьи подсети будут автоматически разрешены. Разделитель - вертикальная черта (|). Пример: AS15169|AS13238
iskwaf_iskwaf_auto_block_as_names Блокируемые имена компаний (AS Name) Имена компаний (ASN), чьи подсети будут автоматически заблокированы. Разделитель - вертикальная черта (|). Пример: DigitalOcean|OVH
iskwaf_iskwaf_auto_block_as_numbers Блокируемые номера AS (ASN) Номера автономных систем (ASN), чьи подсети будут автоматически заблокированы. Разделитель - вертикальная черта (|). Пример: AS14061|AS16276

2. Страница CAPTCHA

Как указано выше, создайте ресурс MODX для отображения CAPTCHA. Он должен быть некэшируемым и содержать вызов сниппета [[!IskWafCaptcha? &tpl=`имя_вашего_чанка_формы`]] (параметр &tpl опционален, по умолчанию `iskWafCaptchaFormTpl`).

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

Компонент IskWaf использует базы данных IP2Location LITE для определения геолокации, ASN и другой информации по IP-адресам. Сами файлы баз данных не входят в установочный пакет компонента, а скачиваются с помощью специального CRON-скрипта.

  1. Получите токен: Зарегистрируйтесь на lite.ip2location.com и получите ваш персональный токен для скачивания. Введите его в системную настройку iskwaf_ip2location_download_token.
  2. PHP-библиотека IP2Location:

    Для работы с BIN-файлами баз IP2Location необходима соответствующая PHP-библиотека. Компонент IskWaf использует PHP-файлы библиотеки, которые должны быть размещены в папке core/components/iskwaf/lib/ip2location/src/. Вы можете скачать "IP2Location PHP Module" (для BIN Data File) с официального сайта IP2Location и разместить содержимое его папки `src` по указанному пути.

  3. Директории для баз данных: Убедитесь, что на сервере существуют и доступны для записи PHP следующие директории (относительно core/components/iskwaf/):
    • tmp_db_download/ (для временных файлов при скачивании)
    • geoip_db/ (для хранения распакованных BIN-файлов баз)
  4. Первоначальное скачивание баз: После настройки токена и размещения PHP-библиотеки, запустите CRON-скрипт ip2location_download.php (см. ниже) один раз вручную из командной строки сервера для первоначальной загрузки баз (IP2LOCATION-LITE-DB11.BIN и IP2LOCATION-LITE-ASN.BIN).

4. CRON-задачи

Для автоматической работы компонента настройте три CRON-задачи:

Скачивание/обновление баз GeoIP (IP2Location):
  • Скрипт: core/components/iskwaf/elements/cron/ip2location_download.php
  • Периодичность: Рекомендуется раз в месяц (например, 1-го числа каждого месяца).
  • Пример команды: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/ip2location_download.php
Анализ IP-адресов, заполнение GeoIP и авто-создание правил:
  • Скрипт: core/components/iskwaf/elements/cron/analyze_ip2location_details.php
  • Периодичность: Рекомендуется раз в 5-15 минут для оперативного создания правил.
  • Пример команды: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/analyze_ip2location_details.php
Очистка старых логов:
  • Скрипт: core/components/iskwaf/elements/cron/clear_log.php
  • Периодичность: Рекомендуется раз в сутки.
  • Пример команды: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/clear_log.php
Формирования отчетов:
  • Скрипт: core/components/iskwaf/elements/cron/reports_daily.php
  • Периодичность: Рекомендуется раз в сутки.
  • Пример команды: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/reports_daily.php

Убедитесь, что пути к PHP-интерпретатору и к скриптам указаны верно для вашего сервера.

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

Доступ к интерфейсу управления IskWaf осуществляется через главное меню менеджера MODX (обычно в разделе "Пакеты" или "Приложения").

  • Вкладка "Логи": Просмотр всех записей лога WAF с поиском. Теперь должны отображаться колонки "Страна" и "Город" для IP-адресов, по которым есть данные.
  • Вкладки правил (IP, User-Agent, Referrer, Request URI): Управление правилами.
  • Вкладка "Отчет": Просмотр ежедневных сводных отчетов.

Типы правил (Детально)

IP-правила

Предназначены для блокировки, разрешения или показа CAPTCHA на основе IP-адреса или CIDR-подсети посетителя.

  • Поля: IP/CIDR, Тип правила (действие), Описание, Активно.
  • Логика приоритета: Точное совпадение IP имеет приоритет над CIDR-подсетью. Среди CIDR-подсетей, содержащих один и тот же IP, приоритет у более узкой (с наибольшей маской).
Примеры паттернов для IP/CIDR:
  • Одиночный IPv4: 192.168.1.100
  • IPv4 CIDR (подсеть): 10.0.0.0/8
  • IPv6 CIDR: 2001:db8::/32

Блокировка по странам

Это не отдельный тип правила в интерфейсе, а встроенный механизм WAF, который срабатывает после проверки IP-правил. Он позволяет блокировать трафик из стран, указанных в системной настройке iskwaf_iskwaf_blocked_countries.

  • Логика работы: Решение о блокировке принимается в момент запроса на основе данных о геолокации IP, которые регулярно обновляются cron-скриптом.
  • Приоритет: Эта проверка имеет более низкий приоритет, чем IP-правила. Это означает, что если для IP-адреса существует разрешающее (`allow`) правило (например, для подсети Google), посетитель будет пропущен, даже если его страна находится в черном списке.

User-Agent правила

Позволяют применять действия на основе строки User-Agent.

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

Referrer правила

Фильтруют запросы на основе HTTP Referrer.

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

Request URI правила

Применяют действия на основе запрашиваемого URI.

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

Система CAPTCHA

IskWaf использует локальную числовую CAPTCHA. Генерируется изображение с 6 цифрами, пользователю предлагается ввести первые или последние три. Прохождение запоминается в сессии. Отображается через сниппет [[!IskWafCaptcha]] (поддерживает &tpl).

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

Ежедневные сводки в IskWafReportDaily включают: общее количество событий 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 -> Request URI. Первое сработавшее правило определяет действие.
  • Регулярные выражения: Должны включать ограничители/флаги (например, /badbot/i). Тестируйте.
  • IP-адрес посетителя: По умолчанию $_SERVER['REMOTE_ADDR']. Для сайтов за прокси может потребоваться адаптация.
  • Производительность: Большое количество правил или режим логирования full могут влиять на производительность.
  • Ложные срабатывания: Возможны. Регулярно проверяйте логи.

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

IskWaf является инструментом для базовой защиты и не заменяет собой комплексные корпоративные решения безопасности или специализированные сервисы WAF. Используйте его на свой страх и риск. Рекомендуется всегда иметь актуальные резервные копии вашего сайта.