publish helo.checks as NPM module

.eslintrc.yaml

@@ -5,3 +5,6 @@ env:
   es2022: true
 
 extends: ['@haraka']
+
+rules:
+  no-unused-vars: 1

README.md

@@ -3,71 +3,153 @@
 
 [![NPM][npm-img]][npm-url]
 
-# haraka-plugin-template
+# haraka-plugin-helo.checks
 
-Clone me, to create a new Haraka plugin!
+This plugin performs a number of checks on the HELO string.
 
-## Template Instructions
+HELO strings are very often forged or dubious in spam and so this can be a
+highly effective and false-positive free anti-spam measure.
 
-These instructions will not self-destruct after use. Use and destroy.
+## Usage
 
-See also, [How to Write a Plugin](https://github.com/haraka/Haraka/wiki/Write-a-Plugin) and [Plugins.md](https://github.com/haraka/Haraka/blob/master/docs/Plugins.md) for additional plugin writing information.
+helo.checks results can be accessed by subsequent plugins:
 
-## Create a new repo for your plugin
+```js
+const h = connection.results.get('helo.checks');
+if (h.pass && h.pass.length > 5) {
+    // nice job, you passed 6+ tests
+}
+if (h.fail && h.fail.length > 3) {
+    // yikes, you failed 4+ tests!
+}
+if (connection.results.has('helo.checks','pass', /^forward_dns/) {
+    // the HELO hostname is valid
+}
+```
 
-Haraka plugins are named like `haraka-plugin-something`. All the namespace after `haraka-plugin-` is yours for the taking. Please check the [Plugins](https://github.com/haraka/Haraka/blob/master/Plugins.md) page and a Google search to see what plugins already exist.
+## Configuration
 
-Once you've settled on a name, create the GitHub repo. On the [template repo's main page](https://github.com/haraka/haraka-plugin-template), click the _Use this template_ button and create your new repository. Then paste that URL into a local ENV variable with a command like this:
+- helo.checks.regexps
 
-```sh
-export MY_GITHUB_ORG=haraka
-export MY_PLUGIN_NAME=haraka-plugin-SOMETHING
-```
+  List of regular expressions to match against the HELO string. The regular
+  expressions are automatically wrapped in `^` and `$` so they always match
+  the entire string.
 
-Clone and rename the template repo:
+- helo.checks.ini
 
 ```sh
-git clone [email protected]:haraka/$MY_PLUGIN_NAME.git
-cd $MY_PLUGIN_NAME
+cp node_modules/haraka-plugin-helo.checks/config/helo.checks.ini config/helo.checks.ini
+$EDITOR config/helo.checks.ini
 ```
 
-Now you'll have a local git repo to begin authoring your plugin
+INI file which controls enabling of certain checks:
 
-## rename boilerplate
+- dns_timeout=30
 
-Replaces all uses of the word `template` with your plugin's name.
+How many seconds to wait for DNS queries to timeout.
 
-./redress.sh [something]
+### [check]
 
-You'll then be prompted to update package.json and then force push this repo onto the GitHub repo you've created earlier.
+- valid_hostname=true
 
-# Add your content here
+  Checks that the HELO has at least one '.' in it and the organizational
+  name is possible (ie, a host within a Public Suffix).
 
-## INSTALL
+- bare_ip=true
 
-```sh
-cd /path/to/local/haraka
-npm install haraka-plugin-template
-echo "template" >> config/plugins
-service haraka restart
-```
+  Checks for HELO <IP> where the IP is not surrounded by square brackets.
+  This is an RFC violation so should always be enabled.
 
-### Configuration
+- dynamic=true
 
-If the default configuration is not sufficient, copy the config file from the distribution into your haraka config dir and then modify it:
+  Checks to see if all or part the connecting IP address appears within
+  the HELO argument to indicate that the client has a dynamic IP address.
 
-```sh
-cp node_modules/haraka-plugin-template/config/template.ini config/template.ini
-$EDITOR config/template.ini
+- literal_mismatch=1|2|3
+
+  Checks to see if the IP literal used matches the connecting IP address.
+  If set to 1, the full IP must match. If set to 2, the /24 must match.
+  If set to 3, the /24 may match, or the IP can be private (RFC 1918).
+
+- match_re=true
+
+  See above. This is merely an on/off toggle.
+
+- big_company=true
+
+  See below. This is merely an on/off toggle.
+
+- forward_dns=true
+
+  Perform a DNS lookup of the HELO hostname and validate that the IP of
+  the remote is included in the IP(s) of the HELO hostname.
+
+  This test requires that the valid_hostname check is also enabled.
+
+- rdns_match=true
+
+  Sees if the HELO hostname (or at least the domain) match the rDNS
+  hostname(s).
+
+- host_mismatch=true
+
+  If HELO is called multiple times, checks if the hostname differs between
+  EHLO invocations.
+
+- proto_mismatch=true
+
+  If EHLO was sent and the host later tries to then send HELO or vice-versa.
+
+### [reject]
+
+For all of the checks included above, a matching key in the reject section
+controls whether messages that fail the test are rejected.
+
+Defaults shown:
+
+```ini
+[reject]
+host_mismatch=false
+literal_mismatch=false
+proto_mismatch=false
+rdns_match=false
+dynamic=false
+bare_ip=false
+valid_hostname=false
+forward_dns=false
+big_company=false
 ```
 
-## USAGE
+### [skip]
+
+- private_ip=true
+
+  Bypasses checks for clients within RFC1918, Loopback or APIPA IP address ranges.
+
+- relaying
+
+  Bypass checks for clients who have relaying privileges (whitelisted IP,
+  SMTP-AUTH, etc).
+
+### [bigco]
+
+A list of <helo>=<rdns>[,<rdns>...] to match against. If the HELO matches
+what's on the left hand side, the reverse-DNS must match one of the
+entries on the right hand side or the mail is blocked.
+
+Example:
+
+```ini
+yahoo.com=yahoo.com,yahoo.co.jp
+aol.com=aol.com
+gmail.com=google.com
+```
 
 <!-- leave these buried at the bottom of the document -->
 
-[ci-img]: https://github.com/haraka/haraka-plugin-template/actions/workflows/ci.yml/badge.svg
-[ci-url]: https://github.com/haraka/haraka-plugin-template/actions/workflows/ci.yml
-[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-template/badges/gpa.svg
-[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-template
-[npm-img]: https://nodei.co/npm/haraka-plugin-template.png
-[npm-url]: https://www.npmjs.com/package/haraka-plugin-template
+[ci-img]: https://github.com/haraka/haraka-plugin-helo.checks/actions/workflows/ci.yml/badge.svg
+[ci-url]: https://github.com/haraka/haraka-plugin-helo.checks/actions/workflows/ci.yml
+[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-helo.checks/badges/gpa.svg
+[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-helo.checks
+[npm-img]: https://nodei.co/npm/haraka-plugin-helo.checks.png
+[npm-url]: https://www.npmjs.com/package/haraka-plugin-helo.checks

config/helo.checks.ini

@@ -0,0 +1,52 @@
+; disable checks or reject for each test if you are worried about strictness
+
+;dns_timeout=28
+
+[check]
+; match_re=true
+; bare_ip=true
+; dynamic=true
+; big_company=true
+; literal_mismatch:  1 = exact IP match, 2 = IP/24 match, 3 = /24 or RFC1918
+; literal_mismatch=2
+; valid_hostname=true
+; forward_dns=true
+; rdns_match=true
+; host_mismatch:  hostname differs between EHLO invocations
+; host_mismatch=true
+; proto_mismatch: host sent EHLO but then tries to sent HELO or vice-versa
+; proto_mismatch=true
+
+[reject]
+; host_mismatch=true
+; proto_mismatch=false
+; rdns_match=false
+; dynamic=false
+; bare_ip=false
+; literal_mismatch=false
+; valid_hostname=false
+; forward_dns=false
+; big_company=true
+
+[skip]
+; private_ip=true
+; relaying=true
+; whitelist=true  ; TODO
+
+[bigco]
+msn.com=msn.com
+hotmail.com=hotmail.com
+yahoo.com=yahoo.com,yahoo.co.jp
+yahoo.co.jp=yahoo.com,yahoo.co.jp
+yahoo.co.uk=yahoo.co.uk
+excite.com=excite.com,excitenetwork.com
+mailexcite.com=excite.com,excitenetwork.com
+yahoo.co.jp=yahoo.com,yahoo.co.jp
+mailexcite.com=excite.com,excitenetwork.com
+aol.com=aol.com
+compuserve.com=compuserve.com,adelphia.net
+nortelnetworks.com=nortelnetworks.com,nortel.com
+earthlink.net=earthlink.net
+earthling.net=earthling.net
+google.com=google.com
+gmail.com=google.com,gmail.com