Skip to main content

Custom

CrowdSec

📚 Documentation 💠 Hub 💬 Discourse

CrowdSec Remediation Component written to invoke 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​

Repository​

Setup crowdsec repositories.

sudo apt install crowdsec-custom-bouncer

Manual​

Assisted​

Download the latest crowdsec-custom-bouncer release

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

Edit the configuration file to your desired settings:

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

Then enable the service:

sudo systemctl enable --now crowdsec-custom-bouncer

From source​

Clone the repository:

git clone https://github.com/crowdsecurity/cs-custom-bouncer && cd cs-custom-bouncer

Build the binary:

make release && cd crowdsec-custom-bouncer-v*

Install the build release:

sudo ./install.sh

Edit the configuration file to your desired settings:

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

Then enable the service:

sudo systemctl enable --now crowdsec-custom-bouncer

Default configuration​

sudo vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml
bin_path: <absolute_path_to_binary>
bin_args: []
feed_via_stdin: false # Invokes binary once and feeds incoming decisions to it's stdin.
total_retries: 0 
scenarios_containing: [] # ignore IPs banned for triggering scenarios not containing either of provided word, eg ["ssh", "http"]
scenarios_not_containing: [] # ignore IPs banned for triggering scenarios containing either of provided word
scopes: []  # scopes of the decisions to filter on
origins: [] # origins of the decisions to filter on
piddir: /var/run/
update_frequency: 10s
cache_retention_duration: 10s
daemonize: true
log_mode: file
log_dir: /var/log/
log_level: info
log_compression: true
log_max_size: 100
log_max_backups: 3
log_max_age: 30
api_url: <API_URL>
api_key: <API_KEY>

prometheus:
  enabled: true
  listen_addr: 127.0.0.1
  listen_port: 60602

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.

Logs​

By default you can find the log file /var/log/crowdsec-custom-bouncer.log, however, this can change if you have changed the configuration.

Best pratices​

We recommend using the scopes configuration to filter the scope your script is interested in. This will ensure you get the expected values in your script.

This is only applicable if you have configured your profiles to make use of scopes but is general best pratice to set it to ["Ip"] by default if that is the script aim.

The above will ensure you get values from LAPI to the script, however, you should double check the values in your script to ensure they are as expected.

Usage​

The custom binary will be called with the following arguments :

<my_custom_binary> add <value> <duration> <reason> <json_object> # to add an IP address
<my_custom_binary> del <value> <duration> <reason> <json_object> # to del an IP address
  • value : The value will be the decision scope value (eg 192.168.1.1 for IP)
  • duration: duration of the remediation in seconds
  • reason : reason of the decision
  • json_object: the serialized decision
warning

Remember to set execution permissions for your binary or script. If it's a script, include a shebang on the first line (e.g., #!/bin/sh).

Examples​

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

Configuration Reference​

bin_path​

string

Absolute path to the binary that will be invoked

bin_args​

[ ]string

Array of argument to give to the script that will be invoked

feed_via_stdin​

boolean

Indicate weither or not the script will will be feed via STDIN or via its arguments

total_retries​

int

Number of times to restart binary. relevant if feed_via_stdin=true. Set to -1 for infinite retries.

scenarios_containing​

[ ]string

Get only IPs banned for triggering scenarios containing either of provided word.

Example
scenarios_containing: ["ssh", "http"]

scenarios_not_containing​

[ ]string

Ignore IPs banned for triggering scenarios containing either of provided word.

Example
scenarios_not_containing: ["ssh", "http"]

scopes​

[ ]string

Decisions will be filtered on the provided scopes.

Example
scopes: ["Ip"]

origins​

[ ]string

Decisions will be filtered on the provided origins.

Example
origins: ["cscli", "crowdsec"]

cache_retention_duration​

string

The component 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).

piddir​

string

warning

This field has been depreacted and is ignored by the component

Directory to drop the PID file

update_frequency​

string (That is parseable by time.ParseDuration)

controls how often the component is going to query the local API

daemonize​

boolean

To run the component as a service

warning

This field has now been deprecated and is ignored within the component

log_mode​

file | stdout

Where the log contents are written (With file it will be written to log_dir with the name crowdsec-custom-bouncer.log)

log_dir​

string

Relevant if log_mode is file. This determines where to create log file.

log_level​

trace | debug | info | error

Log level: can be trace, debug, info, or error

log_compression​

boolean

Compress logs on rotation, true or false

log_max_size​

int

Maximum file size before rotation

log_max_backups​

int

How many backup log files to keep

log_max_age​

int

Log file max age before deletion

api_url​

string

URL of the CrowdSec Local API

api_key​

string

API Key to communicate with the CrowdSec Local API

insecure_skip_verify​

boolean

Skip verification of the LAPI certificate, usually used for self-signed certificates

prometheus​

PrometheusConfig

Prometheus configuration

enabled​

boolean

Enable or not the prometheus server

Example:

prometheus:
  enabled: true
  listen_addr: 127.0.0.1
  listen_port: 60602

listen_addr​

string

IP Address to listen on for the prometheus server

listen_port​

int

Port to listen on for the prometheus server

CrowdSec ConsoleCrowdSec Console