Skip to main content
Version: v1.5.0



You may see CrowdSec referred to as "Security Engine" and Bouncers referred to as "Remediation Components" within new documentation. This is to better reflect the role of each component within the CrowdSec ecosystem.

What is CrowdSec Security Engine ?

CrowdSec Security Engine is a open-source security software. See the overview.

I've installed the Security Engine, it detects attacks but doesn't block anything ?!

Yes, the Security Engine is in charge of detecting attacks, and Remediation Component are applying decisions. If you want to block the detected IPs, you should deploy a Remediation Component, such as the ones found on the hub !

How to know if my setup is working correctly ? Some of my logs are unparsed, is it normal ?

Yes, security engine parsers only parse the logs that are relevant for scenarios. Take a look at cscli metrics and understand what do they mean to know if your setup is correct.

You can take an extra step and use cscli explain to understand what log lines are parsed, and how. :


What language is it written in ?

CrowdSec Security Engine is written in Golang.

What resources are needed to run Security Engine ?

Security Engine itself is rather light, and in a small to medium setup should use less than 100Mb of memory.

During intensive logs processing, CPU is going to be the most used resource, and memory should grow slightly.

What licence is provided ?

The Security Engine and Remediation Components are provided under MIT license.

Which information is sent to the APIs ?

Our aim is to build a strong community that can share malevolent attackers IPs, for this we need to collect the decisions triggered locally by each engine.

The signal sent by your Security Engine to the central API and contains only meta-data about the decision :

  • Attacker IP
  • Scenario name
  • Time of start/end of attack

Your logs are NOT sent to our central API.

When pulling block-lists from the platform, the following information is shared as well :

What is the performance impact ?

As the Security Engine only works on logs, it shouldn't impact your production. When it comes to remediation components, please refer to their documentation.

How fast is it ?

The Security Engine can easily handle several thousands of events per second on a rich pipeline (multiple parsers, geoip enrichment, scenarios and so on). Logs are a good fit for sharding by default, so it is definitely the way to go if you need to handle higher throughput.

If you need help for large scale deployment, please get in touch with us on the Form, we love challenges ;)

What backend database does the Security Engine support and how to switch ?

Security Engine versions (after v1) supports SQLite (default), MySQL and PostgreSQL databases. See databases configuration for relevant configuration. Thanks to the Local API, distributed architectures are resolved even with sqlite database.

SQLite by default as it's suitable for standalone/single-engine setups.

How to control granularity of actions ? (whitelists, simulation etc.)

The Security Engine supports both whitelists and simulation :

  • Whitelists allows you to "discard" events or overflows
  • Simulation allows you to simply cancel the decision that is going to be taken, but keep track of it

Profiles allows you to control which decision will be applied to which alert.

How to add whitelists ?

You can follow this guide

How to set up proxy ?

Setting up a proxy works out of the box, the net/http golang library can handle those environment variables:


For example:

export HTTP_PROXY=http://<proxy_url>:<proxy_port>

Systemd variable

On Systemd devices you have to set the proxy variable in the environment section for the CrowdSec service. To avoid overwriting the service file during an update, a folder is created in /etc/systemd/system/crowdsec.service.d and a file in it named http-proxy.conf. The content for this file should look something like this:


After this change you need to reload the systemd daemon using: systemctl daemon-reload

Then you can restart CrowdSec like this: systemctl restart crowdsec


If you use sudo cscli, just add this line in visudo after setting up the previous environment variables:

Defaults        env_keep += "HTTP_PROXY HTTPS_PROXY NO_PROXY"

How to report a bug ?

To report a bug, please open an issue on the repository.

What about false positives ?

Several initiatives have been taken to tackle the false positives approach as early as possible :

  • The scenarios published on the hub are tailored to favor low false positive rates
  • You can find generic whitelists that should allow to cover most common cases (SEO whitelists, CDN whitelists etc.)
  • The simulation configuration allows you to keep a tight control over scenario and their false positives
  • Or add your own whitelists

I need some help

Feel free to ask for some help to the Discourse or directly in the Discord chat.

How to have a dashboard without docker

See the tutorial

How to configure crowdsec/cscli to use Tor

It is possible to configure cscli and crowdsec to use tor to anonymously interact with our API. All (http) requests made to the central API to go through the tor network.

With tor installed, setting HTTP_PROXY and HTTPS_PROXY environment variables to your socks5 proxy will do the trick.

Running the wizard with tor

$ sudo HTTPS_PROXY=socks5:// HTTP_PROXY=socks5://  ./ --bininstall

Do not use the wizard in interactive (-i) mode if you're concerned, as it will start the service at the end of the setup, leaking your IP address.

Edit crowdsec systemd unit to push/pull via tor


Using cscli via tor

$ sudo HTTP_PROXY=socks5:// HTTPS_PROXY=socks5:// cscli capi register

How to setup High Availability for Local API

When setting up High Availability for Local API, do not forget to share the same CS_LAPI_SECRET between your Local API instances : it is the secret used to signed JWT tokens. (By default it's generated from PRNG at startup)

How to disable the central API

To disable the central API, simply comment out the online_client section of the configuration file.

Why are some scenarios/parsers "tainted" or "custom" ?

When using cscli to list your parsers, scenarios and collections, some might appear as "tainted" or "custom".

"tainted" items:

  • Originate from the hub
  • Were locally modified
  • Will not be automatically updated/upgraded by cscli operations (unless --force or similar is specified)
  • Won't be sent to Central API and won't appear in the Console (unless cscli console enable tainted has been specified)

"custom" items:

  • Have been locally created by the user
  • Are not managed by cscli operations
  • Won't be sent to Central API and won't appear in the Console (unless cscli console enable custom has been specified)