# 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`.
```