watcha-synapse/docs/spam_checker.md

Handling spam in Synapse

Synapse has support to customize spam checking behavior. It can plug into a variety of events and affect how they are presented to users on your homeserver.

The spam checking behavior is implemented as a Python class, which must be able to be imported by the running Synapse.

Python spam checker class

The Python class is instantiated with two objects:

• Any configuration (see below).
• An instance of synapse.module_api.ModuleApi.

It then implements methods which return a boolean to alter behavior in Synapse. All the methods must be defined.

There's a generic method for checking every event (check_event_for_spam), as well as some specific methods:

• user_may_invite
• user_may_create_room
• user_may_create_room_alias
• user_may_publish_room
• check_username_for_spam
• check_registration_for_spam
• check_media_file_for_spam

The details of each of these methods (as well as their inputs and outputs) are documented in the synapse.events.spamcheck.SpamChecker class.

The ModuleApi class provides a way for the custom spam checker class to call back into the homeserver internals.

Additionally, a parse_config method is mandatory and receives the plugin config dictionary. After parsing, It must return an object which will be passed to __init__ later.

Example

from synapse.spam_checker_api import RegistrationBehaviour

class ExampleSpamChecker:
    def __init__(self, config, api):
        self.config = config
        self.api = api

    @staticmethod
    def parse_config(config):
        return config
        
    async def check_event_for_spam(self, foo):
        return False  # allow all events

    async def user_may_invite(self, inviter_userid, invitee_userid, room_id):
        return True  # allow all invites

    async def user_may_create_room(self, userid):
        return True  # allow all room creations

    async def user_may_create_room_alias(self, userid, room_alias):
        return True  # allow all room aliases

    async def user_may_publish_room(self, userid, room_id):
        return True  # allow publishing of all rooms

    async def check_username_for_spam(self, user_profile):
        return False  # allow all usernames

    async def check_registration_for_spam(
        self,
        email_threepid,
        username,
        request_info,
        auth_provider_id,
    ):
        return RegistrationBehaviour.ALLOW  # allow all registrations

    async def check_media_file_for_spam(self, file_wrapper, file_info):
        return False  # allow all media

Configuration

Modify the spam_checker section of your homeserver.yaml in the following manner:

Create a list entry with the keys module and config.

• module should point to the fully qualified Python class that implements your custom logic, e.g. my_module.ExampleSpamChecker.

• config is a dictionary that gets passed to the spam checker class.

Example

This section might look like:

spam_checker:
  - module: my_module.ExampleSpamChecker
    config:
      # Enable or disable a specific option in ExampleSpamChecker.
      my_custom_option: true

More spam checkers can be added in tandem by appending more items to the list. An action is blocked when at least one of the configured spam checkers flags it.

Examples

The Mjolnir project is a full fledged example using the Synapse spam checking API, including a bot for dynamic configuration.