CrowdSec NodeJS Bouncer

Documentation • Hub • npm • Issues • @crowdsec

CrowdSec is a behavior detection engine that blocks common attacks like credential brute-force, port scans, and web scans. It maintains a global IP reputation database, curated to avoid false positives, and shares it with all network members.

Basic Usage

Invoking the bouncer is as simple as (Check our examples):

import { CrowdSecBouncer, CrowdSecBouncerConfiguration } from '@crowdsec/nodejs-cs-bouncer';

const config: CrowdSecBouncerConfiguration = {
    url: 'http://localhost:8080',
    bouncerApiToken: 'your-api-key',
};

// Init the bouncer
const bouncer = new CrowdSecBouncer(config);

// Get the remediation for an IP
const remediation = await bouncer.getIpRemediation(malevolentIp);

Apply the remediation

Thanks to the bouncer, you know the remediation about a given IP. To apply the remediation you can use render methods offered by the library. You can either display a ban wall or a captcha wall (Check our examples):

import { renderBanWall, BanWallOptions } from '@crowdsec/nodejs-cs-bouncer';

const wallOptions: BanWallOptions = {
    texts: {
        title: '⚠️ You have been banned ⚠️',
        subtitle: 'You have been banned from accessing this website.',
    },
};

// Render a full customizable HTML page
const banWall = await renderBanWall(wallOptions);

Example of a ban or captcha wall:

API

CrowdSecBouncer

Check the initialization example

constructor(config: CrowdSecBouncerConfiguration) : Create a new instance of the CrowdSecBouncer.
CrowdSecBouncerConfiguration

{
    url: 'string'; // The URL of your CrowdSec Local API
    bouncerApiToken: 'string'; // The API token to use the bouncer
    fallbackRemediation: 'RemediationType'; // The fallback remediation to use. Default: 'ban'
}

getIpRemediation(ip: string): Promise<Remediation>: Get the remediation for a given IP.

Render ban wall

renderBanWall(options: BanWallOptions): Promise<string>: Return a computed HTML page with the ban wall.
BanWallOptions Default options:

{
    tabTitle: 'CrowdSec | Ban Wall', // The title of the tab
    title: 'Access Denied', // Title present in the ban wall card
    subtitle: 'This page is secured against cyber attacks, and your IP has been blocked by our system', // Subtitle present in the ban wall card
    footer: '', // Footer present in the ban wall card
    hideCrowdSecMentions: false, // Hide the CrowdSec mentions
    colors: // Check default colors
    texts: // Check default texts
}

Render captcha wall

renderCaptchaWall(options: CaptchaWallOptions): Promise<string> : Return a computed HTML page with the captcha wall.
CaptchaWallOptions Default options:

{
    tabTitle: 'CrowdSec | Captcha Wall', // The title of the tab
    title: 'Access Denied', // Title present in the captcha wall card
    subtitle: 'This page is secured against cyber attacks, and your IP has been blocked by our system', // Subtitle present in the captcha wall card
    footer: '', // Footer present in the captcha wall card
    hideCrowdSecMentions: false, // Hide the CrowdSec mentions
    colors: // Check default colors
    texts: // Check default texts
    error: '', // The error message to show when the captcha validation fails
    captchaImageTag: '', // The captcha image tag
    redirectUrl: '', // The URL to redirect after the captcha validation
}

julienloizelet/crowdsec-nodejs-bouncer