Skip to content

Commit

Permalink
Merge pull request #458 from crowdsecurity/update_custom_bouncer_doc
Browse files Browse the repository at this point in the history 
Update cusotm bouncer documentation
  • Loading branch information
@AlteredCoder
AlteredCoder authored Oct 9, 2023
2 parents 8b990c4 + 7f72796 commit c3bcf6f
Showing 1 changed file with 212 additions and 43 deletions.
255 changes: 212 additions & 43 deletions crowdsec-docs/docs/bouncers/custom.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ 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
## Installation

[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories).

Expand Down Expand Up @@ -56,50 +56,46 @@ sudo yum install crowdsec-custom-bouncer
</Tabs>




## Manual installation via script

First, download the latest [`crowdsec-custom-bouncer` release](https://github.com/crowdsecurity/cs-custom-bouncer/releases).

```sh
$ tar xzvf crowdsec-custom-bouncer.tgz
$ sudo ./install.sh
```

## From source

Run the following commands:

```bash
git clone https://github.com/crowdsecurity/cs-custom-bouncer.git
cd cs-custom-bouncer/
make release
tar xzvf crowdsec-custom-bouncer.tgz
cd crowdsec-custom-bouncer-v*/
sudo ./install.sh
```

# Configuration
## 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/`

### Basic

```sh
$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml
```

```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
origins: []
piddir: /var/run/
update_frequency: 10s
cache_retention_duration: 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>`
cache_retention_duration: 10s
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).
Expand All @@ -116,17 +112,7 @@ by package upgrades, starting from v0.0.12 you can write them in a `crowdsec-cus
Package upgrades may have good reasons to modify the configuration, so be careful if you use a `.local` file.


# Upgrade (for manual install only)

If you already have `crowdsec-custom-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-custom-bouncer/releases) and run the following commands to upgrade it:

```bash
tar xzvf crowdsec-custom-bouncer.tgz
cd crowdsec-custom-bouncer-v*/
sudo ./upgrade.sh
```

# Usage
### Usage

The custom binary will be called with the following arguments :

Expand All @@ -143,10 +129,193 @@ The custom binary will be called with the following arguments :
:warning: 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:
### Examples

```bash
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 directives

#### `bin_path`
> type: string
Absolute path to the binary that will be invoked

#### `bin_args`
> type: array
Array of argument to give to the script that will be invoked

#### `feed_via_stdin`
> type: bool
Indicate weither or not the script will will be feed via STDIN or via its arguments

#### `total_retries`
> type: int
Number of times to restart binary. relevant if `feed_via_stdin=true`.
Set to -1 for infinite retries.

#### `scenarios_containing`
> type: array
Get only IPs banned for triggering scenarios containing either of provided word, eg ["ssh", "http"]

#### `scenarios_not_containing`
> type: array
Ignore IPs banned for triggering scenarios containing either of provided word, eg ["ssh", "http"]


#### `scopes`
> type: array
Decisions will be filtered on the provided scopes.

#### `origins`
> type: array
Decisions will be filtered on the provided origins.

#### `cache_retention_duration`
> type: string
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).

#### `piddir`

Directory to drop the PID file

#### `update_frequency`
> type: string
controls how often the bouncer is going to query the local API

#### `daemonize`
> type: bool
To run the bouncer as a service

#### `log_mode`
> type: string
Logging mode: can be `file` or `stdout`

#### `log_dir`
> type: string
Log folder path

#### `log_level`
> type: string
Log level: can be `trace`, `debug`, `info`, or `error`

#### `log_compression`
> type: bool
Compress logs on rotation, `true` or `false`

#### `log_max_size`
> type: int
Maximum file size before rotation

#### `log_max_backups`
> type: int
How many backup log files to keep

#### `log_max_age`
> type: int
Log file max age before deletion

#### `api_url`
> type: string
URL of the CrowdSec Local API

#### `api_key`
> type: string
API Key to communicate with the CrowdSec Local API

#### `insecure_skip_verify`
> type: bool
Allow self-signed certificates for LAPI, `false` or `true`

#### `prometheus`
> type: object
Prometheus configuration

##### `enabled`
> type: bool
Enable or not the prometheus server

Example:

```yaml
prometheus:
enabled: true
listen_addr: 127.0.0.1
listen_port: 60602
```
##### `listen_addr`
> type: string

IP Address to listen on for the prometheus server

##### `listen_port`
> type: int

Port to listen on for the prometheus server

## Manual Installation

### Assisted

First, download the latest [`crowdsec-custom-bouncer` release](https://github.com/crowdsecurity/cs-custom-bouncer/releases).

```sh
$ tar xzvf crowdsec-custom-bouncer.tgz
$ sudo ./install.sh
```

### From source

Run the following commands:

```bash
custom_binary.sh add 1.2.3.4/32 3600 "test blacklist"
custom_binary.sh del 1.2.3.4/32 3600 "test blacklist"
git clone https://github.com/crowdsecurity/cs-custom-bouncer.git
cd cs-custom-bouncer/
make release
tar xzvf crowdsec-custom-bouncer.tgz
cd crowdsec-custom-bouncer-v*/
sudo ./install.sh
```

### Upgrade

If you already have `crowdsec-custom-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-custom-bouncer/releases) and run the following commands to upgrade it:

```bash
tar xzvf crowdsec-custom-bouncer.tgz
cd crowdsec-custom-bouncer-v*/
sudo ./upgrade.sh
```


### Logs

Logs can be found in `/var/log/crowdsec-custom-bouncer.log`

0 comments on commit c3bcf6f

Please sign in to comment.