• Stars
    star
    325
  • Rank 129,350 (Top 3 %)
  • Language
    TypeScript
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated 26 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A moderation tool for Matrix

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.

Setting up

See the setup documentation for first-time setup documentation.

See the configuration sample with documentation for detailed information about Mjolnir's configuration.

See the synapse module documentation for information on how to setup Mjolnir's accompanying Synapse Module.

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.

Enabling readable abuse reports

Since version 1.2, Mjölnir offers the ability to replace the Matrix endpoint used to report abuse and display it into a room, instead of requiring you to request this data from an admin API.

This requires two configuration steps:

  1. In your Mjölnir configuration file, typically /etc/mjolnir/config/production.yaml, copy and paste the web section from default.yaml, if you don't have it yet (it appears with version 1.20) and set enabled: true for both web and abuseReporting.
  2. Setup a reverse proxy that will redirect requests from ^/_matrix/client/(r0|v3)/rooms/([^/]*)/report/(.*)$ to http://host:port/api/1/report/$2/$3, where host is the host where you run Mjölnir, and port is the port you configured in production.yaml. For an example nginx configuration, see test/nginx.conf. It's the confirmation we use during runtime testing.

Security note

This mechanism can extract some information from unencrypted rooms. We have taken precautions to ensure that this cannot be abused: the only case in which this feature will publish information from room foo is:

  1. If it is used by a member of room foo; AND
  2. If said member did witness the event; AND
  3. If the event was unencrypted; AND
  4. If the event was not redacted/removed/...

Essentially, this is a more restricted variant of the Admin APIs available on homeservers.

However, if you are uncomfortable with this, please do not activate this feature. Also, you should probably setup your production.yaml to ensure that the web server can only receive requests from your reverse proxy (e.g. localhost).

Development

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

Development and testing with mx-tester

WARNING: mx-tester is currently work in progress, but it can still save you some time and is better than struggling with nothing.

If you have docker installed you can quickly get setup with a development environment by using mx-tester.

To use mx-tester you will need to have rust installed. You can do that at rustup or here, you should probably also check your distro's documentation first to see if they have specific instructions for installing rust.

Once rust is installed you can install mx-tester like so.

$ cargo install mx-tester

Once you have mx-tester installed you we will want to build a synapse image with synapse_antispam from the Mjolnir project root.

$ mx-tester build

Then we can start a container that uses that image and the config in mx-tester.yml.

$ mx-tester up

Once you have called mx-tester up you can run the integration tests.

$ yarn test:integration

After calling mx-tester up, if we want to play with mojlnir locally we can run the following and then point a matrix client to http://localhost:9999. You should then be able to join the management room at #moderators:localhost:9999.

yarn test:manual

Once we are finished developing we can stop the synapse container.

mx-tester down

Running integration tests

The integration tests can be run with yarn test:integration. The config that the tests use is in config/harness.yaml and by default this is configured to work with the server specified in mx-tester.yml, but you can configure it however you like to run against your own setup.

More Repositories

1

synapse

Synapse: Matrix homeserver written in Python/Twisted.
Python
11,791
star
2

dendrite

Dendrite is a second-generation Matrix homeserver written in Go!
Go
4,696
star
3

matrix-js-sdk

Matrix Client-Server SDK for JavaScript
TypeScript
1,505
star
4

matrix-rust-sdk

Matrix Client-Server SDK for Rust
Rust
1,151
star
5

matrix-react-sdk

Matrix SDK for React Javascript
TypeScript
1,095
star
6

matrix-spec-proposals

Proposals for changes to the matrix specification
889
star
7

matrix-appservice-discord

A bridge between Matrix and Discord.
TypeScript
803
star
8

matrix.to

A simple stateless privacy-protecting URL redirecting service for Matrix
JavaScript
766
star
9

thirdroom

Open, decentralised, immersive worlds built on Matrix
C
599
star
10

matrix-appservice-irc

Node.js IRC bridge for Matrix
TypeScript
457
star
11

matrix-ios-sdk

The Matrix SDK for iOS
Objective-C
433
star
12

pinecone

Peer-to-peer overlay routing for the Matrix ecosystem
Go
428
star
13

matrix.org

matrix.org public website
JavaScript
413
star
14

matrix-android-sdk

The Matrix SDK for Android - DEPRECATED
Java
376
star
15

go-neb

Extensible matrix bot written in Go
Go
281
star
16

pantalaimon

E2EE aware proxy daemon for matrix clients.
Python
279
star
17

matrix-appservice-slack

A Matrix <--> Slack bridge
TypeScript
271
star
18

gomatrix

A Golang Matrix client
Go
269
star
19

sydent

Sydent: Reference Matrix Identity Server
Python
259
star
20

matrix-python-sdk

Matrix Client-Server SDK for Python 2 and 3
Python
256
star
21

sliding-sync

Proxy implementation of MSC3575's sync protocol.
Go
250
star
22

purple-matrix

Libpurple protocol plugin for matrix
C
224
star
23

matrix-ircd

An IRCd implementation backed by Matrix.
Rust
224
star
24

matrix-android-sdk2

Matrix SDK for Android, extracted from the Element Android application
Kotlin
189
star
25

matrix-spec

The Matrix protocol specification
HTML
188
star
26

matrix-hookshot

A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.
TypeScript
185
star
27

vodozemac

An implementation of Olm and Megolm in pure Rust.
Rust
171
star
28

matrix-bifrost

General purpose bridging with a variety of backends including libpurple and xmpp.js
TypeScript
162
star
29

rust-synapse-compress-state

A tool to compress some state in a Synapse instance's database
Rust
147
star
30

matrix-appservice-bridge

Bridging infrastructure for Application Services
TypeScript
141
star
31

matrix-ios-kit

Reusable UI interfaces to ease building of Matrix client apps
Objective-C
128
star
32

sygnal

Sygnal: reference Push Gateway for Matrix
Python
128
star
33

matrix-authentication-service

OAuth2.0 + OpenID Provider for Matrix Homeservers
Rust
111
star
34

matrix-synapse-ldap3

An LDAP3 auth provider for Synapse
Python
107
star
35

cerulean

An experimental Matrix client for playing with freestyle public threaded conversations
JavaScript
103
star
36

waterfall

A cascading stream forwarding unit for scalable, distributed voice and video conferencing over Matrix
Go
98
star
37

synapse-s3-storage-provider

Synapse storage provider to fetch and store media in Amazon S3
Python
92
star
38

matrix-rich-text-editor

Matrix Rich Text Editor
Rust
92
star
39

meshsim

Matrix mesh simulator
Python
90
star
40

matrix-static

A static golang generated preview of public world readable Matrix rooms.
Go
87
star
41

seshat

A Matrix message database/indexer
Rust
86
star
42

matrix-viewer

View the history of public and world readable Matrix rooms
JavaScript
74
star
43

matrix-appservice-node

Matrix Application Service framework in Node.js
TypeScript
71
star
44

sytest

Black-box integration testing for Matrix homeservers
Perl
66
star
45

matrix-federation-tester

Tester for matrix federation written in golang.
Go
61
star
46

complement

Matrix compliance test suite
Go
61
star
47

docker-jitsi

Docker files for building images and running jitsi-meet in Docker containers
Lua
58
star
48

matrix-widget-api

JavaScript/TypeScript API for widgets & web clients to communicate
TypeScript
57
star
49

gomatrixserverlib

Go library for matrix federation.
Go
56
star
50

olm

An implementation of the Double Ratchet cryptographic ratchet in C++/C
54
star
51

Matrix-NEB

N E Bot: Generic bot for Matrix with plugin support
Python
49
star
52

rust-opa-wasm

Open Policy Agent WebAssembly Rust SDK
Rust
46
star
53

naffka

Single in-process implementation of the sarama golang kafka APIs
Go
45
star
54

matrix-ios-console

The sample Matrix client for iOS
Objective-C
45
star
55

conference-bot

The conductor for your orchestra^Wconference
TypeScript
44
star
56

gsoc

JavaScript
43
star
57

matrix-appservice-gitter

Matrix <-> Gitter bridge
JavaScript
40
star
58

coap-proxy

HTTP<->CoAP proxy
Go
39
star
59

matrix-appservice-tg

Matrix<->Telegram user-puppeting portal
JavaScript
37
star
60

dendron

Dendron was an experimental Matrix homeserver, succeeded by Dendrite.
Go
35
star
61

matrix-vr-demo

Matrix.org Virtual Reality Demo
JavaScript
31
star
62

python-canonicaljson

Canonical JSON
Python
31
star
63

bullettime

An experimental golang Matrix homeserver
Go
31
star
64

matrix-angular-sdk

JavaScript
28
star
65

matrix-rust-components-swift

Swift package providing components from the matrix-rust-sdk
Swift
27
star
66

rageshake

Bug report server
Go
27
star
67

matrix-android-console

Java
26
star
68

matrix-android-sdk2-sample

Example project for using the android sdk
Kotlin
26
star
69

fed-tester-ui

UI for the matrix federation tester (forked from https://git.lain.haus/f0x/fed-tester)
JavaScript
26
star
70

lb

MSC3079 Low Bandwidth library for servers and clients
Go
25
star
71

prosody-mod-auth-matrix-user-verification

Matrix user verification auth for Prosody
Lua
24
star
72

voip-tester

Tests VoIP
JavaScript
23
star
73

thirdroom-unity-exporter

C#
23
star
74

matrix-user-verification-service

Service to verify details of a user based on a Open ID token.
JavaScript
23
star
75

matrix-search

A generic search engine daemon
Go
22
star
76

tardis

Time Agnostic Room DAG Inspection Service
JavaScript
21
star
77

synapse-auto-accept-invite

Synapse module to automatically accept invites
Python
18
star
78

libp2p-proxy

A p2p transport shim for p2p matrix.
Go
18
star
79

patience

Full stack integration testing for Matrix clients and servers
TypeScript
18
star
80

matrix-sentry-webhooks

Sentry webhooks integration bot for Matrix.
JavaScript
17
star
81

matrix-appservice-verto

A Matrix <--> Verto bridge, designed for conferencing
JavaScript
16
star
82

go-sqlite3-js

Go SQL driver for sqlite3 in browser (sql.js) from go-wasm
Go
15
star
83

matrix-appservice-rocketchat

JavaScript
15
star
84

matrix-content-scanner

[DEPRECATED] A web service for scanning media hosted by a Matrix media repository. Replaced by https://github.com/vector-im/matrix-content-scanner-python
JavaScript
13
star
85

synapse-user-restrictions

This module allows restricting users from performing actions such as creating rooms or sending invites.
Python
13
star
86

docker-dehydrated

A docker image we use internally for managing certificates.
Shell
13
star
87

matrix-rust-components-kotlin

Kotlin
12
star
88

matrix-rust-sdk-crypto-wasm

Rust
12
star
89

matrix-websockets-proxy

Websockets wrapper for matrix.org homeservers
Go
12
star
90

panopticon

panopticon records usage metrics from homeservers
Go
11
star
91

matrix-files-sdk

JS/TS SDK for working with files and folders in Matrix
TypeScript
11
star
92

remember-this-rs

A simple Rust crate to cache data both in-memory and on disk
Rust
11
star
93

complement-crypto

Go
10
star
94

allchange

A multi-project changelog generator
TypeScript
10
star
95

python-unpaddedbase64

Unpadded Base64
Python
10
star
96

synapse-email-account-validity

Account validity plugin for Synapse using email
Python
10
star
97

matrixmon

A small end-to-end prober and Prometheus stats exporter for a Matrix homeserver
Perl
10
star
98

matrix-synapse-saml-mozilla

Mozilla flavour of a Synapse SAML mapping provider
Python
9
star
99

vodozemac-bindings

Language bindings for vodozemac
Rust
9
star
100

synapse-config-generator

A web based synapse config generator
JavaScript
9
star