[![CI Tests][ci-img]][ci-url]
[![Code Climate][clim-img]][clim-url]

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 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
!friend@aol.com

$3

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)).

$3

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

$3

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

``js 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`

`$3`

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

`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:

`ini [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`

`$3`

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)

`$3`

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

`$3`

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

`NOTES`

`$3`

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.

`$3`

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.

$3

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_.

[ci-img]: https://github.com/haraka/haraka-plugin-access/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/haraka/haraka-plugin-access/actions/workflows/ci.yml
[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-access/badges/gpa.svg
[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-access

[![CI Tests][ci-img]][ci-url]
[![Code Climate][clim-img]][clim-url]

haraka-plugin-access - ACLs

ANY

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 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

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
!friend@aol.com

$3

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.

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

$3

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

``js 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`

`$3`

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

`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:

`ini [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`

`$3`

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)

`$3`

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

`$3`

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

`NOTES`

`$3`

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.

`$3`

$3

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