📚 Documentation 💠 Hub 💬 Discourse

crowdsec-custom-bouncer

Crowdsec bouncer written in golang for custom scripts.

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

Installation

With installer

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.git
cd crowdsec-custom-bouncer/
make release
tar xzvf crowdsec-custom-bouncer.tgz
cd crowdsec-custom-bouncer-v*/
sudo ./install.sh

Start

If your bouncer runs on the same machine as your crowdsec local API, you can start the service directly since the install.sh took care of the configuration.

sudo systemctl start crowdsec-custom-bouncer

Upgrade

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

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"

Configuration

Before starting the crowdsec-custom-bouncer service, please edit the configuration 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>`

You can then start the service:

sudo systemctl start crowdsec-custom-bouncer