Haraka 3.1.5 → 3.1.7

package/Plugins.md

@@ -19,123 +19,123 @@ A comprehensive list of known plugins. Create a PR to add yours to these lists.
 
 ### Auth Plugins
 
-| Name                             | Description                                       |
-| -------------------------------- | ------------------------------------------------- |
-| [auth-enc-file][url-authencflat] | Auth against user/pass in an encrypted file       |
-| [flat_file][url-authflat]        | Auth against user/pass in a file                  |
-| [auth_bridge][url-authbridge]    | Auth against remote MTA                           |
-| [auth-imap][url-auth-imap]       | Auth against IMAP server                          |
-| [auth_ldap][url-auth-ldap]       | Auth against LDAP                                 |
-| [auth_proxy][url-authproxy]      | Auth against remote MTA                           |
-| [auth_vpopmaild][url-authvpop]   | Auth against vpopmaild                            |
-| [dkim][url-dkim]                 | DKIM sign & verify                                |
-| [dovecot][url-dovecot]           | SMTP AUTH & recipient validation against dovecot  |
-| [LDAP][url-ldap]                 | Aliases, Auth, and Recipient validation from LDAP |
-| [mailauth][url-mailauth]         | Email Auth (SPF, DKIM, DMARC, ARC, & BIMI)        |
-| [opendkim][url-opendkim]         | DKIM sign and verify email messages               |
-| [spf][url-spf]                   | Perform SPF checks                                |
+| Name                             | Description                                       | Published |
+| -------------------------------- | ------------------------------------------------- | --------- |
+| [auth-enc-file][url-authencflat] | Auth against user/pass in an encrypted file       | 2018      |
+| [flat_file][url-authflat]        | Auth against user/pass in a file                  | 2026      |
+| [auth_bridge][url-authbridge]    | Auth against remote MTA                           | 2026      |
+| [auth-imap][url-auth-imap]       | Auth against IMAP server                          | 2022      |
+| [auth_ldap][url-auth-ldap]       | Auth against LDAP                                 | 2023      |
+| [auth_proxy][url-authproxy]      | Auth against remote MTA                           | 2026      |
+| [auth_vpopmaild][url-authvpop]   | Auth against vpopmaild                            | 2026      |
+| [dkim][url-dkim]                 | DKIM sign & verify                                | 2026      |
+| [dovecot][url-dovecot]           | SMTP AUTH & recipient validation against dovecot  | 2025      |
+| [LDAP][url-ldap]                 | Aliases, Auth, and Recipient validation from LDAP | 2024      |
+| [mailauth][url-mailauth]         | Email Auth (SPF, DKIM, DMARC, ARC, & BIMI)        | 2024      |
+| [opendkim][url-opendkim]         | DKIM sign and verify email messages               | 2018      |
+| [spf][url-spf]                   | Perform SPF checks                                | 2026      |
 
 ### Enrichment Plugins
 
-| Name                           | Description                                |
-| ------------------------------ | ------------------------------------------ |
-| [ASN][url-asn]                 | Get ASN info for remote senders                |
-| [fcrdns][url-fcrdns]           | Forward Confirmed reverse DNS                  |
-| [geoip][url-geoip]             | get geographic information about mail senders  |
-| [p0f][url-p0f]                 | TCP Fingerprinting                             |
-| [karma][url-karma]                  | Dynamic scoring of incoming connections   |
-| [known-senders][url-known-senders]  | Reward emails from those you send mail to |
-| [record_envelope_addresses][url-recordenv] | Adds message headers with ENV recips |
+| Name                                       | Description                                   | Published |
+| ------------------------------------------ | --------------------------------------------- | --------- |
+| [ASN][url-asn]                             | Get ASN info for remote senders               | 2026      |
+| [fcrdns][url-fcrdns]                       | Forward Confirmed reverse DNS                 | 2025      |
+| [geoip][url-geoip]                         | get geographic information about mail senders | 2026      |
+| [p0f][url-p0f]                             | TCP Fingerprinting                            | 2025      |
+| [karma][url-karma]                         | Dynamic scoring of incoming connections       | 2026      |
+| [known-senders][url-known-senders]         | Reward emails from those you send mail to     | 2025      |
+| [record_envelope_addresses][url-recordenv] | Adds message headers with ENV recips          | 2026      |
 
 ### Filtering Plugins
 
-| Name                           | Description                                |
-| ------------------------------ | ------------------------------------------ |
-| [attachment][url-attach]       | Restrict attachment types                  |
-| [block_me][url-blockme]        | Populate block list via forwarded emails   |
-| [avg][url-avg]                 | AVG antivirus scanner                      |
-| [clamd][url-clamd]             | Anti-Virus scanning with ClamAV            |
-| [data.signatures][url-sigs]    | Block emails whose bodies match signatures |
-| [dcc][url-dcc]                 | Distributed Checksum Clearinghouse         |
-| [dns-list][url-dns-list]       | Check against DNS and reputation lists     |
-| [early_talker][url-early]      | Reject remotes that talk early             |
-| [esets][url-esets]             | Virus scanning with ESET Mail Security     |
-| [greylist][url-greylist]       | Greylisting                                |
-| [helo.checks][url-helo]        | Validity checks of the HELO string         |
-| [mail_from.is_resolvable][url-mfres] | Verifies the MAIL FROM domain resolves to a MX |
-| [messagesniffer][url-msgsniff] | Anti-spam via [MessageSniffer][url-ms]     |
-| [milter][url-milter]           | milter support                             |
-| [rspamd][url-rspamd]           | Scan emails with rspamd                    |
-| [spamassassin][url-spamass]    | Scan emails with SpamAssassin              |
-| [uribl][url-uribl]             | Block based on URI blacklists              |
+| Name                                 | Description                                    | Published |
+| ------------------------------------ | ---------------------------------------------- | --------- |
+| [attachment][url-attach]             | Restrict attachment types                      | 2026      |
+| [block_me][url-blockme]              | Populate block list via forwarded emails       | 2026      |
+| [avg][url-avg]                       | AVG antivirus scanner                          | 2024      |
+| [clamd][url-clamd]                   | Anti-Virus scanning with ClamAV                | 2025      |
+| [data.signatures][url-sigs]          | Block emails whose bodies match signatures     | 2026      |
+| [dcc][url-dcc]                       | Distributed Checksum Clearinghouse             | 2025      |
+| [dns-list][url-dns-list]             | Check against DNS and reputation lists         | 2025      |
+| [early_talker][url-early]            | Reject remotes that talk early                 | 2026      |
+| [esets][url-esets]                   | Virus scanning with ESET Mail Security         | 2025      |
+| [greylist][url-greylist]             | Greylisting                                    | 2026      |
+| [helo.checks][url-helo]              | Validity checks of the HELO string             | 2026      |
+| [mail_from.is_resolvable][url-mfres] | Verifies the MAIL FROM domain resolves to a MX | 2026      |
+| [messagesniffer][url-msgsniff]       | Anti-spam via [MessageSniffer][url-ms]         | 2025      |
+| [milter][url-milter]                 | milter support                                 | 2017      |
+| [rspamd][url-rspamd]                 | Scan emails with rspamd                        | 2026      |
+| [spamassassin][url-spamass]          | Scan emails with SpamAssassin                  | 2026      |
+| [uribl][url-uribl]                   | Block based on URI blacklists                  | 2025      |
 
 ### Logging & Telemetry
 
-| Name                             | Description                                                              |
-| -------------------------------- | ------------------------------------------------------------------------ |
-| [accounting_files][url-acc-files]      | Retrieve, Store and Archive custom information of outbound traffic |
-| [elasticsearch][url-elastic]           | Store message metadata in Elasticsearch                            |
-| [log reader][url-logreader]            | extract log entries from the haraka log file                       |
-| [outbound-logger][url-outbound-logger] | JSON logging of outbound email. Logs metadata about delivered/bounced emails |
-| [process_title][url-proctitle]         | Populate `ps` output with activity counters                        |
-| [syslog][url-syslog]                   | Log to syslog                                                      |
-| [watch][url-watch]                     | Watch live SMTP traffic in a web interface                         |
+| Name                                         | Description                                                                  | Published |
+| -------------------------------------------- | ---------------------------------------------------------------------------- | --------- |
+| [accounting_files][url-acc-files]            | Retrieve, Store and Archive custom information of outbound traffic           | 2017      |
+| [elasticsearch][url-elastic]                 | Store message metadata in Elasticsearch                                      | 2026      |
+| [log reader][url-logreader]                  | extract log entries from the haraka log file                                 | 2026      |
+| [outbound-logger][url-outbound-logger]       | JSON logging of outbound email. Logs metadata about delivered/bounced emails | —         |
+| [process_title][url-proctitle]               | Populate `ps` output with activity counters                                  | 2026      |
+| [syslog][url-syslog]                         | Log to syslog                                                                | 2026      |
+| [watch][url-watch]                           | Watch live SMTP traffic in a web interface                                   | 2026      |
 
 ### Queue Plugins
 
-| Name                             | Description                                                              |
-| -------------------------------- | ------------------------------------------------------------------------ |
-| [discard][url-qdisc]             | queues messages to /dev/null                                             |
-| [kafka][url-kafka]               | Queue inbound mail to a Kafka topic                                      |
-| [lmtp][url-qlmtp]                | deliver queued messages via LMTP                                         |
-| [mongodb][mongo-url]             | Queue emails to MongoDB                                                  |
-| [qmail-queue][url-qmail]         | queue to qmail                                                           |
-| [quarantine][url-qquart]         | queue to a quarantine directory                                          |
-| [rabbitmq][url-qrabbit]          | queue to RabbitMQ                                                        |
-| [rabbitmq_amqplib][url-qrabbita] | queue to RabbitMQ using amqplib                                          |
-| [rails][url-qrails]              | queue messages to a Rails app using [Action Mailbox][url-action-mailbox] |
-| [smtp_bridge][url-qbridge]       | Bridge SMTP sessions to another MTA                                      |
-| [smtp_forward][url-qforward]     | Forward emails to another MTA                                            |
-| [smtp_proxy][url-qproxy]         | Proxy SMTP connections to another MTA                                    |
-| [wildduck][url-wildduck]         | queue messages to Wild Duck                                              |
+| Name                               | Description                                                                  | Published |
+| ---------------------------------- | ---------------------------------------------------------------------------- | --------- |
+| [discard][url-qdisc]               | queues messages to /dev/null                                                 | 2026      |
+| [kafka][url-kafka]                 | Queue inbound mail to a Kafka topic                                          | 2023      |
+| [lmtp][url-qlmtp]                  | deliver queued messages via LMTP                                             | 2026      |
+| [mongodb][mongo-url]               | Queue emails to MongoDB                                                      | 2024      |
+| [qmail-queue][url-qmail]           | queue to qmail                                                               | 2026      |
+| [quarantine][url-qquart]           | queue to a quarantine directory                                              | 2026      |
+| [rabbitmq][url-qrabbit]            | queue to RabbitMQ                                                            | 2026      |
+| [rabbitmq_amqplib][url-qrabbita]   | queue to RabbitMQ using amqplib                                              | —         |
+| [rails][url-qrails]                | queue messages to a Rails app using [Action Mailbox][url-action-mailbox]     | —         |
+| [smtp_bridge][url-qbridge]         | Bridge SMTP sessions to another MTA                                          | 2026      |
+| [smtp_forward][url-qforward]       | Forward emails to another MTA                                                | 2026      |
+| [smtp_proxy][url-qproxy]           | Proxy SMTP connections to another MTA                                        | 2026      |
+| [wildduck][url-wildduck]           | queue messages to Wild Duck                                                  | 2026      |
 
 ### Recipient Validation
 
-| Name                               | Description                                           |
-| -----------------------------------| ----------------------------------------------------- |
-| [dovecot][url-dovecot]             | Recipient validation & SMTP AUTH against dovecot      |
-| [LDAP][url-ldap]                   | Aliases, Auth, and Recipient validation from LDAP     |
-| [recipient-routes][url-rroutes]    | Route emails based on their recipient(s)              |
-| [rcpt_to.in_host_list][url-rhost]  | Define local email domains in a file                  |
-| [rcpt_to.ldap][url-rcpt-ldap]      | Validate recipients against LDAP                      |
-| [rcpt-postgresql][url-postgres]    | validate recipients against PostgreSQL                |
-| [qmail-deliverable][url-rqmd]      | Validate recipients against Qmail-Deliverable         |
-| [vmta][url-vmta]                   | Virtual MTA management                                |
-| [wildduck][url-wildduck]           | provides recipient checks against Wild Duck           |
+| Name                               | Description                                           | Published |
+| ---------------------------------- | ----------------------------------------------------- | --------- |
+| [dovecot][url-dovecot]             | Recipient validation & SMTP AUTH against dovecot      | 2025      |
+| [LDAP][url-ldap]                   | Aliases, Auth, and Recipient validation from LDAP     | 2024      |
+| [recipient-routes][url-rroutes]    | Route emails based on their recipient(s)              | 2025      |
+| [rcpt_to.in_host_list][url-rhost]  | Define local email domains in a file                  | 2026      |
+| [rcpt_to.ldap][url-rcpt-ldap]      | Validate recipients against LDAP                      | 2023      |
+| [rcpt-postgresql][url-postgres]    | validate recipients against PostgreSQL                | 2016      |
+| [qmail-deliverable][url-rqmd]      | Validate recipients against Qmail-Deliverable         | 2026      |
+| [vmta][url-vmta]                   | Virtual MTA management                                | 2017      |
+| [wildduck][url-wildduck]           | provides recipient checks against Wild Duck           | 2026      |
 
 ### Every other Plugin
 
-| Name                                       | Description                                                     |
-| ------------------------------------------ | --------------------------------------------------------------- |
-| [access][url-access]                       | ACLs based on IPs, domains, email addrs, etc.                   |
-| [aliases][url-aliases]                     | Email aliases                                                   |
-| [bounce][url-bounce]                       | Many options for bounce processing                              |
-| [delay_deny][url-delay]                    | Delays all pre-DATA 'deny' results                              |
-| [dovecot][url-dovecot]                     | Recipient validation & SMTP AUTH against dovecot                |
-| [headers][url-headers]                     | Inspect and verify various email headers                        |
-| [Limit][url-limit]                         | Apply many types of limits to SMTP connections                  |
-| [prevent_credential_leaks][url-creds]      | Prevent users from emailing their credentials                   |
-| [redis][url-redis]                         | multi-purpose Redis db connection(s)                            |
-| [relay][url-relay]                         | Manage relay permissions                                        |
-| [reseed_rng][url-rng]                      | Reseed the RNG                                                  |
-| [batv-srs][url-batv]                       | BATV & SRS                                                      |
-| [srs][url-srs]                             | Sender Rewriting Scheme                                         |
-| [tarpit][url-tarpit]                       | Slow down connections                                           |
-| [tls][url-tls]                             | Implements TLS                                                  |
-| [toobusy][url-toobusy]                     | Defers connections when too busy                                |
-| [xclient][url-xclient]                     | Implements XCLIENT                                              |
-| [save-sent][url-save-sent]                 | Save sent emails on the serverside to a mailbox of the sender   |
-| [dropbox][url-dropbox]                     | Forward incoming emails to configured Dropbox webhook URLs.     |
+| Name                                       | Description                                                     | Published |
+| ------------------------------------------ | --------------------------------------------------------------- | --------- |
+| [access][url-access]                       | ACLs based on IPs, domains, email addrs, etc.                   | 2026      |
+| [aliases][url-aliases]                     | Email aliases                                                   | 2026      |
+| [bounce][url-bounce]                       | Many options for bounce processing                              | 2026      |
+| [delay_deny][url-delay]                    | Delays all pre-DATA 'deny' results                              | 2026      |
+| [dovecot][url-dovecot]                     | Recipient validation & SMTP AUTH against dovecot                | 2025      |
+| [headers][url-headers]                     | Inspect and verify various email headers                        | 2026      |
+| [Limit][url-limit]                         | Apply many types of limits to SMTP connections                  | 2025      |
+| [prevent_credential_leaks][url-creds]      | Prevent users from emailing their credentials                   | 2026      |
+| [redis][url-redis]                         | multi-purpose Redis db connection(s)                            | 2025      |
+| [relay][url-relay]                         | Manage relay permissions                                        | 2026      |
+| [reseed_rng][url-rng]                      | Reseed the RNG                                                  | 2026      |
+| [batv-srs][url-batv]                       | BATV & SRS                                                      | 2020      |
+| [srs][url-srs]                             | Sender Rewriting Scheme                                         | —         |
+| [tarpit][url-tarpit]                       | Slow down connections                                           | 2026      |
+| [tls][url-tls]                             | Implements TLS                                                  | 2026      |
+| [toobusy][url-toobusy]                     | Defers connections when too busy                                | 2026      |
+| [xclient][url-xclient]                     | Implements XCLIENT                                              | 2026      |
+| [save-sent][url-save-sent]                 | Save sent emails on the serverside to a mailbox of the sender   | —         |
+| [dropbox][url-dropbox]                     | Forward incoming emails to configured Dropbox webhook URLs.     | —         |
 
 <!-- URLs tucked safely out of the way -->
 

package/README.md

@@ -1,144 +1,119 @@
-## Haraka - a Node.js Mail Server
+# Haraka — a Node.js Mail Server
 
 ![Tests](https://github.com/haraka/Haraka/actions/workflows/ci.yml/badge.svg)
 [![Coverage Status][cov-img]][cov-url]
 
-Haraka is a highly scalable [node.js][1] email server with a modular
-plugin architecture. Haraka can serve thousands of concurrent connections
-and deliver thousands of messages per second. Haraka and plugins are written
-in asynchronous JS and are very fast.
+Haraka is a highly scalable [Node.js][1] SMTP server with a modular plugin architecture. It handles thousands of concurrent connections and delivers thousands of messages per second. Haraka and its plugins are written in asynchronous JavaScript, optimised for throughput and low latency.
 
-Haraka has very good spam protection (see [plugins][4]) and works
-well as a filtering [MTA][3]. It also works well as a [MSA][5] running on
-port 587 with auth and [dkim][6] plugins enabled.
+Haraka offers strong spam protection (see [Plugins.md][plugins]) and is widely deployed as a filtering [MTA][3] or as a [MSA][5] on port 465 (and legacy 587) with the auth and [DKIM][6] plugins enabled.
 
-Haraka makes no attempt to be a mail store (like Exchange or Postfix/Exim/Qmail),
-a [LDA][7], nor an IMAP server (like Dovecot or Courier). Haraka is
-typically used **with** such systems.
+Haraka is not a mail store, an [LDA][7], or an IMAP server. It is designed to work **alongside** those systems. A scalable outbound delivery engine is built in: mail flagged as `relaying` (for example, by an auth plugin) is queued for
+outbound delivery automatically.
 
-Haraka has a scalable outbound mail delivery engine built in. Mail
-marked as `relaying` (such as via an `auth` plugin) is automatically
-queued for outbound delivery.
+## Plugin Architecture
 
-### Getting Help
+Haraka's defining feature is its plugin system. Every SMTP transaction is a sequence of well-defined hooks — `connect`, `helo`, `mail`, `rcpt`, `data`, `data_post`, `queue`, and more — and each hook can be extended with a few lines of JavaScript. Plugins are asynchronous by default, so a slow lookup against DNS, Redis, or an HTTP API never blocks the server.
 
-- [Join the mailing list][8] (implemented as a Haraka plugin)
-- [GitHub Issues][15]
+The result is that behaviours which would require a custom MTA elsewhere are typically a small file in Haraka. For example, accepting qmail-style tagged addresses (`user-anything@domain.com`) and rewriting them to `user@domain.com` before forwarding to an Exchange or IMAP backend looks roughly like this:
 
-### Screencast
+```js
+exports.hook_rcpt = (next, connection, params) => {
+  const rcpt = params[0]
+  const [user] = rcpt.user.split('-')
+  rcpt.user = user
+  next()
+}
+```
 
-[Getting started with Haraka][2]
+A comprehensive registry of community and core plugins — auth, DNSBLs, DKIM, SpamAssassin, rspamd, Redis, ClamAV, queue backends, and many others — lives in [Plugins.md][plugins]. To write your own, see the [plugin tutorial][tutorial].
 
-### Why Use Haraka?
+## Documentation
 
-Haraka's plugin architecture provides an easily extensible MTA that
-complements traditional MTAs that excel at managing mail stores but do
-not have sufficient filtering.
+- [Plugins.md][plugins] — plugin registry and configuration reference
+- [docs/][docs] — core documentation (Connection, Transaction, Outbound, …)
+- [Tutorial][tutorial] — step-by-step getting started guide
+- [CHANGELOG.md][changelog] — release notes
+- [SECURITY.md][security] — security policy and reporting
 
-The plugin system makes it easy to code new features. A typical example
-is providing qmail-like extended addresses to an Exchange system,
-whereby you could receive mail as `user-anyword@domain.com`, and yet
-still have it correctly routed to `user@domain.com`. This is a few lines of
-code in Haraka.
+## Getting Help
 
-Plugins are provided for running mail through [SpamAssassin][9], validating
-[HELO][10] names, checking [DNS Blocklists][11], and [many others][12].
+- [GitHub Issues][issues]
+- [Mailing list][mailing-list] (implemented as a Haraka plugin)
+- [Screencast: Getting started with Haraka][screencast]
 
-### Installing Haraka
+## Installation
 
-Haraka requires [node.js][1] to run. Install Haraka with [npm][2]:
+Haraka requires [Node.js][1]. Install via [npm][npm]:
 
 ```sh
-# If the second command gives "nobody" errors, uncomment & run the next command
-# npm -g config set user root
 npm install -g Haraka
 ```
 
-After installation, use the `haraka` binary to set up the service.
-
-### Running Haraka
-
-First, create the service:
+Create a service directory:
 
 ```sh
 haraka -i /path/to/haraka_test
 ```
 
-That creates the directory `haraka_test` with `config` and `plugin`
-directories within. It also sets the host name used by Haraka
-to the output of `hostname`.
+This creates `haraka_test` with `config/` and `plugins/` subdirectories and sets the host name from `hostname(1)`. Edit `config/host_list` to add the domains for which Haraka should accept mail.
 
-If `hostname` is not correct, edit `config/host_list`. For example,
-to receive mail addressed to `user@domain.com`, add `domain.com` to the
-`config/host_list` file.
-
-Finally, start Haraka using root permissions:
+Start Haraka:
 
 ```sh
 haraka -c /path/to/haraka_test
 ```
 
-And it will run.
-
-### Configure Haraka
+## Configuration
 
-To choose which plugins run, edit `config/plugins`. Plugins control the
-overall behaviour of Haraka. By default, only messages to domains listed
-in `config/host_list` will be accepted and then delivered via the
-`smtp-forward` plugin. Configure the destination in `config/smtp_forward.ini`.
+Edit `config/plugins` to select active plugins. By default, mail addressed to domains in `config/host_list` is accepted and forwarded via the `smtp-forward` plugin (configured in `config/smtp_forward.ini`).
 
-### Read the Fine Manual
+Per-plugin documentation is available via:
 
 ```sh
-haraka -h plugins/$name
+haraka -h plugins/<name>
 ```
 
-The docs detail how each plugin is configured. After editing
-`config/plugins`, restart Haraka and enjoy!
-
-### Running from git
+See [Plugins.md][plugins] for the full registry.
 
-If you are unable to use npm to install Haraka, you can run from git by
-following these steps:
+## Running from Source
 
-First clone the repository:
-
-    $ git clone https://github.com/haraka/Haraka.git
-    $ cd Haraka
-
-Install Haraka's node.js dependencies locally:
-
-    $ npm install
-
-Edit `config/plugins` and `config/smtp.ini` to specify the plugins and
-config you want.
+```sh
+git clone https://github.com/haraka/Haraka.git
+cd Haraka
+npm install
+node haraka.js
+```
 
-Finally run Haraka:
+## Authorship and Maintenance
 
-    $ node haraka.js
+Haraka was created by [Matt Sergeant][matt-sergeant] (`baudehlo`), formerly project leader of [SpamAssassin][spamassassin] and a contributor to [Qpsmtpd][qpsmtpd]. The project is currently maintained by
+[Matt Simerson][msimerson] (`msimerson`).
 
-### License and Author
+Haraka is the work of many hands. See [CONTRIBUTORS.md][contributors] for the full list of people who have contributed code, documentation, and plugins.
 
-Haraka is MIT licensed - see the [LICENSE][16] file for details.
+## License
 
-Haraka is a project started by [Matt Sergeant][17], a 10 year veteran of the email and anti-spam world. Previous projects have been the project leader for
-SpamAssassin and a hacker on [Qpsmtpd][13].
+Haraka is released under the MIT License. See [LICENSE][license] for details.
 
-[1]: http://nodejs.org/
-[2]: http://youtu.be/6twKXMAsPsw
-[3]: http://en.wikipedia.org/wiki/Message_transfer_agent
-[4]: https://github.com/haraka/Haraka/blob/master/Plugins.md
-[5]: http://en.wikipedia.org/wiki/Mail_submission_agent
+[1]: https://nodejs.org/
+[3]: https://en.wikipedia.org/wiki/Message_transfer_agent
+[5]: https://en.wikipedia.org/wiki/Message_submission_agent
 [6]: https://github.com/haraka/haraka-plugin-dkim
 [7]: https://en.wikipedia.org/wiki/Mail_delivery_agent
-[8]: mailto:haraka-sub@harakamail.com
-[9]: https://haraka.github.io/plugins/spamassassin
-[10]: https://haraka.github.io/plugins/helo.checks
-[11]: https://haraka.github.io/plugins/dnsbl
-[12]: https://github.com/haraka/Haraka/blob/master/Plugins.md
-[13]: https://github.com/smtpd/qpsmtpd/
-[15]: https://github.com/haraka/Haraka/issues
-[16]: https://github.com/haraka/Haraka/blob/master/LICENSE
-[17]: https://github.com/baudehlo
+[npm]: https://www.npmjs.com/package/Haraka
+[plugins]: https://github.com/haraka/Haraka/blob/master/Plugins.md
+[docs]: https://github.com/haraka/Haraka/tree/master/docs
+[tutorial]: https://github.com/haraka/Haraka/blob/master/docs/Tutorial.md
+[changelog]: https://github.com/haraka/Haraka/blob/master/CHANGELOG.md
+[security]: https://github.com/haraka/Haraka/blob/master/SECURITY.md
+[contributors]: https://github.com/haraka/Haraka/blob/master/CONTRIBUTORS.md
+[license]: https://github.com/haraka/Haraka/blob/master/LICENSE
+[issues]: https://github.com/haraka/Haraka/issues
+[mailing-list]: mailto:haraka-sub@harakamail.com
+[screencast]: https://youtu.be/6twKXMAsPsw
+[matt-sergeant]: https://github.com/baudehlo
+[msimerson]: https://github.com/msimerson
+[spamassassin]: https://spamassassin.apache.org/
+[qpsmtpd]: https://github.com/smtpd/qpsmtpd/
 [cov-img]: https://codecov.io/github/haraka/Haraka/coverage.svg
 [cov-url]: https://codecov.io/github/haraka/Haraka?branch=master

package/SECURITY.md

@@ -0,0 +1,178 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the **current release** only. We encourage all users to run the latest version.
+
+| Version        | Supported |
+| -------------- | --------- |
+| 3.1.x (latest) | ✅        |
+| < 3.1          | ❌        |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Use [GitHub Private Vulnerability Reporting](https://github.com/haraka/Haraka/security/advisories/new) to disclose security issues confidentially. This allows the maintainers to assess and patch the issue before public disclosure.
+
+Include as much of the following as possible:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof-of-concept
+- Affected version(s)
+- Any suggested mitigations or patches
+
+## Response Process
+
+1. **Acknowledgement** — We aim to acknowledge reports within **72 hours**.
+2. **Assessment** — We will confirm the issue, determine severity, and identify affected versions.
+3. **Fix & Release** — A patch release will be prepared and coordinated with the reporter.
+4. **Disclosure** — A GitHub Security Advisory (and CVE if applicable) will be published after the fix is available.
+
+We follow [coordinated vulnerability disclosure](https://vuls.cert.org/confluence/display/CVD). Reporters are credited in the advisory unless they prefer otherwise.
+
+## Security Advisories
+
+Published advisories are listed at:
+**https://github.com/haraka/Haraka/security/advisories**
+
+## Threat Model
+
+Haraka is an SMTP server and plugin host. It accepts inbound network
+connections, parses SMTP commands and message content, and can deliver mail
+outbound when an operator enables relaying or outbound.
+
+This threat model assumes the operator controls the host, configuration,
+enabled plugins, credentials, TLS material, and any external services Haraka
+is configured to use.
+
+### Data flow
+
+```mermaid
+flowchart LR
+    client["SMTP client<br/>(untrusted)"]
+    dns["DNS resolver<br/>(untrusted)"]
+    peer["Outbound peer<br/>(untrusted)"]
+    operator(["Operator<br/>(trusted)"])
+    subgraph haraka["Haraka process — trust boundary"]
+        listener["Listener / TLS / Parser"] --> plugins["Plugin pipeline"]
+        plugins --> queue[("Queue · FS")]
+        queue --> delivery["Delivery"]
+        stores[("Config · TLS keys · Logs")]
+    end
+    client <--> listener
+    plugins <--> dns
+    delivery --> peer
+    operator -.-> stores
+    operator -.-> plugins
+```
+
+The trust boundary is the Haraka process. External peers (SMTP clients, DNS
+resolvers, outbound peers) are untrusted; data crossing the boundary inbound
+must be validated before it affects delivery, state, or process behavior.
+Inside the boundary, plugins, the queue, configuration, TLS material, and
+logs share the Haraka process privilege and are the operator's
+responsibility — they are not a security boundary against each other.
+
+### Assets
+
+The assets Haraka aims to protect:
+
+- **Message content** in transit and queued on disk
+- **AUTH credentials** received via SMTP AUTH, and any upstream credentials
+  Haraka holds for outbound or backend services
+- **TLS private keys** and certificates used by the listener and for
+  outbound delivery
+- **Queue integrity** — no injection, alteration, or deletion of queued
+  messages from outside the trust boundary
+- **Availability** of the SMTP service to legitimate clients
+- **Sender reputation** of the operator's deployment — Haraka must not be
+  abusable as an open relay or spam amplifier under documented
+  configuration
+
+### Entry points and actors
+
+Untrusted data enters Haraka through:
+
+- **SMTP listeners** on the operator-configured ports (typically 25, 465,
+  587, and any additional listeners enabled by plugins or configuration)
+- **PROXY protocol or XCLIENT metadata** when the operator has enabled
+  trusted-relay forwarding
+- **DNS responses** to lookups performed by Haraka core or plugins
+  (rDNS, SPF, DKIM, MX, DNSBL, etc.)
+- **Outbound SMTP responses** received from peers during delivery
+
+Haraka distinguishes these actors:
+
+- **Anonymous SMTP client** — connecting from the network without
+  authentication; trusted only to issue SMTP commands subject to policy
+- **Authenticated submission user** — passed SMTP AUTH; trusted with the
+  envelope and policy the operator's auth backend permits, nothing more
+- **Trusted relay peer** — a network source the operator has configured to
+  bypass certain checks (e.g. permitted to relay, or whose PROXY/XCLIENT
+  metadata is honored)
+- **Operator** — controls the host, configuration, and installed plugins;
+  fully trusted
+- **Plugin code** — runs inside the trust boundary with full process
+  privilege; treated as trusted-as-installed, and not a security boundary
+
+### Haraka does not trust
+
+- SMTP clients and other remote peers, including commands, envelopes, headers,
+  bodies, attachments, authentication attempts, HELO/EHLO names, and proxied
+  client metadata before validation
+- Data returned by remote services Haraka communicates with, such as DNS
+  lookups and outbound SMTP peers
+- Untrusted remote input must not be able to trigger behavior beyond
+  documented SMTP and plugin semantics, such as unauthorized relaying,
+  unintended command execution, protected-data disclosure, or service
+  unavailability
+
+### Haraka trusts
+
+- The operating system, filesystem, Node.js runtime, local network, process
+  privileges, and local administrators operating the service
+- Haraka configuration and deployment choices, including listener exposure,
+  relay and authentication policy, TLS certificates, proxy settings, and
+  enabled plugins
+- Code loaded as plugins or dependencies. Plugins run with Haraka's process
+  privileges and are not a security boundary
+- Upstream services and dependencies as separate projects; flaws in those
+  components are usually reported upstream unless Haraka's integration creates
+  a distinct vulnerability
+
+### STRIDE summary
+
+In-scope threats are classified using [STRIDE][stride] applied at the
+Haraka trust boundary shown above. A finding that lets a remote peer
+cause any of the following under documented or default-safe configuration
+is generally a vulnerability.
+
+| Category                   | Example threats at the Haraka boundary                                                                                 |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **S**poofing               | Forged HELO/EHLO or AUTH, identity bypass, unvalidated XCLIENT or proxy metadata accepted as authoritative             |
+| **T**ampering              | SMTP smuggling, CRLF or header injection, parser inconsistencies that change how a message is delivered or interpreted |
+| **R**epudiation            | Remote input that erases or forges the Received: trail, or otherwise defeats logging under default configuration       |
+| **I**nformation disclosure | Leakage of message content, credentials, or internal state through SMTP responses, DSNs, error messages, or logs       |
+| **D**enial of service      | Deterministic resource exhaustion or crashes triggered by remote input without operator misconfiguration               |
+| **E**levation of privilege | Remote code execution, or escape of documented SMTP/plugin semantics into arbitrary behavior inside the Haraka process |
+
+Plugins execute inside the trust boundary by design, so a malicious or
+vulnerable plugin can produce any STRIDE category above. Findings that
+require installing such a plugin are not vulnerabilities in Haraka itself.
+
+[stride]: https://en.wikipedia.org/wiki/STRIDE_model
+
+## Scope
+
+Issues that require control of a trusted element are out of scope, including:
+
+- Vulnerabilities requiring control of the host OS, filesystem, Node.js
+  runtime, local administrator account, or other trusted infrastructure
+- Malicious or compromised plugins or dependencies intentionally installed or
+  enabled by the operator
+- Pure misconfiguration of listeners, relay policy, TLS, proxying, or
+  outbound destinations unless Haraka's documented defaults create the
+  insecure state
+
+Issues in third-party plugins maintained outside this repository should be reported to their respective maintainers.