Skip to main content
Version: v1.5.0

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.

sudo apt install crowdsec-custom-bouncer

Manual installation via script

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

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

From source

Run the following commands:

git clone
cd cs-custom-bouncer/
make release
tar xzvf crowdsec-custom-bouncer.tgz
cd crowdsec-custom-bouncer-v*/
sudo ./


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, 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 ./


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: add 3600 "test blacklist" del 3600 "test blacklist"