🛡️ Draupnir — Moderation Bot Guide

Quick reference for moderators of this Matrix space.

What is Draupnir?

Draupnir is a Matrix room moderation bot. It monitors protected rooms for policy violations, automates common moderator tasks, and keeps a shared policy list that acts as the single source of truth for who is banned across all rooms. When a user is added to a policy list, the bot enforces the ban in every protected room automatically — moderators only need to act once.

The bot operates from a private management room where it posts alerts, accepts commands, and shows confirmation prompts. Moderators interact with the bot exclusively through that room.

Policy Lists

A policy list is a special Matrix room that stores ban rules (m.policy.rule.user events). Instead of banning a user room-by-room, you add a rule to the policy list and the bot propagates the ban to every protected room.

Adding a user to the policy list → bot bans them in all protected rooms (MemberBanSynchronisation).
Removing a user from the policy list → bot unbans them in all protected rooms.
The !ban and !auto add commands write to the policy list, not directly to rooms.

Note You can watch public community policy lists (e.g. the Matrix.org Community Ban List) with !watch <room>.
Any user listed there will be banned automatically across all your rooms.

Join Alerts (JoinAlertProtection)

When a new user joins any protected room, the bot posts an alert in the management room with the user's MXID, display name, and which room they joined. The alert includes two quick-reaction buttons:

🚫 Ban — bans the user from all protected rooms and adds a policy list entry for permanent exclusion.
✅ Ignore — dismisses the alert without taking action.

No alert shown If the joining user already has a m.ban policy rule in a watched list, no alert is posted.
MemberBanSynchronisation handles the ban automatically and silently.

Space join deduplication

When a user joins a Matrix space, they can quickly join several rooms inside that space. The bot is aware of this: only the space join itself triggers an alert. Subsequent joins to child rooms within the configured time window (default: 5 minutes) are silently suppressed.

If a user joins a non-space protected room directly — without first joining the parent space — the alert fires normally.

Auto-actions

The bot can take action automatically on join, without posting an alert, if the user matches any of the configured rules. Matching users are acted on immediately and the management room receives a notification
(e.g. 🔨 Auto-banned @spam:server — matched pattern: casino|crypto).

Three types of auto-action rules exist:

Regex patterns (!auto add) — tested against both MXID and display name. All patterns are case-insensitive. Plain strings match as substrings anywhere (e.g. casino matches BestCasinoDeals).
MXID local part length (!limit local) — flags users whose MXID local part (before the colon) exceeds the limit. Throwaway accounts often have long numeric IDs.
Display name length (!limit display) — flags users whose display name exceeds the limit. Spammers set long display names because they're shown on room joins.

Ban Propagation

When a moderator manually bans a user from a room using their Matrix client (not through the bot command), BanPropagationProtection detects the room-level ban and automatically adds a ban rule to the configured default policy list. From there, MemberBanSynchronisation enforces the ban across all other protected rooms.

No moderator input is required — the ban propagates fully automatically.

Note Propagation only triggers for bans issued by human moderators. Bans issued by the bot itself (e.g. from !ban or auto-actions) are already policy-backed and do not need to be propagated again.

Kick Propagation

The !kick command kicks the user from every protected room they are currently joined in — not just the room where the command is issued. Kicks are not permanent; the user can rejoin unless a ban is also in place.

Redactions

When a user is banned with the reason ---, RedactionSynchronisationProtection automatically redacts that user's recent messages across all protected rooms. No separate command is needed.

This applies to both manual client bans and the !ban command (which uses --- as its default reason).
Use the !red command to redact without banning.

Commands

Moderation — Quick Actions

Command	Description
`!ban <user>`	Adds a ban rule to the default policy list with reason `---` (which also triggers automatic redactions). Accepts a bare localpart (`alice`) which is expanded to `@alice:matrix.org`, or a full MXID.
`!uban <user>`	Removes all policy rules for a user and unbans them from all protected rooms. No confirmation prompt. Same localpart expansion as `!ban`.
`!kick <user>`	Kicks a user from every protected room they are currently joined in. Same localpart expansion. Does not add a policy rule — the user can rejoin.
`!red <user>`	Redacts all recent messages from a user across all protected rooms without banning them. Same localpart expansion.

Auto-Action Patterns

Command	Description
`!auto`	Lists all currently configured auto-action regex patterns
`!auto add <pattern>`	Adds a regex pattern. Tested case-insensitively against MXID and display name on every join. Example: `!auto add "casino\|crypto"`
`!auto del <pattern>`	Removes an existing pattern. The string must match exactly

Regex tips

Plain strings are substring matches: spam matches anything containing "spam".
Use | for alternatives: casino|viagra|forex.
Match MXID-only patterns with ^@: ^@\d{8,}: matches 8+ digit local parts.
Example for common variations: b[o0]+[o0]+bs matches boobs, b00bs, booooobs, etc.

Whitelist

Whitelisted users bypass all join alerts and auto-action rules entirely. When a whitelisted user joins a protected room, a brief notification is posted in the management room — no Ban/Ignore buttons, no auto-action.

Command	Description
`!white`	List all currently whitelisted users
`!white add <user>`	Add a user to the whitelist. Bare localparts expand to `@localpart:matrix.org` Example: `!white add alice` → `@alice:matrix.org`
`!white del <user>`	Remove a user from the whitelist. Bare localpart expansion applies — `!white del alice` removes `@alice:matrix.org` only, not `@alice:other.server`

Note Whitelisting does not affect policy list rules. If a whitelisted user has a ban policy rule, MemberBanSynchronisation will still enforce the ban. The whitelist only suppresses the management room alert and auto-actions — policy enforcement is handled separately.

Length Limits

Command	Description
`!limit local <n>`	Auto-acts on users whose MXID local part exceeds `n` characters. Set to `0` to disable. Example: `!limit local 20`
`!limit display <n>`	Auto-acts on users whose display name exceeds `n` characters. Set to `0` to disable. Example: `!limit display 30`

Rooms

Command	Description
`!rooms`	Lists all rooms currently under bot protection
`!rooms clear-bans <room>`	Shows a preview of all room-level bans in the specified room with a count, then asks for ✅ OK / ❌ Cancel confirmation before removing them. Does not affect policy list rules.
`!rooms clear-bans everything`	Same as above but processes all protected rooms at once. Rooms where the bot lacks permission are listed as skipped.

Rules & Protections

Command	Description
`!rules`	Lists all active policy rules across all watched policy lists
`!protections`	Lists all available protections and whether each is enabled or disabled
`!protections show <name>`	Shows current configuration and capability settings for a specific protection. Example: `!protections show JoinAlertProtection`

Protection Configuration

Ban vs. Kick mode

By default, both manual reaction buttons and auto-actions issue bans. To switch to kicks (lighter-touch, user can rejoin):

!protections config set JoinAlertProtection kickInsteadOfBan true

To switch back to bans:

!protections config set JoinAlertProtection kickInsteadOfBan false

Warning In kick mode, no policy rule is written and the action does not propagate to other rooms.
Use ban mode for persistent, space-wide exclusion.

Space deduplication window

Controls how long (in seconds) after a user joins a space during which joins to child rooms are suppressed. Default is 300 seconds (5 minutes).

!protections config set JoinAlertProtection spaceDedupWindowSeconds 300

Increase this if users are seeing duplicate alerts for the same person joining many rooms in a large space.

Full Command Reference

The short commands above are aliases. The full equivalents are listed here for reference — they are not typically needed but may be useful for advanced configuration or scripting.

Short command	Full equivalent
`!ban <user>`	`!bans <@user:server> <list> <reason>`
`!uban <user>`	`!unban <@user:server> --no-confirm`
`!kick <user>`	`!kicks <@user:server>`
`!red <user>`	`!redact <@user:server>`
`!auto add pattern`	`!protections config add JoinAlertProtection autoActionPatterns "pattern"`
`!auto del pattern`	`!protections config remove JoinAlertProtection autoActionPatterns "pattern"`
`!limit local <n>`	`!protections config set JoinAlertProtection maxMxidLocalpartLength <n>`
`!limit display <n>`	`!protections config set JoinAlertProtection maxDisplayNameLength <n>`
`!white add` / `!white del`	`!protections config [add\|remove] JoinAlertProtection whitelistedUsers <@user:server>`

Other Useful Commands

Command	Description
`!info`	A short version of this guide
`!watch <room>`	Start watching a policy list room. All users listed there will be banned automatically.
`!unwatch <room>`	Stop watching a policy list room
`!rooms add <room>`	Add a room to the bot's protected set
`!rooms remove <room>`	Remove a room from the bot's protected set
`!rules matching <user>`	Show which policy rules match a given user, room, or server
`!status`	Show the bot's current status, connected rooms, and policy lists
`!help`	List all available commands

Based on Draupnir v3.0.0 with custom protections and shortcut commands.