Initial Release v1.0.0

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

01-matrix-whitelist.yaml

@@ -0,0 +1,9 @@
+name: my/matrix-whitelist
+description: "Whitelist Matrix/Synapse requests from NPMplus logs"
+filter: "evt.Meta.service == 'http' && evt.Meta.log_type in ['http_access-log', 'http_error-log']"
+whitelist:
+  reason: "Matrix federation/client traffic"
+  expression:
+    - "evt.Meta.http_path startsWith '/_matrix/'"
+    - "evt.Meta.http_path startsWith '/_synapse/'"
+    - "evt.Meta.http_path startsWith '/.well-known/matrix/'"

README.md

@@ -1,11 +1,35 @@
-# template_repository
+# CrowdSec Parser-Whitelist für Matrix/Synapse
 
+Eine Parser-Whitelist für [CrowdSec](https://www.crowdsec.net/), die legitimen Matrix/Synapse-Traffic in NPMplus-Logs vom Parsen ausschließt. Damit wird verhindert, dass Federation- und Client-Anfragen fälschlicherweise als verdächtig eingestuft werden.
 
+## Überblick
 
+| Pfad-Muster | Beschreibung |
+|---|---|
+| `/_matrix/` | Matrix Federation & Client-Server API |
+| `/_synapse/` | Synapse Admin & interne Endpunkte |
+| `/.well-known/matrix/` | Matrix Server-Discovery |
 
-Wichtig: Link für Lizenz anpassen.
+## Schnellstart
 
+1. Datei kopieren:
+   ```bash
+   cp 01-matrix-whitelist.yaml /etc/crowdsec/parsers/s02-enrich/01-matrix-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="">

docs/installation.md

@@ -0,0 +1,99 @@
+# 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 01-matrix-whitelist.yaml /etc/crowdsec/parsers/s02-enrich/01-matrix-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 '/_matrix/' /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/matrix-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/matrix-whitelist                | Matrix federation/client traffic | 6085 | 5746        |
++------------------------------------+----------------------------------+------+-------------+
+```
+
+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-Muster | Zweck |
+|---|---|
+| `/_matrix/` | Matrix Federation API & Client-Server API (Nachrichten, Räume, Sync, …) |
+| `/_synapse/` | Synapse-spezifische Endpunkte (Admin API, interne Routen) |
+| `/.well-known/matrix/` | Matrix Server-Discovery (andere Server finden den Homeserver hierüber) |
+
+## Anpassung
+
+Die Datei kann bei Bedarf um eigene Pfade erweitert werden. Dazu einfach weitere Einträge unter `expression` hinzufügen:
+
+```yaml
+whitelist:
+  reason: "Matrix federation/client traffic"
+  expression:
+    - "evt.Meta.http_path startsWith '/_matrix/'"
+    - "evt.Meta.http_path startsWith '/_synapse/'"
+    - "evt.Meta.http_path startsWith '/.well-known/matrix/'"
+    - "evt.Meta.http_path startsWith '/eigener-pfad/'"
+```
+
+Nach jeder Änderung muss CrowdSec neu gestartet werden.