50f80f2392
Mjolnir can now be run as an application service, meaning it will host multiple independent mjolnirs that can be requested by users. If the user is on the same homeserver as the appservice is deployed on, then they can provision a mjolnir via a widget https://github.com/matrix-org/mjolnir-widget. Otherwise they can invite the appservice bot to a room they want to protect. This will create them a mjolnir, a management room and a policy list. The appservice shares the same docker image as the bot, but is started slightly differently by specifying "appservice" as the first argument to docker run (this s managed by `mjolnir-entrypoint.sh`. We could have used another Dockerfile for the appservice, extending the existing one but we decided not to because there would have been lots of fiddling around the entrypoint and logistics involved around adding a tag for it via github actions. Not to mention that this would be duplicating the image just to run it with a different binary. A list of followup issues can be found here https://github.com/issues?q=is%3Aopen+is%3Aissue+author%3AGnuxie+archived%3Afalse+label%3AA-Appservice. Somewhat relevant and squashed commit messages(regrettably squashing because frankly these won't make sense in isolation): * draft widget backend * add `managementRoomId` to `provisionNewMjolnir` * remove ratelimits from appservice mjolnirs * add /join endpoint to api backend * tighter guard around room type in PolicyList matrix-bot-sdk imporved the types for this * enable esModuleInterop * launch and use postgres in a container whilst using mx-tester * limited access control policy list used for access control * Redesign initialization API of many mjolnir. It's much harder to forget to initialize the components now that you have to in order to construct them in the first place. * Ammend config not to clash with existing CI this means that the appsrvice bot is now called 'mjolnir-bot' by default which was easier than going through old code base and renaming * Change entrypoint in Dockerfile so that we can start the appservice. We could have used another Dockerfile for the appservice, extending the exising one but we decided not to because there would have been lots of fiddling around the entrypoint and logistics involved around adding a tag for it via github actions. Not to mention that this would be duplicating the image just to run it with a different binary. This solution is much simpler, backwards compatible, and conscious about the future. Co-authored-by: gnuxie <gnuxie@element.io> |
||
|---|---|---|
| .github/workflows | ||
| config | ||
| docs | ||
| src | ||
| synapse_antispam | ||
| test | ||
| .dockerignore | ||
| .gitignore | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| LICENSE | ||
| mjolnir-entrypoint.sh | ||
| mx-tester.yml | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| tslint.json | ||
| yarn.lock | ||
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:
!mjolnir list create COC code-of-conduct-ban-list- This will create a new ban list with the shortcodeCOCand 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.!mjolnir default COC- This sets the default ban list to the list we just created to help with the ban commands later on.- Review the Moderator's Guide.
- Review
!mjolnir helpto 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:
- In your Mjölnir configuration file, typically
/etc/mjolnir/config/production.yaml, copy and paste thewebsection fromdefault.yaml, if you don't have it yet (it appears with version 1.20) and setenabled: truefor bothwebandabuseReporting. - Setup a reverse proxy that will redirect requests from
^/_matrix/client/(r0|v3)/rooms/([^/]*)/report/(.*)$tohttp://host:port/api/1/report/$2/$3, wherehostis the host where you run Mjölnir, andportis the port you configured inproduction.yaml. For an example nginx configuration, seetest/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:
- If it is used by a member of room foo; AND
- If said member did witness the event; AND
- If the event was unencrypted; AND
- 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.