feat: Progressive Sperren (Recidive) – Wiederholungstäter werden stufenweise länger gesperrt

- Neues Recidive-System: Sperrdauer steigt exponentiell bei wiederholten Verstößen (wie fail2ban) - Konfigurierbar: Multiplikator, Max-Stufe mit permanenter Sperre, Zähler-Reset-Zeit - Offense-Tracking via *.offenses State-Dateien - Permanente Sperren werden nicht automatisch aufgehoben - Neuer Befehl: reset-offenses [IP] zum Zurücksetzen der Offense-Zähler - Status-Anzeige zeigt Stufe, Dauer und Wiederholungstäter-Übersicht - Benachrichtigungen enthalten Stufe und progressive Sperrdauer - unban-expired.sh berücksichtigt permanente Sperren - Dokumentation vollständig aktualisiert (Konfig, Befehle, Architektur, Troubleshooting, README)
2026-03-03 22:16:29 +01:00
parent 9d1879ba55
commit 4f679cadd4
10 changed files with 479 additions and 53 deletions
--- a/doc/architektur.md
+++ b/doc/architektur.md
@@ -34,11 +34,13 @@
 3. Die Anfragen werden pro Client+Domain-Kombination gezählt
 4. Monitor erkennt: 45 > 30 (Limit überschritten)
 5. Prüfung: Ist der Client auf der Whitelist? → Nein
-6. iptables-Regel wird erstellt: `DROP` für `192.168.1.50` auf allen DNS-Ports
-7. State-Datei wird angelegt: `/var/lib/adguard-shield/192.168.1.50.ban`
-8. Ban-History Eintrag wird in `/var/log/adguard-shield-bans.log` geschrieben
-9. Log-Eintrag + optionale Webhook-Benachrichtigung
-10. Nach 3600 Sekunden (1 Stunde): automatische Entsperrung + History-Eintrag
+6. **Progressive Sperren:** Offense-Level wird geprüft/erhöht, Sperrdauer berechnet
+7. iptables-Regel wird erstellt: `DROP` für `192.168.1.50` auf allen DNS-Ports
+8. State-Datei wird angelegt: `/var/lib/adguard-shield/192.168.1.50.ban`
+9. Offense-Datei wird aktualisiert: `/var/lib/adguard-shield/192.168.1.50.offenses`
+10. Ban-History Eintrag wird in `/var/log/adguard-shield-bans.log` geschrieben
+11. Log-Eintrag + optionale Webhook-Benachrichtigung
+12. Nach Ablauf der (progressiven) Sperrdauer: automatische Entsperrung + History-Eintrag

 ## iptables Strategie

@@ -82,12 +84,31 @@ COUNT=45
 BAN_TIME=2026-03-03 14:30:00
 BAN_UNTIL_EPOCH=1741012200
 BAN_UNTIL=2026-03-03 15:30:00
+BAN_DURATION=3600
+OFFENSE_LEVEL=1
+IS_PERMANENT=false
+```
+
+Zusätzlich wird für jede IP ein Offense-Tracker gespeichert:
+
+```
+/var/lib/adguard-shield/192.168.1.50.offenses
+```
+
+Inhalt:
+```
+CLIENT_IP=192.168.1.50
+OFFENSE_LEVEL=2
+LAST_OFFENSE_EPOCH=1741008600
+LAST_OFFENSE=2026-03-03 14:30:00
+FIRST_OFFENSE=2026-03-03 12:15:00
 ```

 Das ermöglicht:
 - Persistenz über Script-Neustarts hinweg
 - Statusabfragen jederzeit möglich
 - Automatisches Aufräumen per Cron-Job
+- Progressive Sperrzeiten über mehrere Ban-Zyklen hinweg

 ## Dateistruktur nach Installation

@@ -105,6 +126,7 @@ Das ermöglicht:

 /var/lib/adguard-shield/
 ├── *.ban                          # State-Dateien aktiver Sperren
+├── *.offenses                     # Offense-Zähler (Progressive Sperren)
 └── external-blocklist/            # Cache für externe Blocklisten

 /var/log/
--- a/doc/befehle.md
+++ b/doc/befehle.md
@@ -73,6 +73,12 @@ sudo /opt/adguard-shield/adguard-shield.sh test
 # Dry-Run (nur loggen, nichts sperren)
 sudo /opt/adguard-shield/adguard-shield.sh dry-run

+# Offense-Zähler für alle IPs zurücksetzen (Progressive Sperren)
+sudo /opt/adguard-shield/adguard-shield.sh reset-offenses
+
+# Offense-Zähler für eine bestimmte IP zurücksetzen
+sudo /opt/adguard-shield/adguard-shield.sh reset-offenses 192.168.1.100
+
 # Externe Blocklist - Status anzeigen
 sudo /opt/adguard-shield/adguard-shield.sh blocklist-status

--- a/doc/konfiguration.md
+++ b/doc/konfiguration.md
@@ -41,11 +41,34 @@ Dadurch muss der Benutzer bei Updates die Konfiguration nicht manuell austausche

 | Parameter | Standard | Beschreibung |
 |-----------|----------|--------------|
-| `BAN_DURATION` | `3600` | Sperrdauer in Sekunden (3600 = 1 Stunde) |
+| `BAN_DURATION` | `3600` | Basis-Sperrdauer in Sekunden (3600 = 1 Stunde) |
 | `IPTABLES_CHAIN` | `ADGUARD_SHIELD` | Name der iptables Chain |
-| `BLOCKED_PORTS` | `53 443 853 784 8853` | Ports die gesperrt werden |
+| `BLOCKED_PORTS` | `53 443 853` | Ports die gesperrt werden (IPv4 + IPv6) |
 | `WHITELIST` | `127.0.0.1,::1` | IPs die nie gesperrt werden (kommagetrennt) |

+### Progressive Sperren (Recidive)
+
+Wiederholungstäter werden wie bei fail2ban stufenweise länger gesperrt. Wird eine IP nach dem Ablauf ihrer Sperre erneut auffällig, steigt die Sperrdauer exponentiell.
+
+| Parameter | Standard | Beschreibung |
+|-----------|----------|--------------|
+| `PROGRESSIVE_BAN_ENABLED` | `true` | Progressive Sperren aktivieren |
+| `PROGRESSIVE_BAN_MULTIPLIER` | `2` | Multiplikator pro Stufe (2 = Verdopplung) |
+| `PROGRESSIVE_BAN_MAX_LEVEL` | `5` | Ab dieser Stufe wird permanent gesperrt (0 = nie) |
+| `PROGRESSIVE_BAN_RESET_AFTER` | `86400` | Zähler-Reset nach X Sekunden ohne Vergehen (86400 = 24h) |
+
+#### Beispiel bei Standardwerten
+
+| Vergehen | Stufe | Sperrdauer | Berechnung |
+|----------|-------|------------|------------|
+| 1. Mal   | 1     | 1 Stunde   | 3600 × 1   |
+| 2. Mal   | 2     | 2 Stunden  | 3600 × 2   |
+| 3. Mal   | 3     | 4 Stunden  | 3600 × 4   |
+| 4. Mal   | 4     | 8 Stunden  | 3600 × 8   |
+| 5. Mal   | 5     | **PERMANENT** | Max-Stufe erreicht |
+
+> **Hinweis:** Der Offense-Zähler wird automatisch zurückgesetzt, wenn eine IP für den konfigurierten Zeitraum (`PROGRESSIVE_BAN_RESET_AFTER`) kein erneutes Vergehen begeht. Permanente Sperren werden **nicht** automatisch aufgehoben – sie müssen manuell mit `unban` oder `flush` entfernt werden.
+
 ### Logging

 | Parameter | Standard | Beschreibung |
@@ -59,9 +82,13 @@ Dadurch muss der Benutzer bei Updates die Konfiguration nicht manuell austausche

 | Parameter | Standard | Beschreibung |
 |-----------|----------|--------------|
-| `NOTIFY_ENABLED` | `false` | Webhook-Benachrichtigungen aktivieren |
-| `NOTIFY_WEBHOOK_URL` | *(leer)* | Webhook-URL |
-| `NOTIFY_TYPE` | `generic` | Typ: `discord`, `slack`, `gotify`, `generic` |
+| `NOTIFY_ENABLED` | `false` | Benachrichtigungen aktivieren |
+| `NOTIFY_TYPE` | `ntfy` | Typ: `ntfy`, `discord`, `slack`, `gotify`, `generic` |
+| `NOTIFY_WEBHOOK_URL` | *(leer)* | Webhook-URL (nur für discord, slack, gotify, generic) |
+| `NTFY_SERVER_URL` | `https://ntfy.sh` | Ntfy Server-URL |
+| `NTFY_TOPIC` | *(leer)* | Ntfy Topic-Name |
+| `NTFY_TOKEN` | *(leer)* | Optionaler Ntfy Access-Token |
+| `NTFY_PRIORITY` | `4` | Ntfy Priorität (1–5) |

 ### Erweitert

@@ -75,7 +102,7 @@ Dadurch muss der Benutzer bei Updates die Konfiguration nicht manuell austausche
 Ermöglicht das Einbinden externer IP-Blocklisten (z.B. gehostete Textdateien mit einer IP pro Zeile). Der Worker läuft als Hintergrundprozess und prüft periodisch auf Änderungen.

 | Parameter | Standard | Beschreibung |
-|-----------|----------|}--------------|
+|-----------|----------|--------------|
 | `EXTERNAL_BLOCKLIST_ENABLED` | `false` | Aktiviert den externen Blocklist-Worker |
 | `EXTERNAL_BLOCKLIST_URLS` | *(leer)* | URL(s) zu Textdateien mit IPs (kommagetrennt) |
 | `EXTERNAL_BLOCKLIST_INTERVAL` | `300` | Prüfintervall in Sekunden (300 = 5 Min.) |
@@ -115,16 +142,14 @@ sudo systemctl restart adguard-shield
 ```
 ## Gesperrte Ports im Detail

-Bei einem Rate-Limit-Verstoß werden **alle** DNS-Protokoll-Ports für den Client gesperrt:
+Bei einem Rate-Limit-Verstoß werden **alle** DNS-Protokoll-Ports für den Client gesperrt (IPv4 via `iptables` und IPv6 via `ip6tables`):

 | Port | Protokoll | Beschreibung |
 |------|-----------|-------------|
 | 53   | UDP/TCP   | Standard DNS |
 | 443  | TCP       | DNS-over-HTTPS (DoH) |
-| 853  | TCP       | DNS-over-TLS (DoT) |
-| 853  | UDP       | DNS-over-QUIC (DoQ) |
-| 784  | UDP       | DNS-over-QUIC (alternativ) |
-| 8853 | UDP       | DNS-over-QUIC (alternativ) |
+| 853  | TCP       | DNS-over-TLS (`tls://dns1.techniverse.net:853`) |
+| 853  | UDP       | DNS-over-QUIC (`quic://dns1.techniverse.net:853`) |

 ## Whitelist richtig pflegen

--- a/doc/tipps-und-troubleshooting.md
+++ b/doc/tipps-und-troubleshooting.md
@@ -49,12 +49,30 @@ sudo /opt/adguard-shield/adguard-shield.sh start
   ```bash
   sudo /opt/adguard-shield/adguard-shield.sh history | grep 192.168.1.100
   ```
-3. IP zur Whitelist hinzufügen in `adguard-shield.conf`
-3. Service neustarten:
+3. Offense-Zähler für die IP zurücksetzen (damit die progressive Sperre wieder bei Stufe 1 beginnt):
+   ```bash
+   sudo /opt/adguard-shield/adguard-shield.sh reset-offenses 192.168.1.100
+   ```
+4. IP zur Whitelist hinzufügen in `adguard-shield.conf`
+5. Service neustarten:
   ```bash
   sudo systemctl restart adguard-shield
   ```

+### Client wurde permanent gesperrt (Progressive Sperren)
+
+Wenn eine IP die maximale Stufe der progressiven Sperren erreicht hat, wird sie permanent gesperrt und nicht automatisch aufgehoben.
+
+1. IP entsperren:
+   ```bash
+   sudo /opt/adguard-shield/adguard-shield.sh unban 192.168.1.100
+   ```
+2. Offense-Zähler zurücksetzen:
+   ```bash
+   sudo /opt/adguard-shield/adguard-shield.sh reset-offenses 192.168.1.100
+   ```
+3. Prüfen ob die IP auf die Whitelist gehört, oder die Progressive-Ban-Einstellungen anpassen (`PROGRESSIVE_BAN_MAX_LEVEL` erhöhen oder auf `0` setzen für keine permanenten Sperren)
+
 ### Sperren überleben Reboot nicht

 Das ist normal — iptables-Regeln sind flüchtig. Der **Service** erstellt die Chain beim Start automatisch neu. Aktive Sperren aus dem State-Verzeichnis werden aber nicht automatisch wiederhergestellt.
--- a/doc/update.md
+++ b/doc/update.md
@@ -0,0 +1,76 @@
+# Update-Anleitung
+
+## Voraussetzungen
+
+- AdGuard Shield ist bereits installiert (`/opt/adguard-shield/`)
+- Git ist installiert (`sudo apt install git`)
+- Zugriff auf den Server per SSH mit Root-Rechten
+
+## Update durchführen
+
+### 1. Git-Repository aktualisieren
+
+Wechsle in das Verzeichnis, in dem du das Repository geklont hast, und hole die neueste Version:
+
+```bash
+cd /pfad/zum/adguard-shield
+git pull
+```
+
+> **Hinweis:** Falls du das Repository z.B. nach `/opt/adguard-shield-repo` geklont hast:
+> ```bash
+> cd /opt/adguard-shield-repo
+> git pull
+> ```
+
+### 2. Update-Script ausführen
+
+```bash
+sudo bash install.sh update
+```
+
+Das Update-Script macht automatisch folgendes:
+
+1. **Abhängigkeiten prüfen** — Fehlende Pakete werden nachinstalliert
+2. **Scripts aktualisieren** — Alle `.sh`-Dateien werden nach `/opt/adguard-shield/` kopiert
+3. **Konfigurations-Migration** — Neue Parameter werden automatisch zur bestehenden Konfiguration hinzugefügt, bestehende Einstellungen bleiben **unverändert**
+4. **Backup erstellen** — Die alte Konfiguration wird als `adguard-shield.conf.old` gesichert
+5. **Service aktualisieren** — Die systemd Service-Datei wird aktualisiert und `daemon-reload` ausgeführt
+6. **Service neustarten** — Der Service wird automatisch neu gestartet (falls er vorher lief)
+
+### 3. Neue Parameter prüfen (optional)
+
+Nach dem Update empfiehlt es sich, eventuell neu hinzugefügte Konfigurationsparameter zu prüfen:
+
+```bash
+sudo nano /opt/adguard-shield/adguard-shield.conf
+```
+
+Falls etwas nicht stimmt, kann das Backup wiederhergestellt werden:
+
+```bash
+sudo cp /opt/adguard-shield/adguard-shield.conf.old /opt/adguard-shield/adguard-shield.conf
+sudo systemctl restart adguard-shield
+```
+
+## Kurzfassung (Copy & Paste)
+
+```bash
+cd /pfad/zum/adguard-shield
+git pull
+sudo bash install.sh update
+```
+
+## Versionsprüfung
+
+Installierte Version anzeigen:
+
+```bash
+sudo /opt/adguard-shield/adguard-shield.sh status
+```
+
+Oder über den Installer:
+
+```bash
+sudo bash install.sh status
+```