Skip to main content
Version: Next

Firewall Bouncer

📚 Documentation💠 Hub💬 Discourse

CrowdSec bouncer written in golang for firewalls.

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 :

IPTables​

sudo apt install crowdsec-firewall-bouncer-iptables

NFTables​

sudo apt install crowdsec-firewall-bouncer-nftables

pf​

sudo pkg install crowdsec-firewall-bouncer

See as well Manual Installation documentation below

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), bouncer creates all the needed elements (rules, sets) and insert the appropriate rules in nftables or iptables.

danger

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 iptable set-only mode (mode ipset), the bouncer only handles the contents of sets that are specified by blacklists_ipv4 and blacklists_ipv6. These sets must be created before starting the bouncer, and it is the user's responsibility to create the associated iptables rules.

danger

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 bouncer only manages the contents of the sets. It's the user's responsibility to create the associated chains and sets :

/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
    }
}

Configuration directives​

  • mode : can be set to iptables, nftables , ipset or pf
  • pid_dir : directory to drop pid file
  • update_frequency controls how often the bouncer is going to query the local API
  • daemonize : for systemd unit
  • log_mode : can be file or stdout
  • log_dir : log directory
  • log_level : can be trace, debug, info, or error
  • log_compression : compress logs on rotation, true or false
  • log_max_size : maximum file size before rotation
  • log_max_backups : how many backup log files to keep
  • log_max_age : oldest backup log file before deletion
  • api_url and api_key control local API parameters.
  • insecure_skip_verify : allow self-signed certificates for LAPI, false or true
  • disable_ipv6 : disable ipv6 support, defaults to false
  • deny_action : firewall action to apply, defaults to DROP, but can be REJECT
  • deny_log : if set to true, enables logging of dropped packets (ie. -j LOG)
  • deny_log_prefix : if logging is true, this sets the log prefix, defaults to "crowdsec: "

Iptables/Ipset specific directives​

  • iptables_chains : specify a list of chains to insert rules (only relevant in iptables mode) :
  • blacklists_ipv4 and blacklists_ipv6 : names of ipv4 and ipv6 sets
  • ipset_size: maximum number of entries in the ipset (default: 131072)
  • ipset_type: type to use for the set (default: nethash)
iptables_chains:
  - INPUT
#  - FORWARD
#  - DOCKER-USER

The default 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 :

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

if set-only is set to true, the bouncer will only manage the set contents.

Manual installation​

Assisted​

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

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

From source​

Run the following commands:

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:

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:

sudo systemctl start 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:
 # 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 to setup crowdsec-firewall-bouncer with pf.

ipset​

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

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