# CrowdSec Manager – Dokumentation

Umfassende Dokumentation für den CrowdSec Manager.

---

## Dokumentationsübersicht

| Dokument | Beschreibung |
|----------|-------------|
| [CONFIGURATION.md](CONFIGURATION.md) | Alle Konfigurationsoptionen im Detail |
| [ALLOWLIST.md](ALLOWLIST.md) | Allowlist-Verwaltung, CLI-Optionen, Cron-Integration |
| [ADMIN.md](ADMIN.md) | Interaktives Menü & CrowdSec-Administration |
| [NOTIFICATIONS.md](NOTIFICATIONS.md) | Benachrichtigungen (Ntfy, Gotify, E-Mail, Desktop) |
| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Fehlerbehebung & FAQ |

---

## Schnellstart

### 1. Installation

```bash
cd /opt
git clone https://github.com/dein-user/crowdsec-manager.git
cd crowdsec-manager
chmod +x crowdsec-manager.sh
```

### 2. Abhängigkeiten

```bash
# Debian / Ubuntu
sudo apt update && sudo apt install -y dnsutils curl

# RHEL / CentOS / Fedora
sudo dnf install -y bind-utils curl

# Alpine
apk add --no-cache bind-tools curl
```

### 3. Konfiguration

```bash
nano config/crowdsec-manager.conf
```

Mindestens setzen:
- `CSCLI_CMD` – CrowdSec CLI Befehl
- `ALLOWLIST_ENTRIES` – Domains/IPs für die Allowlist

### 4. Test

```bash
./crowdsec-manager.sh --test
```

### 5. Verwendung

```bash
# Interaktives Menü (Standard)
./crowdsec-manager.sh

# Allowlist-Sync (für Cron)
./crowdsec-manager.sh --sync-allowlist
```

### 6. Cron einrichten

```bash
crontab -e
```

```cron
*/30 * * * * /opt/crowdsec-manager/crowdsec-manager.sh --sync-allowlist >> /var/log/crowdsec-manager-cron.log 2>&1
```

---

## Architektur

### Dateien

| Datei | Aufgabe |
|-------|---------|
| `crowdsec-manager.sh` | Hauptscript (Allowlist-Sync + Interaktives Admin-Menü) |
| `config/crowdsec-manager.conf` | Zentrale Konfigurationsdatei |
| `examples/crontab.example` | Vorlagen für Cron-Einträge |
| `docs/` | Dokumentation (aufgeteilt nach Themen) |

### Voraussetzungen

- **Bash 4.0+** (für assoziative Arrays)
- **dig** (DNS-Auflösung) – Teil von `dnsutils` / `bind-utils`
- **CrowdSec** mit CLI-Zugriff
- Optional: **curl** (für Ntfy/Gotify/E-Mail-Benachrichtigungen)
- Optional: **python3** (für JSON-Escaping bei Gotify)

### Sicherheitsaspekte

- **Lock-File** verhindert Race Conditions bei paralleler Ausführung
- **Temporäre Dateien** werden nach Ausführung automatisch gelöscht (auch bei Abbruch)
- **Keine sensiblen Daten** in der Log-Ausgabe
- Config-Datei sollte nur vom Script-Benutzer lesbar sein: `chmod 600 config/crowdsec-manager.conf`
- Für DNS-Spoofing Schutz: DNSSEC-validierende DNS-Server verwenden

---

## Logging & Monitoring

### Log-Datei analysieren

```bash
# Letzte Ausführung anzeigen
grep "$(date '+%Y-%m-%d')" /var/log/crowdsec-manager.log

# Nur Fehler
grep "\[ERROR\]" /var/log/crowdsec-manager.log

# Nur Änderungen
grep -E "Hinzugefügt|Entfernt" /var/log/crowdsec-manager.log
```

### Exit-Codes für Monitoring

| Exit-Code | Bedeutung |
|:---:|---------|
| `0` | Erfolgreich |
| `1` | Kritischer Fehler |
| `2` | Teilweise erfolgreich (mit Fehlern) |

---

## Integration

### Ansible

```yaml
- name: Deploy CrowdSec Manager
  hosts: crowdsec_servers
  tasks:
    - name: Clone repository
      git:
        repo: https://github.com/user/crowdsec-manager.git
        dest: /opt/crowdsec-manager

    - name: Deploy config
      template:
        src: crowdsec-manager.conf.j2
        dest: /opt/crowdsec-manager/config/crowdsec-manager.conf
        mode: '0600'

    - name: Setup cron
      cron:
        name: "CrowdSec Manager"
        minute: "*/30"
        job: "/opt/crowdsec-manager/crowdsec-manager.sh --sync-allowlist >> /var/log/crowdsec-manager-cron.log 2>&1"
```

### Docker Compose Sidecar

```yaml
services:
  crowdsec:
    image: crowdsecurity/crowdsec
    container_name: crowdsec

  allowlist-manager:
    image: alpine
    volumes:
      - ./crowdsec-manager:/app
      - /var/run/docker.sock:/var/run/docker.sock
    command: >
      sh -c "apk add --no-cache bash bind-tools curl docker-cli &&
             while true; do
               /app/crowdsec-manager.sh --sync-allowlist;
               sleep 1800;
             done"
```