IskWaf
--------------------
Author: Ivan Sergeevish K.
ivan@ivan345.com
--------------------

For MODx Revolution 3.x.

http://iskwaf.com/
http://iskwaf.ru/

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

Основные возможности
Многоуровневые правила безопасности:
Правила по 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.
Просмотра ежедневных отчетов.
Возможность создавать, редактировать, включать/отключать и удалять правила.
Установка
Загрузите пакет компонента через "Установщик" (Extras -> Installer) в менеджере MODX.
Найдите пакет "IskWaf" и нажмите "Установить".
Следуйте инструкциям на экране.
Конфигурация
После установки компонента необходимо настроить несколько системных параметров и создать страницу для 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. Используйте его на свой страх и риск. Рекомендуется всегда иметь актуальные резервные копии вашего сайта.