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

--------------------
https://ifgdoc.ivan345.com/en/
https://ifgdoc.ivan345.com/ru/

For MODX Revolution 3.x.

**IskFileGuardian**

**Description**

IskFileGuardian is a component for MODX3 that implements an automated file integrity monitoring system for the entire website and the MODX core. It allows for the detection of any changes, modifications, additions, and deletions of files, as well as sending notifications to the administrator via Email and Telegram. All actions are logged, and scan results are available through a built-in interface.

**Key Features**

* **File Change Monitoring**
    Tracks changes, the appearance of new files, and the deletion of old files in specified website directories.
    Automatic creation and updating of file hashes, including the MODX core and custom folders.
* **MODX Core Integrity Control**
    Compares files with the official release, calculates checksums, and tracks any differences.
    Ability to configure any "core" paths and exclusion patterns.
* **Advanced Exclusion Settings**
    Exclude any files and folders from checks using patterns (wildcards, subdirectories, extensions, etc.).
    Separate lists for scanning the website and the core.
* **Flexible Notification System**
    Email notifications for any changes (customizable templates, multiple recipients).
    Instant alerts in Telegram.
    Customizable message format via MODX chunks.
    Separate notification settings for the website and the core.
* **Detailed History and Reports**
    All check results and file statuses are recorded in separate tables.
    Built-in interface for viewing history, logs, and notifications.
    Reports are saved for each scan run, with details for each file.
* **High Performance and Security**
    Runs on a schedule (cron).
    Deletes all temporary files and does not block website operation.

---
**Main Settings**

The component is fully configurable through MODX System Settings:

* **Main:**
    * `iskfileguardian.enabled` — Enable/disable the component.
    * `iskfileguardian.scan_dirs` — Directories to scan (each on a new line).
    * `iskfileguardian.exclude_paths` — Exclusion patterns (each on a new line).
    * `iskfileguardian.hash_algo` — Hashing algorithm (sha256/md5).
* **MODX Core:**
    * `iskfileguardian.core.enabled` — Enable separate core checking.
    * `iskfileguardian.core_modx_ver` — Core version for comparison (detected automatically).
    * `iskfileguardian.core.hashes_url` — Path to store core hashes.
    * `iskfileguardian.core_paths` — Paths considered as core.
    * `iskfileguardian.exclude_patterns` — Exclusions for the core.
* **Notifications (Email):**
    * `iskfileguardian.em.enabled` — Enable email notifications.
    * `iskfileguardian.em.to_addr` — Recipient email addresses (comma-separated).
    * `iskfileguardian.em.from_addr` — Sender's email.
    * `iskfileguardian.em.subj_chunk` — Chunk for the email subject.
    * `iskfileguardian.em.body_chunk` — Chunk for the email body.
    * `iskfileguardian.em.site_notify` — Notify about website files.
    * `iskfileguardian.em.core_notify` — Notify about core files.
* **Notifications (Telegram):**
    * `iskfileguardian.tg.enabled` — Enable Telegram notifications.
    * `iskfileguardian.tg.bot_token` — Telegram bot token.
    * `iskfileguardian.tg.chat_id` — Recipient's Chat ID.
    * `iskfileguardian.tg.site_notify` — Notify about website files.
    * `iskfileguardian.tg.core_notify` — Notify about core files.
* **Logging:**
    * `iskfileguardian.log_level` — Minimum logging level.
    * `iskfileguardian.log_storage` — Log storage method (Database/file).

---
**Example Scenarios**

* **Automatic Cron Check:**
    Simply call the script provided with the component — it will perform the scan, compare hashes, write a report, and send notifications if there are changes.
* **Core Control:**
    Comparison of the current state of core files with a reference, downloaded from the official MODX distribution.
* **Monitoring Custom Files:**
    You can configure any folders and exclusions (e.g., to track only `core/components/` and `assets/components/`).

---
**Built-in Interface**

* ExtJS grid for viewing files and hashes, logs, and reports.
* Quick launch of new hash generation directly from the admin panel.
* Buttons for manual clearing, regeneration, viewing reports, and searching files.

---
**Notifications**

* **Email:** Support for multiple recipients, customization of subject and body via chunks.
* **Telegram:** Simple integration with a bot (only token and chat_id required), messages are sent only when changes are detected.
* Notifications are sent only if there are new/modified/deleted files.

---
**Database**

* All found files and their statuses (added, modified, deleted, current) — stored in the `iskfileguardian_hashes` table.
* MODX core hashes — in a separate `iskfileguardian_core_hashes` table.
* All scan results and reports — in the `iskfileguardian_reports` table.
* Support for extended logging via the `iskfileguardian_logs` table.

---
**Requirements**

* MODX Revolution 3.x
* PHP 7.2+
* PHP Extensions: curl, zip

---
**Installation**

1.  Install the component via the repository.
2.  Configure the parameters in the component's "System Settings".
3.  In the "Core Hashes" tab, click "Download Core" - wait for about a minute or more while the MODX distribution of your version is downloaded and hashes are created.
4.  Create a CRON job.

    `/usr/bin/php8.1 your_path/core/components/iskfileguardian/elements/cron/scan_core.php` – checks only the core

    `/usr/bin/php8.1 your_path/core/components/iskfileguardian/elements/cron/scan_site.php` -
    Checks all sites (website files)

---
IskFileGuardian — your personal guardian for MODX files.
Control everything. Get notified instantly.

