https://iskwaf.ru/ — Документация на русском языке
https://iskwaf.com/ — Документация на английском языке

IskWaf — Web Application Firewall для MODX 3

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

Нововведения в компоненте IskWaf
Компонент был обновлен для внедрения интеллектуальных, автоматизированных механизмов защиты, которые снижают нагрузку на сервер и повышают эффективность блокировок.

Автоматическое управление IP-правилами
Обновлен фоновый cron-скрипт, который анализирует логи и автоматически создает правила для IP-адресов на основе данных об их автономной системе (ASN).

«Белые списки» для ботов: Подсети, принадлежащие доверенным поисковым системам (Google, Yandex и т.д.), автоматически добавляются в разрешающие (allow) правила. Это гарантирует беспрепятственную индексацию сайта.

«Черные списки» для хостеров: Подсети нежелательных хостинг-провайдеров, указанные в настройках, могут автоматически блокироваться.

Эффективность: Правила создаются для подсетей класса C (/24), что позволяет одним правилом покрыть до 254 адресов, сокращая размер таблицы правил.

Блокировка по странам с приоритетными исключениями
Реализована функция блокировки трафика из выбранных стран. Решение о блокировке принимается в момент запроса на основе данных о геолокации IP-адреса. Эти данные регулярно обновляются фоновым cron-скриптом, поэтому для новых IP-адресов возможна небольшая задержка перед тем, как их страна будет определена и правило блокировки сможет быть применено.

Гибкая настройка: Список нежелательных стран (в формате двухбуквенных кодов, например CN,US) задается в системных настройках MODX.

Механизм приоритетов: Внедрена ключевая логика исключений. Если посетитель является доверенным ботом (чей IP или подсеть находится в разрешающем правиле), он будет пропущен, даже если его страна находится в «черном списке».

Результат: Это позволяет эффективно отсекать нецелевой трафик из определенных регионов, не нарушая при этом индексацию сайта поисковыми системами.

Для создания автоматических правил нужно очистить таблицу «Собранные ip», нажав на соответствующею кнопку в адмике.

Основные возможности
Многоуровневые правила безопасности:

• Правила по IP-адресу/CIDR: Блокировка, разрешение или показ CAPTCHA для конкретных IP-адресов или целых подсетей. Реализован приоритет точного совпадения IP над подсетью.
• Правила по User-Agent: Применение действий на основе паттернов в строке User-Agent (типы паттернов: «содержит», «точное совпадение», «регулярное выражение»).
• Правила по Referrer: Фильтрация запросов на основе HTTP Referrer с использованием различных типов паттернов.
• Правила по Request URI: Блокировка или другие действия на основе запрашиваемого URI (пути или полного URI со строкой запроса), с поддержкой паттернов «содержит», «точное совпадение», «регулярное выражение» и «начинается с».

Гибкие действия по правилам:

• Block: Полная блокировка запроса с выдачей страницы 403 Forbidden.
• CAPTCHA: Показ локальной числовой CAPTCHA для проверки пользователя.
• Allow: Явное разрешение запроса, обходящее другие правила более низкого приоритета (в текущей реализации — обход правил того же типа или последующих типов).

Локальная CAPTCHA:

• Простая и настраиваемая CAPTCHA, генерирующая изображение с цифрами.
• Задание для пользователя: ввести первые три или последние три цифры из отображаемого набора (например, из 6 цифр). Задание выбирается случайно.

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

Система логирования:
Подробное логирование всех срабатываний WAF с указанием времени, IP, User-Agent, Referrer, URI, типа сработавшего правила, ID правила и предпринятого действия.

Настраиваемые режимы логирования:

• full: Логируются все запросы к сайту (если ни одно правило WAF не сработало, запрос логируется как 'VISIT').
• triggered: Логируются только те запросы, которые привели к срабатыванию одного из правил WAF. (Это поведение по умолчанию, если настройка пуста).
• off: Логирование событий WAF отключено (но сами правила продолжают работать).
• Автоматическая очистка старых логов с помощью CRON-скрипта (период хранения настраивается).

Ежедневные отчеты:

• Автоматическая генерация ежедневных сводных отчетов по активности WAF (через CRON).
• Статистика включает: общее количество событий, количество блокировок, показов CAPTCHA, разрешений по правилам, срабатываний по каждому типу правил (IP, User-Agent, Referrer, URI).
• Подсчет хитов от основных поисковых систем (Googlebot, Bingbot, YandexBot, DuckDuckBot, Baiduspider, Applebot).
• Сохранение топ-N заблокированных IP-адресов и топ-N сработавших правил в формате JSON.

Интерфейс управления (CMP):

• Удобная страница в менеджере MODX для управления всеми аспектами IskWaf.
• Отдельные вкладки с гридами для:
• Просмотра логов WAF (с поиском и фильтрацией).
• Управления правилами IP.
• Управления правилами User-Agent.
• Управления правилами Referrer.
• Управления правилами Request URI.
• Просмотра ежедневных отчетов.
• Возможность создавать, редактировать, включать/отключать и удалять правила.

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

1. Системные настройки
Найдите их в разделе «Система» -> «Системные настройки», выбрав пространство имен iskwaf.

iskwaf_iskwaf_captcha_resource_id

Описание: ID ресурса MODX, который будет использоваться для отображения страницы CAPTCHA.

Действие: Создайте новый ресурс в MODX (например, с alias captcha-verify), убедитесь, что он не кэшируемый. В поле «Содержимое ресурса» поместите вызов вашего сниппета для отображения формы CAPTCHA, например: [[!IskWafCaptcha]]. Укажите ID этого ресурса в данной настройке.

iskwaf_iskwaf_option_log

Описание: Режим логирования WAF.
Возможные значения:

• full: Логируются все запросы (сработавшие правила + обычные визиты).
• triggered: (Значение по умолчанию, если настройка пуста) Логируются только те запросы, которые привели к срабатыванию правила.
• off: Логирование событий WAF полностью отключено (но правила продолжают действовать).
• iskwaf_iskwaf_log_retention_days

Описание: Количество дней, в течение которых будут храниться записи в логе iskwaf_logs. Старые записи будут удаляться CRON-скриптом.
Значение по умолчанию (если не установлено в скрипте): 7.

2. Настройка CRON-задач
Для автоматической генерации отчетов и очистки старых логов необходимо настроить две CRON-задачи на вашем сервере:

Очистка старых логов:

Скрипт: 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/generate_daily_report.php (аналогично, проверьте путь)
Периодичность: Рекомендуется раз в сутки, после полуночи (например, в 00:05).
Пример команды: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/generate_daily_report.php
Убедитесь, что пути к PHP-интерпретатору и к скриптам указаны верно для вашего сервера.

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

Вкладка «Логи»: Просмотр всех записей лога WAF. Доступен поиск.

Вкладки правил (IP, User-Agent, Referrer, Request URI): Управление соответствующими правилами. Вы можете создавать новые правила, редактировать существующие, временно отключать (деактивировать) или удалять их.

• Паттерн: Основное значение для сравнения (IP/CIDR, строка User-Agent, строка Referrer, строка URI).
• Тип паттерна: Указывает, как интерпретировать паттерн (например, «содержит», «точное совпадение», «регулярное выражение», «начинается с»).
• Учитывать Query String (для URI правил): Флаг, указывающий, следует ли применять паттерн ко всему URI (включая параметры после ?) или только к пути.
• Тип правила (Действие): block, allow, captcha.

Вкладка «Отчет»: Просмотр ежедневных сводных отчетов по активности WAF.

Важные замечания
Порядок выполнения правил: В текущей реализации плагин проверяет правила в следующем порядке: IP-адреса -> User-Agent -> Referrer -> Request URI. Первое же сработавшее правило определяет действие для запроса, и дальнейшие проверки правил (этого типа и последующих типов) не производятся.
Регулярные выражения: При использовании типа паттерна «регулярное выражение» убедитесь, что ваши выражения корректны и включают необходимые ограничители и флаги (например, /badbot/i). Тщательно тестируйте их.
IP-адрес посетителя: Плагин по умолчанию использует $_SERVER['REMOTE_ADDR']. Если ваш сайт находится за обратным прокси-сервером (например, Cloudflare, Nginx), REMOTE_ADDR может содержать IP-адрес прокси. Для получения реального IP посетителя вам может потребоваться считывать другие заголовки (например, HTTP_X_FORWARDED_FOR, HTTP_CF_CONNECTING_IP) и адаптировать логику получения $ipAddress в плагине.
Производительность: Большое количество сложных правил (особенно регулярных выражений) или включенный режим логирования full на сайтах с высокой посещаемостью может повлиять на производительность. Используйте с осторожностью и проводите мониторинг.

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