Skip to content

CrowdSec is an open-source cyber security tool. This Express middleware blocks detected attackers or display them a captcha to check they are not bots.

License

Notifications You must be signed in to change notification settings

crowdsecurity/cs-express-bouncer

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CrowdSec Express JS Bouncer

CrowdSec Express Bouncer

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.

Included features

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

How to use this Express middleware

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

First, install the Crowdsec Bouncer express middleware:

npm install @crowdsec/express-bouncer

or

yarn add @crowdsec/express-bouncer

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

const express = require("express");
const bodyParser = require("body-parser");
const expressCrowdsecBouncer = require("@crowdsec/express-bouncer");

(async () => {
  // Configure CrowdSec Middleware.
  const crowdsecMiddleware = await expressCrowdsecBouncer({
    url: "http://localhost:8080",
    apiKey: "INSERT_YOUR_BOUNCER_API_KEY",
  });

  // Configure Express server.
  const app = express();
  app.use(bodyParser.urlencoded({ extended: true }));
  app.use(crowdsecMiddleware);

  // Create an example route.
  app.all("/", function (req, res) {
    res.status(200).send(`The way is clear!`);
  });

  // Start server.
  app.listen(3000);
  console.log(
    `Express server configured with Crowdsec middleware available here: http://127.0.0.1:3000`
  );
})();

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).

Configuration

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

Name Description Type Default
url (required) The URL of your LAPI instance. Ex: "http://localhost:8080" string -
apiKey (required) The bouncer key (generated via cscli) string -
fallbackRemediation The remediation to use when the received one is unknown Constant * BAN_REMEDIATION
maxRemediation The maximum remediation to use (flex mode) Constant * BAN_REMEDIATION
bypass To enable or disable the bouncing boolean false
captchaTexts To change the text displayed on the CAPTCHA wall object view below **
banTexts To change the text displayed on the BAN wall object view below ***
colors To change the colors of the BAN and CAPTCHA walls object view below ****
customCss CSS code to customize ban and captcha walls string ""
userAgent To use a custom bouncer user agent when requesting LAPI string "CrowdSec Express-NodeJS bouncer/vx.x.x"
timeout The timeout when requesting LAPI number 2000
captchaGenerationCacheDuration The minimum time between two CAPTCHA generations for a same IP number 60 * 1000
captchaResolutionCacheDuration The time we can consider a captcha as resolved (during an active "captcha" decision) number 30 * 60 * 1000
hideCrowdsecMentions To display or hide CrowdSec mention on the BAN and CAPTCHA walls boolean false
customLogger You can use a custom Winston logger Winston logger default logger
bypassConnectionTest To bypass the connection test at middleware initialization boolean false
trustedRangesForIpForwarding The list of IPs to trust as proxies array []

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

**: captchaTexts default value:

{
  "tabTitle": "Oops..",
  "title": "Hmm, sorry but...",
  "subtitle": "Please complete the security check.",
  "refresh_image_link": "refresh image",
  "captcha_placeholder": "Type here...",
  "send_button": "CONTINUE",
  "error_message": "Please try again.",
  "footer": ""
}

***: banTexts default value:

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

****: colors default value:

{
  "text": {
    "primary": "black",
    "secondary": "#AAA",
    "button": "white",
    "error_message": "#b90000"
  },
  "background": {
    "page": "#eee",
    "container": "white",
    "button": "#626365",
    "button_hover": "#333"
  }
}

FAQ

What do I need to make CrowdSec work?

  • 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

MIT Licence

About

CrowdSec is an open-source cyber security tool. This Express middleware blocks detected attackers or display them a captcha to check they are not bots.

Topics

Resources

License

Stars

Watchers

Forks