Repository navigation
Home
Node.js client for the CrowdSec Local API (LAPI): a bouncer and watcher client, an HTTP middleware, detection scenarios and a Model Context Protocol (MCP) server.
Node.js 24 or newer is required.
| Package | What it does |
|---|---|
| crowdsec-client | Low-level LAPI client for bouncers and watchers (decisions, alerts, allowlists, streams). |
| crowdsec-http-middleware | HTTP middleware that checks each request IP and exposes req.decision. |
| crowdsec-client-scenarios | Optional scenarios for the middleware (X-Forwarded-For, allowlist, HTTP and MaxMind enrichment). |
| crowdsec-mcp | Model Context Protocol server exposing decisions, alerts and allowlists to an LLM. |
- Getting started: install a package and create your first client.
- Authentications: machine password, API key or mutual TLS.
- Register a watcher from the API: automate watcher registration.
- HTTP middleware: protect a Node.js HTTP server.
- Scenarios: extract IPs, allowlist addresses and enrich alerts.
- MCP server: connect an LLM to CrowdSec.
- Performances: async design and why bouncer lookups stay fast.
- API reference: generated Typedoc documentation.
- Examples: runnable projects.
The CrowdSec Local API is the HTTP API exposed by the CrowdSec Security Engine. Every client in this project talks to it.
The watcher is the part of the CrowdSec Security Engine
that parses logs and pushes alerts to the LAPI. The name comes from the LAPI
endpoints /v1/watchers. In this project, a watcher client authenticates with a
machine ID and password, and can search alerts, manage allowlists and read
decisions.
A bouncer asks the LAPI for decisions and enforces them (block, captcha...). In this project, a bouncer client authenticates with an API key and consumes the decision stream.
A decision is the LAPI's answer for an IP or a range: its type (ban, captcha,
throttle...), duration and origin. Bouncers enforce decisions.
An alert is the result of a scenario match. It can carry one or more decisions. Watchers create alerts.