express-jail

Express middleware which add malicious actors into a Fail2Ban jail.

Notes:

• This NPM requires fail2ban at version 0.11.1 or later to be installed and running to work correctly.
• This module does include a testkit but, due to the way that localhost blocking works on Linux, you will need to use an external facing IP to test it

var port = 8080;
var express = require('express');
var expressJail = require('express-jail');

app = express();
app.use(expressJail({
	// Options, if any
}));

// Route setup
app.use('/api/foo', (req, res) => res.send({string:'Foo!'}));
server = app.listen(port);

API

expressJail(options) - Main Middleware

The main middleware factory function of the module.

Called as (options) where options is an object which can override the defaults.

Returns an @momsfriendlydevco/eventer EventEmitter(-like) instance which emits the following:

| Event | Emitted as | Description | |------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | ban | (ip, req?, res?) | Emitted before the ban cycle concludes can return an async function which could eventually return boolean false which will prevent the ban | | banned | (ip, req?, res?) | Emitted after the ban cycle concludes | | unban | (ip) | Emitted when calling expressJail.unban(ip), can return an (eventual) boolean false to abort | | unbanned | (ip) | Emitted when expressJail.unban(ip) concluded |

All emitters can optionally return async Promisables which will be waited on.

expressJail.defaults

The default options structure. Can be overridden in each middleware init stage as needed.

| Option | Type | Default | Description | |----------------|-----------------|------------|---------------------------------------------------------------------| | paths | Array<String> | See notes | List of path components to consider malicious | | responseCode | Number | 404 | Initial response code to send before blocking | | clientBinary | Array<Sring> | See notes | Prefix exec paths to access fail2ban-client | | jail | String | "www" | Jail name to use within F2B to collect the ban list | | minVersion | String | "0.11.1" | Minimum Semver version of F2B to work with, set to falsy to disable |

Notes:

• paths are pre-populated from a standard list of malicious scans. If you have any to add please file a PR
• clientBinary is set to ['/usr/bin/sudo', '/usr/bin/fail2ban-client'] by default. Each argument part should be its own part of the array to be correctly escaped
• jail is created before launch if it does not already exist

expressJailInstance.ban(ip)

Can be called manually to ban an IP address.

Returns a Promise which will resolve when the operation has completed.

expressJailInstance.unban(ip)

Can be called manually to unban an IP address.

Returns a Promise which will resolve when the operation has completed.

expressJailInstance.bans()

Returns a promise which will resolve to a collection of all existing bans in the form {ip: String, from: Date, time: Number, to: Date}.

expressJailInstance.hasBan(ip)

Convenience wrapper for expressJailInstance.bans() which queries a specific IP address. Returns a promise which will resolve to a boolean if the provided IP is in the ban list.

expressJailInstance.setup()

Setup and configure the Fail2Ban ruleset. This function is automatically run on initialization. Returns a promise which will resolve when the operation has completed.