diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/markdown/modules/whitelist.md | 63 |
1 files changed, 48 insertions, 15 deletions
diff --git a/doc/markdown/modules/whitelist.md b/doc/markdown/modules/whitelist.md index ec4671e58..5b2417194 100644 --- a/doc/markdown/modules/whitelist.md +++ b/doc/markdown/modules/whitelist.md @@ -1,6 +1,6 @@ # Whitelist module -Whitelist module is intended to negate scores for some messages that are known to +Whitelist module is intended to negate or increase scores for some messages that are known to be from the trusted sources. Due to `SMTP` protocol design flaws, it is quite easy to forge sender. Therefore, rspamd tries to validate sender based on the following additional properties: @@ -14,15 +14,30 @@ properties: Whitelist configuration is quite straightforward. You can define a set of rules within `rules` section. Each rule **must** have `domains` attribute that specifies either map of domains (if specified as a string) or a direct list of domains (if specified as an array). -The following optional parameters are allowed: + +### 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 -These options are combined using `AND` operator, therefore `valid_dkim = true` and +### 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 + +If you do not define any constraints, then all both `strict` and `whitelist` rules just insert result for all mail from the specified domains. For `blacklist` rules the result has normally positive score. + +These options are combined using `AND` operator for `whitelist` and using `OR` for `blacklist` and `strict` rules. Therefore, if `valid_dkim = true` and `valid_spf = true` would require both DKIM and SPF validation to whitelist domains from -the list. +the list. On the contrary, for blacklist and strict rules any violation would cause positive score symbol being inserted. + +### Optional settings You can also set the default metric settings using the ordinary attributes, such as: @@ -50,34 +65,52 @@ whitelist { valid_spf = true; domains = [ "github.com", - ] - score = -1.0 + ]; + score = -1.0; } - + WHITELIST_DKIM = { valid_dkim = true; domains = [ "github.com", - ] - score = -2.0 + ]; + score = -2.0; } - + WHITELIST_SPF_DKIM = { valid_spf = true; valid_dkim = true; domains = [ ["github.com", 2.0], - ] - score = -3.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; # Mention positive score here + } + WHITELIST_DMARC_DKIM = { valid_dkim = true; valid_dmarc = true; domains = [ "github.com", - ] - score = -7.0 + ]; + score = -7.0; } } } |