crowdsec-http-middleware

crowdsec-http-middleware

This library is a Node.js client to talk with crowdsec rest API .

Start

install it

npm i crowdsec-http-middleware

and then read the documentation in the wiki

This package, support a default setup, with default scenarios . You can use the default mode by installing crowdsec-http-middleware and crowdsec-client-scenarios, and passing an empty scenarios configuration

npm i crowdsec-http-middleware crowdsec-client-scenarios

you can read what are the default scenarios enabled in crowdsec-client-scenarios

Usage

This package, is a base package to create HTTP Middleware for HTTP Servers

You can use it like :

import * as http from 'http';
import { CrowdSecHTTPMiddleware } from 'crowdsec-http-middleware';

// init the middleware (we will see the options later)
const middleware = new CrowdSecHTTPMiddleware(middlewareOptions);
//wait async stuff like connection to crowdsec LAPI
await middleware.start();

const server = http.createServer((req: IncomingMessage & { ip?: string; decision?: Decision }, res: ServerResponse) => {
    try {
        middleware.getMiddleware()(req, res);
    } catch (e) {
        console.error('middleware error', e);
    }

    if (!req.decision) {
        res.statusCode = 200;
        res.setHeader('Content-Type', 'text/plain');
        res.end('Hello, World!');
        return;
    }

    res.statusCode = 403;
    res.setHeader('Content-Type', 'text/plain');
    res.end(`You can't access this api, because you are : ${req.decision?.type}`);
});

const port: number = 3000;
server.listen(port, () => {
    console.log(`Server running at http://localhost:${port}/`);
});

options

options are described here : technical documentation

First the global options

const middlewareOptions: ICrowdSecHTTPMiddlewareOptions = {
    // this is the url of the crowdsec instances
    url: process.env.CROWDSEC_URL,
    // options to pass to the crowdsec-client
    clientOptions: {
        // for example, to disable ssl certificate verification
        strictSSL: false
    },
    // here, an optional function to extract Ip from request
    // you can also use a scenario with "extractIp" capability
    // getCurrentIp is prior to scenarios extractIp . If you want to use a default function, create a scenario with only extractIp
    getCurrentIp: (req: IncomingMessage) => req.socket.remoteAddress || '0.0.0.0',
    //we will see this configurations later
    watcher: watcherOptions,
    bouncer: bouncerOptions
}

Watcher options

the watcher options allow you to setup an optional watcher . The watcher, will connect with crowdsec LAPI, and run scenarios to send alerts when analyzing requests

you need to remember, that crowdSec is an IDS, it will detect the alert and block it the next time

about authentication, you can also use TLS certificates . Check the wiki

const watcherOptions = {
    machineID: 'myMachine',
    password: 'myPassword',
    // send heartbeat to LAPI ? it allow the LAPI to see the watcher "online"
    heartbeat: true,
    // a list of scenarios constructors that will be used
    scenarios: [],
    // options passed to the scenarions
    scenariosOptions: {}
}

you can read more about scenarios and scenarioOptions in the crowdsec-client-scenario package

Bouncer options

bouncer, will check if a decision is associated with the current IP .

about authentication, you can also use TLS certificates . Check the wiki

const bouncerOptions = {
    apiKey: process.env.CROWDSEC_API_KEY || ''
}

When a decision is found by the bouncer, req.decision will contain the decision

Debug

this library include debug, to debug, you can set the env variable :

DEBUG=crowdsec-http-middleware:*