Firewall

ModeStream only

MetricsSupported

MTLSSupported

PrometheusSupported

CrowdSec Remediation Component written in golang for firewalls.

When to Choose a Different Bouncer

The firewall bouncer is ideal for protecting infrastructure services like SSH, databases, and SMTP. If you are protecting a web application, consider using an WAF-capable bouncer instead: Nginx, OpenResty, Traefik, or HAProxy SPOA. These provide real-time HTTP inspection, virtual patching, and WAF capabilities that a firewall bouncer cannot offer. Learn more about AppSec.

For maximum protection on web-facing servers, you can run both a firewall bouncer (for IP-level blocking) and an WAF-capable bouncer (for HTTP-level inspection) side by side.

crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API and add them to a blocklist used by supported firewalls.

Supported firewalls:

iptables (IPv4 ✔️ / IPv6 ✔️ )
nftables (IPv4 ✔️ / IPv6 ✔️ )
ipset only (IPv4 ✔️ / IPv6 ✔️ )
pf (IPV4 ✔️ / IPV6 ✔️ )

Installation

Packages for crowdsec-firewall-bouncer are available on our repositories. You need to pick the package according to your firewall system :

info

To know if your system is using iptables or nftables, you can run the following command:

iptables -V If you see the mention of 'nf_tables' in the output, you are using nftables.

IPTables

Debian/Ubuntu
RHEL/Centos/Fedora

SH
sudo apt install crowdsec-firewall-bouncer-iptables

SH
sudo yum install crowdsec-firewall-bouncer-iptables

NFTables

Debian/Ubuntu
RHEL/Centos/Fedora

SH
sudo apt install crowdsec-firewall-bouncer-nftables

SH
sudo yum install crowdsec-firewall-bouncer-nftables

pf

FreeBSD

SH
sudo pkg install crowdsec-firewall-bouncer

Continue with the pf setup section.

See as well Manual Installation documentation below

pf setup (FreeBSD)

The pf mode relies on the pfctl command to alter pf tables. You must create the CrowdSec tables and reference them in your pf.conf.

1) Enable `pf`

pf is not always loaded/enabled by default.

SH
sudo kldload pf
sudo sysrc pf_enable="YES"

2) Configure `/etc/pf.conf`

Add the CrowdSec tables and blocking rules (adjust to your existing ruleset):

/etc/pf.conf
PF/etc/pf.conf
# create crowdsec ipv4 table
table <crowdsec-blacklists> persist

# create crowdsec ipv6 table
table <crowdsec6-blacklists> persist

block drop in quick from <crowdsec-blacklists> to any
block drop in quick from <crowdsec6-blacklists> to any

Reload and verify:

SH
sudo pfctl -f /etc/pf.conf
sudo pfctl -sr
sudo service pf check
sudo service pf status

3) Configure the bouncer

Generate an API key:

SH
sudo cscli bouncers add --name freebsd-pf-bouncer

Edit the bouncer configuration file on FreeBSD (/usr/local/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml) and set at least:

YAML
api_url: http://127.0.0.1:8080/
api_key: <your_api_key>
mode: pf

Then enable and start it:

SH
sudo sysrc crowdsec_firewall_enable="YES"
sudo service crowdsec_firewall start
sudo service crowdsec_firewall status

Configuration

There are two primary ways to use the firewall bouncer:

managed (default): cs-firewall-bouncer will create ipset/nft sets, insert the associated firewall rules and manage the set contents
set only: you already have a (complex) firewall setup, cs-firewall-bouncer will only manage the content of existing specified sets

Managed mode : Iptables/ipset or Nftables

This is the default behaviour

In "managed" mode (mode nftables or iptables), component creates all the needed elements (rules, sets) and insert the appropriate rules in nftables or iptables.

warning

IPSet (when using iptables mode) does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds.

Set Only : Iptables/Ipset table

In iptables set-only mode (mode ipset), the component only handles the contents of sets that are specified by blacklists_ipv4 and blacklists_ipv6. These sets must be created before starting the component, and it is the user's responsibility to create the associated iptables rules.

warning

IPSet does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds.

Set Only : nftables

In nftables set only mode (mode nftables with nftables.{ipv4,ipv6}.set-only set to true), the component only manages the contents of the sets. It's the user's responsibility to create the associated chains and sets :

/tmp/bouncer.nft
YAML/tmp/bouncer.nft
table ip crowdsec {
	set crowdsec-blacklists {
		type ipv4_addr
		flags timeout
	}

	chain crowdsec-chain {
		type filter hook input priority filter; policy accept;
		ip saddr @crowdsec-blacklists drop
	}
}
table ip6 crowdsec6 {
	set crowdsec6-blacklists {
		type ipv6_addr
		flags timeout
	}

	chain crowdsec6-chain {
		type filter hook input priority filter; policy accept;
		ip6 saddr @crowdsec6-blacklists drop
	}
}

Metrics

info

CrowdSec v1.6.3 and Firewall Remediation Component v0.0.30 are minimum versions required to have metrics.

You can check the metrics generated by the firewall-bouncer using the command cscli metrics show bouncers.

firewall-bouncer-metrics

Each line in the output represents a different source of blocked IPs, along with detailed metrics.

Origin refers to the name of the source, which could be:
- CAPI - The community blocklist that you receive in exchange for the information you provide to the network
- crowdsec (security engine) - The decisions made by your Security Engine based on triggered scenarios
- lists:* - Various lists to which you are subscribed
active_decisions IPs represents the number of IPs contained in the respective list
dropped bytes & packets indicates the number of bytes and packets dropped by the firewall due to the actions of the specified origin
processed bytes & packets is only present for the Total line, as it denotes the overall number of bytes and packets processed by your firewall.

As the firewall bouncer operates at the network level, most malicious programs will not progress beyond attempting to establish a connection (and being denied). Therefore, metrics cannot reflect the "potentially saved traffic."

Ipset only mode

If you are running ipset only mode, crowdsec-firewall-bouncer tries parsing the output to produce metrics, but:

"managed" firewalls such ufw might confuse parser and lead to inconsistent metrics.
"total" counters amount since the machine start, or iptables counter are reset, which can lead to inconsistent metrics.

Configuration Reference

You can find a default configuration hosted on the Github Repository this is provided with the installation package.

`pid_dir`

Depreacted

Directory to store the pid file

`daemonize`

Deprecated

Run the component in the background

warning

This field has now been deprecated and is ignored within the component

`mode`

iptables | nftables | ipset | pf

Firewall mode to use

`update_frequency`

string (That is parseable by time.ParseDuration)

Frequency to contact the API for new/deleted decisions

`scenarios_containing`

[ ]string

Get only IPs banned for triggering scenarios containing either of provided word.

Example
YAMLExample
scenarios_containing: ["ssh", "http"]

`scenarios_not_containing`

[ ]string

Ignore IPs banned for triggering scenarios containing either of provided word.

Example
YAMLExample
scenarios_not_containing: ["ssh", "http"]

`scopes`

[ ]string

Decisions will be filtered on the provided scopes.

Example
YAMLExample
scopes: ["Ip", "Range"]

`origins`

[ ]string

Decisions will be filtered on the provided origins.

Example
YAMLExample
origins: ["cscli", "crowdsec"]

`log_mode`

file | stdout

Where the log contents are written (With file it will be written to log_dir with the name crowdsec-firewall-bouncer.log)

`log_dir`

string

Log directory path, that will contain the log file

`log_level`

trace | debug | info | warn | error

Log level

`log_compression`

true | false

Compress log files on rotation

`log_max_size`

int (in MB)

Max size of log files before rotation

`log_max_backups`

int

How many backup log files to keep before deletion (can happen before log_max_age is reached)

`log_max_age`

int (in days)

Max age of backup files before deletion (can happen before log_max_backups is reached)

`api_url`

string

URL of the local API EG: http://127.0.0.1:8080

`api_key`

string

API key to authenticate with the local API

`cert_path`

string

Path to the client certificate for authentication

`key_path`

string

Path to the certificate key used with cert_path

`ca_cert_path`

string

Path to the CA certificate to trust usually used in conjunction with cert_path and key_path

`insecure_skip_verify`

true | false

Skip verification of the API certificate, typical for self-signed certificates

`disable_ipv6`

true | false

disable interacting with ipv6 chains/sets, defaults to false

`disable_ipv4`

true | false

disable interacting with ipv4 chains/sets, defaults to false

`deny_action`

DROP | REJECT

firewall action to apply, defaults to DROP

`deny_log`

true | false

if set to true, enables logging of dropped packets (ie. -j LOG)

`deny_log_prefix`

string

if logging is true, this sets the log prefix, defaults to "crowdsec: "

Iptables/Ipset specific directives

`iptables_chains`

[]string

specify a list of chains to insert rules into both ipv4 and ipv6

YAML
iptables_chains:
  - INPUT
  #- FORWARD
  #- DOCKER-USER

info

If you are using a dockerized application and allow remote connections to the exposed port, you need to add the DOCKER-USER chain to the list of chains.

`iptables_v4_chains`

[]string

Specify a list of chains to insert rules into ipv4 only

YAML
iptables_v4_chains:
  - INPUT
  - DOCKER-USER

`iptables_v6_chains`

[]string

Specify a list of chains to insert rules into ipv6 only

YAML
iptables_v6_chains:
  - INPUT

`blacklists_ipv4`

string

name of the ipv4 set

`blacklists_ipv6`

name of the ipv6 set

`ipset_size`

int

maximum number of entries in the ipset (default: 131072)

`ipset_type`

string

type to use for the set (default: nethash)

info

The default value for ipset_size has been raised in v0.0.28 (from 65536) to allow for larger blocklists.

Nftables specific directives

Nftables mode has its own nftables section, with sub-section of ipv4 and ipv6 :

YAML
## nftables
nftables:
  ipv4:
    enabled: true
    set-only: false
    table: crowdsec
    chain: crowdsec-chain
  ipv6:
    enabled: true
    set-only: false
    table: crowdsec6
    chain: crowdsec6-chain

`enabled`

true | false

Enable or disable ipv4 or ipv6

`set-only`

true | false

If set-only is set to true, the component will only manage the set contents.

`table`

string

Name of the nftables table

`chain`

string

Name of the nftables chain

Manual installation

Assisted

First, download the latest crowdsec-firewall-bouncer release.

SH
$ tar xzvf crowdsec-firewall-bouncer.tgz
$ sudo ./install.sh

From source

Run the following commands:

SH
git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git
cd cs-firewall-bouncer/
make release
tar xzvf crowdsec-firewall-bouncer.tgz
cd crowdsec-firewall-bouncer-v*/
sudo ./install.sh

Upgrade

If you already have crowdsec-firewall-bouncer installed, please download the latest release and run the following commands:

SH
tar xzvf crowdsec-firewall-bouncer.tgz
cd crowdsec-firewall-bouncer-v*/
sudo ./upgrade.sh

Configuration for manual installation

To be functional, the crowdsec-firewall-bouncer service must be able to authenticate with the local API. The install.sh script will take care of it (it will call cscli bouncers add on your behalf). If it was not the case, the default configuration is in /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.

You can then start the service:

SH
sudo systemctl enable --now crowdsec-firewall-bouncer

If you need to make changes to the configuration file and be sure they will never be modified or reverted by package upgrades, starting from v0.0.25 you can write them in a crowdsec-firewall-bouncer.yaml.local file as described in Overriding values. Package upgrades may have good reasons to modify the configuration, so be careful if you use a .local file.

logs

logs can be found in /var/log/crowdsec-firewall-bouncer.log

modes

mode nftables relies on github.com/google/nftables to create table, chain and set.
mode iptables relies on iptables and ipset commands to insert match-set directives and maintain associated ipsets
mode ipset relies on ipset and only manage contents of the sets (they need to exist at startup and will be flushed rather than created)
mode pf relies on pfctl command to alter the tables. You are required to create the following tables on your pf.conf configuration:

SH
 # create crowdsec ipv4 table
table <crowdsec-blacklists> persist

# create crowdsec ipv6 table
table <crowdsec6-blacklists> persist

You can refer to the step-by-step instructions of the [user tutorial on FreeBSD in the pf setup section.

ipset

ipset lists have to exist before crowdsec-firewall-bouncer starts. You can create them and add them to your iptables like this:

SH
ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000
ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000
iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP
ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP

Installation
pf setup (FreeBSD)
Configuration
Metrics
- Ipset only mode
Configuration Reference
Iptables/Ipset specific directives
Nftables specific directives
Manual installation

CrowdSec

Console

Centralized, real-time visibility across all your engines.

Free 3rd-party Blocklists

Additional Alert Context

Stack-wide health metrics

Installation​

IPTables​

NFTables​

pf​

pf setup (FreeBSD)​

1) Enable pf​

2) Configure /etc/pf.conf​

3) Configure the bouncer​

Configuration​

Managed mode : Iptables/ipset or Nftables​

Set Only : Iptables/Ipset table​

Set Only : nftables​

Metrics​

Ipset only mode​

Configuration Reference​

pid_dir​

daemonize​

mode​

update_frequency​

scenarios_containing​

scenarios_not_containing​

scopes​

origins​

log_mode​

log_dir​

log_level​

log_compression​

log_max_size​

log_max_backups​

log_max_age​

api_url​

api_key​

cert_path​

key_path​

ca_cert_path​

insecure_skip_verify​

disable_ipv6​

disable_ipv4​

deny_action​

deny_log​

deny_log_prefix​

Iptables/Ipset specific directives​

iptables_chains​

iptables_v4_chains​

iptables_v6_chains​

blacklists_ipv4​

blacklists_ipv6​

ipset_size​

ipset_type​

Nftables specific directives​

enabled​

set-only​

table​

chain​

Manual installation​

Assisted​

From source​

Upgrade​

Configuration for manual installation​

logs​

modes​

ipset​

Installation

IPTables

NFTables

pf

pf setup (FreeBSD)

1) Enable `pf`

2) Configure `/etc/pf.conf`

3) Configure the bouncer

Configuration

Managed mode : Iptables/ipset or Nftables

Set Only : Iptables/Ipset table

Set Only : nftables

Metrics

Ipset only mode

Configuration Reference

`pid_dir`

`daemonize`

`mode`

`update_frequency`

`scenarios_containing`

`scenarios_not_containing`

`scopes`

`origins`

`log_mode`

`log_dir`

`log_level`

`log_compression`

`log_max_size`

`log_max_backups`

`log_max_age`

`api_url`

`api_key`

`cert_path`

`key_path`

`ca_cert_path`

`insecure_skip_verify`

`disable_ipv6`

`disable_ipv4`

`deny_action`

`deny_log`

`deny_log_prefix`

Iptables/Ipset specific directives

`iptables_chains`

`iptables_v4_chains`

`iptables_v6_chains`

`blacklists_ipv4`

`blacklists_ipv6`

`ipset_size`

`ipset_type`

Nftables specific directives

`enabled`

`set-only`

`table`

`chain`

Manual installation

Assisted

From source

Upgrade

Configuration for manual installation

logs

modes

ipset