Release v1.0.0

2026-03-12 20:19:34 +01:00
parent f64d08f998
commit 7f2fe4dd73
3 changed files with 254 additions and 2 deletions
--- a/03-homeassistant-whitelist.yaml
+++ b/03-homeassistant-whitelist.yaml
@@ -0,0 +1,46 @@
+name: my/homeassistant-whitelist
+description: "Whitelist Home Assistant requests from NPMplus logs"
+filter: "evt.Meta.service == 'http' && evt.Meta.log_type in ['http_access-log', 'http_error-log']"
+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'"
+    - "evt.Meta.http_path startsWith '/api/history'"
+    - "evt.Meta.http_path startsWith '/api/logbook'"
+    - "evt.Meta.http_path startsWith '/api/template'"
+    - "evt.Meta.http_path startsWith '/api/events'"
+    - "evt.Meta.http_path startsWith '/api/webhook/'"
+    - "evt.Meta.http_path startsWith '/api/calendars'"
+    - "evt.Meta.http_path startsWith '/api/shopping_list'"
+    - "evt.Meta.http_path startsWith '/api/components'"
+    - "evt.Meta.http_path startsWith '/api/panels'"
+    - "evt.Meta.http_path startsWith '/api/error_log'"
+    - "evt.Meta.http_path startsWith '/api/discovery_info'"
+    - "evt.Meta.http_path startsWith '/api/onboarding'"
+    - "evt.Meta.http_path startsWith '/api/cloud'"
+    - "evt.Meta.http_path startsWith '/api/camera_proxy'"
+    - "evt.Meta.http_path startsWith '/api/media_player_proxy'"
+    - "evt.Meta.http_path startsWith '/api/tts_proxy'"
+    - "evt.Meta.http_path startsWith '/api/image'"
+    - "evt.Meta.http_path startsWith '/api/intent'"
+    - "evt.Meta.http_path startsWith '/api/conversation'"
+    - "evt.Meta.http_path startsWith '/api/core'"
+    - "evt.Meta.http_path startsWith '/api/hassio'"
+    - "evt.Meta.http_path startsWith '/auth/token'"
+    - "evt.Meta.http_path startsWith '/auth/authorize'"
+    - "evt.Meta.http_path startsWith '/auth/login_flow/'"
+    - "evt.Meta.http_path startsWith '/auth/providers'"
+    - "evt.Meta.http_path startsWith '/auth/sign_path'"
+    - "evt.Meta.http_path startsWith '/auth/long_lived_access_token'"
+    - "evt.Meta.http_path startsWith '/frontend_latest/'"
+    - "evt.Meta.http_path startsWith '/frontend_es5/'"
+    - "evt.Meta.http_path startsWith '/static/'"
+    - "evt.Meta.http_path startsWith '/hacsfiles/'"
+    - "evt.Meta.http_path startsWith '/local/'"
+    - "evt.Meta.http_path startsWith '/hassio/'"
+    - "evt.Meta.http_path startsWith '/lovelace'"
+    - "evt.Meta.http_path == '/manifest.json'"
+    - "evt.Meta.http_path == '/service_worker.js'"
--- a/README.md
+++ b/README.md
@@ -1,11 +1,75 @@
-# template_repository
+# CrowdSec Parser-Whitelist für Home Assistant

+Eine Parser-Whitelist für [CrowdSec](https://www.crowdsec.net/), die legitimen Home Assistant-Traffic in NPMplus-Logs vom Parsen ausschließt.
+Damit wird verhindert, dass API-, Frontend- und WebSocket-Anfragen fälschlicherweise als
+verdächtig eingestuft werden.

+## Überblick

+| Pfad | Beschreibung |
+|------|-------------|
+| `/api/websocket` | WebSocket-Verbindung (Haupt-UI-Kommunikation) |
+| `/api/states` | Entity-Zustände |
+| `/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 |
+| `/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) |
+| `/frontend_es5/` | Frontend-Assets für ältere Browser |
+| `/static/` | Statische Dateien (Icons, Bilder) |
+| `/hacsfiles/` | HACS (Home Assistant Community Store) Dateien |
+| `/local/` | Lokale benutzerdefinierte Dateien |
+| `/hassio/` | Supervisor & Add-on-Verwaltung (Ingress) |
+| `/lovelace` | Dashboard-Routen |
+| `/manifest.json` | Web-App-Manifest |
+| `/service_worker.js` | Service Worker für PWA-Funktionalität |

-Wichtig: Link für Lizenz anpassen.
+## Schnellstart

+1. Datei kopieren:

+   ```bash
+   cp 03-homeassistant-whitelist.yaml /etc/crowdsec/parsers/s02-enrich/03-homeassistant-whitelist.yaml
+   ```
+
+2. CrowdSec neu starten:
+
+   ```bash
+   docker restart crowdsec
+   ```
+
+3. Funktion prüfen:
+
+   ```bash
+   docker exec crowdsec cscli metrics
+   ```
+
+Detaillierte Anleitung: [docs/installation.md](docs/installation.md)

 <p align="center">
  <img src="https://assets.techniverse.net/f1/git/graphics/gray0-catonline.svg" alt="">
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -0,0 +1,142 @@
+# 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:
+
+```bash
+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:
+
+```bash
+docker restart crowdsec
+```
+
+## Überprüfung
+
+### Parser testen
+
+Mit `cscli explain` kann geprüft werden, ob die Whitelist auf eine echte Log-Zeile greift:
+
+```bash
+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:
+
+```bash
+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:
+
+```yaml
+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.