IskWaf - Web Application Firewall for MODX 3

Key Features

• Multi-layered Security Rules:
  • IP Address/CIDR (with priority for exact IP match over subnet).
  • User-Agent (types: contains, exact match, regular expression).
  • Referrer (types: contains, exact match, regular expression).
  • Request URI (types: contains, exact match, regular expression, starts with; with or without query string matching).
• Flexible Rule Actions: Block (403), CAPTCHA, Allow.
• Local CAPTCHA: Numeric, with a "first/last 3 digits" task from a 6-digit image, session-based.
• Optional WAF Check Modes:
  • Check on every request (standard behavior).
  • Check once per session (reduces load for already verified users).
• Logging System: Detailed WAF trigger logs, configurable modes (`full`, `triggered`, `off`), automatic old log cleanup. Logs also reflect if WAF rules were skipped due to the "once per session" mode.
• IP Address Analysis: Determination of country, region, city, ASN, and ISP for IP addresses from logs using local IP2Location LITE databases (via CRON).
• Daily Reports: Aggregated statistics on WAF events, rule types, search engine bot hits, top-N offenders (in JSON), including geolocation data.
• Management Interface (CMP): Tabs for logs (displaying country/city), each rule type, and reports; create, edit, enable/disable, delete rules.

Installation

1. Upload the component package via the "Installer" (Extras -> Installer) in the MODX manager.
2. Find the "IskWaf" package and click "Install".
3. Follow the on-screen instructions.

Configuration

After installing the component, you need to configure a few system settings, a page for CAPTCHA, and prepare the environment for GeoIP databases.

1. System Settings

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

Key	Description	Possible Values/Action
iskwaf_iskwaf_captcha_resource_id	MODX Resource ID for displaying the CAPTCHA page.	Create a new MODX resource (e.g., with alias captcha-verify), ensure it is not cacheable. In the "Resource Content" field, place the snippet call [[!IskWafCaptcha]]. Specify the ID of this resource here.
iskwaf_iskwaf_option_log	WAF Logging Mode.	full: (Default) All requests are logged (triggered rules + normal visits, including those where rules were skipped due to session check). triggered: Only requests that trigger a rule are logged. May optionally log when rules are skipped due to session check (see plugin code). off: Logging is disabled (but rules continue to operate).
iskwaf_waf_check_mode	WAF Rule Check Mode.	on_every_request: (Default) WAF rules are checked on every request. once_per_session: WAF rules are checked for a user only once per session. If the check is passed, subsequent requests in the same session do not undergo full WAF checking (but visits may be logged according to the iskwaf_iskwaf_option_log setting).
iskwaf_iskwaf_log_retention_days	Number of days to retain records in the iskwaf_logs log. Old records are deleted by a CRON script.	Number (e.g., 7, 30). Default in script: 7.
iskwaf_ip2location_download_token	Your personal token for downloading databases from the IP2Location website.	Obtain the token after registering at lite.ip2location.com and enter it here.
iskwaf_ip_analysis_limit_per_run	Maximum number of new/outdated IPs to analyze per single run of the analyze_ip2location_details.php CRON script.	Number. Default in script: 5000.
iskwaf_ip_analysis_update_interval	Frequency in days for updating information for an IP already existing in the details table.	Number. Default in script: 30.

2. CAPTCHA Page

As mentioned above, create a MODX resource to display the CAPTCHA. It should be non-cacheable and contain the snippet call [[!IskWafCaptcha? &tpl=`your_form_chunk_name`]] (the `&tpl` parameter is optional, defaults to `iskWafCaptchaFormTpl`).

3. GeoIP Setup (IP2Location)

The IskWaf component uses IP2Location LITE databases to determine geolocation, ASN, and other information for IP addresses. The database files themselves are not included in the component installation package but are downloaded using a special CRON script.

1. Get Token: Register at lite.ip2location.com and obtain your personal download token. Enter it into the iskwaf_ip2location_download_token system setting.
2. IP2Location PHP Library:

   To work with IP2Location BIN database files, the appropriate PHP library is required. The IskWaf component uses PHP library files that should be placed in the core/components/iskwaf/lib/ip2location/src/ folder. You can download the "IP2Location PHP Module" (for BIN Data File) from the official IP2Location website and place the contents of its `src` folder in the specified path.

3. Directories for Databases: Ensure that the following directories exist on the server and are writable by PHP (relative to core/components/iskwaf/):
   • tmp_db_download/ (for temporary files during download)
   • geoip_db/ (for storing unpacked BIN database files)
4. Initial Database Download: After setting up the token and placing the PHP library, run the ip2location_download.php CRON script (see below) once manually from the server's command line for the initial download of the databases (IP2LOCATION-LITE-DB11.BIN and IP2LOCATION-LITE-ASN.BIN).

4. CRON Jobs

For automatic component operation, set up three CRON jobs:

Ensure the paths to the PHP interpreter and scripts are correct for your server.

Usage (CMP)

Access the IskWaf management interface via the main MODX manager menu (usually in the "Extras" or "Applications" section).

• "Logs" Tab: View all WAF log entries with search. "Country" and "City" columns should now display data for IPs that have been processed.
• Rule Tabs (IP, User-Agent, Referrer, Request URI): Manage rules.
• "Report" Tab: View daily summary reports.

Rule Types (Detailed)

IP Rules

Designed to block, allow, or show CAPTCHA based on the visitor's IP address or CIDR subnet.

• Fields: IP/CIDR, Rule Type (action), Description, Active.
• Priority Logic: An exact IP match takes precedence over a CIDR subnet. Among CIDR subnets containing the same IP, the narrower one (largest mask) takes precedence.

Pattern Examples for IP/CIDR:

• Single IPv4: 192.168.1.100
• IPv4 CIDR (subnet): 10.0.0.0/8
• IPv6 CIDR: 2001:db8::/32

User-Agent Rules

Allow applying actions based on the User-Agent string.

• Fields: User-Agent Pattern, Pattern Type ('contains', 'exact', 'regex'), Rule Type (action), Description, Active.

Pattern Examples for User-Agent Pattern:

• Type: contains, Pattern: AhrefsBot
• Type: regex, Pattern: /^EvilCorp Crawler\/[0-9\.]+/i

Referrer Rules

Filter requests based on the HTTP Referrer.

• Fields: Referrer Pattern, Pattern Type ('contains', 'exact', 'regex'), Rule Type (action), Description, Active.

Pattern Examples for Referrer Pattern:

• Type: contains, Pattern: spam-site.com
• Type: regex, Pattern: /^https?:\/\/([\w-]+\.)*spammerdomain\.com/i

Request URI Rules

Apply actions based on the requested URI.

• Fields: URI Pattern, Pattern Type ('contains', 'exact', 'regex', 'starts_with'), Match Query String (yes/no), Rule Type (action), Description, Active.

Pattern Examples for URI Pattern:

• Type: exact, Query String: no, Pattern: /wp-login.php
• Type: starts_with, Query String: no, Pattern: /admin-backup/
• Type: contains, Query String: yes, Pattern: eval(

CAPTCHA System

IskWaf uses a local numeric CAPTCHA. An image with 6 digits is generated, and the user is asked to enter either the first or last three digits. Completion is remembered in the session. Displayed via the [[!IskWafCaptcha]] snippet (supports &tpl).

Reporting System

Daily summaries in IskWafReportDaily include: total WAF events, blocks, CAPTCHAs, rule allowances, triggers by rule type, search engine bot hits, top N IPs and rules (JSON). Generated by a CRON script.

Important Notes

Disclaimer