Skip to main content
Version: v1.4.0

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 to add them in 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 accord 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 main usage case around the firewall bouncer :

  • managed (default) : cs-firewall-bouncer will create ispet/nft sets, insert the associated firewall rules and manage set's content
  • 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 ispet), bouncer only manages the contents of sets designed by blacklists_ipv4 and blacklists_ipv6. Those sets must exist prior to the bouncer startup, and it is the user's responsability to create the associate 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), bouncer only manages the contents of the sets. It's the user's responsability 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
iptables_chains:
  - INPUT
#  - FORWARD
#  - DOCKER-USER

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 file is located under : /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml

You can then start the service:

Start CrowdSec service
sudo systemctl start crowdsec-firewall-bouncer

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 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 could 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