haraka-plugin-headers

This plugin performs a variety of mail header inspections.

INSTALL

cd /path/to/local/haraka
npm install haraka-plugin-headers
echo "headers" >> config/plugins
service haraka restart

Configuration

If the default configuration is not sufficient, copy the config file from the distribution into your haraka config dir and then modify it:

cp node_modules/haraka-plugin-headers/config/headers.ini config/headers.ini
$EDITOR config/headers.ini

RFC 5322 Section 3.6:

All messages MUST have a 'Date' and 'From' header and a message may not contain more than one 'Date', 'From', 'Sender', 'Reply-To', 'To', 'Cc', 'Bcc', 'Message-Id', 'In-Reply-To', 'References' or 'Subject' header.

The next two tests encompass the RFC 5322 checks:

duplicate_singular

Assure that all the singular headers are present only once. The list of headers can be adjusted in config/headers.ini:

* singular=Date,From,Sender,Reply-To,To,Cc,Bcc,Message-Id,In-Reply-To,References,Subject

missing_required

Assuring that all the required headers are present. The list of required headers can be altered in config/headers.ini:

required=From,Date

invalid_return_path

Messages arriving via the internet should not have a Return-Path header set. This checks for that header (unless connection.relaying is set).

invalid_date

Checks the date header and makes sure it's somewhat sane. By default, the date cannot be more than 2 days in the future nor 15 days in the past. These can be adjusted in config/headers.ini:

date_future_days=2
date_past_days=15

user_agent

Attempt to determine the User-Agent that generated the email. A UA is determinable on about 70% of hammy messages.

direct_to_mx

Counts the received headers. If there aren't at least two, then the MUA is attempting direct delivery to us instead of via their outbound SMTP server. This is typical of spam, our own users sending outbound email (which bypasses this test), and machine generated messages like Facebook/Twitter notifications.

from_match

See if the header From domain matches the envelope FROM domain. There are many legit reasons to not match, but matching domains are far more frequent in ham.

mailing_list

Attempt to determine if this message was sent via an email list. This is very rudimentary at present and only detects the most common email lists.

Forwarders, of which email lists are a special type, constitutes the majority of the minority (~10%) of ham which fails SPF and DKIM tests. This MLM detector is a building block in the ability to detect mail from forwarders and assess their reputability.

from_phish

A common form of phishing is spamming the From display name with the domain name of the popular entity whose accounts they're phishing for. This tests the domains in the [phish_domains] configuration section. If that domains appears in the From header, it must also appear in the envelope sender address.

Configuration

The headers.ini file can contain [check] and [reject] sections.

[check]

To turn on User Agent detection and turn off Mailing List detection: Each key is the test/check name and a boolean value that enables or disables the check.

[check]
duplicate_singular=true
missing_required=true
invalid_return_path=true
invalid_date=true
user_agent=true
direct_to_mx=true
from_match=true
mailing_list=true

[reject]

Turning off reject for a check lets it be enabled (for data collection) without interrupting mail flow. To prevent a missing header from causing messages to be rejected:

[reject]
missing_required=false