1. Overview

IskFileGuardian is a component for MODX Revolution 3.x, representing an automated system for monitoring the file integrity of both the entire website and the MODX core. The component allows for effective detection of any changes, including modifications, additions, and deletions of files. Upon detecting discrepancies, IskFileGuardian can send notifications to the administrator via Email and Telegram messenger. All actions and events are logged, and the results of scans are available for analysis through an intuitive built-in interface in the MODX control panel.

2. Target Platform

  • MODX Revolution 3.x

3. Key Features

The IskFileGuardian component provides a wide range of functions to ensure the security and control of your website's file system:

  • File Change Monitoring:

    • Tracking modifications, appearance of new files, and deletion of existing files in specified website directories for monitoring.
    • Automated creation and regular updating of file hashes, covering both the MODX core and any custom folders.

  • MODX Core Integrity Control:

    • Comparison of current MODX installation files with files from the official release of the corresponding version.
    • Calculation of checksums for core files and tracking of any discrepancies.
    • Flexible configuration of paths related to the core and definition of exclusion patterns for more accurate analysis.

  • Advanced Exclusion Settings:

    • Ability to exclude any files and folders from the verification process using flexible patterns (e.g., file masks, subdirectory specification, extension filtering, etc.).
    • Maintenance of separate exclusion lists for scanning website files and MODX core files.

  • Flexible Notification System:

    • Sending notifications about any detected changes via Email, with support for customizable email templates and the ability to specify multiple recipients.
    • Instant alerts for critical changes via Telegram.
    • Customization of message format using MODX chunks, allowing adaptation to specific needs.
    • Separate configuration of notification settings for events related to website files and core files.

  • Detailed History and Reports:

    • All verification results and current file statuses (e.g., added, modified, deleted) are recorded in specialized database tables.
    • Convenient built-in interface for viewing scan history, system logs, and sent notifications.
    • Saving detailed reports for each verification run, with detailed information for each file that underwent changes.

  • High Performance and Security:

    • Ability to operate on a schedule using the system task scheduler (cron) for automated checks.
    • Automatic deletion of all temporary files created during operation, and no locks affecting website performance.

4. Requirements

For the IskFileGuardian component to work correctly, the following conditions must be met:

  • CMS: MODX Revolution 3.x or higher.
  • PHP: Version 7.2 or higher.
  • PHP Extensions:
    • curl (for downloading MODX core distributions)
    • zip (for unpacking archives)

5. Installation

The installation process for the IskFileGuardian component is standard for MODX:

  1. Installation via Package Manager: Install the IskFileGuardian component from the official MODX repository or by manually uploading the package via the Package Manager in the control panel.
  2. Configuration of System Settings: After installation, go to the "System Settings" section of MODX, select the iskfileguardian namespace, and configure the necessary component parameters (see section 6 for details).
  3. Initialization of Core Hashes: In the component's "Core Hashes" tab (in the CMP), click the "Download Core" button. The process may take some time (about a minute or more), during which the official distribution of your MODX version will be downloaded and reference hashes for core files will be created.
  4. CRON Job Setup (recommended): For automatic monitoring, set up the execution of scan scripts via CRON (see section 7.2 for details).

6. Component Configuration (System Settings)

All main settings for the IskFileGuardian component are configured via "System Settings" in MODX under the iskfileguardian namespace.

6.1. Main:

  • iskfileguardian.enabled: Enable/disable the component (Yes/No).
  • iskfileguardian.scan_dirs: Directories for scanning the website's file system. Specify each path on a new line (e.g., assets/images/, core/components/mycomponent/).
  • iskfileguardian.exclude_paths: Exclusion patterns for scanning website files. Specify each pattern on a new line. You can use wildcards (e.g., *.log, temp/*, assets/cache/).
  • iskfileguardian.hash_algo: Hashing algorithm used for files (sha256 recommended, md5 also available).

6.2. MODX Core:

  • iskfileguardian.core.enabled: Enable separate integrity checking for the MODX core (Yes/No).
  • iskfileguardian.core_modx_ver: MODX core version for comparison. Usually detected automatically when downloading hashes.
  • iskfileguardian.core.hashes_url: Path (URL or local path) for storing the file with reference core hashes. By default, the component manages this automatically.
  • iskfileguardian.core_paths: Paths considered part of the MODX core and subject to verification (e.g., core/, manager/). Specify each path on a new line.
  • iskfileguardian.exclude_patterns: Exclusion patterns for core verification (e.g., core/config/config.inc.php, core/cache/*). Specify each pattern on a new line.

6.3. Notifications (Email):

  • iskfileguardian.em.enabled: Enable email notifications for changes (Yes/No).
  • iskfileguardian.em.to_addr: Email addresses of notification recipients (multiple addresses can be specified, comma-separated).
  • iskfileguardian.em.from_addr: Sender's email address for notifications.
  • iskfileguardian.em.subj_chunk: Name of the MODX chunk for formatting the notification email subject.
  • iskfileguardian.em.body_chunk: Name of the MODX chunk for formatting the notification email body.
  • iskfileguardian.em.site_notify: Notify by Email about changes in website files (Yes/No).
  • iskfileguardian.em.core_notify: Notify by Email about changes in MODX core files (Yes/No).

6.4. Notifications (Telegram):

  • iskfileguardian.tg.enabled: Enable Telegram notifications for changes (Yes/No).
  • iskfileguardian.tg.bot_token: Your Telegram bot token.
  • iskfileguardian.tg.chat_id: Chat ID of the recipient or group in Telegram.
  • iskfileguardian.tg.site_notify: Notify via Telegram about changes in website files (Yes/No).
  • iskfileguardian.tg.core_notify: Notify via Telegram about changes in MODX core files (Yes/No).

6.5. Logging:

  • iskfileguardian.log_level: Minimum logging level for component events (e.g., INFO, ERROR).
  • iskfileguardian.log_storage: Log storage method (Database — in a DB table, or file — in a file).

7. Usage

7.1. Example Scenarios

  • Automatic CRON Check:

    Set up regular execution of scan scripts (see section 7.2). The component will automatically scan specified directories, compare hashes with reference ones, write a detailed report, and, if changes are present, send notifications to the administrator.

  • MODX Core Integrity Control:

    The component allows regular comparison of the current state of your MODX installation's core files with reference files downloaded from the official distribution. This helps detect unauthorized modifications or corruption of core files.

  • Monitoring Custom Files and Components:

    You can flexibly configure the component to monitor any folders important to you, such as directories with your own components (core/components/myextra/, assets/components/myextra/) or folders with media files, while using the exclusion system to ignore temporary files or cache.

7.2. CRON Job Setup

To automatically run scans, set up the following CRON jobs on your server:

Check MODX Core only:

/usr/bin/php8.1 /full/path/to/your/site/core/components/iskfileguardian/elements/cron/scan_core.php

(Replace /usr/bin/php8.1 with the actual path to the PHP interpreter on your server and /full/path/to/your/site/ with the real path to your MODX site's root directory).

Check all website files (according to iskfileguardian.scan_dirs settings):

/usr/bin/php8.1 /full/path/to/your/site/core/components/iskfileguardian/elements/cron/scan_site.php

(Similarly, adapt the paths for PHP and your site).

It is recommended to set up these jobs to run at a frequency corresponding to your security requirements (e.g., daily or hourly).

8. Built-in Interface

The IskFileGuardian component provides a convenient management interface accessible in the MODX admin panel:

  • View Files and Hashes: An ExtJS grid (table) for displaying a list of tracked files, their current hashes, statuses, and change history.
  • Manage Hashes: Ability to quickly initiate generation (or regeneration) of hashes for website or core files directly from the interface.
  • Manage Reports and Logs: Buttons and tools for manually clearing outdated data, viewing detailed scan reports, and searching through files and log entries.

9. Notification System

IskFileGuardian ensures timely information about detected changes:

  • Email Notifications:
    • Support for sending notifications to multiple Email addresses simultaneously.
    • Full customization of the email subject and body using standard MODX chunks, allowing for message branding and inclusion of any necessary information.
  • Telegram Notifications:
    • Simple integration with your Telegram bot (only bot token and recipient's Chat ID required).
    • Messages in Telegram are sent only upon actual detection of new, modified, or deleted files, minimizing informational noise.
  • Sending Condition: Notifications are generated and sent only if changes (new, modified, or deleted files) were recorded during the scan compared to the previous state or reference hashes.

10. Database Structure

The component uses several tables in the MODX database to store its information:

iskfileguardian_hashes
The main table storing information about found website files (non-core), their hashes, and statuses (e.g., added, modified, deleted, current).
iskfileguardian_core_hashes
Table for storing reference hashes of MODX core files.
iskfileguardian_reports
Table where all scan results are saved and reports are formed.
iskfileguardian_logs
Table for supporting extended logging of component actions (if "Database" is selected as the log storage method).

11. Conclusion

IskFileGuardian — your personal guardian for MODX files.

Control everything. Get notified instantly.