Rspamd modules

Rspamd ships with a set of modules. Some modules are written in C to speedup complex procedures while others are written in lua to reduce code size. Actually, new modules are encouraged to be written in lua and add the essential support to the Lua API itself. Truly speaking, lua modules are very close to C modules in terms of performance. However, lua modules can be written and loaded dynamically.

C Modules

C modules provides core functionality of rspamd and are actually statically linked to the main rspamd code. C modules are defined in the options section of rspamd configuration. If no filters attribute is defined then all modules are disabled. The default configuration enables all modules explicitly:

filters = "chartable,dkim,spf,surbl,regexp,fuzzy_check";

Here is the list of C modules available:

  • chartable: checks character sets of text parts in messages.
  • dkim: performs DKIM signatures checks.
  • fuzzy_check: checks messages fuzzy hashes against public blacklists.
  • spf: checks SPF records for messages processed.
  • surbl: this module extracts URLs from messages and check them against public DNS black lists to filter messages with malicious URLs.
  • regexp: the core module that allow to define regexp rules, rspamd internal functions and lua rules.

Lua modules

Lua modules are dynamically loaded on rspamd startup and are reloaded on rspamd reconfiguration. Should you want to write a lua module consult with the Lua API documentation. To define path to lua modules there is a special section named modules in rspamd:

modules {
  path = "/path/to/dir/";
  path = "/path/to/module.lua";
  path = "$PLUGINSDIR/lua";
}

If a path is a directory then rspamd scans it for `*.lua” pattern and load all files matched.

The following Lua modules are enabled in the default configuration (but may require additional configuration to work, see notes below):

  • antivirus - integrates virus scanners (requires configuration)
  • arc - checks and signs ARC signatures
  • asn - looks up ASN-related information
  • clickhouse - pushes scan-related information to clickhouse DBMS (requires configuration)
  • dcc - performs DCC lookups to determine message bulkiness (requires configuration)
  • dkim_signing - adds DKIM signatures to messages (requires configuration)
  • dmarc - performs DMARC policy checks (requires Redis & configuration for reporting)
  • emails - extract emails from a message and checks it against DNS blacklists. (requires configuration)
  • force_actions - forces actions if selected symbols are detected (requires configuration)
  • greylisting - allows to delay suspicious messages (requires Redis)
  • history redis - stores history in Redis (requires Redis)
  • ip_score - dynamically scores sender reputation (requires Redis)
  • maillist - determines the common mailing list signatures in a message.
  • metadata_exporter - pushes message metadata to external systems (requires configuration)
  • metric_exporter - pushes statistics to external monitoring systems (requires configuration)
  • mid - selectively suppresses invalid/missing message-id rules
  • milter_headers - adds/removes headers from messages (requires configuration)
  • mime_types - applies some rules about mime types met in messages
  • multimap - a complex module that operates with different types of maps.
  • neural networks - allows to post-process messages using neural network classification. (requires Redis configuration and log_helper worker setup for activation).
  • once_received - detects messages with a single Received headers and performs some additional checks for such messages.
  • phishing - detects messages with phished URLs.
  • ratelimit - implements leaked bucket algorithm for ratelimiting (requires Redis & configuration)
  • replies - checks if an incoming message is a reply for our own message (requires Redis)
  • rbl - a plugin that checks sending IP addresses or information from Received headers against DNS blacklists.
  • rspamd_update - load dynamic rules and other rspamd updates (requires configuration)
  • spamassassin - load spamassassin rules (requires configuration)
  • trie - uses suffix trie for extra-fast patterns lookup in messages. (requires configuration)
  • whitelist - provides a flexible way to whitelist (or blacklist) messages based on SPF/DKIM/DMARC combinations
  • url_redirector - dereferences redirects (requires Redis and SURBL module configuration)

The following modules are explicitly disabled in the default configuration, set enabled = true in /etc/rspamd/local.d/${MODULE_NAME}.conf to enable them:

  • mx_check - checks if sending domain has a connectable MX (requires Redis)
  • url_reputation - assigns reputation to domains in URLs (requires Redis)
  • url_tags - persists URL tags in Redis (requires Redis)

Disabling module

To disable an entire module you can set enabled = false; in /etc/rspamd/local.d/${MODULE_NAME}.conf