https://github.com/hash-bang/express-jail
Express middleware which add malicious actors into a Fail2Ban jail
https://github.com/hash-bang/express-jail
Last synced: 20 days ago
JSON representation
Express middleware which add malicious actors into a Fail2Ban jail
- Host: GitHub
- URL: https://github.com/hash-bang/express-jail
- Owner: hash-bang
- License: mit
- Created: 2021-08-28T02:17:38.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-08-09T00:08:25.000Z (almost 3 years ago)
- Last Synced: 2025-03-30T18:01:36.980Z (about 2 months ago)
- Language: JavaScript
- Size: 64.5 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
express-jail
============
Express middleware which add malicious actors into a [Fail2Ban](https://www.fail2ban.org) 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
```javascript
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](https://github.com/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` | See notes | List of path components to consider malicious |
| `responseCode` | `Number` | `404` | Initial response code to send before blocking |
| `clientBinary` | `Array` | 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.