Custom

Invokes custom user scripts with new, expired and removed decisions from CrowdSec LAPI.

●Stream
×WAF / AppSec
×Captcha
×Bot Detection
×Remediation Metrics
×mTLS
✓Prometheus
GitHub·Hub

Feed CrowdSec Decisions to Custom Scripts

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

Set up the CrowdSec repositories.

Debian/Ubuntu

RHEL/Centos/Fedora

SH
sudo apt install crowdsec-custom-bouncer

SH
sudo yum install crowdsec-custom-bouncer

Manual

Assisted

Download the latest crowdsec-custom-bouncer release

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

Edit the configuration file to your desired settings:

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

Then enable the service:

SH
sudo systemctl enable --now crowdsec-custom-bouncer

From source

Clone the repository:

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

Build the binary:

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

Install the built release:

sudo ./install.sh

Edit the configuration file to your desired settings:

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

Then enable the service:

SH
sudo systemctl enable --now crowdsec-custom-bouncer

Default configuration

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

YAML
bin_path: <absolute_path_to_binary>
bin_args: []
feed_via_stdin: false # Invokes the binary once and feeds incoming decisions to its 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 are its Type (eg ban, captcha etc) and Value (eg 192.168.1.1, 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 practices

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 it is general best practice to set it to ["Ip"] by default if that is the script's 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

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

Invoke mode

warning

While the default mode, it is not recommended to use it, as calling a binary for each decision can be very costly when a lot are present.

The custom binary will be called with the following arguments :

TEXT

<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 (see the next section for more details)

Examples

TEXT

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

Stdin mode

In this mode, the custom binary will be executed when the bouncer starts and is expected to read data from stdin.

If the binary exits for any reason, it will be reinvoked up to max_retries times. If the maximum number of retries is exhausted, the bouncer will quit.

For each decision, the custom binary will be fed the serialized JSON object on stdin, one object per line.

The JSON object is:

JSON
{
  "duration": "143h58m15s",
  "origin": "CAPI",
  "scenario": "ssh:bruteforce",
  "scope": "Ip",
  "type": "ban",
  "value": "160.187.109.6",
  "id": 83676344,
  "action": "add"
}

duration: duration of the decision, in the go time.Duration format. Can be negative for delete decisions.
origin: origin of the decision. Can be crowdsec, cscli, cscli-import, CAPI, lists.
scenario: scenario that triggered the decision.
scope: Scope of the decision. Most likely Ip or Range with the default config, but can be any value set in your scenarios.
type: Type of the decision. Most likely ban or captcha with the default config, but can be any value set in your profiles.
value: Target of the decision.
id: id of the decision in the crowdsec database.
action: Either add or del.

Configuration Reference

`bin_path`

string

Absolute path to the binary that will be invoked

`bin_args`

[ ]string

Array of arguments to pass to the script that will be invoked.

This option is only supported if feed_via_stdin is set to true.

`feed_via_stdin`

boolean

Indicates whether the script will be fed 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

Only get IPs banned for triggering scenarios containing any of the provided words.

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

`scenarios_not_containing`

[ ]string

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

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

`scopes`

[ ]string

Decisions will be filtered on the provided scopes.

Example
YAMLExample
scopes: ["Ip"]

`origins`

[ ]string

Decisions will be filtered on the provided origins.

Example
YAMLExample
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 are its Type (eg ban, captcha etc) and Value (eg 192.168.1.1, CH etc).

`piddir`

string

warning

This field has been deprecated 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:

YAML
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

Installation​

Repository​

Manual​

Assisted​

From source​

Default configuration​

Logs​

Best practices​

Usage​

Invoke mode​

Examples​

Stdin mode​

Configuration Reference​

bin_path​

bin_args​

feed_via_stdin​

total_retries​

scenarios_containing​

scenarios_not_containing​

scopes​

origins​

cache_retention_duration​

piddir​

update_frequency​

daemonize​

log_mode​

log_dir​

log_level​

log_compression​

log_max_size​

log_max_backups​

log_max_age​

api_url​

api_key​

insecure_skip_verify​

prometheus​

enabled​

listen_addr​

listen_port​

Installation

Repository

Manual

Assisted

From source

Default configuration

Logs

Best practices

Usage

Invoke mode

Examples

Stdin mode

Configuration Reference

`bin_path`

`bin_args`

`feed_via_stdin`

`total_retries`

`scenarios_containing`

`scenarios_not_containing`

`scopes`

`origins`

`cache_retention_duration`

`piddir`

`update_frequency`

`daemonize`

`log_mode`

`log_dir`

`log_level`

`log_compression`

`log_max_size`

`log_max_backups`

`log_max_age`

`api_url`

`api_key`

`insecure_skip_verify`

`prometheus`

`enabled`

`listen_addr`

`listen_port`