5.2 KiB
Installation & Konfiguration
Voraussetzungen
- CrowdSec (als Docker-Container oder nativ installiert)
- NPMplus als Reverse Proxy mit aktiviertem Logging
Installation
1. Whitelist-Datei kopieren
Die YAML-Datei muss in das CrowdSec Parser-Verzeichnis s02-enrich kopiert werden:
cp 03-homeassistant-whitelist.yaml /etc/crowdsec/parsers/s02-enrich/03-homeassistant-whitelist.yaml
Hinweis: Bei einer Docker-Installation liegt das Verzeichnis im gemappten Volume, z. B.
./data/crowdsec/config/parsers/s02-enrich/
2. CrowdSec neu starten
Damit die Whitelist geladen wird, muss CrowdSec neu gestartet werden:
docker restart crowdsec
Überprüfung
Parser testen
Mit cscli explain kann geprüft werden, ob die Whitelist auf eine echte Log-Zeile greift:
grep '/api/' /home/docker-projekte/npmplus/data/npmplus/nginx/logs/access.log \
| tail -n 1 \
| docker exec -i crowdsec cscli explain -f- --type npmplus
In der Ausgabe sollte die Whitelist als Treffer erscheinen, z. B.:
├ s02-enrich
| ├ ☑ crowdsecurity/whitelists
| ├ ☑ my/homeassistant-whitelist ✅ (whitelisted)
Metriken prüfen
Die Wirkung ist in den CrowdSec-Metriken sichtbar:
docker exec crowdsec cscli metrics
Beispielausgabe:
+-----------------------------------------------------------------------------------------------+
| Whitelist Metrics |
+------------------------------------+-------------------------------------+------+-------------+
| Whitelist | Reason | Hits | Whitelisted |
+------------------------------------+-------------------------------------+------+-------------+
| my/homeassistant-whitelist | Home Assistant legitimate traffic | 4210 | 3987 |
+------------------------------------+-------------------------------------+------+-------------+
Die Spalte Whitelisted zeigt an, wie viele Log-Zeilen durch die Whitelist herausgefiltert wurden.
Funktionsweise
Die Whitelist arbeitet als CrowdSec-Parser in der Stufe s02-enrich. Sie prüft eingehende Log-Events anhand folgender Kriterien:
Filter: Nur HTTP-Logs (Access- und Error-Logs) werden berücksichtigt.
Whitelist-Regeln: Anfragen an folgende Pfade werden als legitim eingestuft:
| Pfad | Beschreibung |
|---|---|
/api/websocket |
WebSocket-Verbindung (Haupt-UI-Kommunikation) |
/api/states |
Entity-Zustände lesen/setzen |
/api/services |
Service-Aufrufe (Automationen, Integrationen) |
/api/config |
Konfigurationsdaten |
/api/history |
Verlaufsdaten |
/api/logbook |
Logbuch |
/api/template |
Template-Rendering |
/api/events |
Event-Bus |
/api/webhook/ |
Webhooks (Mobile App, Integrationen) |
/api/calendars |
Kalender-Daten |
/api/shopping_list |
Einkaufsliste |
/api/components |
Geladene Komponenten |
/api/panels |
Panel-Registrierung |
/api/error_log |
Fehler-Log |
/api/discovery_info |
Discovery-Informationen |
/api/onboarding |
Onboarding |
/api/cloud |
Nabu Casa Cloud |
/api/camera_proxy |
Kamera-Proxy |
/api/media_player_proxy |
Media-Player-Proxy |
/api/tts_proxy |
Text-to-Speech-Proxy |
/api/image |
Bild-Proxy |
/api/intent |
Sprachassistent-Intents |
/api/conversation |
Konversations-API |
/api/core |
Core-Informationen |
/api/hassio |
Supervisor-API & Ingress-Proxy für Add-ons |
/auth/token |
Token-Austausch (Login, Refresh) |
/auth/authorize |
OAuth2-Autorisierung |
/auth/login_flow/ |
Multi-Step-Login-Flow (HA-spezifisch) |
/auth/providers |
Authentifizierungs-Provider |
/auth/sign_path |
Signierte Pfade für temporären Zugriff |
/auth/long_lived_access_token |
Langzeit-Zugangstoken |
/frontend_latest/ |
Frontend-Assets (JavaScript, CSS) für aktuelle Browser |
/frontend_es5/ |
Frontend-Assets für ältere Browser (ES5-kompatibel) |
/static/ |
Statische Dateien (Icons, Bilder, Schriftarten) |
/hacsfiles/ |
HACS (Home Assistant Community Store) – Custom Components & Lovelace-Karten |
/local/ |
Lokale benutzerdefinierte Dateien (z. B. eigene Icons, Custom Cards) |
/hassio/ |
Supervisor & Add-on-Verwaltung, Ingress-Proxy für Add-ons |
/lovelace |
Dashboard-Routen (Lovelace UI) |
/manifest.json |
Web-App-Manifest für PWA-Installation |
/service_worker.js |
Service Worker für Offline- und PWA-Funktionalität |
Anpassung
Die Datei kann bei Bedarf um eigene Pfade erweitert werden. Dazu einfach weitere
Einträge unter expression hinzufügen:
whitelist:
reason: "Home Assistant legitimate traffic"
expression:
- "evt.Meta.http_path startsWith '/api/websocket'"
- "evt.Meta.http_path startsWith '/api/states'"
- "evt.Meta.http_path startsWith '/api/services'"
- "evt.Meta.http_path startsWith '/api/config'"
# ... (alle weiteren /api/ Endpunkte, siehe YAML-Datei)
- "evt.Meta.http_path startsWith '/auth/token'"
- "evt.Meta.http_path startsWith '/auth/login_flow/'"
- "evt.Meta.http_path startsWith '/frontend_latest/'"
- "evt.Meta.http_path startsWith '/eigener-pfad/'"
Nach jeder Änderung muss CrowdSec neu gestartet werden.