scriptos/adguard-shield
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity

v0.3.0 - Initial Release

Browse Source
This commit is contained in:
Patrick Asmus
2026-03-03 21:15:54 +01:00
parent a5fb3bcf25
commit 64079f6fef
15 changed files with 896 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
doc/architektur.md
View File

@@ -15,7 +15,7 @@
└─────────────────────┘ │
▼
┌──────────────────────┐
│ adguard-ratelimit.sh │
│ adguard-shield.sh │
│ (Monitor Script) │
└──────────┬───────────┘
│
@@ -35,27 +35,27 @@
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-ratelimit/192.168.1.50.ban`
8. Ban-History Eintrag wird in `/var/log/adguard-ratelimit-bans.log` geschrieben
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
## iptables Strategie
Das Tool erstellt eine eigene Chain `ADGUARD_RATELIMIT`:
Das Tool erstellt eine eigene Chain `ADGUARD_SHIELD`:
```
INPUT Chain
├── ... (bestehende Regeln bleiben unberührt)
├── -p tcp --dport 53 → ADGUARD_RATELIMIT
├── -p udp --dport 53 → ADGUARD_RATELIMIT
├── -p tcp --dport 443 → ADGUARD_RATELIMIT
├── -p udp --dport 443 → ADGUARD_RATELIMIT
├── -p tcp --dport 853 → ADGUARD_RATELIMIT
├── -p udp --dport 853 → ADGUARD_RATELIMIT
├── -p tcp --dport 53 → ADGUARD_SHIELD
├── -p udp --dport 53 → ADGUARD_SHIELD
├── -p tcp --dport 443 → ADGUARD_SHIELD
├── -p udp --dport 443 → ADGUARD_SHIELD
├── -p tcp --dport 853 → ADGUARD_SHIELD
├── -p udp --dport 853 → ADGUARD_SHIELD
└── ...
ADGUARD_RATELIMIT Chain
ADGUARD_SHIELD Chain
├── -s 192.168.1.50 → DROP (gesperrter Client)
├── -s 10.0.0.25 → DROP (gesperrter Client)
└── RETURN (alle anderen passieren)
@@ -64,14 +64,14 @@ ADGUARD_RATELIMIT Chain
**Vorteile der eigenen Chain:**
- Greift nicht in bestehende Firewall-Regeln ein
- Kann komplett geflusht werden ohne andere Regeln zu beeinflussen
- Einfaches Debugging per `iptables -L ADGUARD_RATELIMIT`
- Einfaches Debugging per `iptables -L ADGUARD_SHIELD`
## State-Management
Jede aktive Sperre wird als Datei gespeichert:
```
/var/lib/adguard-ratelimit/192.168.1.50.ban
/var/lib/adguard-shield/192.168.1.50.ban
```
Inhalt:
@@ -92,26 +92,64 @@ Das ermöglicht:
## Dateistruktur nach Installation
```
/opt/adguard-ratelimit/
├── adguard-ratelimit.sh # Haupt-Monitor-Script
├── adguard-ratelimit.conf # Konfiguration (chmod 600)
├── iptables-helper.sh # iptables Verwaltung
└── unban-expired.sh # Cron-basiertes Entsperren
/opt/adguard-shield/
├── adguard-shield.sh # Haupt-Monitor-Script
├── adguard-shield.conf # Konfiguration (chmod 600)
├── adguard-shield.conf.old # Backup der Konfig nach Update
├── iptables-helper.sh # iptables Verwaltung
├── external-blocklist-worker.sh # Externer Blocklist-Worker
└── unban-expired.sh # Cron-basiertes Entsperren
/etc/systemd/system/
└── adguard-ratelimit.service
└── adguard-shield.service # systemd Service (Autostart aktiv)
/var/lib/adguard-ratelimit/
└── *.ban # State-Dateien aktiver Sperren
/var/lib/adguard-shield/
├── *.ban # State-Dateien aktiver Sperren
└── external-blocklist/ # Cache für externe Blocklisten
/var/log/
├── adguard-ratelimit.log # Laufzeit-Log
└── adguard-ratelimit-bans.log # Ban-History (alle Sperren/Entsperrungen)
├── adguard-shield.log # Laufzeit-Log
└── adguard-shield-bans.log # Ban-History (alle Sperren/Entsperrungen)
```
## Installer-Architektur
Der Installer (`install.sh`) bietet ein interaktives Menü und folgende Funktionen:
| Befehl | Beschreibung |
|--------|--------------|
| `install` | Vollständige Neuinstallation (Abhängigkeiten, Dateien, Konfiguration, Service) |
| `update` | Update mit automatischer Konfigurations-Migration und Service-Neustart |
| `uninstall` | Deinstallation mit optionalem Behalten der Konfiguration |
| `status` | Installationsstatus, Version und Service-Status anzeigen |
| `--help` | Hilfe und Befehlsübersicht |
### Konfigurations-Migration beim Update
```
┌─────────────────────────┐ ┌─────────────────────────┐
│ Bestehende Konfig │ │ Neue Konfig (Repo) │
│ (Benutzer-Settings) │ │ (mit neuen Parametern) │
└───────────┬─────────────┘ └───────────┬─────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────┐
│ Konfigurations-Migration │
│ 1. Backup als .conf.old erstellen │
│ 2. Alle Schlüssel vergleichen │
│ 3. Neue Schlüssel zur Konfig ergänzen │
│ 4. Bestehende Werte NICHT ändern │
└──────────────────────┬───────────────────┘
▼
┌──────────────────────────┐
│ Aktualisierte Konfig │
│ (alte Werte + neue Keys) │
└──────────────────────────┘
```
## Ban-History
Jede Sperre und Entsperrung wird dauerhaft in der Ban-History protokolliert (`/var/log/adguard-ratelimit-bans.log`). Das ermöglicht eine lückenlose Nachvollziehbarkeit, auch nachdem State-Dateien bereits gelöscht wurden.
Jede Sperre und Entsperrung wird dauerhaft in der Ban-History protokolliert (`/var/log/adguard-shield-bans.log`). Das ermöglicht eine lückenlose Nachvollziehbarkeit, auch nachdem State-Dateien bereits gelöscht wurden.
**Format:**
```
@@ -133,6 +171,6 @@ ZEITSTEMPEL | AKTION | CLIENT-IP | DOMAIN
**History anzeigen:**
```bash
sudo /opt/adguard-ratelimit/adguard-ratelimit.sh history # letzte 50
sudo /opt/adguard-ratelimit/adguard-ratelimit.sh history 200 # letzte 200
sudo /opt/adguard-shield/adguard-shield.sh history # letzte 50
sudo /opt/adguard-shield/adguard-shield.sh history 200 # letzte 200
```