Haraka SPF Plugin

1.2.11 · active · verified Sun Apr 19

This package, `haraka-plugin-spf`, implements the Sender Policy Framework (SPF) within the Haraka SMTP server. The current stable version is 1.2.11. It primarily adds `Received-SPF` headers to emails, with robust configurable options to defer or deny mail based on SPF test results, such as `mfrom_fail` for sender validation. While it has seen consistent updates recently, including ES6 refactoring, dependency bumps, and header formatting improvements, it does not adhere to a strict time-based release cadence, focusing instead on bug fixes and enhancements. Its key differentiator is its deep and flexible integration into the Haraka ecosystem, allowing granular control via `spf.ini` for handling various SPF outcomes (none, softfail, fail, permerror) for both HELO and MAIL FROM contexts, and specifically for relayed connections. It also provides a valuable command-line tool for debugging SPF records and validating domain configurations. The plugin allows Haraka operators to enforce SPF policies ranging from mere informational headers to hard rejections, providing essential protection against email spoofing.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'length') OR similar crash related to MX records.
```
cause An issue where the plugin attempted to process DNS MX records that were either missing or malformed, leading to an undefined variable.

fix Upgrade `haraka-plugin-spf` to version 1.2.9 or newer, which contains a fix for crashes in `mech_mx` code when no valid MX records are found.
```
Haraka failed to load plugin: spf (Error: ENOENT: no such file or directory, open '.../haraka/config/spf.ini')
```
cause The `spf.ini` configuration file is either missing from Haraka's `config` directory or is incorrectly named.

fix Create `spf.ini` in your Haraka `config` directory. You can start with the commented-out default settings provided in the `haraka-plugin-spf` repository's README or package.
```
Haraka plugin 'spf' returned an error during [hook name]: ReferenceError: someLegacyConfigVariable is not defined OR plugin behaves unexpectedly due to config.
```
cause Your `spf.ini` file contains deprecated or unsupported configuration directives, likely due to an upgrade from an older plugin version.

fix Review the `spf.ini` file and remove any options that are no longer documented or have been deprecated. Specifically, ensure no 'legacy config support' options are present if upgrading to v1.2.10+.

Warnings

breaking Legacy configuration support was removed in version 1.2.10. Users upgrading from very old versions might need to update their `spf.ini` files.
Fix: Review your `spf.ini` against the latest documentation and default settings. Remove any outdated or non-standard directives.
breaking The formatting of the `Received-SPF` header was refactored in version 1.2.11 to fold the header and remove redundant server names for better readability and compliance.
Fix: No action is required, but be aware that automated parsers or logs relying on the exact previous header format might need adjustments.
gotcha SPF HELO tests rarely pass for legitimate senders, as most do not publish SPF records for their mail server hostnames. Relying heavily on HELO validation for denial often leads to false positives.
Fix: It is generally recommended to disable `deny.helo_fail` and similar HELO-based denial options. Focus instead on `mfrom_fail` for more reliable SPF enforcement.
gotcha Enabling SPF error deferrals (`defer.helo_temperror`, `defer.mfrom_temperror`) can cause excessive delays or bounced mail for senders with broken DNS configurations.
Fix: Only enable deferrals for temporary errors if you are willing to accept potential delays or loss of valid mail. It's often safer to log these errors than to defer on them.
gotcha Broken SPF records by valid senders are common. Denying mail based on SPF errors (e.g., `helo_permerror`, `mfrom_permerror`) can lead to legitimate emails being rejected.
Fix: Exercise caution when enabling denial for SPF error results. `mfrom_fail` is typically the only deny option most sites should consider, and even then, be aware of legitimate mail from forwarders/mailing lists.

Install

npm install haraka-plugin-spf npm
yarn add haraka-plugin-spf yarn
pnpm add haraka-plugin-spf pnpm

Imports

spf
wrong:
```
import { spf } from 'haraka-plugin-spf'; // Direct programmatic imports are not for end-users.
```
correct:
```
Add 'spf' to Haraka's config/plugins file.
```
This package is a Haraka plugin. End-users enable it by listing 'spf' in their Haraka `config/plugins` file, rather than importing it directly into application code. Haraka handles the loading and execution.
spf.ini
wrong:
```
Configure SPF settings via JavaScript code or environment variables directly.
```
correct:
```
Create a file named `spf.ini` within Haraka's `config` directory.
```
The primary configuration for `haraka-plugin-spf` is done through the `spf.ini` file. This INI file allows for fine-grained control over lookup timeouts, denial policies for various SPF outcomes (e.g., `helo_fail`, `mfrom_softfail`), and behavior for relayed connections.
Plugin
wrong:
```
import { Plugin } from 'haraka-plugin-spf'; // Not typically used by end-users.
```
correct:
```
const Plugin = require('haraka-plugin-spf'); // Used internally by Haraka or by developers extending the plugin.
```
While the plugin's `index.js` may have undergone ES6 refactoring (v1.2.10), Haraka's plugin loading mechanism fundamentally uses CommonJS `require()`. This pattern is for Haraka itself or for developers creating other plugins that interact with `haraka-plugin-spf` programmatically, not for typical end-user setup.

Quickstart

This quickstart demonstrates how to enable the `haraka-plugin-spf` by adding it to Haraka's `config/plugins` file and setting up a basic `spf.ini` configuration to deny messages that explicitly fail SPF for the MAIL FROM address.

/* Haraka config/plugins file */
# This is a comment
# Your other plugins...
data.headers
rules
queue/smtp_proxy

spf  # Add this line to enable the SPF plugin


/* Haraka config/spf.ini file */
; Place this file in your Haraka config directory (e.g., /etc/haraka/config/spf.ini)

lookup_timeout = 29

[relay]
context=sender

[skip]
relaying=false
auth=false

[deny]
mfrom_fail=true  ; Only deny explicit MAIL FROM SPF failures
openspf_text=true ; Add OpenSPF explanation text on deny

[deny_relay]
; Typically do not deny SPF for relayed mail, unless specific policies are needed.
mfrom_fail=false
openspf_text=false


// After configuring, restart Haraka:
// sudo haraka -c /etc/haraka
// (or whichever command you use to start Haraka)

view raw JSON →