From 817f847b314e09e3d50cb453711d43b7222c9a5c Mon Sep 17 00:00:00 2001
From: thomasciesla <thomas.ciesla@jtl-software.com>
Date: Mon, 22 Dec 2025 14:28:21 +0100
Subject: [PATCH] README.md aktualisiert

---
 README.md | 502 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 317 insertions(+), 185 deletions(-)

diff --git a/README.md b/README.md
index f5edf99..e4659ec 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-# 🛡️ JTL-WAFi v2.3
+# 🛡️ JTL-WAFi v2.4
 
 **Web Application Firewall für JTL-Shops** - Ein verteiltes Bot-Protection und GeoIP-Blocking System mit Echtzeit-Dashboard, WebSocket-Kommunikation und zentraler Verwaltung mehrerer Server.
 
-![Version](https://img.shields.io/badge/version-2.3.0-blue)
+![Version](https://img.shields.io/badge/version-2.4.0-blue)
 ![Python](https://img.shields.io/badge/python-3.8+-green)
 ![License](https://img.shields.io/badge/license-MIT-orange)
 
@@ -22,6 +22,8 @@
   - [Einzelne Shops](#einzelne-shops-verwalten)
   - [Massenaktionen](#massenaktionen)
   - [Monitoring](#monitoring)
+- [Blocking-Mechanismus](#-blocking-mechanismus)
+- [Bot-Erkennung](#-bot-erkennung)
 - [API-Referenz](#-api-referenz)
 - [WebSocket Events](#-websocket-events)
 - [Datenstrukturen](#-datenstrukturen)
@@ -43,14 +45,15 @@ JTL-WAFi besteht aus zwei Komponenten:
 
 | Modus | Beschreibung | Anwendungsfall |
 |-------|--------------|----------------|
-| **🤖 Bot Rate-Limiting** | Erkennt und limitiert aggressive Bots basierend auf User-Agent-Analyse | Schutz vor Scraping, SEO-Bots, Crawlern |
+| **🤖 Bot Rate-Limiting** | Erkennt und limitiert aggressive Bots basierend auf User-Agent und IP-Analyse | Schutz vor Scraping, SEO-Bots, AI-Crawlern |
+| **🔍 Bot Monitor-Only** | Erkennt und loggt Bots ohne zu blockieren | Analyse vor Aktivierung |
 | **🌍 GeoIP-Blocking** | Blockiert Traffic aus nicht-relevanten Regionen | Shops die nur DACH/EU beliefern |
 
 ---
 
 ## ✨ Features
 
-### Dashboard (v2.3)
+### Dashboard (v2.4)
 
 #### Übersicht & Monitoring
 - **📊 Echtzeit-Statistiken** - Server online, aktive Shops, Requests/min, aktive Bans
@@ -64,6 +67,7 @@ JTL-WAFi besteht aus zwei Komponenten:
 - **🔍 Sortierbare Shop-Liste** - Nach Requests/min oder aktiven Bans
 - **🖥️ Multi-Agent Support** - Verwaltung beliebig vieler Server von einem Dashboard
 - **🔐 Token-basierte Auth** - Sichere Agent-Freigabe
+- **🔄 Modus-Wechsel** - Direkter Wechsel zwischen Bot/GeoIP/Monitor im Detail-Modal
 
 #### Technisch
 - **WebSocket Real-Time** - Keine Polling, sofortige Updates
@@ -71,20 +75,22 @@ JTL-WAFi besteht aus zwei Komponenten:
 - **SSL/TLS** - Automatische selbstsignierte Zertifikatsgenerierung
 - **Responsive Design** - Funktioniert auf Desktop, Tablet und Mobile
 
-### Agent (v2.3)
+### Agent (v2.4)
 
 #### Erkennung & Blocking
-- **🔍 Auto-Discovery** - Findet automatisch alle JTL-Shops auf dem Server
-- **📝 Log-Analyse** - Parst Nginx Access-Logs in Echtzeit
-- **🤖 Bot-Erkennung** - Identifiziert 50+ bekannte Bot-Typen
-- **🚫 IP-Banning** - Dynamisches Blocking via iptables
-- **🌍 GeoIP-Lookup** - MaxMind GeoLite2 Datenbank
+- **🔍 Auto-Discovery** - Findet automatisch alle JTL-Shops in `/var/www/vhosts/`
+- **📝 Log-Analyse** - Liest Shop-Logs für Statistiken
+- **🤖 Bot-Erkennung** - Identifiziert **200+ bekannte Bot-Typen** via User-Agent
+- **🌐 IP-basierte Erkennung** - Erkennt getarnte Bots (z.B. Alibaba) anhand ihrer IP-Ranges
+- **🚫 PHP-Blocking** - Dynamisches Blocking via PHP-Skript (kein iptables!)
+- **🌍 GeoIP-Lookup** - IP-Ranges von ipdeny.com für Länder-Blocking
 
 #### Zuverlässigkeit
-- **♻️ Auto-Reconnect** - Automatische Wiederverbindung zum Dashboard
+- **♻️ Auto-Reconnect** - Automatische Wiederverbindung zum Dashboard mit Exponential Backoff
 - **🔑 Token-Auth** - Sichere Authentifizierung nach Freigabe
 - **⏹️ Graceful Shutdown** - Sauberes Beenden mit Ctrl+C (SIGINT/SIGTERM)
-- **💾 Token-Persistenz** - Token wird lokal gespeichert
+- **💾 Token-Persistenz** - Token wird lokal in `/etc/jtl-wafi/token` gespeichert
+- **📋 Log-Rotation** - Automatische Rotation bei 10 MB (3 Backups)
 
 ---
 
@@ -128,7 +134,7 @@ JTL-WAFi besteht aus zwei Komponenten:
 │  Agent  │ ──── agent.connect ────────► │ Dashboard │
 │         │ ◄─── auth.approved ───────── │           │
 │         │                              │           │
-│         │ ──── agent.heartbeat ──────► │           │  (alle 30s)
+│         │ ──── agent.heartbeat ──────► │           │  (alle 60s)
 │         │ ──── shop.full_update ─────► │           │
 │         │ ──── shop.stats ───────────► │           │  (alle 10s)
 │         │                              │           │
@@ -143,6 +149,105 @@ JTL-WAFi besteht aus zwei Komponenten:
 
 ---
 
+## 🔧 Blocking-Mechanismus
+
+### So funktioniert das Blocking
+
+JTL-WAFi blockiert **NICHT** via iptables, sondern durch ein **PHP-Skript**, das in die Shop-`index.php` eingebunden wird:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      HTTP Request                            │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Nginx / Apache                            │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      index.php                               │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  require_once __DIR__ . '/jtl-wafi.php';  ◄── NEU     │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                          │                                   │
+│                          ▼                                   │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │                   jtl-wafi.php                         │  │
+│  │  • Prüft IP gegen erlaubte Länder (GeoIP-Mode)        │  │
+│  │  • Erkennt Bots via User-Agent + IP-Ranges            │  │
+│  │  • Rate-Limiting pro Bot-Typ (nicht pro IP!)          │  │
+│  │  • Bei Verstoß: 403 Forbidden + exit                  │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                          │                                   │
+│                          ▼                                   │
+│              [Rest der Shop-Logik]                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Dateien pro Shop (bei Aktivierung)
+
+| Datei | Beschreibung |
+|-------|--------------|
+| `index.php` | Modifiziert mit `require_once` für jtl-wafi.php |
+| `index.php.jtl-wafi_backup` | Backup der Original index.php |
+| `jtl-wafi.php` | Das eigentliche Blocking-Skript |
+| `jtl-wafi_ip_ranges.cache` | Gecachte IP-Ranges (nur GeoIP-Mode) |
+| `jtl-wafi_blocked.log` | Log der blockierten Requests |
+| `jtl-wafi_ratelimit/` | Verzeichnis für Rate-Limit-Daten (nur Bot-Mode) |
+
+### GeoIP-Blocking
+
+- Lädt IP-Ranges von **ipdeny.com** (z.B. `de-aggregated.zone`)
+- Cached die Ranges lokal für 24 Stunden
+- **FAIL-OPEN**: Bei Problemen mit dem Cache wird Traffic durchgelassen
+- Mindestanforderung: 1000 Ranges (DACH) / 5000 Ranges (Eurozone)
+
+### Bot Rate-Limiting
+
+- Erkennung via **User-Agent Patterns** (200+ Bots)
+- Erkennung via **IP-Ranges** (z.B. Alibaba Cloud)
+- Rate-Limit gilt **pro Bot-Typ**, nicht pro IP
+- Beispiel: Alle AhrefsBot-Requests teilen sich ein Limit
+- Ban-Dateien speichern Bot-Namen für Dashboard-Anzeige
+
+---
+
+## 🤖 Bot-Erkennung
+
+### Erkannte Bot-Kategorien
+
+| Kategorie | Beispiele | Anzahl |
+|-----------|-----------|--------|
+| **AI/LLM Services** | GPTBot, ClaudeBot, PerplexityBot, Bytespider | 50+ |
+| **Suchmaschinen** | Googlebot, Bingbot, Baiduspider, YandexBot | 30+ |
+| **SEO & Marketing** | AhrefsBot, SemrushBot, MJ12Bot, DotBot | 15+ |
+| **Social Media** | FacebookBot, Twitterbot, LinkedInBot | 20+ |
+| **E-Commerce** | Amazonbot, Alibaba-Bot, Idealo, Shopify | 15+ |
+| **Archiv & Research** | Archive.org Bot, CCBot, Heritrix | 10+ |
+| **HTTP Libraries** | Python-Requests, cURL, Wget, Scrapy | 30+ |
+| **Security Scanner** | Nessus, SQLMap, Nikto, Burp Suite | 15+ |
+| **Headless Browsers** | PhantomJS, Puppeteer, Playwright | 10+ |
+
+### IP-basierte Erkennung
+
+Manche Bots tarnen sich mit normalem User-Agent. Diese werden über ihre IP-Ranges erkannt:
+
+```
+Alibaba-Bot IP-Ranges:
+├── 43.0.0.0/9        (Alibaba Cloud Singapore)
+├── 8.128.0.0/10      (Alibaba Cloud)
+├── 47.74.0.0/15      (Alibaba Cloud)
+├── 39.96.0.0/13      (Aliyun China)
+└── ... (40+ weitere Ranges)
+```
+
+### Generische Fallback-Patterns
+
+Falls kein spezifischer Bot erkannt wird, prüft das System auf generische Begriffe:
+`bot`, `crawler`, `spider`, `scraper`, `fetch`, `scan`, `monitor`, `probe`, `index`, `archive`, etc.
+
+---
+
 ## 📦 Voraussetzungen
 
 ### Dashboard Server
@@ -152,7 +257,7 @@ JTL-WAFi besteht aus zwei Komponenten:
 python3 --version
 
 # Benötigte Pakete
-pip3 install fastapi uvicorn websockets python-multipart --break-system-packages
+pip3 install fastapi uvicorn python-multipart --break-system-packages
 
 # OpenSSL für Zertifikate
 apt install openssl
@@ -164,21 +269,17 @@ apt install openssl
 # Python 3.8+
 python3 --version
 
-# Benötigte Pakete
-pip3 install websockets geoip2 watchdog --break-system-packages
+# Benötigte Pakete (NUR websockets!)
+pip3 install websockets --break-system-packages
 
-# MaxMind GeoLite2 Datenbank
-# Download von: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
-mkdir -p /var/lib/GeoIP
-# GeoLite2-Country.mmdb hierhin kopieren
+# PHP CLI (für Cache-Generierung)
+apt install php-cli
 
-# iptables für IP-Blocking
-apt install iptables
-
-# Nginx (für Log-Analyse)
-# Muss bereits installiert sein
+# Nginx oder Apache (muss bereits installiert sein)
 ```
 
+> **Hinweis**: Der Agent benötigt KEIN `geoip2` oder `watchdog` Modul! Die GeoIP-Prüfung erfolgt komplett im PHP-Skript.
+
 ---
 
 ## 🚀 Installation
@@ -213,8 +314,6 @@ systemctl status jtl-wafi
 ```bash
 # Port 8000 öffnen (oder anderen konfigurierten Port)
 ufw allow 8000/tcp
-# ODER
-iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
 ```
 
 #### Erster Login
@@ -230,20 +329,21 @@ iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
 
 ```bash
 # Verzeichnis erstellen
-mkdir -p /opt/jtl-wafi-agent
-mkdir -p /etc/jtl-wafi-agent
-cd /opt/jtl-wafi-agent
+mkdir -p /opt/jtl-wafi
+mkdir -p /etc/jtl-wafi
+mkdir -p /var/lib/jtl-wafi
+cd /opt/jtl-wafi
 
 # Agent kopieren
-cp jtl_wafi_agent.py /opt/jtl-wafi-agent/
+cp jtl_wafi_agent.py /opt/jtl-wafi/
 
 # Systemd Service installieren
-python3 /opt/jtl-wafi-agent/jtl_wafi_agent.py --install-service
+python3 /opt/jtl-wafi/jtl_wafi_agent.py --install-service
 
 # Service konfigurieren (Dashboard URL setzen)
 nano /etc/systemd/system/jtl-wafi-agent.service
 # ExecStart anpassen:
-# ExecStart=/usr/bin/python3 /opt/jtl-wafi-agent/jtl_wafi_agent.py --url wss://DASHBOARD-IP:8000/ws/agent
+# ExecStart=/usr/bin/python3 /opt/jtl-wafi/jtl_wafi_agent.py --url wss://DASHBOARD-IP:8000/ws/agent
 
 # Service aktivieren und starten
 systemctl daemon-reload
@@ -259,7 +359,7 @@ systemctl status jtl-wafi-agent
 1. Im Dashboard erscheint der neue Agent mit Status "🟡 Warte"
 2. Auf "✓ Freigeben" klicken
 3. Agent erhält Token und wird "🟢 Online"
-4. Token wird automatisch in `/etc/jtl-wafi-agent/token` gespeichert
+4. Token wird automatisch in `/etc/jtl-wafi/token` gespeichert
 
 ---
 
@@ -277,10 +377,10 @@ systemctl status jtl-wafi-agent
 python3 jtl_wafi_dashboard.py --help
 
 Options:
-  --host TEXT      Host zum Binden [default: 0.0.0.0]
-  --port INTEGER   Port [default: 8000]
-  --no-ssl         SSL deaktivieren
-  --install-service  Systemd Service erstellen
+  --host TEXT          Host zum Binden [default: 0.0.0.0]
+  --port INTEGER       Port [default: 8000]
+  --no-ssl             SSL deaktivieren
+  --install-service    Systemd Service erstellen
 ```
 
 ### Agent Kommandozeilen-Optionen
@@ -289,163 +389,152 @@ Options:
 python3 jtl_wafi_agent.py --help
 
 Options:
-  --url TEXT       Dashboard WebSocket URL [required]
-  --token TEXT     Auth Token (optional, wird nach Freigabe gespeichert)
-  --install-service  Systemd Service erstellen
+  --url TEXT           Dashboard WebSocket URL 
+                       [default: wss://shop000.jtl-hosting.de:8000/ws/agent]
+  --debug              Debug-Logging aktivieren
+  --install-service    Systemd Service erstellen
+  --check-deps         Abhängigkeiten prüfen
 ```
 
-### Dateipfade
+### Agent Pfade
 
-#### Dashboard
-```
-/opt/jtl-wafi/jtl_wafi_dashboard.py      # Hauptprogramm
-/var/lib/jtl-wafi/config.json            # Passwort-Hash
-/var/lib/jtl-wafi/tokens.json            # Agent-Tokens
-/var/lib/jtl-wafi/ssl/server.crt         # SSL Zertifikat
-/var/lib/jtl-wafi/ssl/server.key         # SSL Private Key
-```
+| Pfad | Beschreibung |
+|------|--------------|
+| `/etc/jtl-wafi/token` | Gespeicherter Auth-Token |
+| `/var/lib/jtl-wafi/active_shops.json` | Liste aktiver Shops mit Konfiguration |
+| `/var/log/jtl-wafi.log` | Agent-Logdatei (mit Rotation) |
+| `/var/www/vhosts/` | Shop-Verzeichnisse (Auto-Discovery) |
 
-#### Agent
-```
-/opt/jtl-wafi-agent/jtl_wafi_agent.py    # Hauptprogramm
-/etc/jtl-wafi-agent/token                 # Auth Token
-/var/log/jtl-wafi-agent.log               # Log-Datei
-/var/lib/GeoIP/GeoLite2-Country.mmdb     # GeoIP Datenbank
-```
+### GeoIP Regionen
+
+| Region | Länder | Beschreibung |
+|--------|--------|--------------|
+| `dach` | DE, AT, CH | Deutschland, Österreich, Schweiz |
+| `eurozone` | 22 Länder | DE, AT, CH, BE, CY, EE, ES, FI, FR, GB, GR, HR, IE, IT, LT, LU, LV, MT, NL, PT, SI, SK |
+| `none` | - | Kein GeoIP (nur für Bot-Mode) |
+
+### Rate-Limit Defaults
+
+| Parameter | Wert | Beschreibung |
+|-----------|------|--------------|
+| Rate-Limit | 30 req/min | Pro Bot-Typ |
+| Ban-Dauer | 5 Minuten | Nach Überschreitung |
+| Script-Gültigkeit | 72 Stunden | Danach automatische Deaktivierung |
 
 ---
 
-## 📖 Verwendung
+## 🖥️ Verwendung
 
 ### Einzelne Shops verwalten
 
-#### Shop aktivieren (Bot Rate-Limiting)
+#### Aktivieren (Bot-Mode)
+```
+Dashboard → Shop auswählen → "Aktivieren"
+→ Modus: Bot Rate-Limiting
+→ Rate-Limit: 30/min (Standard)
+→ Ban-Dauer: 5 min (Standard)
+```
 
-1. Shop in der Liste finden
-2. "Start" Button klicken
-3. Modus wählen: "🤖 Bot Rate-Limiting"
-4. Rate-Limit einstellen (z.B. 30 Requests/min pro Bot)
-5. Ban-Dauer einstellen (z.B. 300 Sekunden = 5 Minuten)
-6. "Aktivieren" klicken
+#### Aktivieren (GeoIP-Mode)
+```
+Dashboard → Shop auswählen → "Aktivieren"
+→ Modus: GeoIP-Blocking
+→ Region: DACH oder Eurozone
+```
 
-#### Shop aktivieren (GeoIP-Blocking)
+#### Aktivieren (Monitor-Only)
+```
+Dashboard → Shop auswählen → "Aktivieren"
+→ Modus: Bot Rate-Limiting
+→ ☑️ Nur Monitoring (kein Blocking)
+```
 
-1. Shop in der Liste finden
-2. "Start" Button klicken
-3. Modus wählen: "🌍 GeoIP-Blocking"
-4. Region wählen:
-   - **DACH**: Deutschland, Österreich, Schweiz
-   - **Eurozone**: EU-Länder + Großbritannien
-5. "Aktivieren" klicken
-
-#### Shop deaktivieren
-
-1. "Stop" Button beim aktiven Shop klicken
-2. Bestätigung
-3. Alle Bans werden aufgehoben
+#### Modus wechseln
+```
+Dashboard → Shop-Karte klicken → Detail-Modal
+→ "Modus wechseln" Button
+→ Ziel-Modus auswählen
+```
 
 ### Massenaktionen
 
 #### Alle Shops aktivieren
-
-1. "▶️ Aktivieren..." Button klicken
-2. Modus und Parameter wählen
-3. Filter wählen:
-   - Alle inaktiven Shops
-   - Nur Direkte (⚡) - ohne Link11
-   - Nur Link11 (🛡️)
-4. "Aktivieren" klicken
+```
+Dashboard → "⚡ Bulk-Aktivierung"
+→ Filter: Link11 / Direkt / Alle
+→ Modus und Parameter wählen
+→ Bestätigen
+```
 
 #### Alle Shops deaktivieren
-
-1. "⏹️ Deaktivieren..." Button klicken
-2. Filter wählen
-3. "Deaktivieren" klicken
+```
+Dashboard → "🛑 Bulk-Deaktivierung"
+→ Filter: Link11 / Direkt / Alle
+→ Bestätigen
+```
 
 ### Monitoring
 
-#### Top 10 Shops
+#### Live-Logs anzeigen
+```
+Dashboard → Shop-Karte → "📜" Button
+→ Echtzeit-Log-Stream
+→ Gebannte Requests werden rot markiert
+```
 
-- Zeigt die 10 Shops mit den meisten Requests/min
-- Klick auf einen Shop öffnet Detail-Modal
-- Klick auf Überschrift öffnet sortierbare Gesamtliste
+#### Shop-Details & Graph
+```
+Dashboard → Shop-Karte klicken
+→ Statistiken, Top-Bots, aktive Bans
+→ Bot-Aktivitäts-Graph mit Zeitachse
+```
 
-#### Shop-Details
-
-1. Auf Shop-Domain klicken
-2. Detail-Modal zeigt:
-   - **Status, Modus, Region, Rate-Limit, Ban-Dauer, Laufzeit**
-   - **Aktuelle Stats**: Req/min, Aktive Bans, Total Bans
-   - **Bot-Aktivitäts-Graph**: Zeitverlauf pro Bot-Typ
-   - **Top Bots**: Meistaktive Bots
-   - **Gebannte Bots**: Aktuell gesperrte Bot-Typen
-
-#### Live Logs
-
-1. 📜 Icon beim Shop klicken
-2. Log-Panel öffnet sich unten
-3. Echtzeit-Anzeige der Log-Einträge
-4. Farbkodierung:
-   - **Rot**: BANNED Events
-   - **Gelb**: BLOCKED Events
-   - **Grau**: Normale Requests
+#### Alle Shops sortiert anzeigen
+```
+Dashboard → "📊 Alle Shops"
+→ Sortieren nach: Requests/min oder Aktive Bans
+→ Klick auf Zeile öffnet Detail-Modal
+```
 
 ---
 
-## 🔌 API-Referenz
+## 📡 API-Referenz
 
 ### HTTP Endpoints
 
-| Method | Endpoint | Beschreibung |
-|--------|----------|--------------|
-| `GET` | `/` | Dashboard HTML |
-| `POST` | `/setup` | Initiales Passwort setzen |
-| `POST` | `/login` | Anmeldung |
-| `GET` | `/logout` | Abmeldung |
-| `POST` | `/api/agents/{id}/approve` | Agent freigeben |
-| `POST` | `/api/shops/activate` | Shop aktivieren |
-| `POST` | `/api/shops/deactivate` | Shop deaktivieren |
-| `POST` | `/api/shops/bulk-activate` | Massenaktivierung |
-| `POST` | `/api/shops/bulk-deactivate` | Massendeaktivierung |
-| `POST` | `/api/change-password` | Passwort ändern |
-| `GET` | `/api/shop/{domain}/history` | Shop-Historie |
+| Endpoint | Methode | Beschreibung |
+|----------|---------|--------------|
+| `/` | GET | Dashboard-Oberfläche |
+| `/login` | GET/POST | Login-Seite |
+| `/logout` | GET | Logout |
+| `/api/shops/activate` | POST | Shop aktivieren |
+| `/api/shops/deactivate` | POST | Shop deaktivieren |
+| `/api/shops/bulk-activate` | POST | Mehrere Shops aktivieren |
+| `/api/shops/bulk-deactivate` | POST | Mehrere Shops deaktivieren |
+| `/api/agents/approve` | POST | Agent freigeben |
+| `/api/change-password` | POST | Passwort ändern |
 
 ### Aktivierung Parameter
 
-```
-POST /api/shops/activate
-Content-Type: application/x-www-form-urlencoded
-
-domain=example.com
-mode=bot|geoip
-geo_region=dach|eurozone    # nur bei mode=geoip
-rate_limit=30               # nur bei mode=bot
-ban_duration=300            # nur bei mode=bot (Sekunden)
-```
-
-### Massenaktivierung Parameter
-
-```
-POST /api/shops/bulk-activate
-Content-Type: application/x-www-form-urlencoded
-
-mode=bot|geoip
-geo_region=dach|eurozone
-rate_limit=30
-ban_duration=300
-filter_type=all|direct|link11
-```
+| Parameter | Werte | Beschreibung |
+|-----------|-------|--------------|
+| `domain` | String | Shop-Domain |
+| `mode` | `bot`, `geoip` | Blocking-Modus |
+| `geo_region` | `dach`, `eurozone` | Nur bei GeoIP-Mode |
+| `rate_limit` | Integer | Requests/min (nur Bot-Mode) |
+| `ban_duration` | Integer | Sekunden (nur Bot-Mode) |
+| `bot_monitor_only` | `true`/`false` | Nur Logging (nur Bot-Mode) |
 
 ---
 
-## 📡 WebSocket Events
+## 🔌 WebSocket Events
 
 ### Endpoint: `/ws/agent` (Agent → Dashboard)
 
 | Event | Richtung | Beschreibung |
 |-------|----------|--------------|
 | `agent.connect` | Agent → Dashboard | Agent-Registrierung |
-| `agent.heartbeat` | Agent → Dashboard | System-Status (alle 30s) |
+| `agent.heartbeat` | Agent → Dashboard | System-Status (alle 60s) |
 | `shop.full_update` | Agent → Dashboard | Alle Shop-Daten |
 | `shop.stats` | Agent → Dashboard | Shop-Statistiken (alle 10s) |
 | `log.entry` | Agent → Dashboard | Log-Zeile (bei Subscription) |
@@ -493,7 +582,7 @@ filter_type=all|direct|link11
     "agent_id": "a1b2c3d4e5f6",
     "hostname": "shop020.jtl-hosting.de",
     "token": "stored-token-or-null",
-    "version": "2.3.0",
+    "version": "2.4.0",
     "os_info": {
       "system": "Linux",
       "release": "5.15.0",
@@ -507,13 +596,23 @@ filter_type=all|direct|link11
 }
 ```
 
-### Shop Stats
+### Shop Full Update
 
 ```json
 {
-  "type": "shop.stats",
+  "type": "shop.full_update",
   "data": {
     "domain": "example.com",
+    "status": "active",
+    "mode": "bot",
+    "geo_region": "none",
+    "rate_limit": 30,
+    "ban_duration": 300,
+    "bot_monitor_only": false,
+    "link11": true,
+    "link11_ip": "128.65.223.106",
+    "activated": "2024-12-19T10:30:00",
+    "runtime_minutes": 45.5,
     "stats": {
       "log_entries": 15234,
       "total_bans": 47,
@@ -545,9 +644,10 @@ filter_type=all|direct|link11
     "command_id": "cmd_abc123",
     "shop": "example.com",
     "mode": "bot",
-    "geo_region": null,
+    "geo_region": "none",
     "rate_limit": 30,
-    "ban_duration": 300
+    "ban_duration": 300,
+    "bot_monitor_only": false
   }
 }
 ```
@@ -567,7 +667,7 @@ journalctl -u jtl-wafi -f
 lsof -i :8000
 
 # 2. Python-Pakete fehlen
-pip3 install fastapi uvicorn websockets python-multipart --break-system-packages
+pip3 install fastapi uvicorn python-multipart --break-system-packages
 
 # 3. SSL-Verzeichnis fehlt
 mkdir -p /var/lib/jtl-wafi/ssl
@@ -588,13 +688,16 @@ telnet dashboard 8000
 
 # 3. SSL-Zertifikat Problem (selbstsigniert)
 # Agent akzeptiert selbstsignierte Zertifikate automatisch
+
+# 4. websockets-Modul fehlt
+pip3 install websockets --break-system-packages
 ```
 
 ### Agent wird nicht freigegeben
 
 ```bash
 # Token manuell löschen und neu verbinden
-rm /etc/jtl-wafi-agent/token
+rm /etc/jtl-wafi/token
 systemctl restart jtl-wafi-agent
 ```
 
@@ -604,32 +707,52 @@ systemctl restart jtl-wafi-agent
 # Agent Logs prüfen
 journalctl -u jtl-wafi-agent | grep -i shop
 
-# Nginx Konfiguration prüfen
-ls -la /etc/nginx/sites-enabled/
-
-# Shop-Verzeichnisse prüfen
-ls -la /var/www/
+# Shop-Verzeichnisse prüfen (muss index.php enthalten)
+ls -la /var/www/vhosts/*/httpdocs/index.php
 ```
 
-### Bans funktionieren nicht
+### Blocking funktioniert nicht
 
 ```bash
-# iptables Regeln prüfen
-iptables -L -n | grep -i drop
+# Prüfe ob jtl-wafi.php existiert
+ls -la /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi.php
 
-# Berechtigungen prüfen (Agent braucht root)
-whoami
-# Muss "root" sein
+# Prüfe ob index.php modifiziert wurde
+head -20 /var/www/vhosts/DOMAIN/httpdocs/index.php
+# Sollte enthalten: require_once __DIR__ . '/jtl-wafi.php';
+
+# Prüfe Backup
+ls -la /var/www/vhosts/DOMAIN/httpdocs/index.php.jtl-wafi_backup
+
+# PHP-Fehler prüfen
+tail -f /var/log/php*/error.log
 ```
 
-### GeoIP funktioniert nicht
+### GeoIP Cache-Probleme
 
 ```bash
-# Datenbank prüfen
-ls -la /var/lib/GeoIP/GeoLite2-Country.mmdb
+# Cache-Datei prüfen
+ls -la /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi_ip_ranges.cache
 
-# Download falls fehlend
-# https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
+# Cache löschen (wird automatisch neu erstellt)
+rm /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi_ip_ranges.cache
+
+# ipdeny.com erreichbar?
+curl -I https://www.ipdeny.com/ipblocks/data/aggregated/de-aggregated.zone
+```
+
+### Rate-Limit funktioniert nicht
+
+```bash
+# Rate-Limit Verzeichnis prüfen
+ls -la /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi_ratelimit/
+
+# Berechtigungen prüfen (muss 777 sein)
+stat /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi_ratelimit/
+
+# Ban-Dateien anzeigen
+ls -la /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi_ratelimit/bans/
+cat /var/www/vhosts/DOMAIN/httpdocs/jtl-wafi_ratelimit/bans/*.ban
 ```
 
 ### Dashboard reagiert langsam
@@ -649,7 +772,19 @@ ulimit -n 65535
 
 ## 📝 Changelog
 
-### v2.3.0 (2024-12-19)
+### v2.4.0 (2024-12)
+
+#### Neue Features
+- **🔍 Monitor-Only Modus** - Bot-Erkennung ohne Blocking für Analyse
+- **🌐 IP-basierte Bot-Erkennung** - Erkennt getarnte Bots (Alibaba) anhand IP-Ranges
+- **🤖 200+ Bot-Patterns** - Massiv erweiterte Bot-Erkennung inkl. AI-Crawler
+- **⏱️ Heartbeat auf 60s** - Reduzierte Netzwerklast
+
+#### Verbesserungen
+- Modus-Wechsel direkt im Detail-Modal
+- Verbesserte Statistik-Auswertung für Monitor-Mode
+
+### v2.3.0 (2024-12)
 
 #### Neue Features
 - **🔥 Top 10 Shops** - Neue Übersichtskarte mit meistbelasteten Shops
@@ -661,13 +796,9 @@ ulimit -n 65535
 - Dropdown bei Massenaktionen entfernt (Filter jetzt im Modal)
 - Laufzeit-Anzeige korrigiert
 - Graph zeigt jetzt Uhrzeiten auf X-Achse
-- Agent-Logging verbessert (zeigt Rate-Limit statt Region bei Bot-Mode)
+- Agent-Logging verbessert
 
-#### Fixes
-- Laufzeit wird jetzt korrekt angezeigt
-- Graph-Skalierung verbessert
-
-### v2.2.0 (2024-12-19)
+### v2.2.0 (2024-12)
 
 #### Architektur-Änderung
 - **In-Memory Storage** statt SQLite für Echtzeit-Daten
@@ -678,7 +809,7 @@ ulimit -n 65535
 - Passwort in JSON-Datei statt Datenbank
 - Agent-Tokens in JSON-Datei statt Datenbank
 
-### v2.1.0 (2024-12-19)
+### v2.1.0 (2024-12)
 
 #### Neue Features
 - **Link11 Kategorisierung** - Shops werden nach CDN/Direkt getrennt
@@ -692,13 +823,14 @@ ulimit -n 65535
 - Agent Ctrl+C Shutdown funktioniert jetzt sofort
 - Asyncio Signal Handler korrekt implementiert
 
-### v2.0.0 (2024-12-19)
+### v2.0.0 (2024-12)
 
 #### Komplett neu
 - WebSocket-basierte Architektur
 - Echtzeit-Updates ohne Polling
 - Multi-Agent Support
 - Neue moderne UI
+- PHP-basiertes Blocking (kein iptables)
 
 ---