haraka-plugin-access - ACLs

This plugin applies Access Control Lists during the connect, helo, mail, and rcpt phases of the SMTP conversation. It has a split personality, supporting two somewhat different modes, any -vs- precise.

ANY

The any check is premised on blocking a domain name no matter where in the SMTP conversation it appears. That's possible using several regex lists in the precise checks, but it's also much slower.

With any, just drop the offending domain name into the access.domains file and it gets blocked for the rDNS hostname, the HELO hostname, the MAIL FROM domain name, and the RCPT TO domain name.

The any blacklist matches only on the [Organizational Domain](#Organizational Domain) name (see NOTES below). Entries placed in the access.domains file are automatically reduced to the OD. Examples:

       ENTRY                  O.D.
mail.spam-central.com  -> spam-central.com
mail151.wayn.net       -> wayn.net

In case the O.D. match is too broad, whitelist entries are placed in the same access.domains file with a ! prefix. Whitelist entries can be email addresses (for the MAIL FROM and RCPT TO tests) or hostnames for the rDNS and HELO hostnames. To block anything from example.com but not special.example.com:

example.com
!special.example.com

To block everything (supposedly) from aol.com, except messages from that one person you know that still uses it:

aol.com
[email protected]

ANY results

When a whitelisted email or domain matches, a pass result will be saved with the hook name (ex: connect:any). When a blacklisted email or domain matches, a fail result of the same syntax is stored. If neither match, a msg result is saved (ex: unlisted(connect:any)).

ANY data

In addition to checking for a domain in the envelope, ANY can also check in the message headers as well. Settings 'data=true' in the [checks] section of config/access.ini enables this. At present this only checks the From header.

PRECISE

The precise ACLs share a common file format with each phase having a set of 4 files (whitelist, whitelist_regex, blacklist, and blacklist_regex) which are simple lists.

The ACLs for each phase apply their tests in the order listed. The whitelist is primarily to counter blacklist entries that match too much, so the the flow of control is: if whitelisted, stop processing. Then apply the blacklist.

Entries in ACL files are one per line.

Regex entries are anchored, meaning '^' + regex + '$' are added automatically. To bypass that, use a '.*' at the start or the end of the regex. This should help avoid overly permissive rules.

Usage

To enable the access plugin, add an entry (access) to config/plugins. Then add entries to the config files for the addresses or patterns to block.

Upgrading

When upgrading from the rdns_access, mail_from.access, and rcpt_to.access plugins, be sure to remove the plugins from config/plugins, upon pain of wasted CPU cycles.

There is no need to modify your black/white lists.

If you just want the new plugin to work exactly like the old trio it replaces, add this section to config/access.ini:

[check]
any=false
conn=true
helo=false
mail=true
rcpt=true

Checking ACL results

To check access results from other plugins, use the standard results methods.

const ar = connection.results.get('access');
if (ar.pass.length > 2) {
    // they passed the connection and helo checks
}

const ar = connection.transaction.results.get('access');
if (ar.pass.length > 2) {
    // they passed the mail and rcpt checks
}

To determine which file(s) had matching entries, inspect the contents of the pass/fail elements in the result object.

Config Files

access.ini

Each check can be enabled or disabled in the [check] section of access.ini:

[check]
any=true    (see below)
conn=false
helo=false
mail=false
rcpt=false

[rcpt]
accept=false  (see below)

A custom deny message can be configured for each SMTP phase:

[deny_msg]
conn=You are not allowed to connect
helo=That HELO is not allowed to connect
mail=That sender cannot send mail here
rcpt=That recipient is not allowed

PRECISE ACLs

Connect

The connect ACLs are evaluated against the IP address and the rDNS hostname (if any) of the remote.

• connect.rdns_access.whitelist (pass)
• connect.rdns_access.whitelist_regex (pass)
• connect.rdns_access.blacklist (block)
• connect.rdns_access.blacklist_regex (block)

MAIL FROM

• mail_from.access.whitelist (pass)
• mail_from.access.whitelist_regex (pass)
• mail_from.access.blacklist (block)
• mail_from.access.blacklist_regex (block)

RCPT TO

• rcpt_to.access.whitelist (pass)
• rcpt_to.access.whitelist_regex (pass)
• rcpt_to.access.blacklist (block)
• rcpt_to.access.blacklist_regex (block)

NOTES

ANY performance

I did some performance testing of indexOf -vs- precompiled regex. In a list of 3 items, where the matches were at the front of the list, regex matches are 2x as slow. When the list grows to 30 entries, the regex matches are 3x times as slow. When the matches are moved to the end of the 30 member list, the regex searches are over 100x slower than indexOf.

Based on this observation, reducing the domain name and doing an indexOf search of an (even much longer) blacklist is much faster than adding lists of .*domain.com entries to the *_regex files.

rcpt accept mode

By default this plugin only rejects recipients on the blacklists, and ignores those on the whitelists. Setting rcpt.accept=true enables recipient validation for users in whitelists, actually accepting mails instead of only blocking unwanted recipients.

Organizational Domain

The OD is a term that describes the highest level portion of domain name that is under the control of a private organization. Let's clarify a few terms:

TLD

Top Level Domains. Domain labels at the apex of a domain name.

com
net
org
co
us
uk

Public Suffix

The portion of a domain name that is operated by a registry. These are often synonymous with TLDs but frequently also include second and third level domains as well:

com
co.uk

The Organizational Domain is the next level higher than the Public Suffix. So if a hostname is mail.example.com, and com is the Public Suffix, the OD is example.com. If the hostname is www.bbc.co.uk, the PS is co.uk and the OD is bbc.co.uk.