HTTP Middleware

HTTP middleware

crowdsec-http-middleware runs a bouncer inside your Node.js HTTP server. It checks each request IP against CrowdSec decisions and sets req.decision; your code decides the response (custom 403 page, captcha, JSON error...). An optional watcher can also detect and report malicious requests.

Full documentation: package README.

Install

npm i crowdsec-http-middleware

# optional: default scenarios (X-Forwarded-For, allowlist, enrichment)
npm i crowdsec-client-scenarios

Quick start

import * as http from 'node:http';
import { CrowdSecHTTPMiddleware } from 'crowdsec-http-middleware';
import type { Decision } from 'crowdsec-client';

const middleware = new CrowdSecHTTPMiddleware({
    url: process.env.CROWDSEC_URL,
    bouncer: {
        apiKey: process.env.CROWDSEC_API_KEY || ''
    }
});

await middleware.start();

const server = http.createServer((req: http.IncomingMessage & { decision?: Decision }, res) => {
    middleware.getMiddleware()(req, res);

    if (req.decision) {
        res.statusCode = 403;
        res.end('You are blocked by CrowdSec');
        return;
    }

    res.statusCode = 200;
    res.end('Hello, World!');
});

server.listen(3000);

See Authentications for API keys and TLS.

Main options

Option	Default	Description
pollingInterval	10000	Stream poll interval in ms.
subnetLevel	company	resident (/32), company (/24) or country (/16).
live.enabled	false	Check unknown IPs in the background.
live.errorBehavior	failOpen	failOpen or failFast when the LAPI is down.
live.cleanCacheTtl	60	Seconds a clean verdict is cached.
live.maxConcurrentChecks	100	Cap on concurrent live checks.
watcher	none	Optional watcher credentials and scenarios.

The generated option reference is here.

Live mode

On a local cache miss, the current request always passes; the check runs in the background. If the LAPI returns a ban, the decision is injected into the local index, so the next request from that IP is blocked. A malicious unknown IP can pass once, never twice.

Behind a proxy

Do not trust X-Forwarded-For blindly. Either provide getCurrentIp, or use the XForwardedForChecker scenario with the list of trusted proxies. See scenarios documentation.

AI setup guide

The repository ships an agent setup guide that interviews you before writing the configuration.