A moderation tool for Matrix
Go to file
2021-04-21 11:42:19 +02:00
config Add confirmation for wildcard bans 2021-02-05 16:09:11 +00:00
docs Update moderators.md 2020-09-12 23:55:21 -06:00
src Improve force handling 2021-02-05 17:03:36 +00:00
synapse_antispam Add a flag for disabling checking of usernames for spam. 2020-02-13 13:08:09 -05:00
test/commands Improve force handling 2021-02-05 17:03:36 +00:00
.dockerignore Absolute bare minimum for a bot 2019-09-25 20:13:20 -06:00
.gitignore Add an API to filter user directory searches by MXID or display name. 2020-02-11 10:10:27 -05:00
CONTRIBUTING.md Steal contributing guidelines from Synapse 2020-02-13 14:01:42 -07:00
Dockerfile Use yarn in the docker image too 2019-10-31 10:55:44 -06:00
dsl.ts DSL: Let's get back to a DSL in which we send rules through Matrix, instead of a JSON server. 2021-04-21 11:42:19 +02:00
LICENSE Initial commit 2019-09-25 19:36:12 -06:00
package.json FIXUP 2021-04-14 15:01:42 +02:00
README.md Clarify potentially confusing wording in the readme 2020-09-12 23:54:11 -06:00
tsconfig.json Make the [un]ban command smarter 2019-11-13 21:38:19 -07:00
tslint.json Fix tlsint 2019-09-27 13:54:34 -06:00
yarn.lock Bumping dependency y18n 2021-04-14 11:06:52 +02:00

mjolnir

A moderation tool for Matrix. Visit #mjolnir:matrix.org for more information.

Features

As an all-in-one moderation tool, it can protect your server from malicious invites, spam messages, and whatever else you don't want. In addition to server-level protection, Mjolnir is great for communities wanting to protect their rooms without having to use their personal accounts for moderation.

The bot by default includes support for bans, redactions, anti-spam, server ACLs, room directory changes, room alias transfers, account deactivation, room shutdown, and more.

A Synapse module is also available to apply the same rulesets the bot uses across an entire homeserver.

Bot configuration

It is recommended to use Pantalaimon so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.

If you aren't using encrypted rooms anywhere, get an access token by opening Riot in an incognito/private window and log in as the bot. From the Help & Support tab in settings there is an access token field - copy and paste that into your config. Most importantly: do not log out and instead just close the window. Logging out will make the token you just copied useless.

Note: Mjolnir expects to be free of rate limiting - see Synapse #6286 for information on how to achieve this.

Note: To deactivate users, move aliases, shutdown rooms, etc Mjolnir will need to be a server admin.

Docker installation (preferred)

Mjolnir is on Docker Hub as matrixdotorg/mjolnir but can be built yourself with docker build -t mjolnir ..

git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir

# Copy and edit the config. It is not recommended to change the data path.
mkdir -p /etc/mjolnir/config
cp config/default.yaml /etc/mjolnir/config/production.yaml
nano /etc/mjolnir/config/production.yaml

docker run --rm -it -v /etc/mjolnir:/data matrixdotorg/mjolnir:latest

Build it (alternative installation)

This bot requires yarn and Node 10.

git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir

yarn install
yarn build

# Copy and edit the config. It *is* recommended to change the data path.
cp config/default.yaml config/development.yaml
nano config/development.yaml

node lib/index.js

Quickstart guide

After your bot is up and running, you'll want to run a couple commands to get everything set up:

  1. !mjolnir list create COC code-of-conduct-ban-list - This will create a new ban list with the shortcode COC and an alias of #code-of-conduct-ban-list:example.org. You will be invited to the room it creates automatically where you can change settings such as the visibility of the room.
  2. !mjolnir default COC - This sets the default ban list to the list we just created to help with the ban commands later on.
  3. Review the Moderator's Guide.
  4. Review !mjolnir help to see what else the bot can do.

Synapse Module

Using the bot to manage your rooms is great, however if you want to use your ban lists (or someone else's) on your server to affect all of your users then a Synapse module is needed. Primarily meant to block invites from undesired homeservers/users, Mjolnir's Synapse module is a way to interpret ban lists and apply them to your entire homeserver.

First, install the module to your Synapse python environment:

pip install -e "git+https://github.com/matrix-org/mjolnir.git#egg=mjolnir&subdirectory=synapse_antispam"

Note: Where your python environment is depends on your installation method. Visit #synapse:matrix.org if you're not sure.

Then add the following to your homeserver.yaml:

spam_checker:
  module: mjolnir.AntiSpam
  config:
    # Prevent servers/users in the ban lists from inviting users on this
    # server to rooms. Default true.
    block_invites: true
    # Flag messages sent by servers/users in the ban lists as spam. Currently
    # this means that spammy messages will appear as empty to users. Default
    # false.
    block_messages: false
    # Remove users from the user directory search by filtering matrix IDs and
    # display names by the entries in the user ban list. Default false.
    block_usernames: false
    # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,
    # this list cannot be room aliases or permalinks. This server is expected
    # to already be joined to the room - Mjolnir will not automatically join
    # these rooms.
    ban_lists:
      - "!roomid:example.org"

Note: Although this is described as a "spam checker", it does much more than fight spam.

Be sure to change the configuration to match your setup. Your server is expected to already be participating in the ban lists - if it is not, you will need to have a user on your homeserver join. The antispam module will not join the rooms for you.

If you change the configuration, you will need to restart Synapse. You'll also need to restart Synapse to install the plugin.

Development

TODO. It's a TypeScript project with a linter.