Skip to main content

Custom

CrowdSec

📚 Documentation 💠 Hub 💬 Discourse

ModeStream only
MetricsUnsupported
MTLSUnsupported
PrometheusSupported

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 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 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​

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​

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 :

<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​

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:

{
  "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 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 argument to give to the script that will be invoked.

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

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 192.168.1.1, CH etc).

piddir​

string

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

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