Custom Bouncer

📚 Documentation💠 Hub💬 Discourse

CrowdSec bouncers are written in golang for custom scripts.

The crowdsec-custom-bouncer will periodically fetch new, expired and removed decisions from the CrowdSec Local API and will pass them as arguments to a custom user script.

Installation from packages

Setup crowdsec repositories.

Debian/Ubuntu

sudo apt install crowdsec-custom-bouncer

RHEL/Centos/Fedora

sudo yum install crowdsec-custom-bouncer

Manual installation via script

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

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

From source

Run the following commands:

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

Configuration

Before starting the crowdsec-custom-bouncer service, please edit the configuration file to add your API URL and key. The default configuration file is located under : /etc/crowdsec/bouncers/

$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml

bin_path: <absolute_path_to_binary>
piddir: /var/run/
update_frequency: 10s
daemonize: true
log_mode: file
log_dir: /var/log/
log_level: info
api_url: <API_URL>  # when install, default is "localhost:8080"
api_key: <API_KEY>  # Add your API key generated with `cscli bouncers add --name <bouncer_name>`
cache_retention_duration: 10s 

cache_retention_duration : The bouncer keeps track of all custom script invocations from the last cache_retention_duration interval. If a decision is identical to some decision already present in the cache, then the custom script is not invoked. The keys for hashing a decision is it's Type (eg ban, captcha etc) and Value (eg 1.2.3.4, CH etc).

You can then start the service:

sudo systemctl start crowdsec-custom-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.12 you can write them in a crowdsec-custom-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.

Upgrade (for manual install only)

If you already have crowdsec-custom-bouncer installed, please download the latest release and run the following commands to upgrade it:

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

Usage

The custom binary will be called with the following arguments :

<my_custom_binary> add <ip> <duration> <reason> <json_object> # to add an IP address
<my_custom_binary> del <ip> <duration> <reason> <json_object> # to del an IP address

• ip : ip address to block <ip>/<cidr>
• duration: duration of the remediation in seconds
• reason : reason of the decision
• json_object: the serialized decision

⚠️ don't forget to add execution permissions to your binary/script. If it's a script, the first line must be a shebang (like #!/bin/sh).

Examples:

custom_binary.sh add 1.2.3.4/32 3600 "test blacklist"
custom_binary.sh del 1.2.3.4/32 3600 "test blacklist"