Matrix Synapse absichern mit Draupnir Bot & Antispam-Modul

Moderation in Matrix kann schnell anspruchsvoll werden, besonders in offenen Räumen mit vielen unterschiedlichen Teilnehmern.
Um diese Aufgaben zuverlässiger und effizienter zu bewältigen, setze ich auf Draupnir – einen vielseitigen Moderationsbot, der sich nahtlos in bestehende Matrix-Umgebungen integriert.
Draupnir ist ein weiterentwickelter Fork, der auf Mjolnir aufbaut und spürbare Verbesserungen mitbringt: Wiederkehrende Moderationsaufgaben lassen sich automatisieren, während gezielte Schutzmechanismen helfen, Missbrauch frühzeitig einzudämmen.

Ein großer Vorteil ist die Unterstützung von Policy Lists – das sind spezielle Räume, in denen Communities gemeinsam Sperrlisten pflegen.
Indem mein Server an diesen Listen teilnimmt, kann ich auf bestehende Moderationsstrukturen zurückgreifen und muss nicht jede Bedrohung selbst erkennen und abwehren. Gerade bei organisiertem Spam oder systematischen Angriffen macht das einen großen Unterschied.

Zusätzlich habe ich mein Setup durch das synapse-http-antispam-Modul erweitert.
In diesem Beitrag zeige ich dir, wie du Draupnir und das Antispam-Modul zusammen so einrichtest, dass dein Homeserver optimal geschützt ist.

🔑 Bot-Benutzer erstellen und Access Token abrufen

Bevor Draupnir für dich arbeiten kann, braucht er einen eigenen Benutzer auf deinem Homeserver.
Wenn du Matrix über Docker betreibst, kannst du einfach folgenden Befehl auf deinem Matrix Host ausführen:

docker exec -it <matrix-app-docker> register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Vergib einen passenden Benutzernamen wie draupnir und setze ein sicheres Passwort. Adminrechte sind notwendig, da Draupnir gewisse Aktionen im Raum steuern muss.

Den Access Token, den du für die spätere Konfiguration benötigst, kannst du anschließend über eine einfache Anfrage abrufen:

curl -XPOST -d '{"type":"m.login.password", "user":"DEIN_BENUTZERNAME", "password":"DEIN_PASSWORT"}' "https://matrix.domain.com/_matrix/client/r0/login"

Die Antwort enthält ein Feld namens "access_token" – diesen Token trägst du später in deiner production.yaml unter accessToken: ein. Achte darauf, dass der Token sicher aufbewahrt wird, da dieser Adminrechte mit sich bringt.

🏠 Managementraum erstellen

Erstelle einen neuen, privaten Matrix-Raum, der nur per Einladung erreichbar ist. Lade dort deinen Bot (z. B. @draupnir:domain.com) ein.

Hinweis: Aktuell gibt es Einschränkungen bei verschlüsselten Räumen. Ich empfehle daher, die Verschlüsselung für diesen Raum zu deaktivieren. Weitere Informationen dazu findest du in der Dokumentation.

Draupnir tritt dem Raum automatisch bei, sobald du diesen in der Konfiguration angibst und den Docker Container startest.

📂 Docker-Compose für Draupnir aufsetzen

Für den Betrieb erstelle ich ein kleines Docker-Compose-Setup. Hier ein Beispiel:

services:
  matrix-draupnir:
    image: gnuxie/draupnir:v2.3.0-beta.2
    container_name: matrix-draupnir
    hostname: matrix-draupnir
    restart: unless-stopped
    volumes:
      - ./data/matrix-draupnir/production.yaml:/data/config/production.yaml:ro
      - ./data/matrix-draupnir/storage:/data/storage
    command: >
      bot --draupnir-config /data/config/production.yaml

Wichtig:
Damit Draupnir überhaupt mit dem neuen synapse-http-antispam-Modul arbeiten kann, musst du aktuell die neueste Beta-Version von Draupnir verwenden (ab v2.3.0-beta.2).
Erst ab dieser Version werden die HTTP-Abfragen an Synapse vollständig unterstützt.
Ältere Versionen von Draupnir kennen das HTTP-Antispam-Feature noch nicht und könnten deshalb nicht korrekt mit deinem Server zusammenarbeiten.

📄 Die Draupnir-Konfiguration

Erstelle die Konfigurationsdatei aus dem Projektordner heraus:

mkdir -p ./data/matrix-draupnir
nano ./data/matrix-draupnir/production.yaml

Die wichtigste Datei für Draupnir ist production.yaml.
Hier definierst du, wie dein Bot arbeiten soll. Ein einfaches Beispiel:

# URL zum Matrix-Homeserver (Client-API)
homeserverUrl: "https://matrix.domain.com"

# Öffentliche Client-API URL (z. B. für Reports)
rawHomeserverUrl: "https://matrix.domain.com"

# Access Token des Bots
accessToken: "qLm6eqTyCQ9KCbHWDqb6di8g5X5rQZVM"

# Speicherort für Bot-Daten
dataPath: "/data/storage"

# Nur Einladungen von Managern akzeptieren
autojoinOnlyIfManager: true

# Managementraum (Alias oder Raum-ID)
managementRoom: "!jWjChHtdpOkbgTSnK:domain.com"

# Log-Level (DEBUG, INFO, WARN, ERROR)
logLevel: "INFO"

# Moderationsrechte beim Start überprüfen
verifyPermissionsOnStartup: true

# Bot führt Aktionen nur im Testmodus aus
noop: false

# Kein Server ACL setzen
disableServerACL: false

# Nachrichten bei bestimmten Ban-Gründen automatisch löschen
automaticallyRedactForReasons:
  - "spam"
  - "advertising"

# Alle beigetretenen Räume automatisch schützen
protectAllJoinedRooms: true

# Pause zwischen Bot-Aktionen in Millisekunden
backgroundDelayMS: 500

admin:
  # Adminrechte im Raum vergeben können
  enableMakeRoomAdminCommand: true

commands:
  # Befehle ohne !draupnir Präfix zulassen
  allowNoPrefix: false

  # Weitere Befehlsprefixes erlauben
  additionalPrefixes:
    - "draupnir"

  ban:
    # Standard-Ban-Gründe bei fehlendem Grund
    defaultReasons:
      - "spam"
      - "brigading"
      - "harassment"
      - "disagreement"

protections:
  wordlist:
    # Gebannte Wörter bei Raumbeitritt
    words:
      - "bad word"
      - "click here"
     #- "kann-um-beliebig-viele-Worte-erweitert-werden"

    # Minuten bis Benutzer als "vertrauenswürdig" gilt
    minutesBeforeTrusting: 30

roomStateBackingStore:
  # Raumzustand lokal zwischenspeichern
  enabled: true

health:
  healthz:
    # Healthcheck-Endpoint aktivieren (für z. B. Docker)
    enabled: true

  sentry:
    # Fehlerbericht-Tool (optional)
    #dsn: ""

web:
  enabled: true
  address: 0.0.0.0
  port: 8082

  abuseReporting:
    # Abuse-Report Web API aktivieren
    enabled: false

  synapseHTTPAntispam:
    enabled: true
    authorization: 8EEGpJGVsR2yHmXaA9r74SwcmijLpQmraRm6HuivhG8in5KJ8H

# Reports regelmäßig bei Synapse abfragen
pollReports: false

# Neue Reports im Management-Raum anzeigen
displayReports: true

safeMode:
  bootOption: RecoveryOnly  # Oder: Never, Always

retryConfig:
  maxAttempts: 5
  baseDelayMs: 1000

Damit Draupnir und dein Matrix-Server sicher miteinander kommunizieren können, wird ein sogenannter Access Token verwendet.
Dieser Token ist eine Art „geheimer Schlüssel“, der beide Seiten authentifiziert.
Wichtig: Sowohl in der Draupnir-Konfiguration als auch im Synapse-Modul (homeserver.yaml) muss derselbe Token eingetragen werden, damit später das synapseHTTPAntispam-Modul funktioniert.

In meinem Beispiel lautet der Token:

8EEGpJGVsR2yHmXaA9r74SwcmijLpQmraRm6HuivhG8in5KJ8H

Der Token darf gerne mindestens 50 Zeichen lang sein.

Falls du selbst einen neuen sicheren Token erzeugen möchtest, kannst du das einfach auf der Linux-Konsole tun:

tr -dc 'A-Za-z0-9' </dev/urandom | head -c50

Dieser Befehl erzeugt einen zufälligen, 50 Zeichen langen String, den du als Authorization-Token verwenden kannst.

Weitere Konfigurationsmöglichkeiten findest du im Repositoty auf Github.

Die Datei enthält die wichtigsten Einstellungen. Einige erkläre ich dir hier im Kurzformat:

Option	Bedeutung
homeserverUrl	Deine Matrix-Homeserver-URL (Client-API)
accessToken	Token des Bots, muss Adminrechte haben
managementRoom	Raum-ID oder Alias für Steuerungsraum
synapseHTTPAntispam	Access-Token für synapseHTTPAntispam-Modul

🧩 Synapse HTTP Antispam-Modul integrieren

Zusätzlich habe ich meinen Synapse-Server um das Modul synapse-http-antispam erweitert.
Dieses Modul verknüpft deinen Homeserver direkt mit Draupnir und bietet eine wichtige Ergänzung zum klassischen Spam-Schutz.

Wenn ein Benutzer auf einer Bannliste steht, kann das Modul verhindern, dass dieser Chatanfragen an deine Benutzer stellt oder neuen Räumen beitritt.
Der Zugriff auf die aktuelle Version und die Dokumentation des Moduls ist auf GitHub verfügbar.

✅ Bare Metal Nutzer installieren das Modul einfach auf dem Matrix Server:

pip install synapse-http-antispam

✅ Docker-Nutzer (wie ich) bauen ein eigenes Image, mit Synapse und dem Modul:

FROM matrixdotorg/synapse:latest

RUN pip install --no-cache-dir synapse-http-antispam

Alternativ kannst du auch mein fertiges Docker Image verwenden:

repo.techniverse.net/docker-hosted/custom-synapse:latest

Damit Synapse das Modul korrekt nutzt, musst du anschließend in deiner homeserver.yaml folgendes ergänzen:

modules:
  - module: synapse_http_antispam.HTTPAntispam
    config:
      base_url: http://matrix-draupnir:8082/api/1/spam_check
      authorization: '8EEGpJGVsR2yHmXaA9r74SwcmijLpQmraRm6HuivhG8in5KJ8H'
      enabled_callbacks:
        - check_event_for_spam
        - user_may_invite
        - user_may_join_room
      fail_open:
        check_event_for_spam: true
        user_may_invite: false
        user_may_join_room: false
      async:
        check_event_for_spam: true

📖 Was macht dieses Modul eigentlich?

Das synapse-http-antispam-Modul ermöglicht es deinem Synapse-Server, bestimmte Prüfungen an einen externen Dienst auszulagern – in unserem Fall: Draupnir.
Dabei nutzt es sogenannte Callbacks, also definierte Stellen im Nachrichtenfluss, an denen entschieden werden kann, ob ein Verhalten erlaubt ist oder nicht.

Die wichtigsten Hooks, die du in enabled_callbacks aktivierst:

• check_event_for_spam
  Wird ausgelöst, wenn ein Nutzer eine Nachricht sendet oder eine Aktion durchführt. Draupnir kann das Ereignis analysieren und ggf. blockieren.
• user_may_invite
  Prüft, ob ein Nutzer überhaupt jemand anderen in einen Raum einladen darf.
• user_may_join_room
  Entscheidet, ob ein Nutzer einem bestimmten Raum beitreten darf.

Durch diese Mechanismen kann Draupnir proaktiv moderieren – und potenziellen Spam abwehren, bevor er überhaupt in einem deiner Räume ankommt.

🔍 Erklärung der wichtigsten Optionen

Option	Bedeutung
base_url	Die vollständige URL, über die Synapse Draupnir erreicht. Bei Docker reicht der Containername im gleichen Netzwerk (hier z. B. matrix-draupnir).
authorization	Der gleiche Token wie in Draupnir (production.yaml) – dient der sicheren Authentifizierung zwischen Synapse und dem Bot. (siehe „Die Draupnir-Konfiguration“
enabled_callbacks	Aktiviert gezielt nur die Prüfungen, die du brauchst. Draupnir wird nur auf diese Ereignisse reagieren.
fail_open	Gibt an, ob Aktionen erlaubt sein sollen, falls Draupnir nicht erreichbar ist. Sinnvoll als Fallback, damit Synapse nicht „dichtmacht“.
async	Erlaubt die asynchrone Prüfung von Nachrichten, was Synapse bei hoher Last entlasten kann.

🚀 Draupnir starten

Starte jetzt deinen Bot mit einem einfachen:

docker compose up -d

🧭 Und jetzt? Ein Überblick nach dem Start

Nach dem Start ist Draupnir zwar aktiv, aber noch nicht ganz „scharf geschaltet“. Achte unbedingt auf folgende Schritte:

• Der Bot muss Mitglied in den zu schützenden Räumen sein.
• Er braucht dort Adminrechte, um effektiv moderieren zu können.
• Protections wie die Wortfilter müssen aktiviert sein (z. B. !draupnir protections enable WordListProtection).
• Über !draupnir status kannst du den aktuellen Zustand des Bots prüfen.

Wenn das alles passt, übernimmt Draupnir für dich die ersten Moderationsaufgaben vollautomatisch.

⚖️ Policy-Räume aktivieren

Willst du noch eine Schippe drauflegen? Dann abonniere ein paar Policy-Listen in deinem Management-Room:

!draupnir watch #tchncs-ban-list:tchncs.de
!draupnir watch #matrix-org-hs-tos-bl:matrix.org
!draupnir watch #asragrbanlist_general:asra.gr
!draupnir watch #community-moderation-effort-bl:neko.dev
!draupnir watch #techniverse-bans-bl:techniverse.net
!draupnir watch #policy:ztfr.de

Damit aktiviert Draupnir die Community-Listen für automatische Bannregeln.

Diese Policy-Räume beinhalten von der Community gepflegte Blocklisten mit bekannten Spam-Accounts, Trollen oder böswillig agierenden Servern. Sobald du diese Listen mit Draupnir abonnierst, wertet der Bot die enthaltenen Regeln aus und kann automatisch Nutzer bannen oder Server ausschließen, sobald diese einem deiner geschützten Räume beitreten. Damit entsteht ein gemeinschaftlicher Schutzmechanismus, von dem dein Server direkt profitiert.

🧱 Deine eigene Policy List erstellen

Du willst selbst eine Policy-Liste pflegen und mit anderen teilen? Kein Problem – Draupnir bringt alles mit, was du dafür brauchst.

Mit einer eigenen Policy List kannst du Regeln wie Bannlisten oder Einschränkungen zentral verwalten. Statt einzelne User manuell in jedem Raum zu bannen, definierst du deine Regeln einmal – und Draupnir setzt sie dann überall gleichzeitig um.

Die Erstellung ist denkbar einfach:

!draupnir list create community-bans draupnir-bans

Dieser Befehl erzeugt eine neue Policy-Liste mit dem Shortcode community-bans und dem Alias #draupnir-bans:domain.com.

Sobald der Raum erstellt ist, kannst du:

• per !draupnir ban <user> community-bans spam Regeln hinzufügen
• den Raum für andere Communities freigeben (wenn gewünscht)
• mit !draupnir watch diesen Raum auch auf anderen Servern einbinden

💡 Du kannst dir jederzeit mit !draupnir status anzeigen lassen, welche Policy-Räume dein Bot aktuell überwacht – inklusive der jeweiligen Shortcodes.

🛡️ HTTP-Antispam-Modul aktivieren: Zwei wichtige Protections

Damit dein Synapse-Server überhaupt mit dem neuen HTTP-Antispam-Modul arbeitet, musst du zwei spezielle Schutzmechanismen in Draupnir aktivieren:

!draupnir protections enable BlockInvitationsOnServerProtection
!draupnir protections enable RoomTakedownProtection

Ohne diese Aktivierung bleibt das Modul inaktiv und prüft keine Aktionen.
BlockInvitationsOnServerProtection sorgt dafür, dass Einladungen von gebannten Servern automatisch blockiert werden.
RoomTakedownProtection verhindert, dass Benutzer von blockierten Servern neue Räume betreten oder erstellen können.

Erst wenn beide Protections eingeschaltet sind, wird der zusätzliche Schutz durch das synapse-http-antispam-Modul auf deinem Homeserver wirksam.

Wenn ein geblockter Benutzer nun versucht eine Chatanfrage zu stellen, kann man dies auch ganz gut in den Logs sehen:

🔒 Weitere nützliche Protections und Empfehlungen

Hier ein paar weitere Protections, die du aktivieren kannst:

Name	Beschreibung	Empfehlung
WordListProtection	Bannt neue Nutzer bei bösen Wörtern	✅ Sofort aktivieren
BasicFloodingProtection	Bannt bei zu vielen Nachrichten in kurzer Zeit	⚠️ Verbuggt – nur testen, nicht produktiv
FirstMessageIsImageProtection	Bannt, wenn erste Nachricht ein Bild oder Video ist	✅ Sehr hilfreich gegen Spam
JoinWaveShortCircuitProtection	Schützt bei Mass-Join durch Setzen auf Invite-only	✅ Sinnvoll bei öffentlichen Räumen
MentionLimitProtection	Entfernt Nachrichten mit zu vielen @Mentions	✅ Gut für große Communitys
MessageIsMediaProtection	Entfernt Bild-/Video-Spam, aber ohne Bann	✅ Gute Ergänzung
MessageIsVoiceProtection	Entfernt Sprachnachrichten automatisch	🔹 Optional – je nach Raumkultur
NewJoinerProtection	Bannt alle neuen Nutzer von bestimmten Homeservern	⚠️ Sehr aggressiv, mit Vorsicht nutzen
TrustedReporters	Zählt Reports von „trusted“ Usern → automatische Aktionen	🔮 Für Teams mit festen Moderatoren
MemberBanSynchronisationProtection	Synchronisiert Bans aus beobachteten Policy-Listen automatisch (siehe oben)	✅ Essenziell für Ban-Automatisierung

Diese Liste stellt eine Auswahl von Moderationsfunktionen dar, die du in Draupnir gezielt aktivieren kannst, um dein Setup weiter abzusichern. Jede dieser sogenannten Protections beobachtet ein spezifisches Verhalten im Raum und reagiert automatisch darauf – etwa mit einem Bann, einer Nachricht oder einer anderen Aktion.

!draupnir protections enable <PolicyName>
!draupnir protections disable <PolicyName>

Je nach Art deiner Community, der Offenheit deiner Räume und der Anzahl der Nutzer solltest du individuell entscheiden, welche dieser Protections sinnvoll sind. Besonders für öffentliche oder semi-öffentliche Räume, in denen du mit Trollen, Spammern oder Bot-Wellen rechnen musst, sind einige dieser Funktionen echte Gamechanger.

👉 Tipp:
Du kannst jederzeit prüfen, welche Protections aktiv sind, indem du im Managementraum folgendes eingibst:

!draupnir protections

In der Ausgabe siehst du dann eine Liste aller verfügbaren Protections sowie deren aktuellen Status („enabled“ oder „disabled“).

🔧 Weitere nützliche Befehle

Hier findest du eine praktische Kurzübersicht häufig verwendeter Befehle, mit denen du Draupnir direkt über deinen Management-Raum steuern kannst. Die Tabelle bietet dir eine schnelle Orientierung, wie du Status abrufst, Protections aktivierst oder Policy-Räume verwaltest:

Befehl	Funktion
!draupnir status	Zeigt den aktuellen Status des Bots und der geschützten Räume
!draupnir list protected	Zeigt alle aktuell geschützten Räume
!draupnir watch <room>	Aktiviert eine Policy-Liste und schützt Räume gemäß der Regeln
!draupnir unwatch <room>	Deaktiviert eine Policy-Liste
!draupnir protect <room>	Fügt einen Raum manuell zum Schutz hinzu
!draupnir unprotect <room>	Entfernt einen Raum aus der Schutzliste
!draupnir protections	Listet alle verfügbaren Schutzmechanismen
!draupnir ban <entity> <list> <reason>	Bannt einen Nutzer, Server oder Raum und fügt ihn der Policy-Liste hinzu
!draupnir unban <entity>	Entfernt einen Nutzer/Server/Raum aus der Bannliste
!draupnir kick <user>	Entfernt einen Nutzer aus einem Raum (auch mit --room, --glob, --dry-run)
!draupnir redact <entity>	Löscht Nachrichten eines Nutzers (auch mit Limit oder raumspezifisch möglich)
!draupnir shutdown room <room>	Schließt einen Raum und informiert alle Teilnehmer über die Sperrung
!draupnir rules	Zeigt alle aktiven Bann-/Policy-Regeln
!draupnir rooms	Listet alle geschützten Räume
!draupnir rooms add <room>	Fügt einen Raum zum Schutzsystem hinzu
!draupnir rooms remove <room>	Entfernt einen Raum aus dem Schutzsystem
!draupnir list create <shortcode> <alias>	Erstellt eine neue Policy-Liste mit Raum-Alias
!draupnir safe mode	Versetzt den Bot in den Safe-Mode
!draupnir help	Zeigt eine Hilfe zu Befehlen

🚩 Fazit

Mit diesem Setup hast du eine solide Grundlage, um deine Matrix-Räume automatisiert und effektiv zu moderieren. Draupnir ist mächtig, aber auch ein komplexes Werkzeug – nimm dir die Zeit, dich mit den Policy-Optionen und Protection-Mechanismen vertraut zu machen. Dieser Quick Start bringt dich auf jeden Fall direkt ins Geschehen.

👥 Techniverse Community

Matrix, Selfhosting, smarte IT-Lösungen und jede Menge Nerd-Talk – das findest du in der Techniverse Community.
Komm vorbei, tausch dich aus und werde ein Teil von uns.
👉 Unsere Gruppe auf Matrix: #community:techniverse.net
Wir freuen uns auf dich!