first commit

README.md

@@ -0,0 +1,124 @@
+# BotLimiter - Smart Traffic Control & Firewall for PrestaShop
+
+*   **Version:** 1.0.0
+*   **Author:** Panariga
+*   **Compatibility:** PrestaShop 1.7 / 8.x / 9.x
+
+## Overview
+
+**BotLimiter** is a high-performance firewall designed specifically to stop "Faceted Search Scrapers" and aggressive bots that overload PrestaShop servers by iterating through filter combinations (e.g., `?q=Category-Food` or `?order=price.asc`).
+
+Unlike standard CAPTCHAs that annoy users, BotLimiter uses a **"Cookie Trap"** mechanism. It detects heavy requests (filters/sorting) and seamlessly verifies the visitor using a lightweight JavaScript redirection flow. Real users pass instantly; dumb bots get stuck; aggressive scrapers are logged for **Fail2Ban**.
+
+## Features
+
+1.  **Request Interception:** Hooks into `actionFrontControllerInitBefore` to stop processing before the heavy Database/Theme loading starts.
+2.  **HEAD Request Block:** Instantly drops `HEAD` requests on filtered pages (a common bot tactic to check for 200 OK without downloading content).
+3.  **The "Trap" logic:**
+    *   Redirects visitors without a valid session to a lightweight HTML/JS verification page.
+    *   Generates an encrypted token based on the user's IP.
+    *   Validates the token upon auto-submission.
+4.  **Extensible Rules:** Built on a generic `RuleInterface` architecture.
+5.  **Fail2Ban Integration:** Writes offending IPs to a dedicated log file compatible with server-side banning tools.
+
+---
+
+## Installation
+
+1.  Upload the `botlimiter` folder to your `/modules/` directory.
+2.  Go to **Back Office > Modules > Module Manager**.
+3.  Find **Bot Limiter** and click **Install**.
+4.  Clear your PrestaShop cache (`Advanced Parameters > Performance`).
+
+---
+
+## Architecture
+
+The module uses the following flow:
+
+1.  **Hook:** `actionFrontControllerInitBefore`
+2.  **Rule Engine:** Checks if the request is "Heavy" (contains `q=` or `order=` parameters).
+3.  **Allowlist:** Passes `Googlebot`, `Bingbot`, and legitimate users with a verified session cookie.
+4.  **Verification:**
+    *   If unverified, redirects to `module-botlimiter-verify`.
+    *   This controller renders a minimal template (no heavy footer/header).
+    *   Javascript automatically appends an encrypted token and redirects back to the original URL.
+5.  **Validation:** The module decrypts the token. If it matches the IP, a session cookie is set, and the user can browse freely.
+
+---
+
+## Fail2Ban Configuration (Virtualmin / Universal)
+
+The module writes logs to:  
+`/your_shop_root/var/logs/botlimiter_ban.log`
+
+The format is:  
+`[YYYY-MM-DD HH:MM:SS] [IP:192.168.1.1] [REASON:HEAD_REQUEST_SPAM]`
+
+### 1. Create the Filter
+
+Create a new file `/etc/fail2ban/filter.d/prestashop-bot.conf`:
+
+```ini
+[Definition]
+# Regex to match the custom log format from BotLimiter
+failregex = ^\[.*\] \[IP:<HOST>\] \[REASON:.*\]$
+
+# Ignore nothing
+ignoreregex =
+```
+
+### 2. Create the Jail (Virtualmin Universal Rule)
+
+We need a rule that scans **all** virtual servers on your machine. Virtualmin typically stores web roots in `/home/USERNAME/public_html` or `/home/USERNAME/domains/DOMAIN/public_html`.
+
+Add this to your `/etc/fail2ban/jail.local` (or `jail.conf`):
+
+```ini
+[prestashop-bot]
+enabled  = true
+port     = http,https
+filter   = prestashop-bot
+# Multi-path configuration to scan all Virtualmin domains
+logpath  = /home/*/public_html/var/logs/botlimiter_ban.log
+           /home/*/domains/*/public_html/var/logs/botlimiter_ban.log
+
+# OPTIONS:
+# maxretry: Number of times a bot can hit the trap before ban
+maxretry = 5
+
+# findtime: Time window (seconds) to count the retries (10 minutes)
+findtime = 600
+
+# bantime: How long to ban them (1 hour)
+bantime  = 3600
+
+# Backend: standard "auto" or "pyinotify" works best for wildcards
+backend  = auto
+```
+
+### 3. Restart Fail2Ban
+
+```bash
+service fail2ban restart
+# OR
+systemctl restart fail2ban
+```
+
+### 4. Verify It Works
+
+To check if Fail2Ban is correctly monitoring the files across your Virtualmin domains:
+
+```bash
+fail2ban-client status prestashop-bot
+```
+
+You should see a list of "File list" showing the log paths it found across your home directories.
+
+---
+
+## Troubleshooting
+
+*   **Users complain about loops:** Ensure JavaScript is enabled. The verification controller relies on JS to append the token.
+*   **Whitelisting:** If you have a specific monitoring service (like UptimeRobot), ensure you add their User-Agent to `classes/rules/FilterTrapRule.php`.
+```