🛡️ JTL-WAFi v2.3

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.

---

📋 Inhaltsverzeichnis

• Überblick
• Features
• Architektur
• Voraussetzungen
• Installation
  • Dashboard Server
  • Agent Server
• Konfiguration
• Verwendung
  • Einzelne Shops
  • Massenaktionen
  • Monitoring
• API-Referenz
• WebSocket Events
• Datenstrukturen
• Troubleshooting
• Changelog

---

🎯 Überblick

JTL-WAFi besteht aus zwei Komponenten:

Komponente	Beschreibung	Deployment
Dashboard	Zentrale Web-Oberfläche zur Verwaltung aller Shops	1x auf Management-Server
Agent	Lokaler Dienst der das Blocking durchführt	1x pro Shop-Server

Schutzmodi

Modus	Beschreibung	Anwendungsfall
🤖 Bot Rate-Limiting	Erkennt und limitiert aggressive Bots basierend auf User-Agent-Analyse	Schutz vor Scraping, SEO-Bots, Crawlern
🌍 GeoIP-Blocking	Blockiert Traffic aus nicht-relevanten Regionen	Shops die nur DACH/EU beliefern

---

✨ Features

Dashboard (v2.3)

Übersicht & Monitoring

• 📊 Echtzeit-Statistiken - Server online, aktive Shops, Requests/min, aktive Bans
• 🔥 Top 10 Shops - Übersicht der Shops mit höchster Last
• 📈 Bot-Aktivitäts-Graph - Zeitbasierte Darstellung pro Bot-Typ mit Zeitachse
• 📜 Live Logs - Echtzeit Log-Streaming pro Shop
• 🛡️ Link11 Kategorisierung - Unterscheidung zwischen CDN- und Direkt-Shops

Verwaltung

• ⚡ Massenaktionen - Alle Shops gleichzeitig aktivieren/deaktivieren
• 🔍 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

Technisch

• WebSocket Real-Time - Keine Polling, sofortige Updates
• In-Memory Storage - Keine Datenbank-Locks, maximale Performance
• SSL/TLS - Automatische selbstsignierte Zertifikatsgenerierung
• Responsive Design - Funktioniert auf Desktop, Tablet und Mobile

Agent (v2.3)

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

Zuverlässigkeit

• ♻️ Auto-Reconnect - Automatische Wiederverbindung zum Dashboard
• 🔑 Token-Auth - Sichere Authentifizierung nach Freigabe
• ⏹️ Graceful Shutdown - Sauberes Beenden mit Ctrl+C (SIGINT/SIGTERM)
• 💾 Token-Persistenz - Token wird lokal gespeichert

---

🏗 Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        DASHBOARD SERVER                          │
│                      (shop000.example.com)                       │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                  jtl_wafi_dashboard.py                   │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │    │
│  │  │  FastAPI    │  │  WebSocket  │  │  In-Memory      │  │    │
│  │  │  HTTP API   │  │  Server     │  │  DataStore      │  │    │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘  │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│                    WSS (Port 8000)                               │
└──────────────────────────────┼───────────────────────────────────┘
                               │
          ┌────────────────────┼────────────────────┐
          │                    │                    │
          ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  AGENT SERVER 1 │  │  AGENT SERVER 2 │  │  AGENT SERVER N │
│  (shop020.xxx)  │  │  (shop043.xxx)  │  │  (shopXXX.xxx)  │
│  ┌───────────┐  │  │  ┌───────────┐  │  │  ┌───────────┐  │
│  │  Agent    │  │  │  │  Agent    │  │  │  │  Agent    │  │
│  ├───────────┤  │  │  ├───────────┤  │  │  ├───────────┤  │
│  │ Shop A    │  │  │  │ Shop D    │  │  │  │ Shop X    │  │
│  │ Shop B    │  │  │  │ Shop E    │  │  │  │ Shop Y    │  │
│  │ Shop C    │  │  │  │ Shop F    │  │  │  │ Shop Z    │  │
│  └───────────┘  │  │  └───────────┘  │  │  └───────────┘  │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Datenfluss

┌─────────┐                              ┌───────────┐
│  Agent  │ ──── agent.connect ────────► │ Dashboard │
│         │ ◄─── auth.approved ───────── │           │
│         │                              │           │
│         │ ──── agent.heartbeat ──────► │           │  (alle 30s)
│         │ ──── shop.full_update ─────► │           │
│         │ ──── shop.stats ───────────► │           │  (alle 10s)
│         │                              │           │
│         │ ◄─── command.activate ────── │           │
│         │ ◄─── command.deactivate ──── │           │
│         │                              │           │
│         │ ──── log.entry ────────────► │           │  (live)
│         │ ──── bot.banned ───────────► │           │  (events)
│         │ ──── command.result ───────► │           │
└─────────┘                              └───────────┘

---

📦 Voraussetzungen

Dashboard Server

# Python 3.8+
python3 --version

# Benötigte Pakete
pip3 install fastapi uvicorn websockets python-multipart --break-system-packages

# OpenSSL für Zertifikate
apt install openssl

Agent Server

# Python 3.8+
python3 --version

# Benötigte Pakete
pip3 install websockets geoip2 watchdog --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

# iptables für IP-Blocking
apt install iptables

# Nginx (für Log-Analyse)
# Muss bereits installiert sein

---

🚀 Installation

1. Dashboard Server (Zentral)

# Verzeichnis erstellen
mkdir -p /opt/jtl-wafi
cd /opt/jtl-wafi

# Dashboard kopieren
cp jtl_wafi_dashboard.py /opt/jtl-wafi/

# Datenverzeichnis erstellen
mkdir -p /var/lib/jtl-wafi/ssl

# Systemd Service installieren
python3 /opt/jtl-wafi/jtl_wafi_dashboard.py --install-service

# Service aktivieren und starten
systemctl daemon-reload
systemctl enable jtl-wafi
systemctl start jtl-wafi

# Status prüfen
systemctl status jtl-wafi

Firewall konfigurieren

# Port 8000 öffnen (oder anderen konfigurierten Port)
ufw allow 8000/tcp
# ODER
iptables -A INPUT -p tcp --dport 8000 -j ACCEPT

Erster Login

1. Browser öffnen: https://dashboard-server:8000
2. SSL-Warnung akzeptieren (selbstsigniertes Zertifikat)
3. Admin-Passwort setzen (mind. 8 Zeichen)
4. Dashboard ist einsatzbereit

---

2. Agent Server (Pro Shop-Server)

# Verzeichnis erstellen
mkdir -p /opt/jtl-wafi-agent
mkdir -p /etc/jtl-wafi-agent
cd /opt/jtl-wafi-agent

# Agent kopieren
cp jtl_wafi_agent.py /opt/jtl-wafi-agent/

# Systemd Service installieren
python3 /opt/jtl-wafi-agent/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

# Service aktivieren und starten
systemctl daemon-reload
systemctl enable jtl-wafi-agent
systemctl start jtl-wafi-agent

# Status prüfen
systemctl status jtl-wafi-agent

Agent freigeben

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

---

⚙️ Konfiguration

Dashboard Umgebungsvariablen

Variable	Beschreibung	Standard
DASHBOARD_SECRET	Session Secret Key	Auto-generiert

Dashboard Kommandozeilen-Optionen

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

Agent Kommandozeilen-Optionen

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

Dateipfade

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

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

---

📖 Verwendung

Einzelne Shops verwalten

Shop aktivieren (Bot Rate-Limiting)

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

Shop aktivieren (GeoIP-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

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

Alle Shops deaktivieren

1. "⏹️ Deaktivieren..." Button klicken
2. Filter wählen
3. "Deaktivieren" klicken

Monitoring

Top 10 Shops

• Zeigt die 10 Shops mit den meisten Requests/min
• Klick auf einen Shop öffnet Detail-Modal
• Klick auf Überschrift öffnet sortierbare Gesamtliste

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

---

🔌 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

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

---

📡 WebSocket Events

Endpoint: /ws/agent (Agent → Dashboard)

Event	Richtung	Beschreibung
agent.connect	Agent → Dashboard	Agent-Registrierung
agent.heartbeat	Agent → Dashboard	System-Status (alle 30s)
shop.full_update	Agent → Dashboard	Alle Shop-Daten
shop.stats	Agent → Dashboard	Shop-Statistiken (alle 10s)
log.entry	Agent → Dashboard	Log-Zeile (bei Subscription)
bot.banned	Agent → Dashboard	Ban-Event
command.result	Agent → Dashboard	Kommando-Ergebnis
auth.approved	Dashboard → Agent	Token nach Freigabe
command.activate	Dashboard → Agent	Shop aktivieren
command.deactivate	Dashboard → Agent	Shop deaktivieren
log.subscribe	Dashboard → Agent	Log-Streaming starten
log.unsubscribe	Dashboard → Agent	Log-Streaming stoppen

Endpoint: /ws/dashboard (Browser → Dashboard)

Event	Richtung	Beschreibung
initial_state	Dashboard → Browser	Initialer Zustand
refresh	Dashboard → Browser	Aktualisierte Daten
agent.online	Dashboard → Browser	Agent online
agent.offline	Dashboard → Browser	Agent offline
agent.pending	Dashboard → Browser	Agent wartet auf Freigabe
agent.approved	Dashboard → Browser	Agent freigegeben
shop.full_update	Dashboard → Browser	Shop-Update
shop.stats	Dashboard → Browser	Stats-Update
shop_history	Dashboard → Browser	Historie für Graph
top_shops	Dashboard → Browser	Top 10 Shops
all_shops_sorted	Dashboard → Browser	Alle Shops sortiert
log.entry	Dashboard → Browser	Log-Zeile
bot.banned	Dashboard → Browser	Ban-Notification
command.result	Dashboard → Browser	Kommando-Ergebnis
get_shop_history	Browser → Dashboard	Historie anfordern
get_all_shops_sorted	Browser → Dashboard	Sortierte Liste anfordern
log.subscribe	Browser → Dashboard	Logs abonnieren
log.unsubscribe	Browser → Dashboard	Logs abbestellen

---

📊 Datenstrukturen

Agent Connect

{
  "type": "agent.connect",
  "data": {
    "agent_id": "a1b2c3d4e5f6",
    "hostname": "shop020.jtl-hosting.de",
    "token": "stored-token-or-null",
    "version": "2.3.0",
    "os_info": {
      "system": "Linux",
      "release": "5.15.0",
      "hostname": "shop020"
    },
    "shops_summary": {
      "total": 25,
      "active": 12
    }
  }
}

Shop Stats

{
  "type": "shop.stats",
  "data": {
    "domain": "example.com",
    "stats": {
      "log_entries": 15234,
      "total_bans": 47,
      "active_bans": 3,
      "banned_bots": ["AhrefsBot", "SemrushBot"],
      "req_per_min": 45.7,
      "unique_ips": 234,
      "unique_bots": 12,
      "top_bots": {
        "Googlebot": 523,
        "bingbot": 234,
        "AhrefsBot": 189
      },
      "top_ips": {
        "66.249.66.1": 145,
        "157.55.39.1": 98
      }
    }
  }
}

Command Activate

{
  "type": "command.activate",
  "data": {
    "command_id": "cmd_abc123",
    "shop": "example.com",
    "mode": "bot",
    "geo_region": null,
    "rate_limit": 30,
    "ban_duration": 300
  }
}

---

🔧 Troubleshooting

Dashboard startet nicht

# Logs prüfen
journalctl -u jtl-wafi -f

# Häufige Ursachen:
# 1. Port bereits belegt
lsof -i :8000

# 2. Python-Pakete fehlen
pip3 install fastapi uvicorn websockets python-multipart --break-system-packages

# 3. SSL-Verzeichnis fehlt
mkdir -p /var/lib/jtl-wafi/ssl

Agent verbindet nicht

# Logs prüfen
journalctl -u jtl-wafi-agent -f

# Häufige Ursachen:
# 1. Dashboard nicht erreichbar
curl -k https://dashboard:8000/

# 2. Firewall blockiert
telnet dashboard 8000

# 3. SSL-Zertifikat Problem (selbstsigniert)
# Agent akzeptiert selbstsignierte Zertifikate automatisch

Agent wird nicht freigegeben

# Token manuell löschen und neu verbinden
rm /etc/jtl-wafi-agent/token
systemctl restart jtl-wafi-agent

Shops werden nicht erkannt

# 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/

Bans funktionieren nicht

# iptables Regeln prüfen
iptables -L -n | grep -i drop

# Berechtigungen prüfen (Agent braucht root)
whoami
# Muss "root" sein

GeoIP funktioniert nicht

# Datenbank prüfen
ls -la /var/lib/GeoIP/GeoLite2-Country.mmdb

# Download falls fehlend
# https://dev.maxmind.com/geoip/geolite2-free-geolocation-data

Dashboard reagiert langsam

# WebSocket Verbindungen prüfen
ss -tuln | grep 8000

# Memory-Nutzung prüfen
ps aux | grep jtl_wafi

# Bei vielen Agents: Connection-Limits erhöhen
ulimit -n 65535

---

📝 Changelog

v2.3.0 (2024-12-19)

Neue Features

• 🔥 Top 10 Shops - Neue Übersichtskarte mit meistbelasteten Shops
• 📊 Sortierbare Shop-Liste - Modal mit allen Shops, sortierbar nach Requests oder Bans
• 📈 Bot-Aktivitäts-Graph - Mehrere Linien pro Bot-Typ mit Zeitachse
• 🔄 Rebranding - Umbenannt zu "JTL-WAFi"

Verbesserungen

• 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)

Fixes

• Laufzeit wird jetzt korrekt angezeigt
• Graph-Skalierung verbessert

v2.2.0 (2024-12-19)

Architektur-Änderung

• In-Memory Storage statt SQLite für Echtzeit-Daten
• Keine "database is locked" Fehler mehr
• Massiv verbesserte Performance bei vielen Agents

Neue Features

• Passwort in JSON-Datei statt Datenbank
• Agent-Tokens in JSON-Datei statt Datenbank

v2.1.0 (2024-12-19)

Neue Features

• Link11 Kategorisierung - Shops werden nach CDN/Direkt getrennt
• Bulk Actions - Massenaktivierung/-deaktivierung
• Shop Detail Modal - Ausführliche Statistiken und Graph
• Password Change - Passwort im Dashboard ändern
• Live Clock - Echtzeit-Uhr im Header
• Shop Link Button - Direktlink zum Shop

Fixes

• Agent Ctrl+C Shutdown funktioniert jetzt sofort
• Asyncio Signal Handler korrekt implementiert

v2.0.0 (2024-12-19)

Komplett neu

• WebSocket-basierte Architektur
• Echtzeit-Updates ohne Polling
• Multi-Agent Support
• Neue moderne UI

---

📄 Lizenz

MIT License - siehe LICENSE

---

🤝 Contributing

1. Fork erstellen
2. Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit (git commit -m 'Add AmazingFeature')
4. Push (git push origin feature/AmazingFeature)
5. Pull Request erstellen

---

📞 Support

Bei Fragen oder Problemen:

• GitHub Issues öffnen
• Logs beifügen (journalctl -u jtl-wafi -n 100)

---

Made with ❤️ for JTL-Shop Hosting