CrowdSec is composed of a behavior detection engine, able to block classical attacks like credential bruteforce, port scans, web scans, etc.

Based on the type and number of blocked attacks, and after curation of those signals to avoid false positives and poisoning, a global IP reputation DB is maintained and shared with all network members.

Get more info on the CrowdSec official website.

This Express middleware is a “bouncer”, which purpose is to block detected attacks with two remediation systems: ban or challenge detected attackers with a Captcha.

Here is the exhaustive list of bouncer features.

• Block access or offer to fill in a captcha Our bouncer is able to block access or present a captcha (a.k.a. ban wall and captcha wall).
• Customizable wall pages This bouncer allows you to customize the visual aspect of the ban page and the captcha form (these two pages are called "wall"). You can therefore customize the colors of these pages, modify the texts and translations and even add your own CSS stylesheet if necessary.
• Flex mode : For certain specific uses such as online commerce, it is preferable to never block the user and, in the worst case, you should offer to fill out a captcha. We call this feature "flex mode".
• Support IPv4 and IPv6 : Our bouncer supports both IPv4 and IPv6
• Remedy IPs or IP ranges : Decisions from CrowdSec may concern single IPs or ranges of IPs
• Support for unknown remediations Designed to be extensible, CrowdSec allows you to create as many types of remedies as necessary. Our bouncer can handle all these types of remedies, even those that the bouncer does not yet know.
• CDN Whitelisting : When using CDN, the user's IP is hidden behind the CDN. Fortunately the CDN still transmits the IP through a specific header. To avoid IP spoofing through this header, the bouncer can believe this header only if the CDN IP is included in a list filtered by the bouncer user.
• Bypass mode : Allow the user to temporarily disable bouncing to meet specific needs.
• Events logger : To be Production ready, we have implemented a log system. This will also allow you to consult the bouncer usage metrics later. We use the popular library Winston

Note: You must first have CrowdSec installed on your server. The installation is very simple.

First, install the Crowdsec Bouncer express middleware:

1npm install @crowdsec/express-bouncer

or

1yarn add @crowdsec/express-bouncer

Then init the Express middleware. Here is a quick usage example.

1const express = require("express");
2const bodyParser = require("body-parser");
3const expressCrowdsecBouncer = require("@crowdsec/express-bouncer");
4
5(async () => {
6  // Configure CrowdSec Middleware.
7  const crowdsecMiddleware = await expressCrowdsecBouncer({
8    url: "http://localhost:8080",
9    apiKey: "INSERT_YOUR_BOUNCER_API_KEY",
10  });
11
12  // Configure Express server.
13  const app = express();
14  app.use(bodyParser.urlencoded({ extended: true }));
15  app.use(crowdsecMiddleware);
16
17  // Create an example route.
18  app.all("/", function (req, res) {
19    res.status(200).send(`The way is clear!`);
20  });
21
22  // Start server.
23  app.listen(3000);
24  console.log(
25    `Express server configured with Crowdsec middleware available here: http://127.0.0.1:3000`
26  );
27})();

Note: To get a bouncer API key, just type cscli bouncers add express-js-bouncer (you can replace the name express-js-bouncer by anything you prefer).

Here is the full list of parameters than can be passed to expressCrowdsecBouncer.

*: All remediation type are constants and they can be found: express-crowdsec-bouncer/src/nodejs-bouncer/lib/constants.js.

**: captchaTexts default value:

1{
2  "tabTitle": "Oops..",
3  "title": "Hmm, sorry but...",
4  "subtitle": "Please complete the security check.",
5  "refresh_image_link": "refresh image",
6  "captcha_placeholder": "Type here...",
7  "send_button": "CONTINUE",
8  "error_message": "Please try again.",
9  "footer": ""
10}

***: banTexts default value:

1{
2  "tabTitle": "Oops..",
3  "title": "🤭 Oh!",
4  "subtitle": "This page is protected against cyber attacks and your IP has been banned by our system.",
5  "footer": ""
6}

****: colors default value:

1{
2  "text": {
3    "primary": "black",
4    "secondary": "#AAA",
5    "button": "white",
6    "error_message": "#b90000"
7  },
8  "background": {
9    "page": "#eee",
10    "container": "white",
11    "button": "#626365",
12    "button_hover": "#333"
13  }
14}

• You have to install a CrowdSec instance on this server.
• You have to generate a bouncer key on the server on which CrowdSec is running.

MIT Licence