Help safeguard your Linux server from attack with this REST API

CrowdSec's new architecture improves communication among components to better protect systems against cybersecurity threats.
59 readers like this.

JanBaby, via Pixabay CC0.

CrowdSec is an open source cybersecurity detection system meant to identify aggressive behaviors and prevent them from accessing systems. Its user-friendly design offers a low technical barrier of entry with a significant boost to security.

A modern behavior detection system written in Go, CrowdSec combines the philosophy of Fail2ban with Grok patterns and YAML grammar to analyze logs for a modern, decoupled approach for securing the cloud, containers, and virtual machine (VM) infrastructures. Once detected, a threat can be mitigated with bouncers (block, 403, captcha, and so on), and blocked internet protocol addresses (IPs) are shared among all users to improve everyone's security further.

December's official release of CrowdSec v.1.0.x introduces several improvements, including a major architectural change: the introduction of a local REST API. This local API allows all components to communicate more efficiently to support more complex architectures while keeping things simple for single-machine users. It also makes it simpler to create bouncers (the remediation component) and renders them more resilient to upcoming changes, which limits maintenance time.

The CrowdSec architecture was deeply remodeled in the new 1.0 release.

All CrowdSec components (the agent reading logs, cscli for humans, and bouncers to deter the bad guys) can now communicate via a REST API instead of reading or writing directly in the database. With this new version, only the local API service will interact with the database (e.g., SQLite, PostgreSQL, or MySQL).

This article covers how to install and run CrowdSec on a Linux server:

  • CrowdSec setup
  • Testing detection capabilities
  • Bouncer setup
  • Observability

Set up the environment

The machine I used for this test is a Debian 10 Buster t2.medium EC2.

To make it more relevant, install Nginx:

$ sudo apt-get update
$ sudo apt-get install nginx

Configure the security groups so that both secure shell (SSH) (tcp/22) and HTTP (tcp/80) can be reached from the outside world. This will be useful for simulating attacks later.

Install CrowdSec

Grab the latest version of CrowdSec:

$ curl -s | grep browser_download_url| cut -d '"' -f 4  | wget -i -

You can also download it from CrowdSec's GitHub page.

Install it:

$ tar xvzf crowdsec-release.tgz 
$ cd crowdsec-v1.0.0/
$ sudo ./ -i

The wizard helps guide installation and configuration. And I have to say it's very helpful!

First, the wizard identifies services present on the machine:

It allows you to choose which services to monitor. For this tutorial, go with the default option and monitor all three services: Nginx, SSHD, and the Linux system.

For each service, the wizard identifies the associated log files and asks you to confirm (use the defaults again):

Once the services and associated log files have been identified correctly (which is crucial, as this is where CrowdSec will get its information), the wizard prompts you with suggested collections.

A collection is a set of configurations that aims to create a coherent ensemble to protect a technological stack. For example, the crowdsecurity/sshd collection contains a parser for SSHD logs and a scenario to detect SSH bruteforce and SSH user enumeration.

The suggested collections are based on the services that you choose to protect.

The wizard's last step is to deploy generic whitelists to prevent banning private IP addresses. It also reminds you that CrowdSec will detect malevolent IPs but not ban any of them. You need a bouncer to block attacks. This is an essential thing to remember: CrowdSec detects attacks; bouncers block them.

Now that the initial setup is done, CrowdSec should be up and running.

Detect attacks with CrowdSec

By installing CrowdSec, you should already have coverage for common internet background noise. Check it out!

Attack a web server with Wapiti

Simulate a web application vulnerability scan on your Nginx service using Wapiti, a web application vulnerability scanner. You need to do this from an external IP, and keep in mind that private IPs are whitelisted by default:

ATTACKER$ wapiti   -u
[*] Saving scan state, please wait...

This scan has been saved in the file 

On your freshly equipped machine, you can see the attacks in the logs:

My IP triggered different scenarios:

Bear in mind that the website you attacked in this example is an empty Nginx server. If this were a real website, the scanner would perform many other actions that would lead to more detections.

Check results with cscli

cscli is one of the main tools for interacting with the CrowdSec service, and one of its features is visualizing active decisions and past alerts.

The cscli decisions list command displays active decisions at any time, while cscli alerts list shows past alerts (even if decisions are expired or the alert didn't lead to a decision).

You can also inspect a specific alert to get more details with cscli alerts inspect -d <ID> (using the ID displayed in the left-hand column of the alerts list).

cscli offers other features, but one to look at now is to find out which parsers and scenarios are installed in the default setup.


Observability (especially for software that might take defensive countermeasures) is always a key point for a security solution. Besides its "tail the logfile" capability, CrowdSec offers two ways to achieve this: Metabase dashboards and Prometheus metrics.

Metabase dashboard

cscli allows you to deploy a dashboard using Metabase and Docker. Begin by installing Docker using its official documentation.

If you're using an AWS EC2 instance, be sure to expose tcp/3000 to access your dashboard.

cscli dashboard setup enables you to deploy a new Metabase dashboard running on Docker with a random password.

Prometheus metrics

While some people love visual dashboards, others prefer other kinds of metrics. This is where CrowdSec's Prometheus integration comes into play.

One way to visualize these metrics is with cscli metrics.

The cscli metrics command exposes only a subset of Prometheus metrics that are important for system administrators. You can find a detailed description of the metrics in the documentation. The metrics are split into sections:

  • Buckets: How many buckets of each type were created, poured, or have overflowed since the daemon startup?
  • Acquisition: How many lines or events were read from each of the specified sources, and were they parsed and/or poured into buckets later?
  • Parser: How many lines/events were delivered to each parser, and did the parser succeed in processing the mentioned events?
  • Local API: How many times was each route hit, and so on?

Viewing CrowdSec's Prometheus metrics via cscli metrics is convenient but doesn't do justice to Prometheus. It is out of scope for this article to deep dive into Prometheus, but these screenshots offer a quick look at what CrowdSec's Prometheus metrics look like in Grafana.

Defend attacks with bouncers

CrowdSec's detection capabilities provide observability into what is going on. However, to protect yourself, you need to block attackers, which is where bouncers play a major part. Remember: CrowdSec detects, bouncers deter.

Bouncers work by querying CrowdSec's API to know when to block an IP. You can download bouncers directly from the CrowdSec Hub.

For this example, use cs-firewall-bouncer. It directly bans any malevolent IP at the firewall level using iptables or nftables.

Note: If you used your IP to simulate attacks, unban your IP before going further: 

sudo cscli decisions delete -i X.X.X.X

Install the bouncer

First, download the bouncer from the Hub:

$ wget
$ tar xvzf cs-firewall-bouncer.tgz
$ cd cs-firewall-bouncer-v0.0.5/

Install the bouncer with a simple install script:

The install script will check if you have iptables or nftables installed and prompt you to install if not.

Bouncers communicate with CrowdSec via a REST API, so check that the bouncer is registered on the API.

The last command (sudo cscli bouncers list) shows your newly installed bouncer.

Test the bouncer

Warning: Before going further, ensure you have another IP available to access your machine and that you will not kick yourself out. Using your smartphone's internet connection will work.

Now that you have a bouncer to protect you, try the test again.

Try to access the server at the end of the scan:

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

See how it turns out from the defender's point of view.

For the technically curious, cs-firewall-bouncer uses either nftables or iptables. Using nftables (used on Debian 10 by default) 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 backend used by the bouncer in /etc/crowdsec/cs-firewall-bouncer/cs-firewall-bouncer.yaml by changing the mode from nftables to iptables (ipset is required for iptables mode).

Get involved

Please share your feedback about the latest CrowdSec release. If you are interested in testing the software or would like to get in touch with the team, check the following links:

This article has been adapted from Most advanced CrowdSec IPS v.1.0.x is out: how-to guide, originally published on GBHackers on Security.

What to read next
User profile image.
Philippe Humeau graduated in 1999 as IT security engineer from EPITA (Paris, France).

Comments are closed.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.