A quick tutorial on installing and operating the CrowdSec v.1.0.x IP filtering system

8 min


Hello everyone! Before the New Year, we released a large update of our product – CrowdSec v.1.0.X, which contains significant changes compared to the previous version. Most importantly, the local REST API was put into operation and the corresponding architectural changes were made. As a result, the process of creating bouncers has been greatly simplified and their stability has been increased, while the time for system maintenance has decreased.

In this article, you will find basic materials on how CrowdSec was redesigned and, in general, can be considered as a User Guide for those who are going to try our product on their systems.

All CrowdSec components (agents for reading logs, cscli and bouncers) now communicate with each other via the REST API, which avoids multiple reading of database records by each component independently. By the way, we support SQLite, PostgreSQL and MySQL.

Below we will show you how to roll CrowdSec to your Linux Server. In total, the material contains four stages:

  • Installing CrowdSec

  • Testing

  • Installing bouncers

  • Monitoring

Setting up the environment

For a test demo installation of CrowdSec we are using a Debian 10 machine buster t2.medium EC2. For completeness, let’s roll nginx over it:

For this test we are using a Debian 10 buster t2.medium EC2 machine.

To make it more relevant, let’s start by installing nginx on it:

$ sudo apt-get update

$ sudo apt-get install nginx

We have configured security groups so that ssh (tcp / 22) and http (tcp / 80) can be tapped from the outside world. This will be useful for further simulating attacks when checking the system.

Installing CrowdSec

First, let’s install the latest version of CrowdSec (or you can grab it from our GitHub repository):

$ curl -s https://api.github.com/repos/crowdsecurity/crowdsec/releases/latest | grep browserdownloadurl| cut -d '"' -f 4  | wget -i –

$ tar xvzf crowdsec-release.tgz 

$ cd crowdsec-v1.0.0/

$ sudo ./wizard.sh -i

First of all, we will indicate which machine we are working on and what we will monitor

Our installation wizard allows you to select services for monitoring with regular checkboxes. We will be looking at the default set of nginx, sshd and the Linux system itself.

The installation wizard also scans the system for associated log files and prompts the user to specify them for monitoring:

It is extremely important to correctly connect the logs to the monitoring system, because it is from the logs that CrowdSec will draw the bulk of information about what is happening. If you did everything correctly, the installation wizard will prompt you to select a collection.

Collection Is a special set of configurations that was developed for various cases and scenarios of protecting the system and your entire stack. For example, the collection Crowdsecurity / sshd is used for parsing sshd log and detection brute force ssh or brute force

After the services and associated log files are correctly identified (which is very important, since this is where CrowdSec will get its information), the wizard will suggest the collections.

All collections are based on our vision of how and in what directions it is worth protecting the system (that is, no one forbids you to engage in manual configuration of the perimeter, this is just a quick setup crutch).

The last step of the setup wizard is to deploy general whitelisting to prevent banning private IP addresses. This is important because the decision to block is made by the system administrator, not by CrowdSec. In this case, we just provide recommendations.

Once the installation is complete, CrowdSec is ready to go.

First Steps at CrowdSec

So, we have rolled CrowdSec onto our test machine and are ready to test how it will protect us from spam, attacks and other “noise”.

We simulate an attack on our web server via wapiti

First, we will simulate nginx web application scanning via wapiti from an external IP address.

ATTACKER $ wapiti -u

[*] Saving scan state, please wait …



This scan has been saved in the file /home/admin/.wapiti/scans/

Now let’s look at the logs of our “attack”:

We can see that my IP was running different scripts:

– Crowdsecurity / http-path-traversal-probing: detected patterned traversal attempts in URI or GET parameters

– Crowdsecurity / http-sqli-probbing-detection: detect obvious attempts to check SQL injection in URI or GET parameters

And this is provided that we were knocking on, in fact, an empty nginx server, and not on a real site. If we were a real site, then the scanner would catch many more manipulations that occur when an attack on a web server.

Keep in mind that the attacked website is an empty nginx server, the crawler will perform many other actions that will lead to further detections if it were a real website.

Checking the results via cscli

One of the main tools for interacting with the CrowdSec system is cscli… Its main feature is the visualization of current decisions and past alerts:

If you use the command cscli decisions list, you will be able to see all the decisions made during the system operation, and the call cscli alerts list will show a list of past alerts (even if the solution has expired or there has been no reaction to the alert).

To get complete information on any of the decisions made, you can call its log with the command cscli alerts inspect -d (The solution ID is displayed in the left column, see the screenshot above).

cscli offers other functions, but one is of interest to us right now. It’s about the ability to see which parsers and scripts were installed by default:


Monitoring is always the key to building a security perimeter and keeping systems running. And besides the classic “tail the logfile” we suggest using two more tools – metabase dashboard and prometheus metrics


Ubiquitous cscli allows us to deploy our panel based on metabase and docker

To get started, we recommend that you familiarize yourself with the official docker installation documentation

cscli dashboard setup deploys a new metabase dashboard on docker, generating a random password along the way. Well, then everything is relatively clear and beautiful:

Monitoring: Prometheus

If you don’t like all these graphs, buttons and web interfaces, and you generally prefer to work through the console, then Prometheus is suitable for you instead of metabase.

One way to get data is to call cscli metrics:

It is important to understand that cscli metrics reveal only a fraction of the potential of Prometheus. A more detailed description of what can be learned from the indicators, you will receive (suddenly!) In official Prometheus documentation at CrowdSec. If you take a quick tour, then with the help of Prometheus you can get information about the following sections of the system and metrics:

Buckets: how many were created and of what type, filled / were full since the start of the daemon;

Acquisition: how many lines / events were read from each of the specified sources, whether they were analyzed and / or moved later to the trash cans;

Parser: how many lines / events were delivered to each parser and whether it managed to process the mentioned events;

Local API: how many times each route was used, etc.

But no matter how convenient it is to work in the console through cscli, This is not enough. So we recommend using Prometheus in conjunction with Grafana. This is how it looks in practice:

Protection setup: bouncers

So far, we have talked about what CrowdSec can do in terms of detecting and monitoring threats. Now we will talk a little about how our product protects your system and blocks attacks. This is where bouncers come to the fore: CrowdSec detects the attack, and the bouncer sends the attacker home.

Bouncers work through a request to the CrowdSec API when they need to decide block IP or not… You can download ready-made configs right now from our hub on the official website

Here we are using cs-firewall-bouncer. It will directly deny any malicious IP at the firewall level through the use of iptables or nftables. If you need to unblock the address, use the command sudo cscli solutions delete -i XXXX (where XXXX is the IP address).

Installing a bouncer

First, let’s install some bouncer from our GitHub repository:

$ wget https://github.com/crowdsecurity/cs-firewall-bouncer/releases/download/v0.0.5/cs-firewall-bouncer.tgz

$ tar xvzf cs-firewall-bouncer.tgz

$ cd cs-firewall-bouncer-v0.0.5 /

It is installed with a simple script:

As we said earlier, bouncers communicate with the system through the REST API, so we need to check that it is hooked on it:

Team sudo cscli bouncers list you can check if the bouncer is installed.

Bouncer testing

Before you start, make sure you have a spare IP to access your machine so you don’t ban yourself. Agree, it would be embarrassing. The same access point from a mobile phone will do.

Now that we have a bouncer, let’s try to ban someone.

Let’s create an attempt to access the server at the end of the scan:

ATTACKER$ curl --connect-timeout 1
curl: (28) Connection timed out after 1001 milliseconds

Now let’s see how it looks from the side of our defense:

For the sake of clarity, it should be noted that cs-firewall-bouncer uses either nftables or iptables. When using nftables (and in debian 10 it is the default) it creates and maintains two tables named Crowdsec and Crowdsec6 (for ipv4 and ipv6 respectively).

$ sudo nft list ruleset
table ip crowdsec {
	set crowdsec_blocklist {
		type ipv4_addr
		elements = {,,,,,, …

	chain crowdsec_chain {
		type filter hook input priority 0; policy accept;
		ip saddr @crowdsec_blocklist drop
table ip6 crowdsec6 {
	set crowdsec6_blocklist {
		type ipv6_addr

	chain crowdsec6_chain {
		type filter hook input priority 0; policy accept;
		ip6 saddr @crowdsec6_blocklist drop

You can change the firewall setting and switch to iptables instead of mftables, which is accessed by the bouncer, at /etc/crowdsec/cs-firewall-bouncer/cs-firewall-bouncer.yaml/ Remember that ipset is required to run in iptables mode.

You can change the firewall backend used by the bouncer in /etc/crowdsec/cs-firewall-bouncer/cs-firewall-bouncer.yaml, for example by changing the mode from nftables to iptables (iptables mode requires ipset).

Well, that’s all, our brief excursion has come to an end. We hope you give CrowdSec a try. Below we will leave useful links for you:


Leave a Reply