Morpheus Link Bot — Erweiterte URL-Filterung für Matrix

⚡ Funktionsübersicht

🔍

Automatische URL-Filterung Der Bot überwacht alle Textnachrichten in überwachten Räumen. Enthält eine Nachricht eine URL oder Domain, prüft er diese sofort gegen Blacklist und Whitelist.

🔀

Drei-Wege-Routing Jede erkannte Domain landet in einer von drei Kategorien: Whitelist (erlaubt), Blacklist (gesperrt) oder Unbekannt (zur Überprüfung). Die Spezifität bestimmt die Priorität: Exakte Treffer > Wildcard-Treffer > Apex-Treffer.

⚙️

Moderationsworkflow Unbekannte Domains werden automatisch an einen konfigurierten Moderationsraum weitergeleitet. Moderatoren entscheiden per Emoji-Reaktion (✅ / ❌) oder Textbefehl.

💾

Datenbankgestützte Persistenz Alle Runtime-Moderationsentscheidungen sowie offene Moderationsanfragen werden in Maubots nativer Datenbank gespeichert. Bot-Neustarts sind vollständig stateful.

🔐

DSGVO / Privacy by Design Matrix-Nutzer-IDs werden ausschließlich als SHA-256(secret_salt:user_id)-Hash gespeichert. Ein Hintergrund-Retention-Loop löscht Verstoßdaten automatisch nach 24 Stunden.

🎯

Befehlsraum-Einschränkung Über command_rooms kann festgelegt werden, in welchen Räumen der Bot auf Befehle reagiert. Der Moderationsraum und Direktnachrichten sind immer erlaubt.

🌐

Wildcard-Unterstützung Einträge wie *.boese-seite.com sperren alle Subdomains auf einmal. Funktioniert in Blacklist und Whitelist gleichermaßen.

🏔️

Apex-Domain-Matching Ist evil.com direkt in der Blacklist, werden Subdomains wie sub.evil.com automatisch mitgeblockt — ohne gesonderten Wildcard-Eintrag.

🔗

URL-Shortener-Auflösung Bekannte Kurzlink-Dienste (bit.ly, t.co, tinyurl.com u.a.) werden via HEAD-Request aufgelöst. Die finale Ziel-Domain wird geprüft.

🛡️

Spam-Schutz & Auto-Mute Ein konfigurierbarer Warn-Cooldown verhindert Notification Flooding. Optional können Nutzer bei Erreichen eines Verstoß-Schwellenwerts automatisch stummgeschaltet werden.

🖼️

Linkvorschauen Für freigegebene URLs kann der Bot optional Open-Graph-Metadaten abrufen und eine Vorschau (Titel + Beschreibung) im Raum posten.

🔄

Event-ID-Deduplizierung Ein interner LRU-Cache (1.000 Einträge) verhindert Doppelverarbeitung bei Matrix-Sync-Replays nach Bot-Neustarts.

⌨️ Verfügbare Befehle

Öffentliche Befehle (für alle Nutzer)

Befehl	Beschreibung
`!urlstatus <domain>`	Zeigt ob eine Domain whitelisted, blacklisted oder unbekannt ist — inklusive Wildcard- und Apex-Treffern. Akzeptiert auch vollständige URLs.
`!stats`	Gibt die Anzahl geladener Domains sowie Wildcards und offene Überprüfungen aus.
`!hilfe`	Zeigt die vollständige Befehlsübersicht — nur per Direktnachricht (DM). In Gruppenräumen reagiert der Bot nicht.
`!status`	Zeigt den aktuellen Bot-Status inkl. Datenbankverbindung, Uptime und Version.

Moderationsbefehle (erfordern Berechtigung)

ℹ️

Berechtigungen

Ein Nutzer gilt als Moderator, wenn sein Powerlevel im Moderationsraum mindestens min_power_level (Standard: 50) beträgt oder seine Nutzer-ID in allowed_users eingetragen ist.

Befehl	Beschreibung
`!allow <domain>`	Domain sofort whitelisten. Unterstützt Wildcards: `!allow *.vertrauenswuerdig.de`
`!unallow <domain>`	Domain oder Wildcard-Eintrag aus der Whitelist entfernen.
`!block <domain>`	Domain sofort blacklisten. Unterstützt Wildcards: `!block *.boese-seite.com`
`!unblock <domain>`	Domain oder Wildcard-Eintrag aus der Blacklist entfernen.
`!reloadlists`	Alle .txt-Dateien neu einlesen — kein Neustart nötig.
`!pending`	Zeigt alle Domains, die aktuell auf eine Moderationsentscheidung warten.
`!sendpending`	Sendet alle offenen Überprüfungsalarme erneut in den Mod-Raum.
`!mute <@nutzer:server> [-t Min.]`	Nutzer manuell stummschalten (Powerlevel -1). Optional -t für Dauer in Minuten.
`!unmute <@nutzer:server>`	Stummschaltung eines Nutzers manuell aufheben.
`!ignore <domain>`	Domain zur Vorschau-Ignore-Liste hinzufügen.
`!unignore <domain>`	Domain von der Vorschau-Ignore-Liste entfernen.

Emoji-Reaktionen im Moderationsraum

Wenn eine unbekannte Domain erkannt wird, postet der Bot eine Alarmmeldung im Moderationsraum mit zwei Reaktionsknöpfen:

✅ — Domain zur Whitelist hinzufügen und Originalnachricht genehmigen.
❌ — Domain zur Blacklist hinzufügen.

⚠️

Hinweis

Reaktionen von Nutzern ohne ausreichende Berechtigung werden still ignoriert.

🔎 Wie der Bot URLs erkennt

Der Bot verwendet vier Stufen, die nacheinander auf jede Nachricht angewendet werden:

0️⃣

Stufe 0 — Matrix-ID-Bereinigung Matrix-Nutzer-IDs (@nutzer:homeserver) und Raum-IDs (!raum:homeserver) werden aus dem Nachrichtentext entfernt, bevor die URL-Erkennung greift. Verhindert Falschpositive.

1️⃣

Stufe 1 — HTML-Links Matrix-Clients senden formatierte Nachrichten mit <a href="...">. Diese Links werden als erstes und zuverlässigste Quelle ausgewertet.

2️⃣

Stufe 2 — Klassische URLs Explizite URLs mit http://, https:// oder www.-Präfix werden per Regex erkannt.

3️⃣

Stufe 3 — Nackte Domains Domains ohne Protokoll wie example.com werden erkannt, sofern ihre TLD zu einem bekannten Satz von ~230 gültigen Top-Level-Domains gehört. Das verhindert Falschpositive.

🔐

Unicode-Normalisierung

Alle extrahierten Domains werden vor dem Listen-Vergleich normalisiert — Vollbreite-Zeichen (like ｇｏｏｇｌｅ.com) sowie Unicode-Domains werden per IDNA in ihre Punycode-Form umgewandelt.

🎭 Wildcard-Einträge

Mit dem Präfix *. lassen sich ganze Domain-Familien auf einmal erfassen:

!block *.boese-seite.com     → sperrt sub.boese-seite.com, api.boese-seite.com, ...
!allow *.vertrauenswuerdig.de → whitelisted alle Subdomains

Geprüfte Domain	Eintrag	Match?
`sub.banned.com`	`*.banned.com`	✅ Ja — Wildcard
`api.banned.com`	`*.banned.com`	✅ Ja — Wildcard
`banned.com`	`*.banned.com`	❌ Nein — Wildcard deckt nur Subdomains ab
`sub.banned.com`	`banned.com` (exakt)	✅ Ja — Apex-Match
`a.b.banned.com`	`banned.com` (exakt)	✅ Ja — Apex-Match

💡

Tipp

Soll auch die Hauptdomain selbst gesperrt werden, müssen banned.com und *.banned.com als zwei separate Einträge angelegt werden.

⚙️ Konfigurationsoptionen

Diese Optionen werden in base-config.yaml definiert und können pro Instanz im Maubot-Dashboard überschrieben werden.

Grundkonfiguration

Parameter	Standard	Beschreibung
`blacklist_dir`	`/data/blacklists/`	Verzeichnis mit den Blacklist-.txt-Dateien.
`whitelist_dir`	`/data/whitelists/`	Verzeichnis mit den Whitelist-.txt-Dateien.
`mod_room_id`	(Pflichtfeld)	Matrix-Raum-ID des Moderationsraums (Format: `!xxx:homeserver`).
`mod_permissions.min_power_level`	`50`	Mindest-Powerlevel für Moderationsaktionen. 100 = nur Admin, 0 = jeder.
`mod_permissions.allowed_users`	`[]`	YAML-Array von Nutzer-IDs mit fester Moderationsberechtigung.
`command_rooms`	`[]`	Liste von Raum-IDs in denen der Bot auf Befehle reagiert.

Datenschutz / DSGVO

Parameter	Standard	Beschreibung
`secret_salt`	(Pflichtfeld)	Zufälliger Geheimschlüssel für SHA-256-Nutzer-Hashing. Generierung: `python3 -c "import secrets; print(secrets.token_hex(32))"`

Linkvorschauen

Parameter	Standard	Beschreibung
`enable_link_previews`	`true`	Linkvorschauen für whitelisted URLs aktivieren.
`link_preview_timeout`	`5`	HTTP-Timeout in Sekunden für Vorschau-Abrufe.

Spam-Schutz & Auto-Mute

Parameter	Standard	Beschreibung
`warn_cooldown`	`60`	Warn-Cooldown in Sekunden.
`mute_enabled`	`false`	Automatisches Stummschalten aktivieren.
`mute_threshold`	`5`	Anzahl der Verstöße innerhalb des Beobachtungsfensters.
`mute_window_minutes`	`5`	Beobachtungsfenster in Minuten.
`mute_duration_minutes`	`60`	Dauer der automatischen Stummschaltung (0 = unbegrenzt).
`mute_commands_enabled`	`true`	Manuelle !mute und !unmute Befehle aktivieren.
`global_mute`	`true`	Globales Stummschalten in allen Räumen des Bots.

🚀 Installation mit Docker

Voraussetzungen

Maubot läuft in Docker (Standard-Image: dock.mau.dev/maubot/maubot)
Maubot läuft standardmäßig als UID/GID 1337 im Container

Schritt 1 — Plugin paketieren

cd /pfad/zum/plugin
zip -r url_filter.mbp \
    maubot.yaml base-config.yaml main.py \
    blacklists/custom.txt blacklists/ignore.txt whitelists/custom.txt

Schritt 2 — Plugin hochladen

Maubot-Dashboard aufrufen: https://dein-server/_matrix/maubot/#/plugins
"Upload plugin" klicken und die .mbp-Datei hochladen
Neue Instanz erstellen, Bot-Client zuweisen und speichern

Schritt 3 — Verzeichnisstruktur anlegen

mkdir -p ./data/blacklists ./data/whitelists
touch ./data/blacklists/custom.txt
touch ./data/whitelists/custom.txt

Schritt 4 — Blacklist-Dateien ablegen

Hostfile-formatierte .txt-Dateien in ./data/blacklists/ ablegen.

Geeignete Quellen:

oisd.nl — verschiedene Kategorien
StevenBlack/hosts — konsolidierte Listen
The Block List Project — nach Kategorie sortiert

./data/blacklists/
├── malware.txt
├── phishing.txt
├── scam.txt
└── custom.txt      ← vom Bot verwaltet

Schritt 5 — Berechtigungen setzen ⚠️

⚠️

Wichtig

Da Maubot im Container als UID 1337 läuft, müssen die Verzeichnisse diesem Nutzer gehören. Ohne korrekte Berechtigungen kann der Bot nicht in custom.txt schreiben.

chown -R 1337:1337 ./data/blacklists ./data/whitelists

Schritt 6 — Instanz konfigurieren

Im Maubot-Dashboard mindestens folgende Werte setzen:

blacklist_dir: /data/blacklists/
whitelist_dir: /data/whitelists/
mod_room_id: "!DEIN_MOD_RAUM_ID:homeserver.example"
secret_salt: "dein-zufaelliger-salt-hier"

Schritt 7 — Bot in Räume einladen

Bot in alle zu überwachenden Räume einladen
Bot in diesen Räumen auf Powerlevel 50 (Moderator) setzen
Bot in den Moderationsraum einladen und Schreibrechte erteilen
Wenn Auto-Mute verwendet wird: Bot auf Powerlevel 100 (Admin) setzen

🔧 Fehlerbehebung

Bot schreibt nicht in custom.txt

Berechtigungen auf dem Host korrigieren: chown -R 1337:1337 ./data/blacklists ./data/whitelists

Bot kann keine Nachrichten löschen

Bot im betreffenden Raum auf Powerlevel 50 setzen.

Auto-Mute funktioniert nicht

Bot benötigt ein höheres Powerlevel als der Zielnutzer (empfohlen: PL 100).

Bot sendet nicht in den Moderationsraum

Prüfen ob der Bot eingeladen wurde und Schreibrechte hat.

Keine .txt-Dateien beim Start gefunden

Verzeichnis und Dateien anlegen (Schritt 3), Berechtigungen setzen (Schritt 5).

!botstatus meldet DB-Fehler

Sicherstellen, dass database: true und database_type: asyncpg in maubot.yaml gesetzt sind.

Warnung „secret_salt ist nicht gesetzt"

Den secret_salt in der Instanzkonfiguration auf einen sicheren Zufallswert setzen.

📦 Paketerstellung und Deployment

Nach Änderungen an den Quelldateien neu paketieren:

zip -r url_filter.mbp \
    maubot.yaml base-config.yaml main.py \
    blacklists/custom.txt blacklists/ignore.txt whitelists/custom.txt

Das aktualisierte .mbp im Maubot-Dashboard hochladen und die Instanz neu starten.

💡

Listen manuell aktualisieren

Neue .txt-Dateien in ./data/blacklists/ ablegen, Berechtigungen prüfen, dann !reloadlists im Moderationsraum eingeben — kein Neustart nötig.

📋 Anforderungen

Komponente	Mindestversion
Maubot	>= 0.4.0
mautrix-python	>= 0.20.0
Python	>= 3.10

Keywords

Matrix Maubot URL filtering Blacklist Whitelist Phishing Anti-Spam Moderation Link-Filter Security GDPR DSGVO Auto-Mute URL-Shortener Wildcard Apex-Domain