thomasciesla/JTL-WAFI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README.md aktualisiert

Browse Source
This commit is contained in:
thomasciesla
2025-12-19 22:09:53 +01:00
parent 8bab66c2fa
commit 390614a759
1 changed files with 728 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

730
README.md
View File

@@ -1,3 +1,729 @@
# JTL-WAFI
# 🛡️ JTL-WAFi v2.3
Die JTL-WAFI. Aktuell hat sie Geoblocking und Bot-Ratelimit funktionalität.
**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)
![Python](https://img.shields.io/badge/python-3.8+-green)
![License](https://img.shields.io/badge/license-MIT-orange)
---
## 📋 Inhaltsverzeichnis
- [Überblick](#-überblick)
- [Features](#-features)
- [Architektur](#-architektur)
- [Voraussetzungen](#-voraussetzungen)
- [Installation](#-installation)
- [Dashboard Server](#1-dashboard-server-zentral)
- [Agent Server](#2-agent-server-pro-shop-server)
- [Konfiguration](#-konfiguration)
- [Verwendung](#-verwendung)
- [Einzelne Shops](#einzelne-shops-verwalten)
- [Massenaktionen](#massenaktionen)
- [Monitoring](#monitoring)
- [API-Referenz](#-api-referenz)
- [WebSocket Events](#-websocket-events)
- [Datenstrukturen](#-datenstrukturen)
- [Troubleshooting](#-troubleshooting)
- [Changelog](#-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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
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
```bash
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
```json
{
"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
```json
{
"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
```json
{
"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
```bash
# 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
```bash
# 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
```bash
# Token manuell löschen und neu verbinden
rm /etc/jtl-wafi-agent/token
systemctl restart jtl-wafi-agent
```
### Shops werden nicht erkannt
```bash
# 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
```bash
# iptables Regeln prüfen
iptables -L -n | grep -i drop
# Berechtigungen prüfen (Agent braucht root)
whoami
# Muss "root" sein
```
### GeoIP funktioniert nicht
```bash
# 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
```bash
# 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](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**