IskWaf
--------------------
Author: Ivan Sergeevish K.
ivan@iskwaf.com
ivan@iskwaf.ru
--------------------

For MODx Revolution 3.x.

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

IskWaf - Simple Web Application Firewall for MODX 3

IskWaf is a component for MODX Revolution 3.x, providing a simple yet flexible Web Application Firewall (WAF). It is designed to offer basic protection for your website against some common threats, unwanted bots, and suspicious activity by applying a set of customizable rules. The component also includes detailed logging and a reporting system.

Key Features
Multi-layered Security Rules:

IP Address/CIDR Rules: Block, allow, or display CAPTCHA for specific IP addresses or entire subnets. Priority for exact IP matches over subnets is implemented.
User-Agent Rules: Apply actions based on patterns in the User-Agent string (pattern types: "contains", "exact match", "regular expression").
Referrer Rules: Filter requests based on HTTP Referrer using various pattern types.
Request URI Rules: Block or other actions based on the requested URI (path or full URI with query string), supporting "contains", "exact match", "regular expression", and "starts with" patterns.
Flexible Rule Actions:

Block: Complete request blocking, issuing a 403 Forbidden page.
CAPTCHA: Display a local numeric CAPTCHA for user verification.
Allow: Explicitly permit a request, bypassing other lower-priority rules (in the current implementation, this bypasses rules of the same type or subsequent types in the processing order).
Local CAPTCHA:

Simple and customizable CAPTCHA that generates an image with digits.
Task for the user: enter either the first three or the last three digits from the displayed set (e.g., out of 6 digits). The task is chosen randomly.
Uses sessions to remember successful completion, avoiding repeated challenges on every page.
Logging System:

Detailed logging of all WAF triggers, including time, IP, User-Agent, Referrer, URI, triggered rule type, rule ID, and action taken.
Configurable Logging Modes:

full: All site requests are logged (if no WAF rule is triggered, the request is logged as 'VISIT').
triggered: Only requests that trigger a WAF rule are logged. (This is the default behavior if the setting is empty).
off: WAF event logging is disabled (but the WAF rules themselves continue to operate).
Automatic cleanup of old logs via a CRON script (retention period is configurable).
Daily Reports:

Automatic generation of daily summary reports on WAF activity (via CRON).
Statistics include: total number of events, number of blocks, CAPTCHA displays, allowances by rule, triggers for each rule type (IP, User-Agent, Referrer, URI).
Hit counts from major search engines (Googlebot, Bingbot, YandexBot, DuckDuckBot, Baiduspider, Applebot).
Storage of top-N blocked IP addresses and top-N triggered rules in JSON format.
Management Interface (CMP):

A user-friendly page in the MODX manager to control all aspects of IskWaf.
Separate tabs with grids for:
Viewing WAF logs (with search and filtering).
Managing IP rules.
Managing User-Agent rules.
Managing Referrer rules.
Managing Request URI rules.
Viewing daily reports.
Ability to create, edit, enable/disable, and delete rules.
Installation
Download the component package via the "Installer" (Extras -> Installer) in the MODX manager.
Find the "IskWaf" package and click "Install".
Follow the on-screen instructions.
Configuration
After installing the component, you need to configure a few system settings and create a page for the CAPTCHA.

1. System Settings
Find them in "System" (cog icon) -> "System Settings", selecting the iskwaf namespace.

iskwaf_iskwaf_captcha_resource_id

Description: MODX Resource ID to be used for displaying the CAPTCHA page.
Action: Create a new resource in MODX (e.g., with alias captcha-verify), ensure it is not cacheable. In the "Resource Content" field, place your snippet call for displaying the CAPTCHA form, e.g., [[!IskWafCaptcha]]. Specify the ID of this resource in this setting.
iskwaf_iskwaf_option_log

Description: WAF Logging Mode.
Possible values:
full: All requests are logged (triggered rules + normal visits).
triggered: (Default value if the setting is empty) Only requests that trigger a rule are logged.
off: WAF event logging is completely disabled (but rules still apply).
iskwaf_iskwaf_log_retention_days

Description: Number of days to retain records in the iskwaf_logs log. Old entries will be deleted by a CRON script.
Default value (if not set in the script): 7.
2. Setting up CRON Jobs
To automatically generate reports and clean up old logs, you need to set up two CRON jobs on your server:

Cleaning up old logs:

Script: core/components/iskwaf/elements/cron/clear_log.php (the path may vary slightly depending on your structure)
Frequency: Recommended once daily.
Example command: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/clear_log.php
Generating daily reports:

Script: core/components/iskwaf/elements/cron/generate_daily_report.php (similarly, check the path)
Frequency: Recommended once daily, after midnight (e.g., at 00:05).
Example command: /usr/bin/php /path/to/your/site/core/components/iskwaf/elements/cron/generate_daily_report.php
Ensure the paths to the PHP interpreter and scripts are correct for your server.

Usage
Access to the IskWaf component management interface is via the main MODX manager menu (usually in the "Extras" or "Applications" section, if you added a menu item).

"Logs" Tab: View all WAF log entries. Search is available.
Rule Tabs (IP, User-Agent, Referrer, Request URI): Manage the respective rules. You can create new rules, edit existing ones, temporarily disable (deactivate), or delete them.
Pattern: The primary value for comparison (IP/CIDR, User-Agent string, Referrer string, URI string).
Pattern Type: Specifies how to interpret the pattern (e.g., "contains", "exact match", "regular expression", "starts with").
Match Query String (for URI rules): A flag indicating whether the pattern should apply to the entire URI (including parameters after ?) or only to the path.
Rule Type (Action): block, allow, captcha.
"Report" Tab: View daily summary reports of WAF activity.
Important Notes
Order of Rule Execution: In the current implementation, the plugin checks rules in the following order: IP Addresses -> User-Agent -> Referrer -> Request URI. The very first triggered rule determines the action for the request, and no further rule checks (of that type or subsequent types in that specific request) are performed.
Regular Expressions: When using the "regular expression" pattern type, ensure your expressions are correct and include necessary delimiters and flags (e.g., /badbot/i). Test them thoroughly.
Visitor's IP Address: The plugin uses $_SERVER['REMOTE_ADDR'] by default. If your site is behind a reverse proxy (e.g., Cloudflare, Nginx), REMOTE_ADDR may contain the proxy's IP address. To get the real visitor IP, you may need to read other headers (e.g., HTTP_X_FORWARDED_FOR, HTTP_CF_CONNECTING_IP) and adapt the $ipAddress retrieval logic in the plugin.
Performance: A large number of complex rules (especially regular expressions) or enabling full logging mode on high-traffic sites can impact performance. Use with caution and monitor performance.
False Positives: There is always a risk of false positives. Regularly review logs, especially after adding new rules. It is recommended to initially create new "aggressive" rules with a non-blocking action (e.g., if a "log only" action were available) to assess their impact before setting them to block.
Disclaimer
IskWaf is a tool for basic protection and is not a substitute for comprehensive enterprise security solutions or specialized WAF services. Use it at your own risk. It is always recommended to have up-to-date backups of your site.