Initialer Import

2026-03-11 16:49:45 +01:00
parent ab9d9870dd
commit efb11a0bfa
12 changed files with 3442 additions and 8 deletions
@@ -0,0 +1,182 @@
+# CrowdSec Manager – Dokumentation
+
+## Version 0.1.0
+
+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 --run
+```
+
+### 6. Cron einrichten
+
+```bash
+crontab -e
+```
+
+```cron
+*/30 * * * * /opt/crowdsec-manager/crowdsec-manager.sh --run >> /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 --run >> /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 --run;
+               sleep 1800;
+             done"
+```