Getting Started

Getting started

Requirements

• Node.js 24 or newer.
• A running CrowdSec Local API (LAPI). See the CrowdSec documentation to install it.
• Credentials: a bouncer API key, or a watcher machine ID and password.

Choose your client

Goal	Package	Authentication
Block IPs flagged by CrowdSec	crowdsec-client (BouncerClient) or crowdsec-http-middleware	bouncer API key
Report malicious requests / read alerts	crowdsec-client (WatcherClient)	machine ID + password
Give an LLM access to CrowdSec	crowdsec-mcp	bouncer key or watcher credentials
Add scenarios to the middleware	crowdsec-client-scenarios	none (used by the middleware)

Bouncer in a few lines

npm i crowdsec-client

import { BouncerClient } from 'crowdsec-client';

const client = new BouncerClient({
    url: process.env.CROWDSEC_URL,
    auth: {
        apiKey: process.env.CROWDSEC_API_KEY || ''
    }
});

await client.login();

const stream = client.Decisions.getStream({
    // the stream polls the LAPI at this interval, in ms
    interval: 10000
});

stream.on('added', (decision) => {
    console.log('added', decision.type, decision.value);
});

stream.on('deleted', (decision) => {
    console.log('deleted', decision.type, decision.value);
});

stream.resume();

Create the API key with:

cscli bouncers add node-bouncer

Keep the generated key: it is only displayed once.

For a self-signed certificate in development, set strictSSL: false. The stream polls the LAPI every interval milliseconds. See Performances for why the client yields to the event loop.

Watcher in a few lines

npm i crowdsec-client

import { WatcherClient } from 'crowdsec-client';

const client = new WatcherClient({
    url: process.env.CROWDSEC_URL,
    auth: {
        machineID: process.env.CROWDSEC_MACHINE_ID || '',
        password: process.env.CROWDSEC_PASSWORD || '',
        // default: true, renews the token before it expires
        autoRenew: true
    }
});

await client.login();

const alerts = await client.Alerts.search({
    has_active_decision: true
});

console.log(alerts);

Create the machine with:

cscli machines add node-watcher -p myPassword -f ./node_credential.yaml

Or register it from the API: see Register a watcher from the API.

HTTP middleware

If you want a ready-made bouncer for a Node.js HTTP server, use crowdsec-http-middleware and read HTTP middleware.

MCP server

To expose CrowdSec to an LLM, read MCP server.

Next steps

• Authentications: API key, machine password or mutual TLS.
• API reference: generated Typedoc documentation.
• Examples: runnable projects.