Skip to content

Commit

Permalink
enhance: reword bouncer usage to remediation
Browse files Browse the repository at this point in the history
  • Loading branch information
LaurenceJJones committed Jul 4, 2024
1 parent c1e02dc commit 8b18b38
Show file tree
Hide file tree
Showing 17 changed files with 180 additions and 172 deletions.
4 changes: 2 additions & 2 deletions crowdsec-docs/unversioned/bouncers/aws-waf.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ How often the remediation will contact LAPI to update its content.
> Environment variable: `BOUNCER_SUPPORTED_ACTIONS`
Which actions (ie, remediation type) the bouncer supports.
Which actions (ie, remediation type) the remediation supports.
List with any of the following: `ban`, `captcha`, `count`.
Expand Down Expand Up @@ -192,7 +192,7 @@ Must be one of `captcha`, `ban` or `count`.
> Environment variable: `BOUNCER_WAF_CONFIG_X_RULE_GROUP_NAME`
Name of the rule group the bouncer will create and add to the WAF ACL.
Name of the rule group the remediation will create and add to the WAF ACL.
Must be unique across all the configuration.
Expand Down
4 changes: 2 additions & 2 deletions crowdsec-docs/unversioned/bouncers/blocklist-mirror.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ Used to nest the configuration related to crowdsec.
#### `lapi_url`
> string
The URL of CrowdSec LAPI. It should be accessible from whichever network the bouncer has access.
The URL of CrowdSec LAPI. It should be accessible from whichever network the remediation has access.

#### `lapi_key`
> string
Expand Down Expand Up @@ -292,7 +292,7 @@ Package upgrades may have good reasons to modify the configuration, so be carefu

## Formats

The bouncer can expose the blocklist in the following formats. You can configure the format of the blocklist by setting it's `format` parameter to any of the supported formats described below.
The remediation can expose the blocklist in the following formats. You can configure the format of the blocklist by setting it's `format` parameter to any of the supported formats described below.

### plain_text

Expand Down
10 changes: 5 additions & 5 deletions crowdsec-docs/unversioned/bouncers/cloudflare.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ cloudflare_config:

update_frequency: 30s # the frequency to update the cloudflare IP list

# Bouncer Config
# Remediation Config
daemon: true
log_mode: file
log_dir: /var/log/
Expand Down Expand Up @@ -249,7 +249,7 @@ The remediation binary has built in helper scripts to do various operations.

### Auto config generator

Generates bouncer config by discovering all the accounts and the zones associated with provided list of tokens.
Generates remediation config by discovering all the accounts and the zones associated with provided list of tokens.

Example Usage:

Expand Down Expand Up @@ -278,7 +278,7 @@ sudo crowdsec-cloudflare-bouncer -s

### Cloudflare Cleanup

This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer.
This deletes all IP lists and firewall rules at cloudflare which were created by the remediation.

Example Usage:
```bash
Expand Down Expand Up @@ -444,7 +444,7 @@ Valid choice includes either of
- `challenge`
- `managed_challenge`.

The bouncer creates an IP list for each action. IP list is at account level, so multiple zones with same parent account will share lists for particular action.
The remediation creates an IP list for each action. IP list is at account level, so multiple zones with same parent account will share lists for particular action.

:::warning
`challenge` action is deprecated in favour of `managed_challenge`
Expand All @@ -467,7 +467,7 @@ Following table is mapping of decision type to it's destination IP list, which a
> boolean

:::warning
This field has now been deprecated as is ignored within the remediation
This field has now been deprecated and is ignored within the remediation
:::

Run the remediation as a daemon.
Expand Down
10 changes: 7 additions & 3 deletions crowdsec-docs/unversioned/bouncers/custom.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ origins: ["cscli", "crowdsec"]
### `cache_retention_duration`
> string

The bouncer keeps track of all custom script invocations from the last `cache_retention_duration` interval.
The remediation 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 @@ -281,12 +281,16 @@ Directory to drop the PID file
### `update_frequency`
> string (That is parseable by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration))

controls how often the bouncer is going to query the local API
controls how often the remedation is going to query the local API

### `daemonize`
> boolean

To run the bouncer as a service
To run the remediation as a service

:::warning
This field has now been deprecated and is ignored within the remediation
:::

### `log_mode`
> `file` | `stdout`
Expand Down
10 changes: 5 additions & 5 deletions crowdsec-docs/unversioned/bouncers/fastly.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';

# cs-fastly-bouncer

A bouncer that syncs the decisions made by CrowdSec with Fastly's VCL. Manages multi account, multi service setup. Supports IP, Country and AS scoped decisions.
A remedation that syncs the decisions made by CrowdSec with Fastly's VCL. Manages multi account, multi service setup. Supports IP, Country and AS scoped decisions.
To learn how to setup crowdsec to consume fastly logs see [this](/docs/next/user_guides/consuming_fastly_logs)


Expand Down Expand Up @@ -69,7 +69,7 @@ sudo cscli -oraw bouncers add fastlybouncer # -oraw flag can discarded for human

The `lapi_url` must be accessible from the container.

### Run the bouncer
### Run the remediation

```bash
docker run \
Expand All @@ -80,7 +80,7 @@ The `lapi_url` must be accessible from the container.

## Activate the new configuration:

After starting the bouncer, go in the fastly web UI. For each configured service review the version created by the bouncer. If everything looks good, you can activate the new configration !
After starting the remediation, go in the fastly web UI. For each configured service review the version created by the bouncer. If everything looks good, you can activate the new configration !

# Configuration:

Expand Down Expand Up @@ -110,7 +110,7 @@ log_file: /var/log/crowdsec-fastly-bouncer.log # Ignore if logging to stdout or
# Helpers:
The bouncer has few builtin helper features:
The remediation has few builtin helper features:
## Auto config generator:
Expand All @@ -134,6 +134,6 @@ Crowdsec config is copied from the config at `PATH_TO_BASE_CONFIG`.
sudo crowdsec-fastly-bouncer -c <PATH_TO_BASE_CONFIG> -d
```

This deletes the fastly resources created by the bouncer.
This deletes the fastly resources created by the remediation.
It only works if the configured service version is not locked.
It is useful for quick iteration before activateing the new service.
6 changes: 5 additions & 1 deletion crowdsec-docs/unversioned/bouncers/firewall.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,11 @@ Directory to store the pid file
### `daemonize`
> Deprecated
Run the bouncer in the background
Run the remediation in the background

:::warning
This field has now been deprecated and is ignored within the remediation
:::

### `mode`
> `iptables` | `nftables` | `ipset` | `pf`
Expand Down
24 changes: 12 additions & 12 deletions crowdsec-docs/unversioned/bouncers/haproxy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,15 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
</p>


A lua bouncer for haproxy.
A lua remediation for haproxy.

:::warning
This bouncer is compatible with HAProxy version 2.5 and higher.
This remediation is compatible with HAProxy version 2.5 and higher.
:::

## How does it work ?

This bouncer leverages haproxy lua's API to check e IP address against the local API.
This remediation leverages haproxy lua's API to check e IP address against the local API.

Supported features:

Expand Down Expand Up @@ -64,7 +64,7 @@ sudo apt install crowdsec-haproxy-bouncer


:::info
In stream mode, the bouncer will launch an internal timer to pull the local API at the first request made to the server.
In stream mode, the remediation will launch an internal timer to pull the local API at the first request made to the server.
:::

### Manual installation
Expand Down Expand Up @@ -105,7 +105,7 @@ sudo systemctl restart haproxy

## Configuration

### Bouncer configuration
### Remediation configuration

```bash title="/etc/crowdsec/bouncers/crowdsec-haproxy-bouncer.conf"
API_KEY=<CROWDSEC_LAPI_KEY>
Expand Down Expand Up @@ -206,7 +206,7 @@ Validated ips are cached in a [Stick table](https://www.haproxy.com/blog/introdu
### Setup captcha
> Currently, we have support for 3 providers: recaptcha, hcaptcha or turnstile
If you want to use captcha with your HAProxy Bouncer, you must provide a Site key and Secret key in your bouncer configuration.
If you want to use captcha with your HAProxy remediation, you must provide a Site key and Secret key in your remediation configuration.
If you wish to use any other provider than recaptcha you **MUST** adapt the server name in the backend:
Expand Down Expand Up @@ -264,7 +264,7 @@ sudo cscli decisions add -i <IP_TO_TEST> -t captcha
### Why aren't decisions applied instantly
In stream mode, the bouncer will launch an internal timer to pull the local API at the first request. So the cache won't be refreshed until the first request hits the service.
In stream mode, the remediation will launch an internal timer to pull the local API at the first request. So the cache won't be refreshed until the first request hits the service.
### SSL and certificates
Expand All @@ -291,7 +291,7 @@ BOUNCING_ON_TYPE=all
```
Type of remediation we want to bounce.
If you choose `ban` only and receive a decision with `captcha` as remediation, the bouncer will skip the decision.
If you choose `ban` only and receive a decision with `captcha` as remediation, the remediation will skip the decision.
### `FALLBACK_REMEDIATION`
> ban | captcha
Expand All @@ -300,7 +300,7 @@ If you choose `ban` only and receive a decision with `captcha` as remediation, t
FALLBACK_REMEDIATION=ban
```
The fallback remediation is applied if the bouncer receives a decision with an unknown remediation.
The fallback remediation is applied if the remediation receives a decision with an unknown remediation.
### `REQUEST_TIMEOUT`
> int
Expand All @@ -309,7 +309,7 @@ The fallback remediation is applied if the bouncer receives a decision with an u
REQUEST_TIMEOUT=1000
```
Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or captcha provider (for the captcha verification).
Timeout in milliseconds for the HTTP requests done by the remediation to query CrowdSec local API or captcha provider (for the captcha verification).
### `EXCLUDE_LOCATION`
> string (Seperate by comma)
Expand Down Expand Up @@ -346,7 +346,7 @@ REDIRECT_LOCATION=/<path>
The location to redirect the user when there is a ban.
If it is not set, the bouncer will return the page defined in the `BAN_TEMPLATE_PATH` with the `RET_CODE` (403 by default).
If it is not set, the remediation will return the page defined in the `BAN_TEMPLATE_PATH` with the `RET_CODE` (403 by default).
### `BAN_TEMPLATE_PATH`
> string (path to file)
Expand Down Expand Up @@ -410,7 +410,7 @@ CAPTCHA_TEMPLATE_PATH=<path_to_html_template>
The path to a captcha HTML template.
The bouncer will try to replace `{{captcha_site_key}}` in the template with `SITE_KEY` parameter.
The remediation will try to replace `{{captcha_site_key}}` in the template with `SITE_KEY` parameter.
By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`.
Expand Down
34 changes: 17 additions & 17 deletions crowdsec-docs/unversioned/bouncers/ingress-nginx.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ import useBaseUrl from '@docusaurus/useBaseUrl';



A lua plugin bouncer for Ingress Nginx Controller.
A lua plugin remediation for Ingress Nginx Controller.

## How does it work ?

This bouncer leverages OpenResty lua's API, used the ingress nginx controller as a [plugin](https://github.com/kubernetes/ingress-nginx/blob/main/rootfs/etc/nginx/lua/plugins/README.md).
This remediation leverages OpenResty lua's API, used the ingress nginx controller as a [plugin](https://github.com/kubernetes/ingress-nginx/blob/main/rootfs/etc/nginx/lua/plugins/README.md).

Supported features:

Expand All @@ -38,7 +38,7 @@ Supported features:
- Works with IPv4/IPv6
- Support IP ranges (can apply a remediation on an IP range)

At the back, this bouncer uses [crowdsec lua lib](https://github.com/crowdsecurity/lua-cs-bouncer/).
At the back, this remediation uses [crowdsec lua lib](https://github.com/crowdsecurity/lua-cs-bouncer/).

## Installation

Expand Down Expand Up @@ -108,12 +108,12 @@ kubectl -n ingress-nginx get pods
```

:::info
In stream mode, the bouncer will launch an internal timer to pull the local API at the first request made to the ingress controller.
In stream mode, the remediation will launch an internal timer to pull the local API at the first request made to the ingress controller.
:::

### Ingress controller Configuration

The bouncer uses [lua_shared_dict](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#lua-shared-dicts) to share cache between all workers.
The remediation uses [lua_shared_dict](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#lua-shared-dicts) to share cache between all workers.

If you want to increase the cache size you need to change this value :

Expand All @@ -123,13 +123,13 @@ controller:
lua-shared-dicts: "crowdsec_cache: 50m"
````

:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore.
:warning: Do not rename the `crowdsec_cache` shared dict, else the remediation will not work anymore.

#### When using captcha remediation

To make HTTP request in the bouncer, we need to set a `resolver` in the configuration. We choose `local=on` directive since we query `google.com` for the captcha verification, but you can replace it with a valid one.
To make HTTP request in the remediation, we need to set a `resolver` in the configuration. We choose `local=on` directive since we query `google.com` for the captcha verification, but you can replace it with a valid one.

To make secure HTTP request in the bouncer, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`).
To make secure HTTP request in the remediation, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`).
You can also change this with a valid one :
```
- /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo)
Expand Down Expand Up @@ -170,7 +170,7 @@ BOUNCING_ON_TYPE=all
```

Type of remediation we want to bounce.
If you choose `ban` only and receive a decision with `captcha` as remediation, the bouncer will skip the decision.
If you choose `ban` only and receive a decision with `captcha` as remediation, the remediation will skip the decision.

### `FALLBACK_REMEDIATION`
> ban | captcha
Expand All @@ -179,7 +179,7 @@ If you choose `ban` only and receive a decision with `captcha` as remediation, t
FALLBACK_REMEDIATION=ban
```

The fallback remediation is applied if the bouncer receives a decision with an unknown remediation.
The fallback remediation is applied if the remediation receives a decision with an unknown remediation.

### `MODE`
> stream | live
Expand All @@ -188,9 +188,9 @@ The fallback remediation is applied if the bouncer receives a decision with an u
MODE=stream
```

The bouncer mode:
- stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter).
- live: The bouncer will query the local API for each requests (if IP is not in cache) and will store the IP in cache for X seconds (`CACHE_EXPIRATION` parameter).
The remediation mode:
- stream: The remediation will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter).
- live: The remediation will query the local API for each requests (if IP is not in cache) and will store the IP in cache for X seconds (`CACHE_EXPIRATION` parameter).

:::note
The timer that pull the local API will be triggered after the first request.
Expand All @@ -203,7 +203,7 @@ The timer that pull the local API will be triggered after the first request.
REQUEST_TIMEOUT=1000
```

Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or captcha provider (for the captcha verification).
Timeout in milliseconds for the HTTP requests done by the remediation to query CrowdSec local API or captcha provider (for the captcha verification).

### `EXCLUDE_LOCATION`
> string (comma separated)
Expand All @@ -226,7 +226,7 @@ The locations to exclude while bouncing. It is a list of location, separated by
CACHE_EXPIRATION=120
```

The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode.
The cache expiration, in second, for IPs that the remediation store in cache in `live` mode.

### `UPDATE_FREQUENCY`
> int
Expand All @@ -251,7 +251,7 @@ REDIRECT_LOCATION=/<path>

The location to redirect the user when there is a ban.

If it is not set, the bouncer will return the page defined in the `BAN_TEMPLATE_PATH` with the `RET_CODE` (403 by default).
If it is not set, the remediation will return the page defined in the `BAN_TEMPLATE_PATH` with the `RET_CODE` (403 by default).

### `BAN_TEMPLATE_PATH`
> string (path to file)
Expand Down Expand Up @@ -327,7 +327,7 @@ CAPTCHA_TEMPLATE_PATH=<path_to_html_template>

The path to a captcha HTML template.

The bouncer will try to replace `{{captcha_site_key}}` in the template with `SITE_KEY` parameter.
The remediation will try to replace `{{captcha_site_key}}` in the template with `SITE_KEY` parameter.

By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/captcha.html`.

Expand Down
2 changes: 1 addition & 1 deletion crowdsec-docs/unversioned/bouncers/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Please keep this key since you will not be able to retrieve it!
```

:::info
This command must be run on the server where the local API is installed (or at least with a cscli that has valid credentials to communicate with the database used by the API). This is only necessary if you "manually" install a bouncer, packages and install scripts usually take care of this.
This command must be run on the server where the local API is installed (or at least with a cscli that has valid credentials to communicate with the database used by the API). This is only necessary if you "manually" install a remediation, packages and install scripts usually take care of this.
:::

If you wish to create your own remediation component, look at [this section](/docs/next/local_api/bouncers) of the local API documentation.
Expand Down
Loading

0 comments on commit 8b18b38

Please sign in to comment.