# Fail2Ban Integration für das Deploymentcenter

Das Deploymentcenter führt alle sicherheitsrelevanten Vorfälle (fehlgeschlagene WebUI-Logins, Kontosperren, IP-Drosselungen, ungültige API-Tokens und Rate-Limit-Verstöße) in einem dedizierten, maschinenlesbaren Sicherheitslog:

```
var/log/security.log
```

Im Gegensatz zu den anwendungsinternen Logs (`var/log/dc-YYYY-MM-DD.log`) behält diese Datei einen **stabilen Dateinamen**, sodass Log-Watcher wie **Fail2Ban** sie unterbrechungsfrei auswerten können.

---

## 1. Logformat

Jeder Eintrag folgt dem festen Schema:

```text
[YYYY-MM-DD HH:MM:SS] [SECURITY] [EVENT_TYPE] ip=<IP> key="val" ...
```

### Typische Ereignisse:

| Event-Typ | Bedeutung | Beispielzeile |
|---|---|---|
| `AUTH_FAIL` | Falsches Passwort oder Benutzer existiert nicht | `[2026-09-08 11:30:00] [SECURITY] [AUTH_FAIL] ip=198.51.100.2 user="admin" reason="invalid_password" failures=1` |
| `ACCOUNT_LOCKED` | Kontosperre nach $N$ Fehlversuchen | `[2026-09-08 11:30:15] [SECURITY] [ACCOUNT_LOCKED] ip=198.51.100.2 user="admin" duration=900 reason="too_many_failed_logins"` |
| `IP_LOCKED` | IP-Sperre nach 10 Fehlversuchen | `[2026-09-08 11:30:20] [SECURITY] [IP_LOCKED] ip=198.51.100.2 failures=10 duration=900` |
| `API_AUTH_FAIL` | Ungültiges Bearer-/Agent-Token übermittelt | `[2026-09-08 11:30:25] [SECURITY] [API_AUTH_FAIL] ip=198.51.100.2 path="/api/bugtracker/v1/projects" reason="token_rejected"` |
| `API_BRUTE_FORCE` | Schwellenwert ungültiger Tokens pro IP überschritten | `[2026-09-08 11:30:30] [SECURITY] [API_BRUTE_FORCE] ip=198.51.100.2 path="/api/bugtracker/v1/projects" reason="too_many_invalid_tokens"` |
| `RATE_LIMITED` | Endpunkt-Drosselung ausgelöst | `[2026-09-08 11:30:35] [SECURITY] [RATE_LIMITED] ip=198.51.100.2 bucket="setup_login" limit=10 count=11` |

---

## 2. Server-Installation & Konfiguration

### Schritt 1: Filter-Definition hinterlegen

Kopiere die Filterdatei nach `/etc/fail2ban/filter.d/deploymentcenter.conf`:

```bash
sudo cp config/fail2ban/filter.d/deploymentcenter.conf /etc/fail2ban/filter.d/deploymentcenter.conf
```

### Schritt 2: Jail aktivieren

Kopiere die Jail-Vorlage nach `/etc/fail2ban/jail.d/deploymentcenter.local`:

```bash
sudo cp config/fail2ban/jail.d/deploymentcenter.local /etc/fail2ban/jail.d/deploymentcenter.local
```

Passe in `/etc/fail2ban/jail.d/deploymentcenter.local` den Pfad zur Logdatei an deine Webroot an:

```ini
[deploymentcenter]
enabled  = true
port     = http,https
filter   = deploymentcenter
logpath  = /var/www/deploymentcenter/var/log/security.log
maxretry = 5
findtime = 600
bantime  = 3600
```

### Schritt 3: Filter testen

Mit `fail2ban-regex` kann die Erkennung direkt gegen das Log geprüft werden:

```bash
sudo fail2ban-regex /var/www/deploymentcenter/var/log/security.log /etc/fail2ban/filter.d/deploymentcenter.conf
```

Die Ausgabe sollte die erkannten Treffer und die extrahierten IP-Adressen anzeigen:

```text
Lines: 12 lines, 0 ignored, 12 matched, 0 missed
```

### Schritt 4: Fail2Ban neu laden

```bash
sudo fail2ban-client reload
sudo fail2ban-client status deploymentcenter
```

---

## 3. Logrotate für `security.log`

Damit `security.log` nicht unbegrenzt wächst, wird eine Logrotate-Konfiguration empfohlen:

`/etc/logrotate.d/deploymentcenter-security`:

```text
/var/www/deploymentcenter/var/log/security.log {
    weekly
    rotate 12
    missingok
    notifempty
    compress
    delaycompress
    copytruncate
}
```

> **Hinweis:** `copytruncate` erlaubt das Rotieren, ohne dass der PHP-Prozess neu gestartet werden muss oder Dateideskriptoren verloren gehen.

---

## 4. Manuelle Entsperrung (Unban)

Wurde eine IP fälschlicherweise gebannt, kann sie administrativ freigegeben werden:

```bash
# Aktuellen Status und gebannte IPs ansehen:
sudo fail2ban-client status deploymentcenter

# IP freigeben:
sudo fail2ban-client set deploymentcenter unbanip 198.51.100.2
```

Parallel dazu kann ein gesperrtes Benutzerkonto in der Verwaltungsoberfläche des Deploymentcenters unter **System → Benutzer** jederzeit mit einem Klick auf **🔓 Entsperren** wieder freigeschaltet werden.