Skip to main content
Version: v1.4.0

Custom Bouncer

CrowdSec

📚 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 ./install.sh

From source#

Run the following commands:

git clone https://github.com/crowdsecurity/crowdsec-custom-bouncer.gitcd crowdsec-custom-bouncer/make releasetar xzvf crowdsec-custom-bouncer.tgzcd 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: 10sdaemonize: truelog_mode: filelog_dir: /var/log/log_level: infoapi_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

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.tgzcd 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"