Whitelist module

Whitelist module is intended to decrease or increase scores for some messages that are known to be from the trusted sources based on DKIM/SPF/DMARC policies (for generic lists please use multimap module).

This module exists because the design flaws in the SMTP protocol make it relatively simple to forge a sender. Consequently, rspamd endeavors to verify the sender's authenticity by considering the following supplementary policies:

• DKIM: a message has a valid DKIM signature for this domain (similar to DMARC alignment but for DKIM only)
• SPF: a message matches SPF record for the domain
• DMARC: a message satisfies domain's DMARC policy (implies aligned SPF or DKIM according to the DMARC standard)

Whitelist setup

Configuring the Whitelist is a simple and straightforward process. Within the rules section, you can define a collection of rules. Each rule must include the domains attribute, which can be defined as either a string representing a map of domains or an array directly listing the domains.

Whitelist constraints

The following constraints are allowed:

• valid_spf: require a valid SPF policy
• valid_dkim: require DKIM validation
• valid_dmarc: require a valid DMARC policy

Whitelist rules modes

Each whitelist rule can work in 3 modes:

• whitelist (default): add symbol when a domain has been found and one of constraints defined is satisfied (e.g. valid_dmarc)
• blacklist: add symbol when a domain has been found and one of constraints defined is NOT satisfied (e.g. valid_dmarc)
• strict: add symbol with negative (ham) score when a domain has been found and one of constraints defined is satisfied (e.g. valid_dmarc) and add symbol with POSITIVE (spam) score when some of constraints defined has failed. When strict = true is set at the rule level, the module internally forces how = both for every map lookup, regardless of the per-entry value prefix (wl:, bl:, or plain multiplier). This means both the ham and the spam branches are always active for all domains in the list.

If no constraints are defined, both the strict and whitelist rules will apply to all emails from the specified domains. For blacklist rules, a positive score is typically assigned to the result.

These options are combined using the AND operator for whitelist rules and the OR operator for blacklist and strict rules. Therefore, if both valid_dkim = true and valid_spf = true are specified, both DKIM and SPF validation are required to whitelist domains from the list. Conversely, for blacklist and strict rules, any violation will result in a positive score symbol being assigned.

Whitelist values

In a map, each whitelist entry can have a value override, allowing you to modify the default rule policy and even adjust the score multiplier. This enables you to create a whitelist for DMARC while specifying certain entries to adhere to a strict policy, which adds a spam symbol in the event of a DMARC policy failure. To achieve this, you can utilize the following values in your map:

example.com # normal whitelist entry: whitelisting on hit, nothing on no hit
bank.com both:1.0 # strict whitelist entry: spam symbol on policy failure and ham symbol on policy success
foo.com both:2.0 # same as previous but with 2.0 multiplier for score
bar.com bl:1.0 # add spam symbol on failure but do not enable ham symbol on success
baz.com wl:2.0 # vice-versa - return to the normal behaviour but with 2.0 multiplier for policy success

You can also check maps shipped with Rspamd in the following repo: https://github.com/rspamd/maps/ Reasonable pull requests are very welcome.

Optional settings

You can also set the default metric settings using the ordinary attributes, such as:

• score: default score
• group: default group (whitelist group is used if not specified explicitly)
• one_shot: default one shot mode
• description: default description
• inverse_symbol: name of a virtual symbol that is registered as a child of the main rule symbol and fired on the violated (blacklist/spam) branch instead of the main symbol. Its default score is set to the negation of the main rule's score. Use this when you want the whitelist hit and the violation hit to appear as separate symbols in the metric.
• inverse_multiplier: a numeric multiplier applied to the score only on the violated branch (i.e., when a policy failure is detected). This is independent of per-entry map multipliers.

In lists, you also have the option to include an optional multiplier argument, which specifies an additional multiplier for the score assigned by this module. For instance, if you want to assign a score twice as large for github.com, you can define it as follows:

["github.com", 2.0]

or if using map:

github.com 2.0

Note with regard to DKIM whitelist

The valid_dkim = true check goes beyond verifying the triggering of just R_DKIM_ALLOW. It also ensures that the DKIM domain being validated matches the domain in the FROM envelope. Therefore, if a message is sent by a sender with the domain x.com but has been DKIM signed by mailchimp.app, the valid_dkim flag will not be set to true, and the whitelist rule will not be triggered

Global options

The following global options can be set for the whitelist module:

Option	Default	Description
check_local	false	Apply the blacklist (violation) branch to messages from local IPs. When false, local senders that trigger an SPF or DMARC blacklist hit are silently skipped; whitelist hits are always applied regardless of this setting. Note: DKIM-only blacklist rules are not subject to this exemption.
check_authed	false	Same as check_local but for authenticated (SMTP AUTH) users.
dmarc_allow_symbol	DMARC_POLICY_ALLOW	Symbol to check for DMARC validation
spf_allow_symbol	R_SPF_ALLOW	Symbol to check for SPF validation
dkim_allow_symbol	R_DKIM_ALLOW	Symbol to check for DKIM validation

Configuration example

whitelist {
    rules {
        WHITELIST_SPF = {
            valid_spf = true;
            domains = [
                "github.com",
            ];
            score = -1.0;
        }

        WHITELIST_DKIM = {
            valid_dkim = true;
            domains = [
                "github.com",
            ];
            score = -2.0;
        }

        WHITELIST_SPF_DKIM = {
            valid_spf = true;
            valid_dkim = true;
            domains = [
                ["github.com", 2.0],
            ];
            score = -3.0;
        }

        STRICT_SPF_DKIM = {
            valid_spf = true;
            valid_dkim = true;
            strict = true;
            domains = [
                ["paypal.com", 2.0],
            ];
            score = -3.0; # For strict rules negative score should be defined
        }

        BLACKLIST_DKIM = {
            valid_spf = true;
            valid_dkim = true;
            blacklist = true;
            domains = "/some/file/blacklist_dkim.map";
            score = 3.0; # Note positive score here
        }

        WHITELIST_DMARC_DKIM = {
            valid_dkim = true;
            valid_dmarc = true;
            domains = [
                "github.com",
            ];
            score = -7.0;
        }
    }
}

Rspamd also provides a collection of pre-defined whitelisted domains that can be beneficial for getting started.