IskWaf - Web Application Firewall для MODX 3

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

• Многоуровневые правила безопасности:
  • IP-адрес/CIDR (с приоритетом точного IP над подсетью).
  • Страна (с исключениями для доверенных ботов).
  • User-Agent (типы: содержит, точное совпадение, регулярное выражение).
  • Referrer (типы: содержит, точное совпадение, регулярное выражение).
  • Request URI (типы: содержит, точное совпадение, регулярное выражение, начинается с; с учетом или без учета query string).
• Интеллектуальная автоматизация правил:
  • Автоматическое создание разрешающих правил для подсетей доверенных ботов (Google, Yandex и др.).
  • Автоматическое создание блокирующих правил для подсетей нежелательных хостеров/прокси.
  • Правила создаются на основе данных об автономной системе (ASN) через CRON.
• Realtime-проверки (без ожидания CRON):
  • Определение страны напрямую по локальной базе IP2Location в момент запроса (iskwaf_country_check_mode = realtime).
  • Мгновенная блокировка/разрешение по ASN и имени компании (iskwaf_enable_realtime_asn_rules), не дожидаясь CRON.
• Белый список стран: разрешить трафик только из указанных стран, блокируя все остальные (iskwaf_allowed_countries); имеет приоритет над чёрным списком.
• Верификация поисковых ботов: гибридный метод ASN + DNS (rDNS/fDNS). Верифицированные боты Google/Yandex/Bing/Apple/DuckDuckGo проходят мимо блокировок по стране и ASN.
• Экспорт и импорт правил в CSV: выгрузка и загрузка правил (IP, User-Agent, Referrer, Request URI) прямо из интерфейса; импорт через штатный файловый менеджер MODX, с валидацией строк.
• Инспекция запросов (защита от SQL-инъекций): проверка значений GET/POST/Cookie (и при желании тела запроса) по настраиваемым сигнатурам атак, с режимами «только лог» и «блокировка».
• Гибкие действия по правилам: 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_country_check_mode	Режим проверки по стране	cached (по умолчанию): страна берётся из таблицы деталей, наполняемой CRON. Быстро, но новые IP блокируются только после прохода крона. realtime: страна определяется прямым запросом к локальной базе IP2Location в момент запроса — блокировка мгновенная; результат сохраняется в таблицу. Требует файл geoip_db/IP2LOCATION-LITE-DB11.BIN.
iskwaf_iskwaf_blocked_countries	Блокируемые страны (чёрный список)	Двухбуквенные коды стран (ISO 3166-1 alpha-2) через запятую. Трафик из этих стран блокируется (кроме доверенных ботов). Пример: CN,RU,KP. Игнорируется, если задан белый список.
iskwaf_iskwaf_allowed_countries	Разрешённые страны (белый список)	Если заполнено — разрешается трафик только из перечисленных стран, остальные блокируются (доверенные боты проходят). Имеет приоритет над чёрным списком. Пример: RU,BY,KZ. Если страну IP определить не удалось — он не блокируется (fail-open).
iskwaf_iskwaf_enable_dns_verification	Верификация поисковых ботов	Если «Да» — WAF верифицирует ботов Google/Yandex/Bing/Apple/DuckDuckGo. Верифицированный бот проходит мимо всех правил, включая блокировку по стране. Настоятельно рекомендуется при использовании блокировки по стране.
iskwaf_iskwaf_bot_verification_method	Метод верификации ботов	asn_dns (по умолч.) — сначала быстрая локальная проверка по ASN, затем DNS как резерв; asn — только ASN (без сетевых DNS-запросов; требует IP2LOCATION-LITE-ASN.BIN); dns — только двойная DNS-проверка (rDNS+fDNS).
iskwaf_iskwaf_auto_allow_as_names	Разрешённые имена компаний (AS Name)	Имена компаний (ASN), которым разрешён доступ. Наивысший приоритет: проверяются в реальном времени и раньше блокировки по стране — такие компании не блокируются, даже если их страна в чёрном списке. Разделитель — |. Пример: Google LLC|Cloudflare. Также используются CRON для авто-создания /24-правил.
iskwaf_iskwaf_auto_allow_as_numbers	Разрешённые номера AS (ASN)	Номера AS, которым разрешён доступ. Наивысший приоритет (как выше). Разделитель — |. Пример: AS15169|AS13238
iskwaf_iskwaf_auto_block_as_names	Блокируемые имена компаний (AS Name)	Имена компаний (ASN) для блокировки. Разделитель — |. Пример: DigitalOcean|OVH
iskwaf_iskwaf_auto_block_as_numbers	Блокируемые номера AS (ASN)	Номера AS для блокировки. Разделитель — |. Пример: AS14061|AS16276
iskwaf_iskwaf_enable_realtime_asn_rules	Проверка по ASN в реальном времени	Управляет мгновенной блокировкой по ASN в момент запроса (не дожидаясь CRON). Разрешающие списки (allow) работают всегда, независимо от этой опции. Требует geoip_db/IP2LOCATION-LITE-ASN.BIN.
iskwaf_iskwaf_csv_delimiter	Разделитель CSV (экспорт правил)	Разделитель колонок при экспорте правил. По умолчанию ; (для корректного открытия в Excel). Допустимо: ;, , или tab. При импорте разделитель определяется автоматически либо выбирается в окне импорта.

Настройки инспекции запросов (защита от SQL-инъекций)

Отдельная группа настроек (область «Инспекция запросов»). По умолчанию модуль выключен.

Ключ	Описание	Возможные значения
iskwaf_iskwaf_payload_inspection_mode	Режим инспекции параметров запроса.	off (по умолчанию) — выключено; log — только записывать срабатывания в лог; block — блокировать запрос (403). Рекомендуется сначала log для подбора сигнатур.
iskwaf_iskwaf_payload_scan_sources	Какие входные данные проверять.	Через запятую из: get, post, cookie, body (сырое тело). По умолчанию: get,post,cookie.
iskwaf_iskwaf_payload_max_body	Макс. размер тела для инспекции (байт).	Число. По умолчанию 262144 (256 КБ).
iskwaf_iskwaf_payload_signatures	Сигнатуры (регулярные выражения).	По одному выражению на строку (строки с # — комментарии). Регистронезависимо, разделитель шаблона — ~. Если пусто — используется встроенный набор для типичных SQL-инъекций.

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-задачи:

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

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

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

• Вкладка "Логи": Просмотр всех записей лога WAF с поиском. Отображаются колонки "Страна" и "Город", а также колонка "Инъекция" (пометка «ДА» для срабатываний инспекции запросов).
• Вкладки правил (IP, User-Agent, Referrer, Request URI): Управление правилами, плюс кнопки «Экспорт CSV» и «Импорт CSV» для выгрузки/загрузки правил.
• Вкладка "Отчет": Просмотр ежедневных сводных отчетов.

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

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. Поддерживаются два режима списков:

• Чёрный список (iskwaf_iskwaf_blocked_countries): блокируется трафик из перечисленных стран.
• Белый список (iskwaf_iskwaf_allowed_countries): если задан — пропускаются только перечисленные страны, все остальные блокируются. Белый список имеет приоритет над чёрным (при заданном белом списке чёрный игнорируется).

• Режим определения страны: зависит от iskwaf_iskwaf_country_check_mode — cached (из таблицы деталей, наполняется CRON) или realtime (прямой запрос к базе IP2Location в момент запроса; новые IP блокируются мгновенно).
• Исключения: верифицированные поисковые боты и компании из ASN-allow-списков проходят, даже если страна заблокирована (см. ниже).
• Если страну определить не удалось (нет в базе) — IP не блокируется (fail-open), чтобы не отрезать неопознанные адреса.
• В логе у такой блокировки в заметках указывается причина, режим и источник, например: Reason: country not in whitelist. Mode: realtime (source: table).

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(

Верификация поисковых ботов

Чтобы настоящие поисковые боты не попадали под блокировки (по стране, ASN и т.п.), IskWaf верифицирует их подлинность. Проверка выполняется в самом начале обработки запроса: если бот верифицирован — он проходит мимо всех правил.

• Включение: настройка iskwaf_iskwaf_enable_dns_verification = «Да».
• Гибридный метод (iskwaf_iskwaf_bot_verification_method):
  • asn_dns (по умолчанию) — сначала быстрая локальная проверка ASN по базе IP2Location (Googlebot=AS15169, YandexBot=AS13238, bingbot=AS8075, Applebot=AS714), затем, если нужно, двойная DNS-проверка (rDNS+fDNS) как резерв;
  • asn — только ASN (без сетевых DNS-запросов, быстрее);
  • dns — только rDNS+fDNS (как в прежних версиях).
• Кэширование: успешная верификация IP кэшируется на 24 часа.
• Поддерживаемые боты: Google, Yandex, Bing, Apple, DuckDuckGo (у последнего — только DNS).

Спуфер с UA «YandexBot», но не из сети Яндекса, верификацию не пройдёт и попадёт под обычные правила.

Правила и приоритеты по ASN

Помимо авто-создания /24-правил через CRON, IskWaf умеет принимать решения по ASN/имени компании прямо в момент запроса (требуется geoip_db/IP2LOCATION-LITE-ASN.BIN).

• Разрешающие списки (iskwaf_iskwaf_auto_allow_as_names / ..._numbers) — наивысший приоритет: действуют всегда (независимо от опции realtime-блокировки) и раньше блокировки по стране. Доверенная компания не блокируется, даже если её страна в чёрном списке (или не в белом).
• Блокирующие списки (..._block_as_names / ..._numbers) — мгновенная блокировка включается опцией iskwaf_iskwaf_enable_realtime_asn_rules.
• Приоритет: сначала проверяется allow, затем block.
• В логе: Rule type: asn ... Match: allow by AS name. Mode: realtime (source: ip2location_db|table).

Экспорт и импорт правил (CSV)

На каждой вкладке правил (IP, User-Agent, Referrer, Request URI) есть кнопки «Экспорт CSV» и «Импорт CSV».

• Экспорт: выгружает все правила выбранного типа в CSV (с BOM для корректной кириллицы в Excel). Разделитель задаётся настройкой iskwaf_iskwaf_csv_delimiter (по умолчанию ;).
• Импорт: файл выбирается через штатный файловый менеджер MODX (можно и загрузить новый), читается на сервере. Разделитель определяется автоматически или выбирается в окне.
• Валидация при импорте: каждая строка проверяется (формат IP/CIDR, тип паттерна, компилируемость regex, тип правила). Некорректные строки пропускаются с указанием номера и причины, корректные импортируются.
• Режим при совпадении: «пропускать дубликаты» или «обновлять существующие».
• По завершении показывается сводка: добавлено / обновлено / пропущено / ошибок.

Инспекция запросов (защита от SQL-инъекций)

Дополнительный слой защиты («defence in depth»): проверка входных данных запроса по сигнатурам атак (прежде всего SQL-инъекций). Это не замена исправлению уязвимого кода, а компенсирующая мера. По умолчанию выключено.

• Что проверяется: значения GET, POST, Cookie и (опционально) сырое тело запроса — настройка iskwaf_iskwaf_payload_scan_sources.
• Режимы (iskwaf_iskwaf_payload_inspection_mode): off — выключено; log — только лог; block — 403. Рекомендуется сначала log, подобрать сигнатуры, и лишь потом block.
• Сигнатуры (iskwaf_iskwaf_payload_signatures): regex по одной на строку; пусто → встроенный набор под типичные SQLi (UNION SELECT, INFORMATION_SCHEMA, SLEEP(, BENCHMARK(, ORD(MID(, UPDATEXML( и др.). Значения нормализуются (raw/urldecode) перед сравнением.
• Логирование: срабатывания пишутся в общий лог (triggered_rule = payload); на вкладке «Логи» есть колонка «Инъекция» с пометкой «ДА», в заметках — шаблон, источник и параметр.
• Внимание: широкие сигнатуры дают ложные срабатывания. Для запросов к коннекторам компонентов (которые могут не вызывать OnHandleRequest) можно подключить файл iskwaf-guard.php.

Система CAPTCHA

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

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

Ежедневные сводки в IskWafReportDaily включают: общее количество событий WAF, блокировок, CAPTCHA, разрешений по правилам, срабатываний по типам правил, хиты поисковых ботов, топ N IP и правил (JSON). Генерируются CRON-скриптом.

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

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