diff --git a/crowdsec-docs/docs/bouncers/haproxy.mdx b/crowdsec-docs/docs/bouncers/haproxy.mdx index 10c54927..2427123b 100644 --- a/crowdsec-docs/docs/bouncers/haproxy.mdx +++ b/crowdsec-docs/docs/bouncers/haproxy.mdx @@ -279,7 +279,7 @@ API_KEY= CrowdSec Local API key. -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. +Generated with [`sudo cscli bouncers add`](/cscli/cscli_bouncers_add.md) command. ### `BOUNCING_ON_TYPE` ```bash diff --git a/crowdsec-docs/docs/bouncers/ingress-nginx.mdx b/crowdsec-docs/docs/bouncers/ingress-nginx.mdx index f55a41be..6a9a47de 100644 --- a/crowdsec-docs/docs/bouncers/ingress-nginx.mdx +++ b/crowdsec-docs/docs/bouncers/ingress-nginx.mdx @@ -149,7 +149,7 @@ API_KEY= CrowdSec Local API key. -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. +Generated with [`sudo cscli bouncers add`](/cscli/cscli_bouncers_add.md) command. ### `API_URL` ```bash diff --git a/crowdsec-docs/docs/bouncers/nginx.mdx b/crowdsec-docs/docs/bouncers/nginx.mdx index 6617a19d..33f2f7aa 100644 --- a/crowdsec-docs/docs/bouncers/nginx.mdx +++ b/crowdsec-docs/docs/bouncers/nginx.mdx @@ -277,7 +277,7 @@ API_KEY= CrowdSec Local API key. -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. +Generated with [`sudo cscli bouncers add`](/cscli/cscli_bouncers_add.md) command. ### `API_URL` ```bash diff --git a/crowdsec-docs/docs/bouncers/openresty.mdx b/crowdsec-docs/docs/bouncers/openresty.mdx index 885f1194..e6a9e837 100644 --- a/crowdsec-docs/docs/bouncers/openresty.mdx +++ b/crowdsec-docs/docs/bouncers/openresty.mdx @@ -282,7 +282,7 @@ API_KEY= CrowdSec Local API key. -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. +Generated with [`sudo cscli bouncers add`](/cscli/cscli_bouncers_add.md) command. ### `API_URL` ```bash diff --git a/crowdsec-docs/docusaurus.config.js b/crowdsec-docs/docusaurus.config.js index d657ae3c..782fee08 100644 --- a/crowdsec-docs/docusaurus.config.js +++ b/crowdsec-docs/docusaurus.config.js @@ -56,6 +56,12 @@ module.exports = { position: 'left', label: 'Cscli', }, + { + type: 'doc', + docId: 'bouncers/intro', + position: 'left', + label: 'Remediation', + }, { type: 'doc', docId: 'cti_api/getting_started', diff --git a/crowdsec-docs/versioned_docs/version-v0.3/bouncers b/crowdsec-docs/versioned_docs/version-v0.3/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v0.3/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v0.3/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v0.3/bouncers/intro.md deleted file mode 100644 index 977f2ca7..00000000 --- a/crowdsec-docs/versioned_docs/version-v0.3/bouncers/intro.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: v0.X not supported -id: intro ---- - -:::warning - -This version is not supported anymore. Migrate to v1.2.X or later. - -::: \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers b/crowdsec-docs/versioned_docs/version-v1.0/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.0/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/cloudflare.mdx deleted file mode 100644 index 8b98b7fe..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/cloudflare.mdx +++ /dev/null @@ -1,158 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -**WARNING**: This bouncer does not work for this version of Crowdsec. - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -# Installation - -## Install script - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -sudo cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # Verify the generated config and paste it in bouncer's config. -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - - -## From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - -**Always run `/usr/bin/crowdsec-cloudflare-bouncer -d` to cleanup cloudflare components before editing the config files.** - -# Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${LAPI_KEY} -crowdsec_update_frequency: 10s - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: challenge - zones: - - actions: - - challenge # valid choices are either of challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -cache_path: /var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json -``` - -## Cloudflare Configuration: - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/v1.0/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - -**Note:** If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. - -# Helpers - -The bouncer's 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. - -Example Usage: - -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -g ,... > cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -**Note:** This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. - -Using custom config: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup: - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup: - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. It also deletes the local cache. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -d -``` - -# How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - - -# Troubleshooting - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - The cache is at `/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json`. It can be inspected to see the state of bouncer and cloudflare components locally. - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/custom.mdx deleted file mode 100644 index 62d6338d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/custom.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for custom scripts. - -crowdsec-custom-bouncer will periodically fetch new and expired/removed decisions from CrowdSec Local API and will pass them as arguments to a custom user script. - -## Installation from packages - -[Setup crowdsec repositories](/docs/v1.0/getting_started/install_crowdsec#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## Manual install (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 - -Before starting the `crowdsec-custom-bouncer` service, please edit the configuration to add your API url and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -:warning: don't forget to add execution permissions to your binary/script - -### Examples: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/firewall.mdx deleted file mode 100644 index dd7c2415..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/firewall.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -### Using packages - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/docs/v1.0/getting_started/install_crowdsec#install-our-repositories). You need to pick the package accord to your firewall system: - -#### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -#### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -## Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -## Configuration - -**note : this is only relevant for "manual" or "from source" installation, as packages would take care of all the needed configuration** - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - -```yaml title="/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml" -mode: "iptables" -pid_dir: "/var/run/" -update_frequency: "10s" -daemonize: true -log_mode: "file" -log_dir: "/var/log/" -log_level: "info" -api_url: "" # when install, default is "localhost:8080" -api_key: "" # Add your API key generated with `cscli bouncers add --name ` -disable_ipv6: "false" -deny_mode: "DROP" -deny_log: "false -#deny_log_prefix: "crowdsec: " -#if present, insert rule in those chains -iptables_chains: - - "INPUT" - - "FORWARD" -``` - - - `mode` can be set to `iptables`, `nftables` , `ipset` or `pf` - - `update_frequency` controls how often the bouncer is going to query the local API - - `api_url` and `api_key` control local API parameters. - - `iptables_chains` allows (in _iptables_ mode) to control in which chain rules are going to be inserted. (if empty, bouncer will only maintain ipset lists) - - `disable_ipv6` - set to true to disable ipv6 - - `deny_mode` - what action to use to deny, one of DROP or REJECT - - `deny_log` - set this to true to add a log statement to the firewall rule - - `deny_log_prefix` - if logging is true, this sets the log prefix, defaults to "crowdsec: " - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/ingress-nginx.mdx deleted file mode 100644 index b77f2ae0..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; # If you want captcha support otherwise remove this line -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/intro.md deleted file mode 100644 index 4f6ade3d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/docs/v1.0/local_api/intro) to be able to get informations about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/docs/v1.0/local_api/bouncers) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/nginx.mdx deleted file mode 100644 index 8d73f86e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/nginx.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/openresty.mdx deleted file mode 100644 index deb00ace..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/openresty.mdx +++ /dev/null @@ -1,416 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`). You can also change this with a valid one. - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.0/bouncers/wordpress.mdx deleted file mode 100644 index 28d0b138..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.0/bouncers/wordpress.mdx +++ /dev/null @@ -1,498 +0,0 @@ ---- -id: wordpress -title: Wordpress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## How does it work ? - -This wordpress plugin allows you to apply decisions from crowdsec directly within the wordpress application. - -It relies on the [associated php library](https://github.com/crowdsecurity/php-cs-bouncer) and provides the ability to not only block users, but challenge them with captchas. - -## Installation - -The bouncer itself can be installed from the marketplace in wordpress back-office : - -

-CrowdSec -

- -## Configuration - -You only need to configure your local API endpoint and API key so the bouncer can get its decisions from crowdsec : - -

-CrowdSec -

- -A key point of the bouncer is to allow not only to block users, but as well to present them with captchas : - -

-CrowdSec -

- - -## Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - -## WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Developer resources - -### Install with `docker-compose` - -#### Install the wordpress and the plugin locally using docker-compose - -Follow this guide to get the development stack installed locally. - -> Prerequises: -> -> - you should have [`docker`](https://docs.docker.com/get-docker/) installed -> - `docker` should be [`runnable without sudo`](https://docs.docker.com/engine/install/linux-postinstall/). -> - [`docker-compose`](https://docs.docker.com/compose/install/) installed locally. -> - IPv6 should be enable in your docker configuration. Enabled it following [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll may have to create the file `/etc/docker/daemon.json`). -> - If your develop environnment is MacOS, please refer to the [MacOS host installation guide](wordpress#contribute-to-this-plugin-from-a-macos-host). - -##### Install the stack for development purpose - -Before all, create a `.env` file, using: - -```bash -cp .env.example .env -``` - -> Note about PHP 8.0: WordPress official docker image [does not officially supports PHP 8.0](https://hub.docker.com/_/wordpress?tab=tags&page=1&ordering=last_updated) at this time. However, as the CrowdSec PHP Library does support PHP 8.0, there is a good chance that the plugin will work fine with PHP 8.0, but we can not currently test it. - -##### Configure WordPress and the CrowdSec Plugin - -Now there are two options, you can fill the Wordpress installation wizard manually OR use let the e2e tests to do it for you. - -###### A) Automatic configuration - -Install Wordpress instance and activate plugin launching the e2e tests (limited to the installation steps): - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -###### B) Manual comfiguration - -Alternatively, you can install wordpress and the plugin manually with: - -```bash -docker-compose up -d wordpress crowdsec mysql redis memcached -``` - -Then visit the wordpress instance here: http://localhost and install the wordpress instance. - -##### Infos to setup the plugin - -###### Get a bouncer key - -```bash -docker-compose exec crowdsec cscli bouncers add wordpress-bouncer -``` - -###### LAPI URL - -``` -http://crowdsec:8080 -``` - -##### Try the plugin behavior - -| Info | Value | -| --------------- | ------------------------------------ | -| Public blog URL | http://localhost | -| Blog admin URL | http://localhost/wp-admin | -| Admin username | `admin` | -| Pasword | `my_very_very_secret_admin_password` | - -### Demo guide - - -#### Full guide - -This guide exposes you the main features of the plugin. - -##### Let's get started! - -We will start using "live" mode. You'll understand what it is after try the stream mode. - -* First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). - -* open a terminal to display LAPI logs in realtime: - -```bash -docker-compose logs -f crowdsec -``` - -* In wp-admin, [ensure the bouncer is configured with **live** mode](http://localhost/wp-admin/admin.php?page=crowdsec_plugin) (stream mode disabled). - -###### Discover the cache system - -* In a tab, visit the [public home](http://localhost/). You're allowed because LAPI said your IP is clean. - -> To avoid latencies when the clean IP browse the website, the bouncer will keep this information in cache for 30 seconds (you can change this value in the [avdanced settings page](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings)). In other words, LAPI will not be requested to check this IP for the next 30 seconds. - - * You can call the website as many times as you want, the cache system will take relay during the ban period and so LAPI will not be disturbed. The ban decision will stay in cache for the full ban duration. Then the [public home](http://localhost/) should be available again. - - ###### Try ban remediation - -* If you want to skip this delay, feel free to [clear the cache in the wp-admin](http://localhost/wp-admin/admin.php?page=crowdsec_plugin). - -The `DOCKER_HOST_IP` environnement variable is initialized via a call to: - -```bash -source ./load-env-vars.sh -``` - -* In a terminal, ban your own IP for 4 hours: - -```bash - -# Ban your own IP for 4 hours: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* Immediately, the [public home](http://localhost/) is now locked with a short message to explain you that you are banned. - -###### Try "captcha" remediation - - -* Now, request captcha for your own IP for 15m: - -```bash - -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all - -# Add a captcha -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha -``` - -* The [public home](http://localhost/) now request you to fill a captcha. - -* Unless you manage to solve the captcha, you'll not be able to access the website. - -> Note: when you resolve the captcha in your browser, the associated PHP session is considered as sure. -> If you remove the captcha decision with `cscli`, then you add a new captcha decision for your IP, you'll not be prompted for the current PHP session. To view the captcha page, You can force using a new PHP session opening the front page with incognito mode. - -##### Stream mode, for the high traffic websites - -With live mode, as you tried it just before, each time a user arrives to the website for the first time, a call is made to LAPI. If the traffic on your website is high, the bouncer will call LAPI very often. - -To avoid this, LAPI offers a "stream" mode. The decisions list is updated at a predefined frequency and kept in cache. Let's try it! - -> This bouncer uses the WordPress cron system. For demo purposes, we encourage you to [install the WP-Control plugin](http://localhost/wp-admin/plugin-install.php?s=wp-control&tab=search&type=term), a plugin to view and control each Wordpress Cron task jobs. - -First, clear the previous decisions: - -```bash -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all -``` - -* Then enable "stream" mode [right here](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) and set the resync frequency to 30 seconds. If you installed WP-Control plugin, you can see that a new cron tak has just been added here http://localhost/wp-admin/tools.php?page=crontrol_admin_manage_page. - -* As the whole blocklist has just been loaded in cache (0 decision!), your IP is allowed. The [public home](http://localhost/) is available. - -* Now, if you ban your IP for 4h: - -```bash -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* In less than 30 seconds your IP will be banned and the [public home](http://localhost/) will be locked. - -Conclusion: with the stream mode, LAPI decisions are fetched on a regular basis rather than being called when user arrives for the first time. - -#### Try Redis or Memcached - -In order to get better performances, you can switch the cache technology. - -The docker-compose file started 2 unused containers, redis and memcached. - -Let's try **Redis**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Redis" and -- type `redis://redis:6379` in the "Redis DSN" field. - -Very similar with **Memcached**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Memcached" and -- type `memcached://memcached:11211` in the "Memcached DSN" field. - - -#### Statistics - -The bouncer has a stats page indicating each time : -- an IP has been banned by your website, or -- when a captcha has been presented to an IP visiting your website -- when a captcha has been solved or not. - - -### How to contribute? - -#### Contribute to this plugin - -> First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). -#### Play with crowdsec state - -```bash - -#### Add captcha your own IP for 15m: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -#### Ban your own IP for 15 sec: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15s --type ban - -#### Remove all decisions: -docker-compose exec crowdsec cscli decisions delete --all - -#### View CrowdSec logs: -docker-compose logs crowdsec -``` - -> Note: The `DOCKER_HOST_IP` environnment variable is initialized via `source ./load-env-vars.sh`. - -#### WP Scan pass - -```bash -docker-compose run --rm wpscan --url http://wordpress5-6/ -``` - -##### Reinstall `composer` dependencies - -```bash -docker-compose exec wordpress5-6 composer install --working-dir /var/www/html/wp-content/plugins/cs-wordpress-bouncer --prefer-source -``` - -> In this dev environment, we use `--prefer-source` to be able to develop the bouncer library at the same time. Composer may ask you for your own Github token to download sources instead of using dist packages. - - -###### Quick `docker-compose` cheet sheet - -```bash -docker-compose run wordpress sh # run sh on wordpress container -docker-compose ps # list running containers -docker-compose stop # stop -docker-compose rm # destroy -``` - -###### Try the plugin with another PHP version - -```bash -docker-compose down -docker images | grep wordpress-bouncer_wordpress # to get the container id -docker rmi -``` - -Then, in the `.env` file, replace: - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION=7.2 -``` - -with : - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION= -``` - -Then re-run the stack. - -###### Try the plugin with another WordPress version - - -The plugin is tested under each of these WordPress versions: `5.6`, `5.5`, `5.4`, `5.3`, `5.2`, `5.1`, `5.0`, `4.9`. -(Representing [more than 90% of the wordpress websites](https://wordpress.org/about/stats/)) - - -###### Add support for a new WordPress version - -This is a cheat sheet to help testing briefly the support: - -```bash - -# To install a specific version -docker-compose up -d wordpress crowdsec mysql redis memcached && docker-compose exec crowdsec cscli bouncers add wordpress-bouncer - -# To display the captcha wall - -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -# To delete the image in order to rebuild it - -docker-compose down && docker rmi wordpress-bouncer_wordpress - -# To debug inside the container - -docker-compose run wordpress bash -``` - -> Note: The `DOCKER_HOST_IP` environnement variable is initialized via `source ./load-env-vars.sh`. - -###### Plugin debug mode VS production mode - -The debug mode throws verbose errors. The production mode hides every error to let users navigate in every edge cases. - -This plugin goes in debug mode when Wordpress debug mode is enabled. - -To try the production mode of this plugin, just disable the wordpress debug mode: in `docker-compose.yml`, comment the line: -```yml - WORDPRESS_DEBUG: 1 # Comment this line the simulate the production mode -``` - -###### Display the plugin logs - -```bash -tail -f logs/debug-* -``` - - -## FAQ - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the wordpress host command line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - htt://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace [host]:[port] with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -### Contribute to this plugin from a MacOS host - -You can test the Linux behavior of this project using **Vagrant**. - -#### One time setup - -##### Run the VM and initialize it - -```bash -vagrant up -vagrant ssh -sudo usermod -aG docker vagrant -sudo systemctl restart docker -``` - -You have to log out and log back for permission to be updated: - -```bash -exit -vagrant ssh -``` -##### Enabled Docker IPV6 support inside the Linux VM - -follow [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll have to create the file `/etc/docker/daemon.json`). - - -##### Install NodeJS - -Follow [this guide](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions)/ - -##### Install Yarn - -Follow [this guide](https://linuxize.com/post/how-to-install-yarn-on-ubuntu-18-04/). - -##### Add deps to run playwright - -```bash -sudo apt-get install libnss3\ - libnspr4\ - libatk1.0-0\ - libatk-bridge2.0-0\ - libxcb1\ - libxkbcommon0\ - libx11-6\ - libxcomposite1\ - libxdamage1\ - libxext6\ - libxfixes3\ - libxrandr2\ - libgbm1\ - libgtk-3-0\ - libpango-1.0-0\ - libcairo2\ - libgdk-pixbuf2.0-0\ - libasound2\ - libatspi2.0-0 -``` - -##### Edit you local host file: - -Type `sudo vim /etc/hosts` and add: - -```bash -# select the one you want to try by uncommenting only ont of the two -# 172.16.0.50 wordpress5-6 # Uncomment to use IPV4 -fde4:8dba:82e1::c4 wordpress5-6 # Uncomment to use IPV6 -``` - -##### Configure your `.env` file - -```bash -cd /vagrant -cp .env.example .env -``` - -Update the created `.env` file with: - -```bash -DEBUG=0 -DOCKER_HOST_IP=172.16.238.1 # OR IF YOU WANT TO TEST WITH IPV6 USE: 2001:3200:3200::1 -``` - -##### Run "plugin auto setup" via e2e tests (limited to setup steps) - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Browse the WordPress website admin - -Visit [http://wordpress5-6/wp-admin](http://wordpress5-6/wp-admin). - -##### Run tests - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Stop the Virtal Machine -```bash -vagrant stop # vagrant up to start after -``` - -##### Clean up environnement - -To destroy the vagrant instance: - -```bash -vagrant destroy -``` - - -## Licence - -[MIT License](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/LICENSE) diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers b/crowdsec-docs/versioned_docs/version-v1.1/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.1/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/cloudflare.mdx deleted file mode 100644 index 5f932d25..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/cloudflare.mdx +++ /dev/null @@ -1,257 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Don't redirect the generated configuration to `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` with bash redirection (`>`) but use the `-o` flag instead, else you will loose your existing configuration (eg. `crowdsec_lapi_key`). - -::: - - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - - -## Manual Installation - -### Assisted - - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -d` to cleanup cloudflare components before editing the config files. - -::: - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -git clone https://github.com/crowdsecurity/cs-cloudflare-bouncer.git -cd cs-cloudflare-bouncer -docker build . -t cs-cloudflare-bouncer -docker run cs-cloudflare-bouncer -g > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # add the appropriate crowdsec_lapi_url and crowdsec_lapi_key values. Make sure LAPI is accessible from the container. -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash -docker run -v \ - $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml\ - -p 2112:2112\ - crowdflare -``` - - - - -# Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${LAPI_KEY} -crowdsec_update_frequency: 10s - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: challenge - zones: - - actions: - - challenge # valid choices are either of challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -cache_path: /var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -g ,... > cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. It also deletes the local cache. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -d -``` - -# How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - - -# Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - The cache is at `/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json`. It can be inspected to see the state of bouncer and cloudflare components locally. - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/custom.mdx deleted file mode 100644 index 8ca9ff9f..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/custom.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for custom scripts. - -crowdsec-custom-bouncer will periodically fetch new and expired/removed decisions from CrowdSec Local API and will pass them as arguments to a custom user script. - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## Manual install (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 - -Before starting the `crowdsec-custom-bouncer` service, please edit the configuration to add your API url and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -:warning: don't forget to add execution permissions to your binary/script - -### Examples: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/firewall.mdx deleted file mode 100644 index 2395b058..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/firewall.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -### Using packages - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - -#### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -#### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables crowdsec-firewall-bouncer -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -## Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -## Configuration - -**note : this is only relevant for "manual" or "from source" installation, as packages would take care of all the needed configuration** - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - -```yaml title="/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml" -mode: "iptables" -pid_dir: "/var/run/" -update_frequency: "10s" -daemonize: true -log_mode: "file" -log_dir: "/var/log/" -log_level: "info" -api_url: "" # when install, default is "localhost:8080" -api_key: "" # Add your API key generated with `cscli bouncers add --name ` -disable_ipv6: "false" -deny_mode: "DROP" -deny_log: "false -#deny_log_prefix: "crowdsec: " -#if present, insert rule in those chains -iptables_chains: - - "INPUT" - - "FORWARD" -``` - - - `mode` can be set to `iptables`, `nftables` , `ipset` or `pf` - - `update_frequency` controls how often the bouncer is going to query the local API - - `api_url` and `api_key` control local API parameters. - - `iptables_chains` allows (in _iptables_ mode) to control in which chain rules are going to be inserted. (if empty, bouncer will only maintain ipset lists) - - `disable_ipv6` - set to true to disable ipv6 - - `deny_mode` - what action to use to deny, one of DROP or REJECT - - `deny_log` - set this to true to add a log statement to the firewall rule - - `deny_log_prefix` - if logging is true, this sets the log prefix, defaults to "crowdsec: " - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/ingress-nginx.mdx deleted file mode 100644 index b77f2ae0..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; # If you want captcha support otherwise remove this line -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/intro.md deleted file mode 100644 index 4bfabc4d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/local_api/intro.md) to be able to get informations about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/nginx.mdx deleted file mode 100644 index 8d73f86e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/nginx.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/openresty.mdx deleted file mode 100644 index eb73a3e1..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/openresty.mdx +++ /dev/null @@ -1,415 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`). You can also change this with a valid one. - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/php.mdx deleted file mode 100644 index a83b73f1..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/php.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -id: php -title: PHP Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -## How does it work ? - -This bouncer leverages the PHP `auto_preprend` mechanism. - -New/unknown IP are checked against crowdsec API, and if request should be blocked, a **403** or a captcha can be returned to the user, and put in cache. - -At the back, this bouncer uses [crowdsec PHP lib](https://github.com/crowdsecurity/php-cs-bouncer). - -## Installation - -### Prerequisite - - -#### Install `composer` - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - - -#### Download the bouncer - - -Download the Github bouncer repository. - -```bash -git clone https://github.com/crowdsecurity/cs-php-bouncer.git -cd cs-php-bouncer/ -``` - - - -### Apache - -For Apache, the install script can handle most of the work. - -```bash -./install.sh --apache - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - -crowdsec_apache apache2 configuration enabled - -And reload apache2 service - - sudo systemctl reload apache2 - -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -Then just changed the owner of the bouncer folder to your webserver user and reload your apache2 service. - -### Other web servers - -For other web servers, use the install script. - -```bash -./install.sh - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de kkado : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - - -Add the "php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php'" to your .htacess file. - -And reload your webserver. - -``` - -Then changed the owner of the bouncer folder to your webserver user. - -Now you need to add the `auto_preprend_file` to your htacess file like: - -``` -php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php' -``` - -And reload your webserver. - -## Upgrade - -Clone the Github repository and run the upgrade script: - -```bash -./upgrade.sh -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -## Configuration - -Here is the configuration used by the bouncer, located in `/usr/local/php/crowdsec/settings.php`. - -```php title=/usr/local/php/crowdsec/settings.php -$crowdSecStandaloneBouncerConfig = [ - 'api_url' => 'http://127.0.0.1:8080', // Default local API is 127.0.0.1:8080. Example in the docker-compose dev context, use http://crowdsec:8080 - 'api_key' => '${API_KEY}', // [FILL ME] Set a bouncer key here - 'debug_mode' => false, // [FILL ME] Set to true to stop the process and display errors if any - 'log_directory_path' => __DIR__.'/.logs', // [FILL ME] Important note: be sur this path won't be publicly accessible! - 'fs_cache_path' => __DIR__.'/.cache', // [FILL ME] Important note: be sur this path won't be publicly accessible! - - 'bouncing_level' => 'normal_boucing', - - 'stream_mode' => false, - - 'cache_system' => 'phpfs', - 'redis_dsn' => '', - 'memcached_dsn' => '', - - 'clean_ip_cache_duration' => 5, - 'bad_ip_cache_duration' => 10, - 'fallback_remediation' => 'captcha', - - 'hide_mentions' => false, - 'trust_ip_forward' => '', - 'trust_ip_forward_array' => [], - - 'theme_color_text_primary' => 'black', - 'theme_color_text_secondary' => '#AAA', - 'theme_color_text_button' => 'white', - 'theme_color_text_error_message' => '#b90000', - 'theme_color_background_page' => '#eee', - 'theme_color_background_container' => 'white', - 'theme_color_background_button' => '#626365', - 'theme_color_background_button_hover' => '#333', - - 'theme_text_captcha_wall_tab_title' => 'Oops..', - 'theme_text_captcha_wall_title' => 'Hmm, sorry but...', - 'theme_text_captcha_wall_subtitle' => 'Please complete the security check.', - 'theme_text_captcha_wall_refresh_image_link' => 'refresh image', - 'theme_text_captcha_wall_captcha_placeholder' => 'Type here...', - 'theme_text_captcha_wall_send_button' => 'CONTINUE', - 'theme_text_captcha_wall_error_message' => 'Please try again.', - 'theme_text_captcha_wall_footer' => '', - - 'theme_text_ban_wall_tab_title' => 'Oops..', - 'theme_text_ban_wall_title' => '🤭 Oh!', - 'theme_text_ban_wall_subtitle' => 'This page is protected against cyber attacks and your IP has been banned by our system.', - 'theme_text_ban_wall_footer' => '', - 'theme_custom_css' => '', -]; - -``` - - -## References - -- https://crowdsec.net/protect-php-websites/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.1/bouncers/wordpress.mdx deleted file mode 100644 index 28d0b138..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.1/bouncers/wordpress.mdx +++ /dev/null @@ -1,498 +0,0 @@ ---- -id: wordpress -title: Wordpress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## How does it work ? - -This wordpress plugin allows you to apply decisions from crowdsec directly within the wordpress application. - -It relies on the [associated php library](https://github.com/crowdsecurity/php-cs-bouncer) and provides the ability to not only block users, but challenge them with captchas. - -## Installation - -The bouncer itself can be installed from the marketplace in wordpress back-office : - -

-CrowdSec -

- -## Configuration - -You only need to configure your local API endpoint and API key so the bouncer can get its decisions from crowdsec : - -

-CrowdSec -

- -A key point of the bouncer is to allow not only to block users, but as well to present them with captchas : - -

-CrowdSec -

- - -## Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - -## WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Developer resources - -### Install with `docker-compose` - -#### Install the wordpress and the plugin locally using docker-compose - -Follow this guide to get the development stack installed locally. - -> Prerequises: -> -> - you should have [`docker`](https://docs.docker.com/get-docker/) installed -> - `docker` should be [`runnable without sudo`](https://docs.docker.com/engine/install/linux-postinstall/). -> - [`docker-compose`](https://docs.docker.com/compose/install/) installed locally. -> - IPv6 should be enable in your docker configuration. Enabled it following [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll may have to create the file `/etc/docker/daemon.json`). -> - If your develop environnment is MacOS, please refer to the [MacOS host installation guide](wordpress#contribute-to-this-plugin-from-a-macos-host). - -##### Install the stack for development purpose - -Before all, create a `.env` file, using: - -```bash -cp .env.example .env -``` - -> Note about PHP 8.0: WordPress official docker image [does not officially supports PHP 8.0](https://hub.docker.com/_/wordpress?tab=tags&page=1&ordering=last_updated) at this time. However, as the CrowdSec PHP Library does support PHP 8.0, there is a good chance that the plugin will work fine with PHP 8.0, but we can not currently test it. - -##### Configure WordPress and the CrowdSec Plugin - -Now there are two options, you can fill the Wordpress installation wizard manually OR use let the e2e tests to do it for you. - -###### A) Automatic configuration - -Install Wordpress instance and activate plugin launching the e2e tests (limited to the installation steps): - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -###### B) Manual comfiguration - -Alternatively, you can install wordpress and the plugin manually with: - -```bash -docker-compose up -d wordpress crowdsec mysql redis memcached -``` - -Then visit the wordpress instance here: http://localhost and install the wordpress instance. - -##### Infos to setup the plugin - -###### Get a bouncer key - -```bash -docker-compose exec crowdsec cscli bouncers add wordpress-bouncer -``` - -###### LAPI URL - -``` -http://crowdsec:8080 -``` - -##### Try the plugin behavior - -| Info | Value | -| --------------- | ------------------------------------ | -| Public blog URL | http://localhost | -| Blog admin URL | http://localhost/wp-admin | -| Admin username | `admin` | -| Pasword | `my_very_very_secret_admin_password` | - -### Demo guide - - -#### Full guide - -This guide exposes you the main features of the plugin. - -##### Let's get started! - -We will start using "live" mode. You'll understand what it is after try the stream mode. - -* First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). - -* open a terminal to display LAPI logs in realtime: - -```bash -docker-compose logs -f crowdsec -``` - -* In wp-admin, [ensure the bouncer is configured with **live** mode](http://localhost/wp-admin/admin.php?page=crowdsec_plugin) (stream mode disabled). - -###### Discover the cache system - -* In a tab, visit the [public home](http://localhost/). You're allowed because LAPI said your IP is clean. - -> To avoid latencies when the clean IP browse the website, the bouncer will keep this information in cache for 30 seconds (you can change this value in the [avdanced settings page](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings)). In other words, LAPI will not be requested to check this IP for the next 30 seconds. - - * You can call the website as many times as you want, the cache system will take relay during the ban period and so LAPI will not be disturbed. The ban decision will stay in cache for the full ban duration. Then the [public home](http://localhost/) should be available again. - - ###### Try ban remediation - -* If you want to skip this delay, feel free to [clear the cache in the wp-admin](http://localhost/wp-admin/admin.php?page=crowdsec_plugin). - -The `DOCKER_HOST_IP` environnement variable is initialized via a call to: - -```bash -source ./load-env-vars.sh -``` - -* In a terminal, ban your own IP for 4 hours: - -```bash - -# Ban your own IP for 4 hours: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* Immediately, the [public home](http://localhost/) is now locked with a short message to explain you that you are banned. - -###### Try "captcha" remediation - - -* Now, request captcha for your own IP for 15m: - -```bash - -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all - -# Add a captcha -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha -``` - -* The [public home](http://localhost/) now request you to fill a captcha. - -* Unless you manage to solve the captcha, you'll not be able to access the website. - -> Note: when you resolve the captcha in your browser, the associated PHP session is considered as sure. -> If you remove the captcha decision with `cscli`, then you add a new captcha decision for your IP, you'll not be prompted for the current PHP session. To view the captcha page, You can force using a new PHP session opening the front page with incognito mode. - -##### Stream mode, for the high traffic websites - -With live mode, as you tried it just before, each time a user arrives to the website for the first time, a call is made to LAPI. If the traffic on your website is high, the bouncer will call LAPI very often. - -To avoid this, LAPI offers a "stream" mode. The decisions list is updated at a predefined frequency and kept in cache. Let's try it! - -> This bouncer uses the WordPress cron system. For demo purposes, we encourage you to [install the WP-Control plugin](http://localhost/wp-admin/plugin-install.php?s=wp-control&tab=search&type=term), a plugin to view and control each Wordpress Cron task jobs. - -First, clear the previous decisions: - -```bash -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all -``` - -* Then enable "stream" mode [right here](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) and set the resync frequency to 30 seconds. If you installed WP-Control plugin, you can see that a new cron tak has just been added here http://localhost/wp-admin/tools.php?page=crontrol_admin_manage_page. - -* As the whole blocklist has just been loaded in cache (0 decision!), your IP is allowed. The [public home](http://localhost/) is available. - -* Now, if you ban your IP for 4h: - -```bash -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* In less than 30 seconds your IP will be banned and the [public home](http://localhost/) will be locked. - -Conclusion: with the stream mode, LAPI decisions are fetched on a regular basis rather than being called when user arrives for the first time. - -#### Try Redis or Memcached - -In order to get better performances, you can switch the cache technology. - -The docker-compose file started 2 unused containers, redis and memcached. - -Let's try **Redis**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Redis" and -- type `redis://redis:6379` in the "Redis DSN" field. - -Very similar with **Memcached**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Memcached" and -- type `memcached://memcached:11211` in the "Memcached DSN" field. - - -#### Statistics - -The bouncer has a stats page indicating each time : -- an IP has been banned by your website, or -- when a captcha has been presented to an IP visiting your website -- when a captcha has been solved or not. - - -### How to contribute? - -#### Contribute to this plugin - -> First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). -#### Play with crowdsec state - -```bash - -#### Add captcha your own IP for 15m: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -#### Ban your own IP for 15 sec: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15s --type ban - -#### Remove all decisions: -docker-compose exec crowdsec cscli decisions delete --all - -#### View CrowdSec logs: -docker-compose logs crowdsec -``` - -> Note: The `DOCKER_HOST_IP` environnment variable is initialized via `source ./load-env-vars.sh`. - -#### WP Scan pass - -```bash -docker-compose run --rm wpscan --url http://wordpress5-6/ -``` - -##### Reinstall `composer` dependencies - -```bash -docker-compose exec wordpress5-6 composer install --working-dir /var/www/html/wp-content/plugins/cs-wordpress-bouncer --prefer-source -``` - -> In this dev environment, we use `--prefer-source` to be able to develop the bouncer library at the same time. Composer may ask you for your own Github token to download sources instead of using dist packages. - - -###### Quick `docker-compose` cheet sheet - -```bash -docker-compose run wordpress sh # run sh on wordpress container -docker-compose ps # list running containers -docker-compose stop # stop -docker-compose rm # destroy -``` - -###### Try the plugin with another PHP version - -```bash -docker-compose down -docker images | grep wordpress-bouncer_wordpress # to get the container id -docker rmi -``` - -Then, in the `.env` file, replace: - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION=7.2 -``` - -with : - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION= -``` - -Then re-run the stack. - -###### Try the plugin with another WordPress version - - -The plugin is tested under each of these WordPress versions: `5.6`, `5.5`, `5.4`, `5.3`, `5.2`, `5.1`, `5.0`, `4.9`. -(Representing [more than 90% of the wordpress websites](https://wordpress.org/about/stats/)) - - -###### Add support for a new WordPress version - -This is a cheat sheet to help testing briefly the support: - -```bash - -# To install a specific version -docker-compose up -d wordpress crowdsec mysql redis memcached && docker-compose exec crowdsec cscli bouncers add wordpress-bouncer - -# To display the captcha wall - -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -# To delete the image in order to rebuild it - -docker-compose down && docker rmi wordpress-bouncer_wordpress - -# To debug inside the container - -docker-compose run wordpress bash -``` - -> Note: The `DOCKER_HOST_IP` environnement variable is initialized via `source ./load-env-vars.sh`. - -###### Plugin debug mode VS production mode - -The debug mode throws verbose errors. The production mode hides every error to let users navigate in every edge cases. - -This plugin goes in debug mode when Wordpress debug mode is enabled. - -To try the production mode of this plugin, just disable the wordpress debug mode: in `docker-compose.yml`, comment the line: -```yml - WORDPRESS_DEBUG: 1 # Comment this line the simulate the production mode -``` - -###### Display the plugin logs - -```bash -tail -f logs/debug-* -``` - - -## FAQ - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the wordpress host command line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - htt://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace [host]:[port] with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -### Contribute to this plugin from a MacOS host - -You can test the Linux behavior of this project using **Vagrant**. - -#### One time setup - -##### Run the VM and initialize it - -```bash -vagrant up -vagrant ssh -sudo usermod -aG docker vagrant -sudo systemctl restart docker -``` - -You have to log out and log back for permission to be updated: - -```bash -exit -vagrant ssh -``` -##### Enabled Docker IPV6 support inside the Linux VM - -follow [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll have to create the file `/etc/docker/daemon.json`). - - -##### Install NodeJS - -Follow [this guide](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions)/ - -##### Install Yarn - -Follow [this guide](https://linuxize.com/post/how-to-install-yarn-on-ubuntu-18-04/). - -##### Add deps to run playwright - -```bash -sudo apt-get install libnss3\ - libnspr4\ - libatk1.0-0\ - libatk-bridge2.0-0\ - libxcb1\ - libxkbcommon0\ - libx11-6\ - libxcomposite1\ - libxdamage1\ - libxext6\ - libxfixes3\ - libxrandr2\ - libgbm1\ - libgtk-3-0\ - libpango-1.0-0\ - libcairo2\ - libgdk-pixbuf2.0-0\ - libasound2\ - libatspi2.0-0 -``` - -##### Edit you local host file: - -Type `sudo vim /etc/hosts` and add: - -```bash -# select the one you want to try by uncommenting only ont of the two -# 172.16.0.50 wordpress5-6 # Uncomment to use IPV4 -fde4:8dba:82e1::c4 wordpress5-6 # Uncomment to use IPV6 -``` - -##### Configure your `.env` file - -```bash -cd /vagrant -cp .env.example .env -``` - -Update the created `.env` file with: - -```bash -DEBUG=0 -DOCKER_HOST_IP=172.16.238.1 # OR IF YOU WANT TO TEST WITH IPV6 USE: 2001:3200:3200::1 -``` - -##### Run "plugin auto setup" via e2e tests (limited to setup steps) - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Browse the WordPress website admin - -Visit [http://wordpress5-6/wp-admin](http://wordpress5-6/wp-admin). - -##### Run tests - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Stop the Virtal Machine -```bash -vagrant stop # vagrant up to start after -``` - -##### Clean up environnement - -To destroy the vagrant instance: - -```bash -vagrant destroy -``` - - -## Licence - -[MIT License](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/LICENSE) diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/cloudflare.mdx deleted file mode 100644 index 14eb05c7..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/cloudflare.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Don't redirect the generated configuration to `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` with bash redirection (`>`) but use the `-o` flag instead, else you will loose your existing configuration (eg. `crowdsec_lapi_key`). - -::: - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - - -## Manual Installation - -### Assisted - - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -d` to cleanup cloudflare components before editing the config files. - -::: - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -git clone https://github.com/crowdsecurity/cs-cloudflare-bouncer.git -cd cs-cloudflare-bouncer -docker build . -t cs-cloudflare-bouncer -docker run cs-cloudflare-bouncer -g > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # add the appropriate crowdsec_lapi_url and crowdsec_lapi_key values. Make sure LAPI is accessible from the container. -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash -docker run -v \ - $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml\ - -p 2112:2112\ - crowdflare -``` - - - - -# Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${LAPI_KEY} -crowdsec_update_frequency: 10s - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: challenge - zones: - - actions: - - challenge # valid choices are either of challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -cache_path: /var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -g ,... > cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. It also deletes the local cache. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -d -``` - -# How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - - -# Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - The cache is at `/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json`. It can be inspected to see the state of bouncer and cloudflare components locally. - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/custom.mdx deleted file mode 100644 index 8ca9ff9f..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/custom.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for custom scripts. - -crowdsec-custom-bouncer will periodically fetch new and expired/removed decisions from CrowdSec Local API and will pass them as arguments to a custom user script. - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## Manual install (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 - -Before starting the `crowdsec-custom-bouncer` service, please edit the configuration to add your API url and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -:warning: don't forget to add execution permissions to your binary/script - -### Examples: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/firewall.mdx deleted file mode 100644 index 8509d568..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/firewall.mdx +++ /dev/null @@ -1,221 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -### Using packages - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - -#### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -#### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -## Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -## Configuration - -**note : this is only relevant for "manual" or "from source" installation, as packages would take care of all the needed configuration** - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - -```yaml title="/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml" -mode: "iptables" -pid_dir: "/var/run/" -update_frequency: "10s" -daemonize: true -log_mode: "file" -log_dir: "/var/log/" -log_level: "info" -api_url: "" # when install, default is "localhost:8080" -api_key: "" # Add your API key generated with `cscli bouncers add --name ` -disable_ipv6: "false" -deny_mode: "DROP" -deny_log: "false -#deny_log_prefix: "crowdsec: " -#if present, insert rule in those chains -iptables_chains: - - "INPUT" - - "FORWARD" -``` - - - `mode` can be set to `iptables`, `nftables` , `ipset` or `pf` - - `update_frequency` controls how often the bouncer is going to query the local API - - `api_url` and `api_key` control local API parameters. - - `iptables_chains` allows (in _iptables_ mode) to control in which chain rules are going to be inserted. (if empty, bouncer will only maintain ipset lists) - - `disable_ipv6` - set to true to disable ipv6 - - `deny_mode` - what action to use to deny, one of DROP or REJECT - - `deny_log` - set this to true to add a log statement to the firewall rule - - `deny_log_prefix` - if logging is true, this sets the log prefix, defaults to "crowdsec: " - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. - - ### ipset - - ipset lists have to exist before crowdsec-firewall-bouncer starts - you could create them and add them to your iptables like this: - ``` -ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000 -ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000 -iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP -ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/ingress-nginx.mdx deleted file mode 100644 index b77f2ae0..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; # If you want captcha support otherwise remove this line -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/intro.md deleted file mode 100644 index deade5e5..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/local_api/intro.md) to be able to get information about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/nginx.mdx deleted file mode 100644 index 8d73f86e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/nginx.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/openresty.mdx deleted file mode 100644 index deb00ace..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/openresty.mdx +++ /dev/null @@ -1,416 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`). You can also change this with a valid one. - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/php.mdx deleted file mode 100644 index cf72c4cc..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/php.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: php -title: PHP Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -## How does it work ? - -This bouncer leverages the PHP `auto_preprend` mechanism. - -New/unknown IP are checked against crowdsec API, and if request should be blocked, a **403** or a captcha can be returned to the user, and put in cache. - -At the back, this bouncer uses [crowdsec PHP lib](https://github.com/crowdsecurity/php-cs-bouncer). - -## Installation - -### Prerequisite - - -#### Install `composer` - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - - -#### Download the bouncer - - -Download the Github bouncer repository. - -```bash -git clone https://github.com/crowdsecurity/cs-php-bouncer.git -cd cs-php-bouncer/ -``` - - -### Apache - -For Apache, the install script can handle most of the work. - -```bash -./install.sh --apache - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - -crowdsec_apache apache2 configuration enabled - -And reload apache2 service - - sudo systemctl reload apache2 - -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -Then just changed the owner of the bouncer folder to your webserver user and reload your apache2 service. - -### Other web servers - -For other web servers, use the install script. - -```bash -./install.sh - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de kkado : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - - -Add the "php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php'" to your .htacess file. - -And reload your webserver. - -``` - -Then changed the owner of the bouncer folder to your webserver user. - -Now you need to add the `auto_preprend_file` to your htacess file like: - -``` -php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php' -``` - -And reload your webserver. - -## Upgrade - -Clone the Github repository and run the upgrade script: - -```bash -./upgrade.sh -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -## Configuration - -Here is the configuration used by the bouncer, located in `/usr/local/php/crowdsec/settings.php`. - -```php title=/usr/local/php/crowdsec/settings.php -$crowdSecStandaloneBouncerConfig = [ - 'api_url' => 'http://127.0.0.1:8080', // Default local API is 127.0.0.1:8080. Example in the docker-compose dev context, use http://crowdsec:8080 - 'api_key' => '${API_KEY}', // [FILL ME] Set a bouncer key here - 'debug_mode' => false, // [FILL ME] Set to true to stop the process and display errors if any - 'log_directory_path' => __DIR__.'/.logs', // [FILL ME] Important note: be sur this path won't be publicly accessible! - 'fs_cache_path' => __DIR__.'/.cache', // [FILL ME] Important note: be sur this path won't be publicly accessible! - - 'bouncing_level' => 'normal_boucing', - - 'stream_mode' => false, - - 'cache_system' => 'phpfs', - 'redis_dsn' => '', - 'memcached_dsn' => '', - - 'clean_ip_cache_duration' => 5, - 'bad_ip_cache_duration' => 10, - 'fallback_remediation' => 'captcha', - - 'hide_mentions' => false, - 'trust_ip_forward' => '', - 'trust_ip_forward_array' => [], - - 'theme_color_text_primary' => 'black', - 'theme_color_text_secondary' => '#AAA', - 'theme_color_text_button' => 'white', - 'theme_color_text_error_message' => '#b90000', - 'theme_color_background_page' => '#eee', - 'theme_color_background_container' => 'white', - 'theme_color_background_button' => '#626365', - 'theme_color_background_button_hover' => '#333', - - 'theme_text_captcha_wall_tab_title' => 'Oops..', - 'theme_text_captcha_wall_title' => 'Hmm, sorry but...', - 'theme_text_captcha_wall_subtitle' => 'Please complete the security check.', - 'theme_text_captcha_wall_refresh_image_link' => 'refresh image', - 'theme_text_captcha_wall_captcha_placeholder' => 'Type here...', - 'theme_text_captcha_wall_send_button' => 'CONTINUE', - 'theme_text_captcha_wall_error_message' => 'Please try again.', - 'theme_text_captcha_wall_footer' => '', - - 'theme_text_ban_wall_tab_title' => 'Oops..', - 'theme_text_ban_wall_title' => '🤭 Oh!', - 'theme_text_ban_wall_subtitle' => 'This page is protected against cyber attacks and your IP has been banned by our system.', - 'theme_text_ban_wall_footer' => '', - 'theme_custom_css' => '', -]; - -``` - - -## References - -- https://crowdsec.net/protect-php-websites/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/wordpress.mdx deleted file mode 100644 index 28d0b138..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2.2/bouncers/wordpress.mdx +++ /dev/null @@ -1,498 +0,0 @@ ---- -id: wordpress -title: Wordpress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## How does it work ? - -This wordpress plugin allows you to apply decisions from crowdsec directly within the wordpress application. - -It relies on the [associated php library](https://github.com/crowdsecurity/php-cs-bouncer) and provides the ability to not only block users, but challenge them with captchas. - -## Installation - -The bouncer itself can be installed from the marketplace in wordpress back-office : - -

-CrowdSec -

- -## Configuration - -You only need to configure your local API endpoint and API key so the bouncer can get its decisions from crowdsec : - -

-CrowdSec -

- -A key point of the bouncer is to allow not only to block users, but as well to present them with captchas : - -

-CrowdSec -

- - -## Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - -## WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Developer resources - -### Install with `docker-compose` - -#### Install the wordpress and the plugin locally using docker-compose - -Follow this guide to get the development stack installed locally. - -> Prerequises: -> -> - you should have [`docker`](https://docs.docker.com/get-docker/) installed -> - `docker` should be [`runnable without sudo`](https://docs.docker.com/engine/install/linux-postinstall/). -> - [`docker-compose`](https://docs.docker.com/compose/install/) installed locally. -> - IPv6 should be enable in your docker configuration. Enabled it following [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll may have to create the file `/etc/docker/daemon.json`). -> - If your develop environnment is MacOS, please refer to the [MacOS host installation guide](wordpress#contribute-to-this-plugin-from-a-macos-host). - -##### Install the stack for development purpose - -Before all, create a `.env` file, using: - -```bash -cp .env.example .env -``` - -> Note about PHP 8.0: WordPress official docker image [does not officially supports PHP 8.0](https://hub.docker.com/_/wordpress?tab=tags&page=1&ordering=last_updated) at this time. However, as the CrowdSec PHP Library does support PHP 8.0, there is a good chance that the plugin will work fine with PHP 8.0, but we can not currently test it. - -##### Configure WordPress and the CrowdSec Plugin - -Now there are two options, you can fill the Wordpress installation wizard manually OR use let the e2e tests to do it for you. - -###### A) Automatic configuration - -Install Wordpress instance and activate plugin launching the e2e tests (limited to the installation steps): - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -###### B) Manual comfiguration - -Alternatively, you can install wordpress and the plugin manually with: - -```bash -docker-compose up -d wordpress crowdsec mysql redis memcached -``` - -Then visit the wordpress instance here: http://localhost and install the wordpress instance. - -##### Infos to setup the plugin - -###### Get a bouncer key - -```bash -docker-compose exec crowdsec cscli bouncers add wordpress-bouncer -``` - -###### LAPI URL - -``` -http://crowdsec:8080 -``` - -##### Try the plugin behavior - -| Info | Value | -| --------------- | ------------------------------------ | -| Public blog URL | http://localhost | -| Blog admin URL | http://localhost/wp-admin | -| Admin username | `admin` | -| Pasword | `my_very_very_secret_admin_password` | - -### Demo guide - - -#### Full guide - -This guide exposes you the main features of the plugin. - -##### Let's get started! - -We will start using "live" mode. You'll understand what it is after try the stream mode. - -* First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). - -* open a terminal to display LAPI logs in realtime: - -```bash -docker-compose logs -f crowdsec -``` - -* In wp-admin, [ensure the bouncer is configured with **live** mode](http://localhost/wp-admin/admin.php?page=crowdsec_plugin) (stream mode disabled). - -###### Discover the cache system - -* In a tab, visit the [public home](http://localhost/). You're allowed because LAPI said your IP is clean. - -> To avoid latencies when the clean IP browse the website, the bouncer will keep this information in cache for 30 seconds (you can change this value in the [avdanced settings page](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings)). In other words, LAPI will not be requested to check this IP for the next 30 seconds. - - * You can call the website as many times as you want, the cache system will take relay during the ban period and so LAPI will not be disturbed. The ban decision will stay in cache for the full ban duration. Then the [public home](http://localhost/) should be available again. - - ###### Try ban remediation - -* If you want to skip this delay, feel free to [clear the cache in the wp-admin](http://localhost/wp-admin/admin.php?page=crowdsec_plugin). - -The `DOCKER_HOST_IP` environnement variable is initialized via a call to: - -```bash -source ./load-env-vars.sh -``` - -* In a terminal, ban your own IP for 4 hours: - -```bash - -# Ban your own IP for 4 hours: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* Immediately, the [public home](http://localhost/) is now locked with a short message to explain you that you are banned. - -###### Try "captcha" remediation - - -* Now, request captcha for your own IP for 15m: - -```bash - -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all - -# Add a captcha -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha -``` - -* The [public home](http://localhost/) now request you to fill a captcha. - -* Unless you manage to solve the captcha, you'll not be able to access the website. - -> Note: when you resolve the captcha in your browser, the associated PHP session is considered as sure. -> If you remove the captcha decision with `cscli`, then you add a new captcha decision for your IP, you'll not be prompted for the current PHP session. To view the captcha page, You can force using a new PHP session opening the front page with incognito mode. - -##### Stream mode, for the high traffic websites - -With live mode, as you tried it just before, each time a user arrives to the website for the first time, a call is made to LAPI. If the traffic on your website is high, the bouncer will call LAPI very often. - -To avoid this, LAPI offers a "stream" mode. The decisions list is updated at a predefined frequency and kept in cache. Let's try it! - -> This bouncer uses the WordPress cron system. For demo purposes, we encourage you to [install the WP-Control plugin](http://localhost/wp-admin/plugin-install.php?s=wp-control&tab=search&type=term), a plugin to view and control each Wordpress Cron task jobs. - -First, clear the previous decisions: - -```bash -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all -``` - -* Then enable "stream" mode [right here](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) and set the resync frequency to 30 seconds. If you installed WP-Control plugin, you can see that a new cron tak has just been added here http://localhost/wp-admin/tools.php?page=crontrol_admin_manage_page. - -* As the whole blocklist has just been loaded in cache (0 decision!), your IP is allowed. The [public home](http://localhost/) is available. - -* Now, if you ban your IP for 4h: - -```bash -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* In less than 30 seconds your IP will be banned and the [public home](http://localhost/) will be locked. - -Conclusion: with the stream mode, LAPI decisions are fetched on a regular basis rather than being called when user arrives for the first time. - -#### Try Redis or Memcached - -In order to get better performances, you can switch the cache technology. - -The docker-compose file started 2 unused containers, redis and memcached. - -Let's try **Redis**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Redis" and -- type `redis://redis:6379` in the "Redis DSN" field. - -Very similar with **Memcached**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Memcached" and -- type `memcached://memcached:11211` in the "Memcached DSN" field. - - -#### Statistics - -The bouncer has a stats page indicating each time : -- an IP has been banned by your website, or -- when a captcha has been presented to an IP visiting your website -- when a captcha has been solved or not. - - -### How to contribute? - -#### Contribute to this plugin - -> First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). -#### Play with crowdsec state - -```bash - -#### Add captcha your own IP for 15m: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -#### Ban your own IP for 15 sec: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15s --type ban - -#### Remove all decisions: -docker-compose exec crowdsec cscli decisions delete --all - -#### View CrowdSec logs: -docker-compose logs crowdsec -``` - -> Note: The `DOCKER_HOST_IP` environnment variable is initialized via `source ./load-env-vars.sh`. - -#### WP Scan pass - -```bash -docker-compose run --rm wpscan --url http://wordpress5-6/ -``` - -##### Reinstall `composer` dependencies - -```bash -docker-compose exec wordpress5-6 composer install --working-dir /var/www/html/wp-content/plugins/cs-wordpress-bouncer --prefer-source -``` - -> In this dev environment, we use `--prefer-source` to be able to develop the bouncer library at the same time. Composer may ask you for your own Github token to download sources instead of using dist packages. - - -###### Quick `docker-compose` cheet sheet - -```bash -docker-compose run wordpress sh # run sh on wordpress container -docker-compose ps # list running containers -docker-compose stop # stop -docker-compose rm # destroy -``` - -###### Try the plugin with another PHP version - -```bash -docker-compose down -docker images | grep wordpress-bouncer_wordpress # to get the container id -docker rmi -``` - -Then, in the `.env` file, replace: - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION=7.2 -``` - -with : - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION= -``` - -Then re-run the stack. - -###### Try the plugin with another WordPress version - - -The plugin is tested under each of these WordPress versions: `5.6`, `5.5`, `5.4`, `5.3`, `5.2`, `5.1`, `5.0`, `4.9`. -(Representing [more than 90% of the wordpress websites](https://wordpress.org/about/stats/)) - - -###### Add support for a new WordPress version - -This is a cheat sheet to help testing briefly the support: - -```bash - -# To install a specific version -docker-compose up -d wordpress crowdsec mysql redis memcached && docker-compose exec crowdsec cscli bouncers add wordpress-bouncer - -# To display the captcha wall - -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -# To delete the image in order to rebuild it - -docker-compose down && docker rmi wordpress-bouncer_wordpress - -# To debug inside the container - -docker-compose run wordpress bash -``` - -> Note: The `DOCKER_HOST_IP` environnement variable is initialized via `source ./load-env-vars.sh`. - -###### Plugin debug mode VS production mode - -The debug mode throws verbose errors. The production mode hides every error to let users navigate in every edge cases. - -This plugin goes in debug mode when Wordpress debug mode is enabled. - -To try the production mode of this plugin, just disable the wordpress debug mode: in `docker-compose.yml`, comment the line: -```yml - WORDPRESS_DEBUG: 1 # Comment this line the simulate the production mode -``` - -###### Display the plugin logs - -```bash -tail -f logs/debug-* -``` - - -## FAQ - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the wordpress host command line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - htt://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace [host]:[port] with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -### Contribute to this plugin from a MacOS host - -You can test the Linux behavior of this project using **Vagrant**. - -#### One time setup - -##### Run the VM and initialize it - -```bash -vagrant up -vagrant ssh -sudo usermod -aG docker vagrant -sudo systemctl restart docker -``` - -You have to log out and log back for permission to be updated: - -```bash -exit -vagrant ssh -``` -##### Enabled Docker IPV6 support inside the Linux VM - -follow [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll have to create the file `/etc/docker/daemon.json`). - - -##### Install NodeJS - -Follow [this guide](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions)/ - -##### Install Yarn - -Follow [this guide](https://linuxize.com/post/how-to-install-yarn-on-ubuntu-18-04/). - -##### Add deps to run playwright - -```bash -sudo apt-get install libnss3\ - libnspr4\ - libatk1.0-0\ - libatk-bridge2.0-0\ - libxcb1\ - libxkbcommon0\ - libx11-6\ - libxcomposite1\ - libxdamage1\ - libxext6\ - libxfixes3\ - libxrandr2\ - libgbm1\ - libgtk-3-0\ - libpango-1.0-0\ - libcairo2\ - libgdk-pixbuf2.0-0\ - libasound2\ - libatspi2.0-0 -``` - -##### Edit you local host file: - -Type `sudo vim /etc/hosts` and add: - -```bash -# select the one you want to try by uncommenting only ont of the two -# 172.16.0.50 wordpress5-6 # Uncomment to use IPV4 -fde4:8dba:82e1::c4 wordpress5-6 # Uncomment to use IPV6 -``` - -##### Configure your `.env` file - -```bash -cd /vagrant -cp .env.example .env -``` - -Update the created `.env` file with: - -```bash -DEBUG=0 -DOCKER_HOST_IP=172.16.238.1 # OR IF YOU WANT TO TEST WITH IPV6 USE: 2001:3200:3200::1 -``` - -##### Run "plugin auto setup" via e2e tests (limited to setup steps) - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Browse the WordPress website admin - -Visit [http://wordpress5-6/wp-admin](http://wordpress5-6/wp-admin). - -##### Run tests - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Stop the Virtal Machine -```bash -vagrant stop # vagrant up to start after -``` - -##### Clean up environnement - -To destroy the vagrant instance: - -```bash -vagrant destroy -``` - - -## Licence - -[MIT License](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/LICENSE) diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers b/crowdsec-docs/versioned_docs/version-v1.2/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.2/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/cloudflare.mdx deleted file mode 100644 index 7acb2e98..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/cloudflare.mdx +++ /dev/null @@ -1,254 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Don't redirect the generated configuration to `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` with bash redirection (`>`) but use the `-o` flag instead, else you will loose your existing configuration (eg. `crowdsec_lapi_key`). - -::: - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - - -## Manual Installation - -### Assisted - - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -d` to cleanup cloudflare components before editing the config files. - -::: - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/cloudflare-bouncer \ - -g > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -touch cloudflare-cache.json -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml \ - -v $PWD/cloudflare-cache.json:/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json \ - -p 2112:2112 \ - crowdsecurity/cloudflare-bouncer -``` - - -# Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${LAPI_KEY} -crowdsec_update_frequency: 10s - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: challenge - zones: - - actions: - - challenge # valid choices are either of challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -cache_path: /var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -g ,... > cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. It also deletes the local cache. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -d -``` - -# How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - - -# Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - The cache is at `/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json`. It can be inspected to see the state of bouncer and cloudflare components locally. - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/custom.mdx deleted file mode 100644 index 8ca9ff9f..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/custom.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for custom scripts. - -crowdsec-custom-bouncer will periodically fetch new and expired/removed decisions from CrowdSec Local API and will pass them as arguments to a custom user script. - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## Manual install (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 - -Before starting the `crowdsec-custom-bouncer` service, please edit the configuration to add your API url and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -:warning: don't forget to add execution permissions to your binary/script - -### Examples: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/firewall.mdx deleted file mode 100644 index 55f1d4df..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/firewall.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -### Using packages - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - -#### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -#### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -## Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -## Configuration - -**note : this is only relevant for "manual" or "from source" installation, as packages would take care of all the needed configuration** - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - -```yaml title="/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml" -mode: "iptables" -pid_dir: "/var/run/" -update_frequency: "10s" -daemonize: true -log_mode: "file" -log_dir: "/var/log/" -log_level: "info" -api_url: "" # when install, default is "localhost:8080" -api_key: "" # Add your API key generated with `cscli bouncers add --name ` -disable_ipv6: "false" -deny_mode: "DROP" -deny_log: "false -#deny_log_prefix: "crowdsec: " -#if present, insert rule in those chains -iptables_chains: - - "INPUT" - - "FORWARD" -``` - - - `mode` can be set to `iptables`, `nftables` , `ipset` or `pf` - - `update_frequency` controls how often the bouncer is going to query the local API - - `api_url` and `api_key` control local API parameters. - - `iptables_chains` allows (in _iptables_ mode) to control in which chain rules are going to be inserted. (if empty, bouncer will only maintain ipset lists) - - `disable_ipv6` - set to true to disable ipv6 - - `deny_mode` - what action to use to deny, one of DROP or REJECT - - `deny_log` - set this to true to add a log statement to the firewall rule - - `deny_log_prefix` - if logging is true, this sets the log prefix, defaults to "crowdsec: " - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/ingress-nginx.mdx deleted file mode 100644 index b77f2ae0..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; # If you want captcha support otherwise remove this line -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/intro.md deleted file mode 100644 index 4bfabc4d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/local_api/intro.md) to be able to get informations about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/nginx.mdx deleted file mode 100644 index 8d73f86e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/nginx.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/openresty.mdx deleted file mode 100644 index deb00ace..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/openresty.mdx +++ /dev/null @@ -1,416 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`). You can also change this with a valid one. - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/php.mdx deleted file mode 100644 index cf72c4cc..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/php.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: php -title: PHP Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -## How does it work ? - -This bouncer leverages the PHP `auto_preprend` mechanism. - -New/unknown IP are checked against crowdsec API, and if request should be blocked, a **403** or a captcha can be returned to the user, and put in cache. - -At the back, this bouncer uses [crowdsec PHP lib](https://github.com/crowdsecurity/php-cs-bouncer). - -## Installation - -### Prerequisite - - -#### Install `composer` - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - - -#### Download the bouncer - - -Download the Github bouncer repository. - -```bash -git clone https://github.com/crowdsecurity/cs-php-bouncer.git -cd cs-php-bouncer/ -``` - - -### Apache - -For Apache, the install script can handle most of the work. - -```bash -./install.sh --apache - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - -crowdsec_apache apache2 configuration enabled - -And reload apache2 service - - sudo systemctl reload apache2 - -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -Then just changed the owner of the bouncer folder to your webserver user and reload your apache2 service. - -### Other web servers - -For other web servers, use the install script. - -```bash -./install.sh - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de kkado : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - - -Add the "php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php'" to your .htacess file. - -And reload your webserver. - -``` - -Then changed the owner of the bouncer folder to your webserver user. - -Now you need to add the `auto_preprend_file` to your htacess file like: - -``` -php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php' -``` - -And reload your webserver. - -## Upgrade - -Clone the Github repository and run the upgrade script: - -```bash -./upgrade.sh -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -## Configuration - -Here is the configuration used by the bouncer, located in `/usr/local/php/crowdsec/settings.php`. - -```php title=/usr/local/php/crowdsec/settings.php -$crowdSecStandaloneBouncerConfig = [ - 'api_url' => 'http://127.0.0.1:8080', // Default local API is 127.0.0.1:8080. Example in the docker-compose dev context, use http://crowdsec:8080 - 'api_key' => '${API_KEY}', // [FILL ME] Set a bouncer key here - 'debug_mode' => false, // [FILL ME] Set to true to stop the process and display errors if any - 'log_directory_path' => __DIR__.'/.logs', // [FILL ME] Important note: be sur this path won't be publicly accessible! - 'fs_cache_path' => __DIR__.'/.cache', // [FILL ME] Important note: be sur this path won't be publicly accessible! - - 'bouncing_level' => 'normal_boucing', - - 'stream_mode' => false, - - 'cache_system' => 'phpfs', - 'redis_dsn' => '', - 'memcached_dsn' => '', - - 'clean_ip_cache_duration' => 5, - 'bad_ip_cache_duration' => 10, - 'fallback_remediation' => 'captcha', - - 'hide_mentions' => false, - 'trust_ip_forward' => '', - 'trust_ip_forward_array' => [], - - 'theme_color_text_primary' => 'black', - 'theme_color_text_secondary' => '#AAA', - 'theme_color_text_button' => 'white', - 'theme_color_text_error_message' => '#b90000', - 'theme_color_background_page' => '#eee', - 'theme_color_background_container' => 'white', - 'theme_color_background_button' => '#626365', - 'theme_color_background_button_hover' => '#333', - - 'theme_text_captcha_wall_tab_title' => 'Oops..', - 'theme_text_captcha_wall_title' => 'Hmm, sorry but...', - 'theme_text_captcha_wall_subtitle' => 'Please complete the security check.', - 'theme_text_captcha_wall_refresh_image_link' => 'refresh image', - 'theme_text_captcha_wall_captcha_placeholder' => 'Type here...', - 'theme_text_captcha_wall_send_button' => 'CONTINUE', - 'theme_text_captcha_wall_error_message' => 'Please try again.', - 'theme_text_captcha_wall_footer' => '', - - 'theme_text_ban_wall_tab_title' => 'Oops..', - 'theme_text_ban_wall_title' => '🤭 Oh!', - 'theme_text_ban_wall_subtitle' => 'This page is protected against cyber attacks and your IP has been banned by our system.', - 'theme_text_ban_wall_footer' => '', - 'theme_custom_css' => '', -]; - -``` - - -## References - -- https://crowdsec.net/protect-php-websites/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.2/bouncers/wordpress.mdx deleted file mode 100644 index 28d0b138..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.2/bouncers/wordpress.mdx +++ /dev/null @@ -1,498 +0,0 @@ ---- -id: wordpress -title: Wordpress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## How does it work ? - -This wordpress plugin allows you to apply decisions from crowdsec directly within the wordpress application. - -It relies on the [associated php library](https://github.com/crowdsecurity/php-cs-bouncer) and provides the ability to not only block users, but challenge them with captchas. - -## Installation - -The bouncer itself can be installed from the marketplace in wordpress back-office : - -

-CrowdSec -

- -## Configuration - -You only need to configure your local API endpoint and API key so the bouncer can get its decisions from crowdsec : - -

-CrowdSec -

- -A key point of the bouncer is to allow not only to block users, but as well to present them with captchas : - -

-CrowdSec -

- - -## Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - -## WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Developer resources - -### Install with `docker-compose` - -#### Install the wordpress and the plugin locally using docker-compose - -Follow this guide to get the development stack installed locally. - -> Prerequises: -> -> - you should have [`docker`](https://docs.docker.com/get-docker/) installed -> - `docker` should be [`runnable without sudo`](https://docs.docker.com/engine/install/linux-postinstall/). -> - [`docker-compose`](https://docs.docker.com/compose/install/) installed locally. -> - IPv6 should be enable in your docker configuration. Enabled it following [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll may have to create the file `/etc/docker/daemon.json`). -> - If your develop environnment is MacOS, please refer to the [MacOS host installation guide](wordpress#contribute-to-this-plugin-from-a-macos-host). - -##### Install the stack for development purpose - -Before all, create a `.env` file, using: - -```bash -cp .env.example .env -``` - -> Note about PHP 8.0: WordPress official docker image [does not officially supports PHP 8.0](https://hub.docker.com/_/wordpress?tab=tags&page=1&ordering=last_updated) at this time. However, as the CrowdSec PHP Library does support PHP 8.0, there is a good chance that the plugin will work fine with PHP 8.0, but we can not currently test it. - -##### Configure WordPress and the CrowdSec Plugin - -Now there are two options, you can fill the Wordpress installation wizard manually OR use let the e2e tests to do it for you. - -###### A) Automatic configuration - -Install Wordpress instance and activate plugin launching the e2e tests (limited to the installation steps): - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -###### B) Manual comfiguration - -Alternatively, you can install wordpress and the plugin manually with: - -```bash -docker-compose up -d wordpress crowdsec mysql redis memcached -``` - -Then visit the wordpress instance here: http://localhost and install the wordpress instance. - -##### Infos to setup the plugin - -###### Get a bouncer key - -```bash -docker-compose exec crowdsec cscli bouncers add wordpress-bouncer -``` - -###### LAPI URL - -``` -http://crowdsec:8080 -``` - -##### Try the plugin behavior - -| Info | Value | -| --------------- | ------------------------------------ | -| Public blog URL | http://localhost | -| Blog admin URL | http://localhost/wp-admin | -| Admin username | `admin` | -| Pasword | `my_very_very_secret_admin_password` | - -### Demo guide - - -#### Full guide - -This guide exposes you the main features of the plugin. - -##### Let's get started! - -We will start using "live" mode. You'll understand what it is after try the stream mode. - -* First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). - -* open a terminal to display LAPI logs in realtime: - -```bash -docker-compose logs -f crowdsec -``` - -* In wp-admin, [ensure the bouncer is configured with **live** mode](http://localhost/wp-admin/admin.php?page=crowdsec_plugin) (stream mode disabled). - -###### Discover the cache system - -* In a tab, visit the [public home](http://localhost/). You're allowed because LAPI said your IP is clean. - -> To avoid latencies when the clean IP browse the website, the bouncer will keep this information in cache for 30 seconds (you can change this value in the [avdanced settings page](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings)). In other words, LAPI will not be requested to check this IP for the next 30 seconds. - - * You can call the website as many times as you want, the cache system will take relay during the ban period and so LAPI will not be disturbed. The ban decision will stay in cache for the full ban duration. Then the [public home](http://localhost/) should be available again. - - ###### Try ban remediation - -* If you want to skip this delay, feel free to [clear the cache in the wp-admin](http://localhost/wp-admin/admin.php?page=crowdsec_plugin). - -The `DOCKER_HOST_IP` environnement variable is initialized via a call to: - -```bash -source ./load-env-vars.sh -``` - -* In a terminal, ban your own IP for 4 hours: - -```bash - -# Ban your own IP for 4 hours: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* Immediately, the [public home](http://localhost/) is now locked with a short message to explain you that you are banned. - -###### Try "captcha" remediation - - -* Now, request captcha for your own IP for 15m: - -```bash - -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all - -# Add a captcha -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha -``` - -* The [public home](http://localhost/) now request you to fill a captcha. - -* Unless you manage to solve the captcha, you'll not be able to access the website. - -> Note: when you resolve the captcha in your browser, the associated PHP session is considered as sure. -> If you remove the captcha decision with `cscli`, then you add a new captcha decision for your IP, you'll not be prompted for the current PHP session. To view the captcha page, You can force using a new PHP session opening the front page with incognito mode. - -##### Stream mode, for the high traffic websites - -With live mode, as you tried it just before, each time a user arrives to the website for the first time, a call is made to LAPI. If the traffic on your website is high, the bouncer will call LAPI very often. - -To avoid this, LAPI offers a "stream" mode. The decisions list is updated at a predefined frequency and kept in cache. Let's try it! - -> This bouncer uses the WordPress cron system. For demo purposes, we encourage you to [install the WP-Control plugin](http://localhost/wp-admin/plugin-install.php?s=wp-control&tab=search&type=term), a plugin to view and control each Wordpress Cron task jobs. - -First, clear the previous decisions: - -```bash -# Clear all existing decisions -docker-compose exec crowdsec cscli decisions delete --all -``` - -* Then enable "stream" mode [right here](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) and set the resync frequency to 30 seconds. If you installed WP-Control plugin, you can see that a new cron tak has just been added here http://localhost/wp-admin/tools.php?page=crontrol_admin_manage_page. - -* As the whole blocklist has just been loaded in cache (0 decision!), your IP is allowed. The [public home](http://localhost/) is available. - -* Now, if you ban your IP for 4h: - -```bash -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 4h --type ban -``` - -* In less than 30 seconds your IP will be banned and the [public home](http://localhost/) will be locked. - -Conclusion: with the stream mode, LAPI decisions are fetched on a regular basis rather than being called when user arrives for the first time. - -#### Try Redis or Memcached - -In order to get better performances, you can switch the cache technology. - -The docker-compose file started 2 unused containers, redis and memcached. - -Let's try **Redis**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Redis" and -- type `redis://redis:6379` in the "Redis DSN" field. - -Very similar with **Memcached**! - -- Just go to the [advanced settings](http://localhost/wp-admin/admin.php?page=crowdsec_advanced_settings) page -- select the **Caching technology** named "Memcached" and -- type `memcached://memcached:11211` in the "Memcached DSN" field. - - -#### Statistics - -The bouncer has a stats page indicating each time : -- an IP has been banned by your website, or -- when a captcha has been presented to an IP visiting your website -- when a captcha has been solved or not. - - -### How to contribute? - -#### Contribute to this plugin - -> First, be sure to [get the stack installed using the docker-compose guide](wordpress#install-with-docker-compose). -#### Play with crowdsec state - -```bash - -#### Add captcha your own IP for 15m: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -#### Ban your own IP for 15 sec: -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15s --type ban - -#### Remove all decisions: -docker-compose exec crowdsec cscli decisions delete --all - -#### View CrowdSec logs: -docker-compose logs crowdsec -``` - -> Note: The `DOCKER_HOST_IP` environnment variable is initialized via `source ./load-env-vars.sh`. - -#### WP Scan pass - -```bash -docker-compose run --rm wpscan --url http://wordpress5-6/ -``` - -##### Reinstall `composer` dependencies - -```bash -docker-compose exec wordpress5-6 composer install --working-dir /var/www/html/wp-content/plugins/cs-wordpress-bouncer --prefer-source -``` - -> In this dev environment, we use `--prefer-source` to be able to develop the bouncer library at the same time. Composer may ask you for your own Github token to download sources instead of using dist packages. - - -###### Quick `docker-compose` cheet sheet - -```bash -docker-compose run wordpress sh # run sh on wordpress container -docker-compose ps # list running containers -docker-compose stop # stop -docker-compose rm # destroy -``` - -###### Try the plugin with another PHP version - -```bash -docker-compose down -docker images | grep wordpress-bouncer_wordpress # to get the container id -docker rmi -``` - -Then, in the `.env` file, replace: - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION=7.2 -``` - -with : - -```bash -CS_WORDPRESS_BOUNCER_PHP_VERSION= -``` - -Then re-run the stack. - -###### Try the plugin with another WordPress version - - -The plugin is tested under each of these WordPress versions: `5.6`, `5.5`, `5.4`, `5.3`, `5.2`, `5.1`, `5.0`, `4.9`. -(Representing [more than 90% of the wordpress websites](https://wordpress.org/about/stats/)) - - -###### Add support for a new WordPress version - -This is a cheat sheet to help testing briefly the support: - -```bash - -# To install a specific version -docker-compose up -d wordpress crowdsec mysql redis memcached && docker-compose exec crowdsec cscli bouncers add wordpress-bouncer - -# To display the captcha wall - -docker-compose exec crowdsec cscli decisions add --ip ${DOCKER_HOST_IP} --duration 15m --type captcha - -# To delete the image in order to rebuild it - -docker-compose down && docker rmi wordpress-bouncer_wordpress - -# To debug inside the container - -docker-compose run wordpress bash -``` - -> Note: The `DOCKER_HOST_IP` environnement variable is initialized via `source ./load-env-vars.sh`. - -###### Plugin debug mode VS production mode - -The debug mode throws verbose errors. The production mode hides every error to let users navigate in every edge cases. - -This plugin goes in debug mode when Wordpress debug mode is enabled. - -To try the production mode of this plugin, just disable the wordpress debug mode: in `docker-compose.yml`, comment the line: -```yml - WORDPRESS_DEBUG: 1 # Comment this line the simulate the production mode -``` - -###### Display the plugin logs - -```bash -tail -f logs/debug-* -``` - - -## FAQ - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the wordpress host command line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - htt://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace [host]:[port] with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -### Contribute to this plugin from a MacOS host - -You can test the Linux behavior of this project using **Vagrant**. - -#### One time setup - -##### Run the VM and initialize it - -```bash -vagrant up -vagrant ssh -sudo usermod -aG docker vagrant -sudo systemctl restart docker -``` - -You have to log out and log back for permission to be updated: - -```bash -exit -vagrant ssh -``` -##### Enabled Docker IPV6 support inside the Linux VM - -follow [this guide](https://docs.docker.com/config/daemon/ipv6/). (Note that you'll have to create the file `/etc/docker/daemon.json`). - - -##### Install NodeJS - -Follow [this guide](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions)/ - -##### Install Yarn - -Follow [this guide](https://linuxize.com/post/how-to-install-yarn-on-ubuntu-18-04/). - -##### Add deps to run playwright - -```bash -sudo apt-get install libnss3\ - libnspr4\ - libatk1.0-0\ - libatk-bridge2.0-0\ - libxcb1\ - libxkbcommon0\ - libx11-6\ - libxcomposite1\ - libxdamage1\ - libxext6\ - libxfixes3\ - libxrandr2\ - libgbm1\ - libgtk-3-0\ - libpango-1.0-0\ - libcairo2\ - libgdk-pixbuf2.0-0\ - libasound2\ - libatspi2.0-0 -``` - -##### Edit you local host file: - -Type `sudo vim /etc/hosts` and add: - -```bash -# select the one you want to try by uncommenting only ont of the two -# 172.16.0.50 wordpress5-6 # Uncomment to use IPV4 -fde4:8dba:82e1::c4 wordpress5-6 # Uncomment to use IPV6 -``` - -##### Configure your `.env` file - -```bash -cd /vagrant -cp .env.example .env -``` - -Update the created `.env` file with: - -```bash -DEBUG=0 -DOCKER_HOST_IP=172.16.238.1 # OR IF YOU WANT TO TEST WITH IPV6 USE: 2001:3200:3200::1 -``` - -##### Run "plugin auto setup" via e2e tests (limited to setup steps) - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Browse the WordPress website admin - -Visit [http://wordpress5-6/wp-admin](http://wordpress5-6/wp-admin). - -##### Run tests - -```bash -SETUP_ONLY=1 ./run-tests.sh -``` - -##### Stop the Virtal Machine -```bash -vagrant stop # vagrant up to start after -``` - -##### Clean up environnement - -To destroy the vagrant instance: - -```bash -vagrant destroy -``` - - -## Licence - -[MIT License](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/LICENSE) diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/cloudflare.mdx deleted file mode 100644 index 7acb2e98..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/cloudflare.mdx +++ /dev/null @@ -1,254 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Don't redirect the generated configuration to `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` with bash redirection (`>`) but use the `-o` flag instead, else you will loose your existing configuration (eg. `crowdsec_lapi_key`). - -::: - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - - -## Manual Installation - -### Assisted - - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -d` to cleanup cloudflare components before editing the config files. - -::: - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/cloudflare-bouncer \ - -g > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -touch cloudflare-cache.json -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml \ - -v $PWD/cloudflare-cache.json:/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json \ - -p 2112:2112 \ - crowdsecurity/cloudflare-bouncer -``` - - -# Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${LAPI_KEY} -crowdsec_update_frequency: 10s - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: challenge - zones: - - actions: - - challenge # valid choices are either of challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -cache_path: /var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -g ,... > cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. It also deletes the local cache. - -Example Usage: -```bash -/usr/local/bin/crowdsec-cloudflare-bouncer -d -``` - -# How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - - -# Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - The cache is at `/var/lib/crowdsec/crowdsec-cloudflare-bouncer/cache/cloudflare-cache.json`. It can be inspected to see the state of bouncer and cloudflare components locally. - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/custom.mdx deleted file mode 100644 index 8ca9ff9f..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/custom.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for custom scripts. - -crowdsec-custom-bouncer will periodically fetch new and expired/removed decisions from CrowdSec Local API and will pass them as arguments to a custom user script. - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## Manual install (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 - -Before starting the `crowdsec-custom-bouncer` service, please edit the configuration to add your API url and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -:warning: don't forget to add execution permissions to your binary/script - -### Examples: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/firewall.mdx deleted file mode 100644 index d38c9919..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/firewall.mdx +++ /dev/null @@ -1,221 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -Crowdsec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -### Using packages - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - -#### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -#### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -## Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -## Configuration - -**note : this is only relevant for "manual" or "from source" installation, as packages would take care of all the needed configuration** - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - -```yaml title="/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml" -mode: "iptables" -pid_dir: "/var/run/" -update_frequency: "10s" -daemonize: true -log_mode: "file" -log_dir: "/var/log/" -log_level: "info" -api_url: "" # when install, default is "localhost:8080" -api_key: "" # Add your API key generated with `cscli bouncers add ` -disable_ipv6: "false" -deny_mode: "DROP" -deny_log: "false -#deny_log_prefix: "crowdsec: " -#if present, insert rule in those chains -iptables_chains: - - "INPUT" - - "FORWARD" -``` - - - `mode` can be set to `iptables`, `nftables` , `ipset` or `pf` - - `update_frequency` controls how often the bouncer is going to query the local API - - `api_url` and `api_key` control local API parameters. - - `iptables_chains` allows (in _iptables_ mode) to control in which chain rules are going to be inserted. (if empty, bouncer will only maintain ipset lists) - - `disable_ipv6` - set to true to disable ipv6 - - `deny_mode` - what action to use to deny, one of DROP or REJECT - - `deny_log` - set this to true to add a log statement to the firewall rule - - `deny_log_prefix` - if logging is true, this sets the log prefix, defaults to "crowdsec: " - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. - - ### ipset - - ipset lists have to exist before crowdsec-firewall-bouncer starts - you could create them and add them to your iptables like this: - ``` -ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000 -ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000 -iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP -ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/ingress-nginx.mdx deleted file mode 100644 index b77f2ae0..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; # If you want captcha support otherwise remove this line -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/intro.md deleted file mode 100644 index deade5e5..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/local_api/intro.md) to be able to get information about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/nginx.mdx deleted file mode 100644 index 8d73f86e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/nginx.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/openresty.mdx deleted file mode 100644 index 2910f133..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/openresty.mdx +++ /dev/null @@ -1,416 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty, openresty-opm, gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, we need to specify a trusted certificate (`lua_ssl_trusted_certificate`). You can also change this with a valid one. - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/php.mdx deleted file mode 100644 index cf72c4cc..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/php.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: php -title: PHP Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -## How does it work ? - -This bouncer leverages the PHP `auto_preprend` mechanism. - -New/unknown IP are checked against crowdsec API, and if request should be blocked, a **403** or a captcha can be returned to the user, and put in cache. - -At the back, this bouncer uses [crowdsec PHP lib](https://github.com/crowdsecurity/php-cs-bouncer). - -## Installation - -### Prerequisite - - -#### Install `composer` - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - - -#### Download the bouncer - - -Download the Github bouncer repository. - -```bash -git clone https://github.com/crowdsecurity/cs-php-bouncer.git -cd cs-php-bouncer/ -``` - - -### Apache - -For Apache, the install script can handle most of the work. - -```bash -./install.sh --apache - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - -crowdsec_apache apache2 configuration enabled - -And reload apache2 service - - sudo systemctl reload apache2 - -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -Then just changed the owner of the bouncer folder to your webserver user and reload your apache2 service. - -### Other web servers - -For other web servers, use the install script. - -```bash -./install.sh - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de kkado : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - - -Add the "php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php'" to your .htacess file. - -And reload your webserver. - -``` - -Then changed the owner of the bouncer folder to your webserver user. - -Now you need to add the `auto_preprend_file` to your htacess file like: - -``` -php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php' -``` - -And reload your webserver. - -## Upgrade - -Clone the Github repository and run the upgrade script: - -```bash -./upgrade.sh -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -## Configuration - -Here is the configuration used by the bouncer, located in `/usr/local/php/crowdsec/settings.php`. - -```php title=/usr/local/php/crowdsec/settings.php -$crowdSecStandaloneBouncerConfig = [ - 'api_url' => 'http://127.0.0.1:8080', // Default local API is 127.0.0.1:8080. Example in the docker-compose dev context, use http://crowdsec:8080 - 'api_key' => '${API_KEY}', // [FILL ME] Set a bouncer key here - 'debug_mode' => false, // [FILL ME] Set to true to stop the process and display errors if any - 'log_directory_path' => __DIR__.'/.logs', // [FILL ME] Important note: be sur this path won't be publicly accessible! - 'fs_cache_path' => __DIR__.'/.cache', // [FILL ME] Important note: be sur this path won't be publicly accessible! - - 'bouncing_level' => 'normal_boucing', - - 'stream_mode' => false, - - 'cache_system' => 'phpfs', - 'redis_dsn' => '', - 'memcached_dsn' => '', - - 'clean_ip_cache_duration' => 5, - 'bad_ip_cache_duration' => 10, - 'fallback_remediation' => 'captcha', - - 'hide_mentions' => false, - 'trust_ip_forward' => '', - 'trust_ip_forward_array' => [], - - 'theme_color_text_primary' => 'black', - 'theme_color_text_secondary' => '#AAA', - 'theme_color_text_button' => 'white', - 'theme_color_text_error_message' => '#b90000', - 'theme_color_background_page' => '#eee', - 'theme_color_background_container' => 'white', - 'theme_color_background_button' => '#626365', - 'theme_color_background_button_hover' => '#333', - - 'theme_text_captcha_wall_tab_title' => 'Oops..', - 'theme_text_captcha_wall_title' => 'Hmm, sorry but...', - 'theme_text_captcha_wall_subtitle' => 'Please complete the security check.', - 'theme_text_captcha_wall_refresh_image_link' => 'refresh image', - 'theme_text_captcha_wall_captcha_placeholder' => 'Type here...', - 'theme_text_captcha_wall_send_button' => 'CONTINUE', - 'theme_text_captcha_wall_error_message' => 'Please try again.', - 'theme_text_captcha_wall_footer' => '', - - 'theme_text_ban_wall_tab_title' => 'Oops..', - 'theme_text_ban_wall_title' => '🤭 Oh!', - 'theme_text_ban_wall_subtitle' => 'This page is protected against cyber attacks and your IP has been banned by our system.', - 'theme_text_ban_wall_footer' => '', - 'theme_custom_css' => '', -]; - -``` - - -## References - -- https://crowdsec.net/protect-php-websites/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/wordpress.mdx deleted file mode 100644 index 56dbd739..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.0/bouncers/wordpress.mdx +++ /dev/null @@ -1,326 +0,0 @@ ---- -id: wordpress -title: Wordpress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## Usage - -### Description - -The `CrowdSec Bouncer` plugin for WordPress has been designed to protect WordPress websites from all kinds of -attacks by using [CrowdSec](https://crowdsec.net/) technology. - -### Prerequisites - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). -CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost CrowdSec must be installed on a server that is accessible via the WordPress site. - - -### Features - -When a user is suspected by CrowdSec to be malevolent, this bouncer will either send him/her a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he will access the page as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages in a few clicks so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users’ language. - - -### Configurations - -This plugin comes with configurations that you will find under `CrowdSec` admin section. - -These configurations are divided in three main parts : `CrowdSec`, `Theme customization`,and `Advanced`. - -#### General settings - -In the `CrowdSec` part, you will set your connection details and refine bouncing according to your needs. - -Connection details - -*** - -`Connection details → LAPI URL` - -Url to join your CrowdSec LAPI. - -*** - -`Connection details → Bouncer API key` - -Key generated by the cscli command. - -*** - -`Bouncing → Bouncing level` - -Choose if you want to apply CrowdSec directives (`Normal bouncing`) or be more permissive (`Flex bouncing`). - -With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This -mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario. - -*** - -`Bouncing → Public website only` - -If enabled, the admin is not bounced. - -*** - - -#### Theme customization - -In the `Theme customization` part, you can modify texts and colors of ban and captcha walls. - -Captcha wall customization - -Ban wall customization - -Wall CSS - - -#### Advanced settings - -In the `Advanced` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec -LAPI, handle your remediation policy and adjust some debug and log parameters. - -Communication mode - - -*** - -`Communication mode to the API → Enable the "Stream mode"` - -Choose if you want to enable the `stream mode` or stay in `live mode`. - - -By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. - -But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -*** - -`Communication mode to the API → Resync decisions each (stream mode only)` - -With the stream mode, every decision is retrieved in an asynchronous way. Here you can define the frequency of this -cache refresh. - -**N.B** : There is also a refresh button if you want to refresh the cache manually. - -*** - -Cache - -*** - -`Caching configuration → Technology` - -Choose the cache technology that will use your CrowdSec LAPI. - -The File system cache is faster than calling LAPI. Redis or Memcached is faster than the File System cache. - -**N.B** : There are also a `Clear now` button fo all cache technologies and a `Prune now` button dedicated to the -file system cache. - -*** - -`Caching configuration → Recheck clean IPs each (live mode only)` - -The duration between re-asking LAPI about an already checked clean IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - -`Caching configuration → Recheck bad IPs each (live mode only)` - -The duration between re-asking LAPI about an already checked bad IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - - -*** - -`Caching configuration → Captcha flow cache lifetime` - -The lifetime of cached captcha flow for some IP. - -If a user has to interact with a captcha wall, -we store in cache some values in order to know if he has to resolve or not the captcha again. - -Minimum 1 second. Default: 86400 seconds. - - -*** - -Remediations - -*** - -`Remediations → Fallback to` - -Choose which remediation to apply when CrowdSec advises unhandled remediation. - -*** - -`Remediations → Trust these CDN IPs (or Load Balancer, HTTP Proxy)` - -If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate in the bouncer settings the IP ranges of these devices in order to be able to check the IP of your users. For other IPs, the bouncer will not trust the X-Forwarded-For header. -*** - -`Remediations → Hide CrowdSec mentions` - -Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls. - -Debug - -*** - -`Debug mode → Enable debug mode` - -Enable if you want to see some debug information in a specific log file. - -*** - -`Display errors → Enable errors display` - -When this mode is enabled, you will see every unexpected bouncing errors in the browser. -Should be disabled in production. - - -### Auto Prepend File mode - -By default, this extension will bounce every web requests that pass through the classical process of WordPress core loading. -This implies that if another php public script is called (any of your custom public php script for example) -or if you are using some plugin that bypass the WordPress core load process -(as the [WP Super Cache plugin](https://wordpress.org/plugins/wp-super-cache/) in Simple mode for example), bouncing will not be effective. - -To ensure that any php script will be bounced if called from a browser, you should try the `auto prepend file` mode. - -In this mode, every browser access to a php script will be bounced. - -To enable the `auto prepend file` mode, you have to configure your server by adding an `auto_prepend_file` directive -for your php setup. - -**N.B:** -- In this mode, a setting file `inc/standalone-settings.php` will be generated each time you save the - CrowdSec plugin configuration from the WordPress admin. - - -Adding an `auto_prepend_file` directive can be done in different ways: - -#### PHP - -You should add this line to a `.ini` file : - - auto_prepend_file = /wordpress-root-directory/wp-content/plugins/cs-wordpress-bouncer/inc/standalone-bounce.php - - -#### Nginx - - -If you are using Nginx, you should modify your Magento 2 nginx configuration file by adding a `fastcgi_param` -directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "/wordpress-root-directory/wp-content/plugins/cs-wordpress-bouncer/inc/standalone-bounce.php"; -} -``` - -#### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/wordpress-root-directory/wp-content/plugins/cs-wordpress-bouncer/inc/standalone-bounce.php" - - - -### Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - - -## Installation - - -### Add the plugin - -The bouncer itself can be installed from the marketplace in WordPress back-office. - -Installing the CrowdSec WordPress plugin is as easy as installing any other WordPress plugin: - -- Click `Plugins` in the left navigation on your site’s dashboard. -- Type `CrowdSec` in the text field to the right. Hit enter. -- In the CrowdSec plugin click `Install Now` -- Once installed click `Activate`. - - -### WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Technical notes - -We explain here each important technical decision used to design this -plugin. - - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the wordpress host command line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - http://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace `` with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/docs/DEVELOPER.md) - -## License - -[MIT](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/LICENSE) - - - - - - - - - - - - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/aws-waf.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/aws-waf.mdx deleted file mode 100644 index 95417316..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/aws-waf.mdx +++ /dev/null @@ -1,238 +0,0 @@ ---- -id: aws_waf -title: AWS WAF Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -The `crowdsec-awf-waf-bouncer` automatically adds rules to an existing AWS WAF ACL and manages IPSets content to apply decisions taken by crowdsec. - -This allows to protect the following AWS ressources with crowdsec: - - AWS REST API Gateway - - Cloudfront distribution - - AWS Application LoadBalancer - - AWS AppSync GraphQL API - -As the bouncer does not manage your WAF ACLs, you will need to have existing ACLs already associated with your AWS ressources for the bouncer to work properly. -The bouncer supports the `ban` and `captcha` decisions type, and can be configured to fallback to one of those for decisions of unknown type. - -It can block at the IP (using `ip` scope in CrowdSec), range (using `range` scope in CrowdSec) or country level (using `country` scope in CrowdSec). - -The bouncer will create all required resources and associate them with your existing ACLs based on the configuration you provided. - -As the resources will incur an AWS cost, the bouncer will remove everything it created when stopping. - -If you do not have an existing AWS WAF configuration, you can refer to the [official documentation](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to get started. - -## Installation - -### Using packages - -Packages for crowdsec-aws-waf-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-aws-waf-bouncer -``` - - - - -```bash -sudo yum install crowdsec-aws-waf-bouncer -``` - - - - -### Docker - -```shell -docker run -v $(PWD)/config.yaml:/cs-aws-waf-bouncer.yaml crowdsecurity/aws-waf-bouncer -``` - -## Configuration - -You will need to edit `/etc/crowdsec/bouncers/crowdsec-aws-waf-bouncer.yaml` to configure the ACLs you want the bouncer to use. - -```yaml -api_key: XXXX -api_url: "http://127.0.0.1:8080/" -update_frequency: 10s -waf_config: - - web_acl_name: mywebacl - fallback_action: ban - rule_group_name: crowdsec-rule-group-eu-west-1 - scope: REGIONAL - region: eu-west-1 - ipset_prefix: crowdsec-ipset-a - ip_header: X-Forwarded-For - ip_header_position: LAST - aws_profile: myprofile - - web_acl_name: test-cloudfront - fallback_action: captcha - rule_group_name: crowdsec-rule-group-cloudfront - scope: CLOUDFRONT - ipset_prefix: crowdsec-ipset-cf -``` - -Optionally, the bouncer can also be configured using only environment variables. - -Environment variables will take priority over values defined in the configuration file. - -AWS authentication is handled with the standard environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE) or instance role. - -You can also use the `aws_profile` directive to specify a profile to use for a specific waf configuration. - ---- -#### `api_key` -##### Environment variable: `BOUNCER_API_KEY` - -API key to use for communication with LAPI. - -#### `api_url` -##### Environment variable: `BOUNCER_API_URL` - -URL of LAPI. - -#### `update_frequency` -##### Environment variable: `BOUNCER_UPDATE_FREQUENCY` - -How often the bouncer will contact LAPI to update its content. - -The format must be supported by [golang ParseDuration](https://pkg.go.dev/time#ParseDuration). - ---- -### `waf_config` -##### Environment variable: `BOUNCER_WAF_CONFIG_` - - -List of object with the following properties: - -``` -waf_config: - - web_acl_name: mywebacl - fallback_action: ban - rule_group_name: crowdsec-rule-group-XXX - scope: REGIONAL - region: eu-west-1 - ipset_prefix: crowdsec-ipset- -``` - -When configuring through environment variables, you can pass multiple `BOUNCER_WAF_CONFIG_X_` variables, with `X` being a unique identifier (eg, `0`, `1`, `2`, ...). - -#### `web_acl_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_WEB_ACL_NAME` - - -Name of the WAF ACL in which the rule group will be added - -#### `fallback_action` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_FALLBACK_ACTION` - -Action to use if the type of a decision is not `captcha` or `ban`. - -Must be one of `captcha` or `ban`. - -#### `rule_group_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_RULE_GROUP_NAME` - - -Name of the rule group the bouncer will create and add to the WAF ACL. - -Must be unique accross all the configuration. - -2 rules can be created: - - crowdsec-rule-ban - - crowdsec-rule-captcha - -Those rules are automatically deleted if no decisions of the associated type exists. - -If a decision for a country is received, the following rules will be created: - - crowdsec-rule-ban-country: Contains a geomatch statement for banned countries - - crowdsec-rule-captcha-country: Contains a geomatch statement for captcha'ed countries - -Those rules will be deleted on shutdown and will be recreated on startup if they already exists. - -#### `scope` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_SCOPE` - - -Scope of the rule group and ipset. Can be `REGIONAL` or `CLOUDFRONT`. - -Must match the scope of the WAF ACL. - -#### `region` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_REGION` - - -Region where all ressources will be created. - -No required when scope is `CLOUDFRONT` - -#### `ipset_prefix` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IPSET_PREFIX` - -Prefix for all the ipsets the bouncer will create. - -One ipset will be created per 10k IPs, and will be automatically deleted if it becomes empty. - -Differents ipsets are used for ban and captcha. - -All ipsets are deleted on shutdown. - -#### `aws_profile` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_AWS_PROFILE` - -Name of the AWS profile (defined in ~/.aws/config) to use. - -#### `ip_header` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IP_HEADER` - -Name of the header to use to get the source IP. -If not defined, the actual source IP will be used. - -If the header is not present or does not contain any valid IP, the request will be allowed. - -#### `ip_header_position` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IP_HEADER_POSITION` - -If the header used to get the source IP is a comma separated list, this parameter can be used to specify which part of the list should be used. - -Must be one of `FIRST`, `LAST`, `ANY`. - -Required when `ip_header` is defined. - -#### `capacity` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_CAPACITY` - -Capacity of the rule group created by the bouncer. - -If not set, default to 300 (this value is way higher than it needs to be, but this prevents any kind of issue regarding capacity of the rule group). - -For reference, a simple match on a IP with no custom header will cost 1 WCU per IPSet created by the bouncer, or 5 WCU if you are getting the source IP from a header. - -See [AWS WAF documentation](https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works.html#aws-waf-capacity-units) for more information. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/blocklist-mirror.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/blocklist-mirror.mdx deleted file mode 100644 index 6832f669..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/blocklist-mirror.mdx +++ /dev/null @@ -1,248 +0,0 @@ ---- -id: blocklist-mirror -title: Blocklist mirror -sidebar_position: 7 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

-

- - -This bouncer exposes CrowdSec's active decisions via provided HTTP endpoints in pre-defined formats. It can be used by network appliances which support consumption of blocklists via HTTP. - - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-blocklist-mirror -``` - - - - -```bash -sudo yum install crowdsec-blocklist-mirror -``` - - - - - -## Installation using docker: - -Refer to docker [hub docs](https://hub.docker.com/r/crowdsecurity/blocklist-mirror) - - - -## Manual installation via script - -First, download the latest [`crowdsec-blocklist-mirror` release](https://github.com/crowdsecurity/cs-blocklist-mirror/releases). - -```bash -tar xzvf crowdsec-blocklist-mirror.tgz -sudo ./install.sh -``` - -## From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/crowdsec-blocklist-mirror.git -cd crowdsec-blocklist-mirror/ -make release -tar xzvf crowdsec-blocklist-mirror.tgz -cd crowdsec-blocklist-mirror-v*/ -sudo ./install.sh -``` - -# Configuration - -Before starting the `crowdsec-blocklist-mirror` service, please edit the configuration file to add your API URL and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-blocklist-mirror.yaml -``` - -```yaml -config_version: v1.0 -crowdsec_config: - lapi_key: ${API_KEY} - lapi_url: http://127.0.0.1:8080/ - update_frequency: 10s - include_scenarios_containing: [] - exclude_scenarios_containing: [] - only_include_decisions_from: [] - insecure_skip_verify: false - -blocklists: - - format: plain_text # Supported formats are either of "plain_text" - endpoint: /security/blocklist - authentication: - type: none # Supported types are either of "none", "ip_based", "basic" - user: - password: - trusted_ips: # IP ranges, or IPs which don't require auth to access this blocklist - - 127.0.0.1 - - ::1 - -listen_uri: 127.0.0.1:41412 -tls: - cert_file: - key_file: - -metrics: - enabled: true - endpoint: /metrics - -log_media: file -log_dir: /var/log/ -log_level: info -log_max_size: 40 -log_max_age: 30 -log_max_backups: 3 -enable_access_logs: true -compress_logs: true -``` - -### `crowdsec_config` - -#### `lapi_url`: - -The URL of CrowdSec LAPI. It should be accessible from whichever network the bouncer has access. - -#### `lapi_key`: - -It can be obtained by running the following on the machine CrowdSec LAPI is deployed on. -```bash - -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. - -``` - -#### `update_frequency`: - -The bouncer will poll the CrowdSec every `update_frequency` interval. - -#### `include_scenarios_containing`: - -Ignore IPs banned for triggering scenarios not containing either of provided word. - -#### `exclude_scenarios_containing`: - -Ignore IPs banned for triggering scenarios containing either of provided word. - - -#### `only_include_decisions_from`: - -Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -#### `insecure_skip_verify`: - -Set to true to skip verifying certificate. - - -#### `listen_uri`: - -Location where the mirror will start server. - -### `tls_config` - -#### `cert_file`: - -Path to certificate to use if TLS is to be enabled on the mirror server. - -#### `key_file`: - -Path to certificate key file. - -### `metrics`: - -#### `enabled`: - -Boolean (true|false). Set to true to enable serving and collecting metrics. - -#### `endpoint`: - -Endpoint to serve the metrics on. - -### `blocklists`: - -List of blocklists to serve. Each blocklist has the following configuration. - -#### `format`: - -Format of the blocklist. Currently only `plain_text` is supported. - -#### `endpoint`: - -Endpoint to serve the blocklist on. - -### `authentication`: - -Authentication related config. - -#### `type`: - -Currently "basic" and "ip_based" authentication is supported. You can disable authentication completely by setting this to 'none'. - -- `basic`: It's Basic HTTP Authentication. Only requests with valid `user` and `password` as specified in below config would pass through - -- `ip_based`: Only requests originating from `trusted_ips` would be allowed. - -#### `user`: - -Valid username if using `basic` authentication. - -#### `password`: - -Password for the provided user and using `basic` authentication. - -#### `trusted_ips`: - -List of valid IPv4 and IPv6 IPs and ranges which have access to blocklist. It's only applicable when authentication `type` is `ip_based`. - -You can then start the service via: - -```sh -sudo systemctl start crowdsec-blocklist-mirror -``` - -## Formats - -The bouncer can expose the blocklist in the following formats. You can configure the format of the blocklist by setting it's `format` paramter to any of the supported formats described below. - -### plain_text - -Example: - -``` -1.2.3.4 -4.3.2.1 -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/cloudflare.mdx deleted file mode 100644 index 855cb712..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/cloudflare.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Please configure your server to emit real IPs rather than cloudflare IPs in logs, so crowdsec can function properly. See how to [here](https://support.cloudflare.com/hc/en-us/articles/200170786-Restoring-original-visitor-IPs) - -::: - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - -:::note - -You need to run `sudo crowdsec-cloudflare-bouncer -d` to cleanup exisiting cloudflare components created by bouncer before editing the config files. - -::: - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` to generate the configuration by discovering all the accounts and the zones associated with the provided tokens. - -::: - - -## Manual Installation - -### Assisted - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/cloudflare-bouncer \ - -g , > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml \ - -p 2112:2112 \ - crowdsecurity/cloudflare-bouncer -``` - - -## Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${API_KEY} -crowdsec_update_frequency: 10s -include_scenarios_containing: [] # ignore IPs banned for triggering scenarios not containing either of provided word, eg ["ssh", "http"] -exclude_scenarios_containing: [] # ignore IPs banned for triggering scenarios containing either of provided word -only_include_decisions_from: [] # only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: managed_challenge - total_ip_list_capacity: # only this many latest ip scoped decisions would be kept - - zones: - - actions: - - managed_challenge # valid choices are either of managed_challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -log_max_size: 40 -log_max_age: 30 -log_max_backups: 3 -compress_logs: true - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Making changes to configuration - -The bouncer creates Cloudflare infra (IP lists, rules etc) according to your config file. - -Before changing the config, always run the following command to clear old infra: - -``` -sudo crowdsec-cloudflare-bouncer -d -``` - -### Upgrading from v0.0.X to v0.1.Y - -During v0.0.X there was no `managed_challenge` action, instead `challenge` action was used by bouncer. This is deprecated since v0.1.0 . - -This section assumes you used the default config (generated via `crowdsec-cloudflare-bouncer -g ,` ) - -After upgrading the bouncer from v0.0.X to v0.1.Y , run the following commands to migrate to `managed_challenge`. - -```bash -sudo crowdsec-cloudflare-bouncer -d -sudo crowdsec-cloudflare-bouncer -g , -o -sudo systemctl restart crowdsec-cloudflare-bouncer -``` - - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -sudo crowdsec-cloudflare-bouncer -g ,... -o cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -sudo crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -sudo crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. - -Example Usage: -```bash -sudo crowdsec-cloudflare-bouncer -d -``` - -## How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - -## Configuration Reference - -### `crowdsec_lapi_url` - -The URL of CrowdSec LAPI. It should be accessible from the bouncer. - -### `crowdsec_lapi_key` - -It can be obtained by running the following on the machine CrowdSec LAPI is deployed on. -```bash - -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. - -``` - -### `crowdsec_update_frequency` - -The bouncer will poll the CrowdSec every `update_frequency` interval. - -### `include_scenarios_containing` - -Ignore IPs banned for triggering scenarios not containing either of provided word. Example value ["ssh", "http"] - -### `exclude_scenarios_containing` - -Ignore IPs banned for triggering scenarios containing either of provided word. Example value ["ssh", "http"] - - -### `only_include_decisions_from` - -Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -### `cloudflare_config` - -This block contains cloudflare specific config. - -#### `update_frequency` - -The frequency at which to update the cloudflare resources. eg values include `5s` or `1m` etc. - -#### `accounts` - -List of account of configs - -##### `id` - -id of cloudflare account - -##### `token` - -cloudflare token to use to access the account. - -##### `ip_list_prefix` - -The prefix to use for naming the IP lists created by the bouncer. The name of IP list will be of the form `ip_list_prefix`+`action`. - -##### `total_ip_list_capacity` - -Limit the number of items in IP lists by this number. This is required for avoiding limit of 10k items for lists. - -##### `default_action` - -The action to be applied for a decision, if the decision's action is not supported by a zone. - -`default_action` must be supported by all zones. - - -| Decision Type | Zone Action | -| -------------------| ----------- | -| captcha | managed_challenge | -| ban | block | -| js_challenge | js_challenge | - - -Valid choice includes either of either of 'managed_challenge', 'block', 'js_challenge', 'challenge' or 'none' to ignore unsupported decision. - -:::warning -`challenge` action is deprecated in favour of `managed_challenge`. -::: - -#### `zones` - -This block contains config for each zone to be managed by the bouncer. The zone must be accessible from the parent account. - -##### `zone_id` - -The id of the zone. - -##### `actions` - -List of actions to be supported by this zone. If the zone is not subscribed to premium plan, then only a single action can be given. - -The supported action must include the `default_action` of the parent account. - -Valid choice includes either of either of -- `block` -- `js_challenge` -- `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. - -:::warning -`challenge` action is deprecated in favour of `managed_challenge` -::: - -Decisions with action `ban` would be inserted into list created for `block`. -Decisions with action `js_challenge` would be inserted into list created for `js_challenge`. -Decisions with action `captcha` would be inserted into list for `managed_challenge`. - - - -### `daemon` - -Boolean (true|false). Set to true if the bouncer is being run as background daemon service. - -### `log_mode` - -Valid values are `stdout` or `file` - -### `log_dir` - -Relevant if `log_mode` is `file`. This determines where to create log file. - -### `log_level` - -Valid choices are either debug, info, error - -### `log_max_size`, `log_max_age`, `log_max_backups`, `compress_logs` - -Log rotation releated config. - - -## Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/custom.mdx deleted file mode 100644 index 880179ff..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/custom.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -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 - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## 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 - -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/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -:warning: don't forget to add execution permissions to your binary/script - -### Examples: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/fastly.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/fastly.mdx deleted file mode 100644 index 6f27909d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/fastly.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -id: fastly -title: Fastly Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -# 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. -To learn how to setup crowdsec to consume fastly logs see [this](/docs/next/user_guides/consuming_fastly_logs) - - -# Installation: - -## Using pip - -Make sure you have python3.8+ installed. Now in a virtual environment run the following: - -```bash -pip install crowdsec-fastly-bouncer -crowdsec-fastly-bouncer -g , > config.yaml # generate config -vim config.yaml # Set crowdsec LAPI key, url, recaptcha keys, logging etc -crowdsec-fastly-bouncer -c config.yaml # Run it ! -``` - -See how to obtain fastly account tokens [here](https://docs.fastly.com/en/guides/using-api-tokens). The tokens must have write access for the configured services. - -**Note:** If your bouncer is not installed on the same machine than LAPI, don't forget to set the `lapi_url` and `lapi_key` in the configuration file /etc/crowdsec/bouncers/crowdsec-fastly-bouncer.yaml - -**Note:** For captcha to work you must provide the `recaptcha_site_key` and `recaptcha_secret_key` for each service. Learn how [here](http://www.google.com/recaptcha/admin) - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/fastly-bouncer \ - -g , > cfg.yaml # auto-generate fastly config for provided comma separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -touch fastly-cache.json -``` - -The `lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add fastlybouncer # -oraw flag can discarded for human friendly output. -``` - -The `lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-fastly-bouncer.yaml \ - -v $PWD/fastly-cache.json:/var/lib/crowdsec/crowdsec-fastly-bouncer/cache/fastly-cache.json \ - crowdsecurity/fastly-bouncer -``` - -## 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 ! - -# Configuration: - -```yaml -crowdsec_config: - lapi_key: ${LAPI_KEY} - lapi_url: "http://localhost:8080/" - -fastly_account_configs: - - account_token: # Obtain this from fastly - services: - - id: # The id of the service - recaptcha_site_key: # Required for captcha support - recaptcha_secret_key: # Required for captcha support - max_items: 20000 # max_items refers to the capacity of IP/IP ranges to ban/captcha. - activate: false # # Set to true, to activate the new config in production - reference_version: # version to clone/use - clone_reference_version: true # whether to clone the "reference_version". - captcha_cookie_expiry_duration: '1800' # Duration to persist the cookie containing proof of solving captcha - -bouncer_version: -update_frequency: 10 # Duration in seconds to poll the crowdsec API -log_level: info # Valid choices are either of "debug","info","warning","error" -log_mode: stdout # Valid choices are "file" or "stdout" or "stderr" -log_file: /var/log/crowdsec-fastly-bouncer.log # Ignore if logging to stdout or stderr -``` - -# Helpers: - -The bouncer has few builtin helper features: - -## Auto config generator: - -**Usage:** - -```bash -crowdsec-fastly-bouncer -c \ - -g , -``` - -This will print boilerplate config with sane defaults for the provided comma separted fastly tokens. -Always review the generated config before proceeding further. - -Crowdsec config is copied from the config at `PATH_TO_BASE_CONFIG`. - -## Cleaner: - -**Usage:** - -```bash -sudo crowdsec-fastly-bouncer -c -d -``` - -This deletes the fastly resources created by the bouncer. -It only works if the configured service version is not locked. -It is useful for quick iteration before activateing the new service. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/firewall.mdx deleted file mode 100644 index fd49dcdb..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/firewall.mdx +++ /dev/null @@ -1,313 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -CrowdSec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - -### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - -### pf - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -See as well [Manual Installation documentation below](/docs/bouncers/firewall#manual-installation) - - - -## Configuration - -There are two main usage case around the firewall bouncer : - - **managed** (default) : cs-firewall-bouncer will create ispet/nft sets, insert the associated firewall rules and manage set's content - - **set only** : you already have a (complex) firewall setup, cs-firewall-bouncer will only manage the _content_ of existing specified sets - - -### Managed mode : Iptables/ipset or Nftables - -__This is the default behaviour__ - -In "managed" mode (mode `nftables` or `iptables`), bouncer creates all the needed elements (rules, sets) and insert the appropriate rules in nftables or iptables. - -### Set Only : Iptables/Ipset table - -In iptable set only mode (mode `ispet`), bouncer only manages the **contents** of sets designed by `blacklists_ipv4` and `blacklists_ipv6`. -Those sets must exist prior to the bouncer startup, and it is the user's responsability to create the associate iptables rules. - -### Set Only : nftables - -In nftables set only mode (mode `nftables` with `nftables.{ipv4,ipv6}.set-only` set to `true`), bouncer only manages the **contents** of the sets. -It's the user's responsability to create the associated chains and sets : - -```yaml title="/tmp/bouncer.nft" -table ip crowdsec { - set crowdsec-blacklists { - type ipv4_addr - flags timeout - } - - chain crowdsec-chain { - type filter hook input priority filter; policy accept; - ip saddr @crowdsec-blacklists drop - } -} -table ip6 crowdsec6 { - set crowdsec6-blacklists { - type ipv6_addr - flags timeout - } - - chain crowdsec6-chain { - type filter hook input priority filter; policy accept; - ip6 saddr @crowdsec6-blacklists drop - } -} -``` - - -## Configuration directives - - - - `mode` : can be set to `iptables`, `nftables` , `ipset` or `pf` - - `pid_dir` : directory to drop pid file - - `update_frequency` controls how often the bouncer is going to query the local API - - `daemonize` : for systemd unit - - `log_mode` : can be `file` or `stdout` - - `log_dir` : log directory - - `log_level` : can be `trace`, `debug`, `info`, or `error` - - `log_compression` : compress logs on rotation, `true` or `false` - - `log_max_size` : maximum file size before rotation - - `log_max_backups` : how many backup log files to keep - - `log_max_age` : oldest backup log file before deletion - - `api_url` and `api_key` control local API parameters. - - `insecure_skip_verify` : allow self-signed certificates for LAPI, `false` or `true` - - `disable_ipv6` : disable ipv6 support, defaults to `false` - - `deny_action` : firewall action to apply, defaults to `DROP`, but can be `REJECT` - - `deny_log` : if set to `true`, enables logging of dropped packets (ie. `-j LOG`) - - `deny_log_prefix` : if logging is true, this sets the log prefix, defaults to "crowdsec: " - -### Iptables/Ipset specific directives - - - - `iptables_chains` : specify a list of chains to insert rules (only relevant in `iptables` mode) : - - `blacklists_ipv4` and `blacklists_ipv6` : names of ipv4 and ipv6 sets - -```yaml -iptables_chains: - - INPUT -# - FORWARD -# - DOCKER-USER -``` - -### Nftables specific directives - -Nftables mode has its own `nftables` section, with sub-section of ipv4 and ipv6 : - -```yaml -## nftables -nftables: - ipv4: - enabled: true - set-only: false - table: crowdsec - chain: crowdsec-chain - ipv6: - enabled: true - set-only: false - table: crowdsec6 - chain: crowdsec6-chain -``` - -if `set-only` is set to true, the bouncer will only manage the set contents. - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -### Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -### Configuration for manual installation - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - - - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. - - ### ipset - - ipset lists have to exist before crowdsec-firewall-bouncer starts - you could create them and add them to your iptables like this: - ``` -ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000 -ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000 -iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP -ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/ingress-nginx.mdx deleted file mode 100644 index b36b2710..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/intro.md deleted file mode 100644 index deade5e5..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/local_api/intro.md) to be able to get information about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/nginx.mdx deleted file mode 100644 index d92d9ea2..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/nginx.mdx +++ /dev/null @@ -1,421 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base lua-cjson -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - lua-cjson: JSON parser/encoder for Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/openresty.mdx deleted file mode 100644 index f666824d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/openresty.mdx +++ /dev/null @@ -1,425 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/php.mdx deleted file mode 100644 index cf72c4cc..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/php.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: php -title: PHP Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -## How does it work ? - -This bouncer leverages the PHP `auto_preprend` mechanism. - -New/unknown IP are checked against crowdsec API, and if request should be blocked, a **403** or a captcha can be returned to the user, and put in cache. - -At the back, this bouncer uses [crowdsec PHP lib](https://github.com/crowdsecurity/php-cs-bouncer). - -## Installation - -### Prerequisite - - -#### Install `composer` - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - - -#### Download the bouncer - - -Download the Github bouncer repository. - -```bash -git clone https://github.com/crowdsecurity/cs-php-bouncer.git -cd cs-php-bouncer/ -``` - - -### Apache - -For Apache, the install script can handle most of the work. - -```bash -./install.sh --apache - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - -crowdsec_apache apache2 configuration enabled - -And reload apache2 service - - sudo systemctl reload apache2 - -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -Then just changed the owner of the bouncer folder to your webserver user and reload your apache2 service. - -### Other web servers - -For other web servers, use the install script. - -```bash -./install.sh - -Installing crowdsec-php-bouncer -[sudo] Mot de passe de kkado : - -crowdsec-php-bouncer installed successfully! - -Please set the owner of '/usr/local/php/crowdsec/' to www-data or to your webserver owner. - -You can do it with: - - sudo chown www-data /usr/local/php/crowdsec/ - - -Add the "php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php'" to your .htacess file. - -And reload your webserver. - -``` - -Then changed the owner of the bouncer folder to your webserver user. - -Now you need to add the `auto_preprend_file` to your htacess file like: - -``` -php_value auto_prepend_file '/usr/local/php/crowdsec/crowdsec-php-bouncer.php' -``` - -And reload your webserver. - -## Upgrade - -Clone the Github repository and run the upgrade script: - -```bash -./upgrade.sh -``` - -:::note - -Don't run the script as root but your password might be asked during the installation process. - -::: - -## Configuration - -Here is the configuration used by the bouncer, located in `/usr/local/php/crowdsec/settings.php`. - -```php title=/usr/local/php/crowdsec/settings.php -$crowdSecStandaloneBouncerConfig = [ - 'api_url' => 'http://127.0.0.1:8080', // Default local API is 127.0.0.1:8080. Example in the docker-compose dev context, use http://crowdsec:8080 - 'api_key' => '${API_KEY}', // [FILL ME] Set a bouncer key here - 'debug_mode' => false, // [FILL ME] Set to true to stop the process and display errors if any - 'log_directory_path' => __DIR__.'/.logs', // [FILL ME] Important note: be sur this path won't be publicly accessible! - 'fs_cache_path' => __DIR__.'/.cache', // [FILL ME] Important note: be sur this path won't be publicly accessible! - - 'bouncing_level' => 'normal_boucing', - - 'stream_mode' => false, - - 'cache_system' => 'phpfs', - 'redis_dsn' => '', - 'memcached_dsn' => '', - - 'clean_ip_cache_duration' => 5, - 'bad_ip_cache_duration' => 10, - 'fallback_remediation' => 'captcha', - - 'hide_mentions' => false, - 'trust_ip_forward' => '', - 'trust_ip_forward_array' => [], - - 'theme_color_text_primary' => 'black', - 'theme_color_text_secondary' => '#AAA', - 'theme_color_text_button' => 'white', - 'theme_color_text_error_message' => '#b90000', - 'theme_color_background_page' => '#eee', - 'theme_color_background_container' => 'white', - 'theme_color_background_button' => '#626365', - 'theme_color_background_button_hover' => '#333', - - 'theme_text_captcha_wall_tab_title' => 'Oops..', - 'theme_text_captcha_wall_title' => 'Hmm, sorry but...', - 'theme_text_captcha_wall_subtitle' => 'Please complete the security check.', - 'theme_text_captcha_wall_refresh_image_link' => 'refresh image', - 'theme_text_captcha_wall_captcha_placeholder' => 'Type here...', - 'theme_text_captcha_wall_send_button' => 'CONTINUE', - 'theme_text_captcha_wall_error_message' => 'Please try again.', - 'theme_text_captcha_wall_footer' => '', - - 'theme_text_ban_wall_tab_title' => 'Oops..', - 'theme_text_ban_wall_title' => '🤭 Oh!', - 'theme_text_ban_wall_subtitle' => 'This page is protected against cyber attacks and your IP has been banned by our system.', - 'theme_text_ban_wall_footer' => '', - 'theme_custom_css' => '', -]; - -``` - - -## References - -- https://crowdsec.net/protect-php-websites/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/windows-firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/windows-firewall.mdx deleted file mode 100644 index d468251b..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/windows-firewall.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -id: windows_firewall -title: Windows Firewall Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -The windows firewall bouncer interacts with the Windows Firewall to block IPs banned by CrowdSec. - -It will create multiple rules in the firewall (one rule will contains 1000 IPs) and will manage their lifecycle. - -The rules are created on startup and automatically deleted when the bouncer stops. - -## Installation - -:::warning - -The .NET 6 runtime is required for the bouncer to work ! - -::: - -You can download either a MSI (containing only the bouncer) or a setup bundle (containing the bouncer and the .NET 6 runtime) from the github releases: https://github.com/crowdsecurity/cs-windows-firewall-bouncer/releases - -You can also install the bouncer with [Chocolatey](https://chocolatey.org/) (this will automatically install the .NET runtime): - -```powershell -choco install crowdsec-windows-firewall-bouncer -``` - -## Configuration - -The configuration is stored in `C:\Program Files\CrowdSec\bouncers\cs-windows-firewall-bouncer\cs-windows-firewall-bouncer.yaml` - -### Example configuration - -```yaml -api_key: -api_url: http://127.0.0.1:8080 -log_level: info -update_frequency: 10s -log_media: file -log_dir: C:\ProgramData\CrowdSec\log\ -fw_profiles: - - domain -``` - ---- - -#### `api_key` - -API key to use for communication with LAPI. - -#### `api_url` - -URL of LAPI. - -#### `update_frequency` - -How often the bouncer will contact LAPI to update its content in seconds. - -Defaults to `10`. - -#### `log_media` - -Wether to log to file or to the console. - -Defaults to file when running as service and console when running in interactive mode. - -#### `log_dir` - -Location of the log file. - -Defaults to `C:\ProgramData\CrowdSec\log\`. - -#### `log_level` - -Log level. - -Can be one of: - - `trace` - - `debug` - - `info` - - `warn` - - `error` - - `fatal` - -Defaults to `info`. - -#### fw_profiles - -The firewall profile the rules will be associated with. - -The bouncer automatically select the current profile, but you can override this behaviour with this parameter. - -Allowed values are: - - `domain` - - `private` - - `public` - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/wordpress.mdx deleted file mode 100644 index 56dbd739..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.3.4/bouncers/wordpress.mdx +++ /dev/null @@ -1,326 +0,0 @@ ---- -id: wordpress -title: Wordpress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## Usage - -### Description - -The `CrowdSec Bouncer` plugin for WordPress has been designed to protect WordPress websites from all kinds of -attacks by using [CrowdSec](https://crowdsec.net/) technology. - -### Prerequisites - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). -CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost CrowdSec must be installed on a server that is accessible via the WordPress site. - - -### Features - -When a user is suspected by CrowdSec to be malevolent, this bouncer will either send him/her a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he will access the page as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages in a few clicks so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users’ language. - - -### Configurations - -This plugin comes with configurations that you will find under `CrowdSec` admin section. - -These configurations are divided in three main parts : `CrowdSec`, `Theme customization`,and `Advanced`. - -#### General settings - -In the `CrowdSec` part, you will set your connection details and refine bouncing according to your needs. - -Connection details - -*** - -`Connection details → LAPI URL` - -Url to join your CrowdSec LAPI. - -*** - -`Connection details → Bouncer API key` - -Key generated by the cscli command. - -*** - -`Bouncing → Bouncing level` - -Choose if you want to apply CrowdSec directives (`Normal bouncing`) or be more permissive (`Flex bouncing`). - -With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This -mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario. - -*** - -`Bouncing → Public website only` - -If enabled, the admin is not bounced. - -*** - - -#### Theme customization - -In the `Theme customization` part, you can modify texts and colors of ban and captcha walls. - -Captcha wall customization - -Ban wall customization - -Wall CSS - - -#### Advanced settings - -In the `Advanced` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec -LAPI, handle your remediation policy and adjust some debug and log parameters. - -Communication mode - - -*** - -`Communication mode to the API → Enable the "Stream mode"` - -Choose if you want to enable the `stream mode` or stay in `live mode`. - - -By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. - -But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -*** - -`Communication mode to the API → Resync decisions each (stream mode only)` - -With the stream mode, every decision is retrieved in an asynchronous way. Here you can define the frequency of this -cache refresh. - -**N.B** : There is also a refresh button if you want to refresh the cache manually. - -*** - -Cache - -*** - -`Caching configuration → Technology` - -Choose the cache technology that will use your CrowdSec LAPI. - -The File system cache is faster than calling LAPI. Redis or Memcached is faster than the File System cache. - -**N.B** : There are also a `Clear now` button fo all cache technologies and a `Prune now` button dedicated to the -file system cache. - -*** - -`Caching configuration → Recheck clean IPs each (live mode only)` - -The duration between re-asking LAPI about an already checked clean IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - -`Caching configuration → Recheck bad IPs each (live mode only)` - -The duration between re-asking LAPI about an already checked bad IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - - -*** - -`Caching configuration → Captcha flow cache lifetime` - -The lifetime of cached captcha flow for some IP. - -If a user has to interact with a captcha wall, -we store in cache some values in order to know if he has to resolve or not the captcha again. - -Minimum 1 second. Default: 86400 seconds. - - -*** - -Remediations - -*** - -`Remediations → Fallback to` - -Choose which remediation to apply when CrowdSec advises unhandled remediation. - -*** - -`Remediations → Trust these CDN IPs (or Load Balancer, HTTP Proxy)` - -If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate in the bouncer settings the IP ranges of these devices in order to be able to check the IP of your users. For other IPs, the bouncer will not trust the X-Forwarded-For header. -*** - -`Remediations → Hide CrowdSec mentions` - -Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls. - -Debug - -*** - -`Debug mode → Enable debug mode` - -Enable if you want to see some debug information in a specific log file. - -*** - -`Display errors → Enable errors display` - -When this mode is enabled, you will see every unexpected bouncing errors in the browser. -Should be disabled in production. - - -### Auto Prepend File mode - -By default, this extension will bounce every web requests that pass through the classical process of WordPress core loading. -This implies that if another php public script is called (any of your custom public php script for example) -or if you are using some plugin that bypass the WordPress core load process -(as the [WP Super Cache plugin](https://wordpress.org/plugins/wp-super-cache/) in Simple mode for example), bouncing will not be effective. - -To ensure that any php script will be bounced if called from a browser, you should try the `auto prepend file` mode. - -In this mode, every browser access to a php script will be bounced. - -To enable the `auto prepend file` mode, you have to configure your server by adding an `auto_prepend_file` directive -for your php setup. - -**N.B:** -- In this mode, a setting file `inc/standalone-settings.php` will be generated each time you save the - CrowdSec plugin configuration from the WordPress admin. - - -Adding an `auto_prepend_file` directive can be done in different ways: - -#### PHP - -You should add this line to a `.ini` file : - - auto_prepend_file = /wordpress-root-directory/wp-content/plugins/cs-wordpress-bouncer/inc/standalone-bounce.php - - -#### Nginx - - -If you are using Nginx, you should modify your Magento 2 nginx configuration file by adding a `fastcgi_param` -directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "/wordpress-root-directory/wp-content/plugins/cs-wordpress-bouncer/inc/standalone-bounce.php"; -} -``` - -#### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/wordpress-root-directory/wp-content/plugins/cs-wordpress-bouncer/inc/standalone-bounce.php" - - - -### Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - - -## Installation - - -### Add the plugin - -The bouncer itself can be installed from the marketplace in WordPress back-office. - -Installing the CrowdSec WordPress plugin is as easy as installing any other WordPress plugin: - -- Click `Plugins` in the left navigation on your site’s dashboard. -- Type `CrowdSec` in the text field to the right. Hit enter. -- In the CrowdSec plugin click `Install Now` -- Once installed click `Activate`. - - -### WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Technical notes - -We explain here each important technical decision used to design this -plugin. - - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the wordpress host command line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - http://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace `` with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/docs/DEVELOPER.md) - -## License - -[MIT](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/LICENSE) - - - - - - - - - - - - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/aws-waf.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/aws-waf.mdx deleted file mode 100644 index 2384ff6c..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/aws-waf.mdx +++ /dev/null @@ -1,264 +0,0 @@ ---- -id: aws_waf -title: AWS WAF Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -The `crowdsec-awf-waf-bouncer` automatically adds rules to an existing AWS WAF ACL and manages IPSets content to apply decisions taken by crowdsec. - -This allows to protect the following AWS ressources with crowdsec: - - AWS REST API Gateway - - Cloudfront distribution - - AWS Application LoadBalancer - - AWS AppSync GraphQL API - -As the bouncer does not manage your WAF ACLs, you will need to have existing ACLs already associated with your AWS ressources for the bouncer to work properly. -The bouncer supports the `ban` and `captcha` decisions type, and can be configured to fallback to one of those for decisions of unknown type. - -It can block at the IP (using `ip` scope in CrowdSec), range (using `range` scope in CrowdSec) or country level (using `country` scope in CrowdSec). - -The bouncer will create all required resources and associate them with your existing ACLs based on the configuration you provided. - -As the resources will incur an AWS cost, the bouncer will remove everything it created when stopping. - -If you do not have an existing AWS WAF configuration, you can refer to the [official documentation](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to get started. - -## Installation - -### Using packages - -Packages for crowdsec-aws-waf-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-aws-waf-bouncer -``` - - - - -```bash -sudo yum install crowdsec-aws-waf-bouncer -``` - - - - -### Docker - -```shell -docker run -v $(PWD)/config.yaml:/cs-aws-waf-bouncer.yaml crowdsecurity/aws-waf-bouncer -``` - -## Configuration - -You will need to edit `/etc/crowdsec/bouncers/crowdsec-aws-waf-bouncer.yaml` to configure the ACLs you want the bouncer to use. - -```yaml -api_key: XXXX -api_url: "http://127.0.0.1:8080/" -update_frequency: 10s -waf_config: - - web_acl_name: mywebacl - fallback_action: ban - rule_group_name: crowdsec-rule-group-eu-west-1 - scope: REGIONAL - region: eu-west-1 - ipset_prefix: crowdsec-ipset-a - ip_header: X-Forwarded-For - ip_header_position: LAST - aws_profile: myprofile - - web_acl_name: test-cloudfront - fallback_action: captcha - rule_group_name: crowdsec-rule-group-cloudfront - scope: CLOUDFRONT - ipset_prefix: crowdsec-ipset-cf -``` - -Optionaly, the bouncer can also be configured using only environment variables. - -Environment variables will take priority over values defined in the configuration file. - -AWS authentication is handled with the standard environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE) or instance role. - -You can also use the `aws_profile` directive to specify a profile to use for a specific waf configuration. - ---- -#### `api_key` -##### Environment variable: `BOUNCER_API_KEY` - -API key to use for communication with LAPI. - -#### `api_url` -##### Environment variable: `BOUNCER_API_URL` - -URL of LAPI. - -#### `update_frequency` -##### Environment variable: `BOUNCER_UPDATE_FREQUENCY` - -How often the bouncer will contact LAPI to update its content. - -The format must be supported by [golang ParseDuration](https://pkg.go.dev/time#ParseDuration). - -#### `supported_actions` -##### Environment variable: `BOUNCER_SUPPORTED_ACTIONS` - -Which actions (ie, remediation type) the bouncer supports. - -List with any of the following: `ban`, `captcha`, `count`. - -Default to `ban`, `captcha` and `count`. - -If set from the environment, provide a comma-separated list: `ban,captcha,count`. - -#### `cloudwatch_enabled` -##### Environment variable: `BOUNCER_CLOUDWATCH_ENABLED` - -Whether or not AWS WAF will send metrics to CloudWatch for the rule group. - -#### `cloudwatch_metric_name` -##### Environment variable: `BOUNCER_CLOUDWATCH_METRIC_NAME` - -Name of the cloudwatch metric. Default to the rule group name. - -#### `sample_requests` -##### Environment variable: `BOUNCER_SAMPLE_REQUESTS` - -Whether or not to sample requests from the rule groups created by the bouncer. - ---- -### `waf_config` -##### Environment variable: `BOUNCER_WAF_CONFIG_` - - -List of object with the following properties: - -``` -waf_config: - - web_acl_name: mywebacl - fallback_action: ban - rule_group_name: crowdsec-rule-group-XXX - scope: REGIONAL - region: eu-west-1 - ipset_prefix: crowdsec-ipset- -``` - -When configuring through environment variables, you can pass multiple `BOUNCER_WAF_CONFIG_X_` variables, with `X` being a unique identifier (eg, `0`, `1`, `2`, ...). - -#### `web_acl_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_WEB_ACL_NAME` - - -Name of the WAF ACL in which the rule group will be added - -#### `fallback_action` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_FALLBACK_ACTION` - -Action to use if the type of a decision is not in the list defined by `supported_actions`. - -Must be one of `captcha`, `ban` or `count`. - -#### `rule_group_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_RULE_GROUP_NAME` - - -Name of the rule group the bouncer will create and add to the WAF ACL. - -Must be unique accross all the configuration. - -2 rules can be created: - - crowdsec-rule-ban - - crowdsec-rule-captcha - -Those rules are automatically deleted if no decisions of the associated type exists. - -If a decision for a country is received, the following rules will be created: - - crowdsec-rule-ban-country: Contains a geomatch statement for banned countries - - crowdsec-rule-captcha-country: Contains a geomatch statement for captcha'ed countries - -Those rules will be deleted on shutdown and will be recreated on startup if they already exists. - -#### `scope` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_SCOPE` - - -Scope of the rule group and ipset. Can be `REGIONAL` or `CLOUDFRONT`. - -Must match the scope of the WAF ACL. - -#### `region` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_REGION` - - -Region where all ressources will be created. - -No required when scope is `CLOUDFRONT` - -#### `ipset_prefix` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IPSET_PREFIX` - -Prefix for all the ipsets the bouncer will create. - -One ipset will be created per 10k IPs, and will be automatically deleted if it becomes empty. - -Differents ipsets are used for ban and captcha. - -All ipsets are deleted on shutdown. - -#### `aws_profile` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_AWS_PROFILE` - -Name of the AWS profile (defined in ~/.aws/config) to use. - -#### `ip_header` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IP_HEADER` - -Name of the header to use to get the source IP. -If not defined, the actual source IP will be used. - -If the header is not present or does not contain any valid IP, the request will be allowed. - -#### `ip_header_position` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IP_HEADER_POSITION` - -If the header used to get the source IP is a comma separated list, this parameter can be used to specify which part of the list should be used. - -Must be one of `FIRST`, `LAST`, `ANY`. - -Required when `ip_header` is defined. - -#### `capacity` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_CAPACITY` - -Capacity of the rule group created by the bouncer. - -If not set, default to 300 (this value is way higher than it needs to be, but this prevents any kind of issue regarding capacity of the rule group). - -For reference, a simple match on a IP with no custom header will cost 1 WCU per IPSet created by the bouncer, or 5 WCU if you are getting the source IP from a header. - -See [AWS WAF documentation](https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works.html#aws-waf-capacity-units) for more information. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/blocklist-mirror.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/blocklist-mirror.mdx deleted file mode 100644 index 6832f669..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/blocklist-mirror.mdx +++ /dev/null @@ -1,248 +0,0 @@ ---- -id: blocklist-mirror -title: Blocklist mirror -sidebar_position: 7 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

-

- - -This bouncer exposes CrowdSec's active decisions via provided HTTP endpoints in pre-defined formats. It can be used by network appliances which support consumption of blocklists via HTTP. - - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-blocklist-mirror -``` - - - - -```bash -sudo yum install crowdsec-blocklist-mirror -``` - - - - - -## Installation using docker: - -Refer to docker [hub docs](https://hub.docker.com/r/crowdsecurity/blocklist-mirror) - - - -## Manual installation via script - -First, download the latest [`crowdsec-blocklist-mirror` release](https://github.com/crowdsecurity/cs-blocklist-mirror/releases). - -```bash -tar xzvf crowdsec-blocklist-mirror.tgz -sudo ./install.sh -``` - -## From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/crowdsec-blocklist-mirror.git -cd crowdsec-blocklist-mirror/ -make release -tar xzvf crowdsec-blocklist-mirror.tgz -cd crowdsec-blocklist-mirror-v*/ -sudo ./install.sh -``` - -# Configuration - -Before starting the `crowdsec-blocklist-mirror` service, please edit the configuration file to add your API URL and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-blocklist-mirror.yaml -``` - -```yaml -config_version: v1.0 -crowdsec_config: - lapi_key: ${API_KEY} - lapi_url: http://127.0.0.1:8080/ - update_frequency: 10s - include_scenarios_containing: [] - exclude_scenarios_containing: [] - only_include_decisions_from: [] - insecure_skip_verify: false - -blocklists: - - format: plain_text # Supported formats are either of "plain_text" - endpoint: /security/blocklist - authentication: - type: none # Supported types are either of "none", "ip_based", "basic" - user: - password: - trusted_ips: # IP ranges, or IPs which don't require auth to access this blocklist - - 127.0.0.1 - - ::1 - -listen_uri: 127.0.0.1:41412 -tls: - cert_file: - key_file: - -metrics: - enabled: true - endpoint: /metrics - -log_media: file -log_dir: /var/log/ -log_level: info -log_max_size: 40 -log_max_age: 30 -log_max_backups: 3 -enable_access_logs: true -compress_logs: true -``` - -### `crowdsec_config` - -#### `lapi_url`: - -The URL of CrowdSec LAPI. It should be accessible from whichever network the bouncer has access. - -#### `lapi_key`: - -It can be obtained by running the following on the machine CrowdSec LAPI is deployed on. -```bash - -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. - -``` - -#### `update_frequency`: - -The bouncer will poll the CrowdSec every `update_frequency` interval. - -#### `include_scenarios_containing`: - -Ignore IPs banned for triggering scenarios not containing either of provided word. - -#### `exclude_scenarios_containing`: - -Ignore IPs banned for triggering scenarios containing either of provided word. - - -#### `only_include_decisions_from`: - -Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -#### `insecure_skip_verify`: - -Set to true to skip verifying certificate. - - -#### `listen_uri`: - -Location where the mirror will start server. - -### `tls_config` - -#### `cert_file`: - -Path to certificate to use if TLS is to be enabled on the mirror server. - -#### `key_file`: - -Path to certificate key file. - -### `metrics`: - -#### `enabled`: - -Boolean (true|false). Set to true to enable serving and collecting metrics. - -#### `endpoint`: - -Endpoint to serve the metrics on. - -### `blocklists`: - -List of blocklists to serve. Each blocklist has the following configuration. - -#### `format`: - -Format of the blocklist. Currently only `plain_text` is supported. - -#### `endpoint`: - -Endpoint to serve the blocklist on. - -### `authentication`: - -Authentication related config. - -#### `type`: - -Currently "basic" and "ip_based" authentication is supported. You can disable authentication completely by setting this to 'none'. - -- `basic`: It's Basic HTTP Authentication. Only requests with valid `user` and `password` as specified in below config would pass through - -- `ip_based`: Only requests originating from `trusted_ips` would be allowed. - -#### `user`: - -Valid username if using `basic` authentication. - -#### `password`: - -Password for the provided user and using `basic` authentication. - -#### `trusted_ips`: - -List of valid IPv4 and IPv6 IPs and ranges which have access to blocklist. It's only applicable when authentication `type` is `ip_based`. - -You can then start the service via: - -```sh -sudo systemctl start crowdsec-blocklist-mirror -``` - -## Formats - -The bouncer can expose the blocklist in the following formats. You can configure the format of the blocklist by setting it's `format` paramter to any of the supported formats described below. - -### plain_text - -Example: - -``` -1.2.3.4 -4.3.2.1 -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/cloudflare.mdx deleted file mode 100644 index 7c57064e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/cloudflare.mdx +++ /dev/null @@ -1,442 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Please configure your server to emit real IPs rather than cloudflare IPs in logs, so crowdsec can function properly. See how to [here](https://support.cloudflare.com/hc/en-us/articles/200170786-Restoring-original-visitor-IPs) - -::: - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - -:::note - -You need to run `sudo crowdsec-cloudflare-bouncer -d` to cleanup exisiting cloudflare components created by bouncer before editing the config files. - -::: - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` to generate the configuration by discovering all the accounts and the zones associated with the provided tokens. - -::: - - -## Manual Installation - -### Assisted - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/cloudflare-bouncer \ - -g , > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml \ - -p 2112:2112 \ - crowdsecurity/cloudflare-bouncer -``` - - -## Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${API_KEY} -crowdsec_update_frequency: 10s -include_scenarios_containing: [] # ignore IPs banned for triggering scenarios not containing either of provided word, eg ["ssh", "http"] -exclude_scenarios_containing: [] # ignore IPs banned for triggering scenarios containing either of provided word -only_include_decisions_from: [] # only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: managed_challenge - total_ip_list_capacity: # only this many latest ip scoped decisions would be kept - - zones: - - actions: - - managed_challenge # valid choices are either of managed_challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -log_max_size: 40 -log_max_age: 30 -log_max_backups: 3 -compress_logs: true - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Making changes to configuration - -The bouncer creates Cloudflare infra (IP lists, rules etc) according to your config file. - -Before changing the config, always run the following command to clear old infra: - -``` -sudo crowdsec-cloudflare-bouncer -d -``` - -### Upgrading from v0.0.X to v0.1.Y - -During v0.0.X there was no `managed_challenge` action, instead `challenge` action was used by bouncer. This is deprecated since v0.1.0 . - -This section assumes you used the default config (generated via `crowdsec-cloudflare-bouncer -g ,` ) - -After upgrading the bouncer from v0.0.X to v0.1.Y , run the following commands to migrate to `managed_challenge`. - -```bash -sudo crowdsec-cloudflare-bouncer -d -sudo crowdsec-cloudflare-bouncer -g , -o -sudo systemctl restart crowdsec-cloudflare-bouncer -``` - - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -sudo crowdsec-cloudflare-bouncer -g ,... -o cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -sudo crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -sudo crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. - -Example Usage: -```bash -sudo crowdsec-cloudflare-bouncer -d -``` - -## How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - -## Configuration Reference - -### `crowdsec_lapi_url` - -The URL of CrowdSec LAPI. It should be accessible from the bouncer. - -### `crowdsec_lapi_key` - -It can be obtained by running the following on the machine CrowdSec LAPI is deployed on. -```bash - -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. - -``` - -### `crowdsec_update_frequency` - -The bouncer will poll the CrowdSec every `update_frequency` interval. - -### `include_scenarios_containing` - -Ignore IPs banned for triggering scenarios not containing either of provided word. Example value ["ssh", "http"] - -### `exclude_scenarios_containing` - -Ignore IPs banned for triggering scenarios containing either of provided word. Example value ["ssh", "http"] - - -### `only_include_decisions_from` - -Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -### `cloudflare_config` - -This block contains cloudflare specific config. - -#### `update_frequency` - -The frequency at which to update the cloudflare resources. eg values include `5s` or `1m` etc. - -#### `accounts` - -List of account of configs - -##### `id` - -id of cloudflare account - -##### `token` - -cloudflare token to use to access the account. - -##### `ip_list_prefix` - -The prefix to use for naming the IP lists created by the bouncer. The name of IP list will be of the form `ip_list_prefix`+`action`. - -##### `total_ip_list_capacity` - -Limit the number of items in IP lists by this number. This is required for avoiding limit of 10k items for lists. - -##### `default_action` - -The action to be applied for a decision, if the decision's action is not supported by a zone. - -`default_action` must be supported by all zones. - -Valid choice includes either of 'managed_challenge', 'block', 'js_challenge', 'challenge' or 'none' to ignore unsupported decision. - -**Example:** - -Consider your zone config supports the actions `managed_challenge` and `js_challenge`. Your `default_action` is `managed_action`. If you create the following decision: - -``` -sudo cscli decisions add --ip 1.2.3.4 --type ban -``` - -Since the zone doesn't support `ban` decision type, it'll be inserted into the IP list given by `default_action`. In this case it'll be the list for `managed_challenge`. - -You can completely ignore such decisions by setting `default_action` to `none`. It won't be inserted into any list then. - -**Note:** - -Following table is mapping of decision type to it's destination IP list. - -| Decision Type | Default Action | -| -------------------| ----------- | -| captcha | managed_challenge | -| ban | block | -| js_challenge | js_challenge | - - -:::warning -`challenge` action is deprecated in favour of `managed_challenge`. -::: - -#### `zones` - -This block contains config for each zone to be managed by the bouncer. The zone must be accessible from the parent account. - -##### `zone_id` - -The id of the zone. - -##### `actions` - -List of actions to be supported by this zone. If the zone is not subscribed to premium plan, then only a single action can be given. - -The supported action must include the `default_action` of the parent account. - -Valid choice includes either of -- `block` -- `js_challenge` -- `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. - -:::warning -`challenge` action is deprecated in favour of `managed_challenge` -::: - -**Note:** - -Following table is mapping of decision type to it's destination IP list, which are created according to zone actions - - -| Decision Type | Zone Action | -| -------------------| ----------- | -| captcha | managed_challenge | -| ban | block | -| js_challenge | js_challenge | - - - -### `daemon` - -Boolean (true|false). Set to true if the bouncer is being run as background daemon service. - -### `log_mode` - -Valid values are `stdout` or `file` - -### `log_dir` - -Relevant if `log_mode` is `file`. This determines where to create log file. - -### `log_level` - -Valid choices are either debug, info, error - -### `log_max_size`, `log_max_age`, `log_max_backups`, `compress_logs` - -Log rotation releated config. - - -## Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/custom.mdx deleted file mode 100644 index 5703447b..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/custom.mdx +++ /dev/null @@ -1,146 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -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 - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## 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 - -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/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -sudo systemctl start crowdsec-custom-bouncer -``` - -# 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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -: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: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/fastly.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/fastly.mdx deleted file mode 100644 index 6f27909d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/fastly.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -id: fastly -title: Fastly Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -# 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. -To learn how to setup crowdsec to consume fastly logs see [this](/docs/next/user_guides/consuming_fastly_logs) - - -# Installation: - -## Using pip - -Make sure you have python3.8+ installed. Now in a virtual environment run the following: - -```bash -pip install crowdsec-fastly-bouncer -crowdsec-fastly-bouncer -g , > config.yaml # generate config -vim config.yaml # Set crowdsec LAPI key, url, recaptcha keys, logging etc -crowdsec-fastly-bouncer -c config.yaml # Run it ! -``` - -See how to obtain fastly account tokens [here](https://docs.fastly.com/en/guides/using-api-tokens). The tokens must have write access for the configured services. - -**Note:** If your bouncer is not installed on the same machine than LAPI, don't forget to set the `lapi_url` and `lapi_key` in the configuration file /etc/crowdsec/bouncers/crowdsec-fastly-bouncer.yaml - -**Note:** For captcha to work you must provide the `recaptcha_site_key` and `recaptcha_secret_key` for each service. Learn how [here](http://www.google.com/recaptcha/admin) - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/fastly-bouncer \ - -g , > cfg.yaml # auto-generate fastly config for provided comma separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -touch fastly-cache.json -``` - -The `lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add fastlybouncer # -oraw flag can discarded for human friendly output. -``` - -The `lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-fastly-bouncer.yaml \ - -v $PWD/fastly-cache.json:/var/lib/crowdsec/crowdsec-fastly-bouncer/cache/fastly-cache.json \ - crowdsecurity/fastly-bouncer -``` - -## 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 ! - -# Configuration: - -```yaml -crowdsec_config: - lapi_key: ${LAPI_KEY} - lapi_url: "http://localhost:8080/" - -fastly_account_configs: - - account_token: # Obtain this from fastly - services: - - id: # The id of the service - recaptcha_site_key: # Required for captcha support - recaptcha_secret_key: # Required for captcha support - max_items: 20000 # max_items refers to the capacity of IP/IP ranges to ban/captcha. - activate: false # # Set to true, to activate the new config in production - reference_version: # version to clone/use - clone_reference_version: true # whether to clone the "reference_version". - captcha_cookie_expiry_duration: '1800' # Duration to persist the cookie containing proof of solving captcha - -bouncer_version: -update_frequency: 10 # Duration in seconds to poll the crowdsec API -log_level: info # Valid choices are either of "debug","info","warning","error" -log_mode: stdout # Valid choices are "file" or "stdout" or "stderr" -log_file: /var/log/crowdsec-fastly-bouncer.log # Ignore if logging to stdout or stderr -``` - -# Helpers: - -The bouncer has few builtin helper features: - -## Auto config generator: - -**Usage:** - -```bash -crowdsec-fastly-bouncer -c \ - -g , -``` - -This will print boilerplate config with sane defaults for the provided comma separted fastly tokens. -Always review the generated config before proceeding further. - -Crowdsec config is copied from the config at `PATH_TO_BASE_CONFIG`. - -## Cleaner: - -**Usage:** - -```bash -sudo crowdsec-fastly-bouncer -c -d -``` - -This deletes the fastly resources created by the bouncer. -It only works if the configured service version is not locked. -It is useful for quick iteration before activateing the new service. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/firewall.mdx deleted file mode 100644 index 48f764a9..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/firewall.mdx +++ /dev/null @@ -1,325 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -CrowdSec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API to add them in a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - -### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - -### pf - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -See as well [Manual Installation documentation below](/docs/bouncers/firewall#manual-installation) - - - -## Configuration - -There are two main usage case around the firewall bouncer : - - **managed** (default) : cs-firewall-bouncer will create ispet/nft sets, insert the associated firewall rules and manage set's content - - **set only** : you already have a (complex) firewall setup, cs-firewall-bouncer will only manage the _content_ of existing specified sets - - -### Managed mode : Iptables/ipset or Nftables - -__This is the default behaviour__ - -In "managed" mode (mode `nftables` or `iptables`), bouncer creates all the needed elements (rules, sets) and insert the appropriate rules in nftables or iptables. - -:::warning - -IPSet (when using `iptables` mode) does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds. - -::: - -### Set Only : Iptables/Ipset table - -In iptable set only mode (mode `ispet`), bouncer only manages the **contents** of sets designed by `blacklists_ipv4` and `blacklists_ipv6`. -Those sets must exist prior to the bouncer startup, and it is the user's responsability to create the associate iptables rules. - -:::warning - -IPSet does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds. - -::: - -### Set Only : nftables - -In nftables set only mode (mode `nftables` with `nftables.{ipv4,ipv6}.set-only` set to `true`), bouncer only manages the **contents** of the sets. -It's the user's responsability to create the associated chains and sets : - -```yaml title="/tmp/bouncer.nft" -table ip crowdsec { - set crowdsec-blacklists { - type ipv4_addr - flags timeout - } - - chain crowdsec-chain { - type filter hook input priority filter; policy accept; - ip saddr @crowdsec-blacklists drop - } -} -table ip6 crowdsec6 { - set crowdsec6-blacklists { - type ipv6_addr - flags timeout - } - - chain crowdsec6-chain { - type filter hook input priority filter; policy accept; - ip6 saddr @crowdsec6-blacklists drop - } -} -``` - - -## Configuration directives - - - - `mode` : can be set to `iptables`, `nftables` , `ipset` or `pf` - - `pid_dir` : directory to drop pid file - - `update_frequency` controls how often the bouncer is going to query the local API - - `daemonize` : for systemd unit - - `log_mode` : can be `file` or `stdout` - - `log_dir` : log directory - - `log_level` : can be `trace`, `debug`, `info`, or `error` - - `log_compression` : compress logs on rotation, `true` or `false` - - `log_max_size` : maximum file size before rotation - - `log_max_backups` : how many backup log files to keep - - `log_max_age` : oldest backup log file before deletion - - `api_url` and `api_key` control local API parameters. - - `insecure_skip_verify` : allow self-signed certificates for LAPI, `false` or `true` - - `disable_ipv6` : disable ipv6 support, defaults to `false` - - `deny_action` : firewall action to apply, defaults to `DROP`, but can be `REJECT` - - `deny_log` : if set to `true`, enables logging of dropped packets (ie. `-j LOG`) - - `deny_log_prefix` : if logging is true, this sets the log prefix, defaults to "crowdsec: " - -### Iptables/Ipset specific directives - - - - `iptables_chains` : specify a list of chains to insert rules (only relevant in `iptables` mode) : - - `blacklists_ipv4` and `blacklists_ipv6` : names of ipv4 and ipv6 sets - -```yaml -iptables_chains: - - INPUT -# - FORWARD -# - DOCKER-USER -``` - -### Nftables specific directives - -Nftables mode has its own `nftables` section, with sub-section of ipv4 and ipv6 : - -```yaml -## nftables -nftables: - ipv4: - enabled: true - set-only: false - table: crowdsec - chain: crowdsec-chain - ipv6: - enabled: true - set-only: false - table: crowdsec6 - chain: crowdsec6-chain -``` - -if `set-only` is set to true, the bouncer will only manage the set contents. - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -### Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -### Configuration for manual installation - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration file is located under : `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml` - - - - -You can then start the service: - -```bash title="Start CrowdSec service" -sudo systemctl start crowdsec-firewall-bouncer -``` - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to step by step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. - - ### ipset - - ipset lists have to exist before crowdsec-firewall-bouncer starts - you could create them and add them to your iptables like this: - ``` -ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000 -ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000 -iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP -ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/ingress-nginx.mdx deleted file mode 100644 index b36b2710..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/intro.md deleted file mode 100644 index deade5e5..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/intro.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Bouncers - -## Introduction - -bouncers are standalone software pieces in charge of acting upon a decision taken by crowdsec : block an IP, present a captcha, enforce MFA on a given user, etc. - -They can either be within the applicative stack, or work out of band : - -[nginx bouncer](https://github.com/crowdsecurity/cs-nginx-bouncer) will check every unknown IP against the local API before letting go through or serving a *403* to the user, while a [firewall bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-firewall-bouncer) or a [cloudflare bouncer](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer) will simply "add" malevolent IPs to nftables/ipset set of blacklisted IPs. - -Bouncers rely on [crowdsec's Local API](/local_api/intro.md) to be able to get information about a given IP or such. - - -You can explore [available bouncers on the hub](https://hub.crowdsec.net/browse/#bouncers). - - -To be able for your bouncers to communicate with the local API, you have to generate an API token with `cscli` and put it in your bouncer configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you were to create your own bouncers, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/magento.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/magento.mdx deleted file mode 100644 index e2193e37..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/magento.mdx +++ /dev/null @@ -1,623 +0,0 @@ ---- -id: magento -title: Magento 2 Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-💠 Hub -💬 Discourse -

- - - -## Introduction - -The `CrowdSec Bouncer` extension for Magento 2 has been designed to protect Magento 2 websites from all kinds of attacks by using [CrowdSec](https://www.crowdsec.net/) technology. - -### Prerequisites - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). -CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost CrowdSec must be installed on a server that is accessible via the Magento 2 site. - - -## Usage - -### Features - -When a user is suspected by CrowdSec to be malevolent, this bouncer will either send him/her a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he will access the page as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages in a few clicks so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users’ language. - - -### Configurations - -This module comes with configurations that you will find under `Stores → Configurations → Security → CrowdSec Bouncer` admin section. - -These configurations are divided in four main parts : `General Settings`, `Theme customizations`, `Advanced settings` and `Events`. - - -#### General Settings - -In the `General settings` part, you will set your connection details and refine bouncing according to your needs. - -Connection details - -*** - -`Connection details → Your Local API Url` (`global` scope) - -Url to join your CrowdSec Local API. - -If the CrowdSec Agent is installed on this server, you could set this field to `http://localhost:8080`. - - -*** - -`Connection details → Authentication type` (`global` scope) - -Choose between API key and TLS (pki) authentication. - -TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. -Please see [CrowdSec documentation](https://docs.crowdsec.net/docs/local_api/tls_auth/). - - -*** - -`Connection details → Your bouncer key` (`global` scope) - -Key generated by the cscli command. - -Only if you chose `Api key` as authentication type. - -*** - -`Connection details → Path to the bouncer certificate` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -Example: `crowdsec/tls/bouncer.pem`. - -Only if you chose `TLS` as authentication type. - -*** - -`Connection details → Path to the bouncer key` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -Example: `crowdsec/tls/bouncer-key.pem`. - -Only if you chose `TLS` as authentication type. - -*** - -`Connection details → Enable TLS peer verification` (`global` scope) - -This option determines whether request handler verifies the authenticity of the peer's certificate. - -Only if you chose `TLS` as authentication type. - -When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. -If `Enable TLS peer verification` is set to true, request handler verifies whether the certificate is authentic. -This trust is based on a chain of digital signatures, -rooted in certification authority (CA) certificate you supply using the `Path to the CA certificate for peer verification` setting below. - -*** - -`Connection details → Path to the CA certificate for peer verification` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -Example: `crowdsec/tls/ca-chain.pem`. - -Only if you chose `TLS` as authentication type. - -*** - -`Connection details → Use cURL` (`global` scope) - -By default, `file_get_contents` method is used to call Local API. This method requires to have enabled the option -`allow_url_fopen`. -Here, you can choose to use `cURL` requests instead. Beware that in this case, you need to have php `cURL` extension installed and enabled on your system. - - -**N.B** : Even before saving configuration, you can check if your settings are correct by clicking on the test button. - - *** - -Bouncing - - -*** - -`Bouncing → Enable bouncer on Frontend area` (`store view` scope) - -Choose which store views you want to protect. - -*** - -`Bouncing → Enable bouncer on Adminhtml area` (`global` scope) - -Choose if you want to protect admin too. - -*** - -`Bouncing → Enable bouncer on API areas` (`global` scope) - -Choose if you want to protect REST, SOAP and GraphQL endpoints. - - -**N.B** : For API calls, there will be no ban or captcha wall. User will receive a `401` (ban) or `403` (captcha) response code. - -*** - -`Bouncing → Bouncing level` (`store view` scope) - -Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). - -With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This -mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario. - -*** - - - -#### Theme customizations - -In the `Theme customizations` part, you can modify texts and colors of ban and captcha walls. All fields here are -store view scoped, so you can use different languages and designs. - -Captcha wall customization - -Ban wall customization - -Wall CSS - - -#### Advanced settings - - -In the `Advanced settings` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec -Local API, handle your remediation policy and adjust some debug and log parameters. - -Communication mode - -*** - -`Communication mode to the API → Enable the stream mode` (`global` scope) - -Choose if you want to enable the `stream mode` or stay in `live mode`. - - -By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. - -But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -*** - -`Communication mode to the API → Cron expression for cache refresh` (`global` scope) - -With the stream mode, every decision is retrieved in an asynchronous way. Here you can define the frequency of this -cache refresh. - -**N.B** : There is also a refresh button if you want to refresh the cache manually. - - -*** - -Cache - -*** - -`Cache configuration → Technology` (`global` scope) - -Choose the cache technology that will use your CrowdSec Local API. - -The File system cache is faster than calling Local API. Redis or Memcached is faster than the File System cache. - -**N.B** : There are also a clear cache button fo all cache technologies and a prune cache button dedicated to the -file system cache. - -*** - -`Cache configuration → Cron expression for file system cache pruning` (`global` scope) - -If you chose file system as cache technology, you can schedule here an automatic cache pruning cron task. - -*** - - -`Cache configuration → Redis DSN` (`global` scope) - -Only if you choose Redis cache as technology. Example of DSN: redis://localhost:6379. - -*** - - -`Cache configuration → Memcached DSN` (`global` scope) - -Only if you choose Memcached cache as technology. Example of DSN: memcached://localhost:11211. - -*** - - -`Cache configuration → Clean IPs cache duration` (`global` scope) - -The duration between re-asking Local API about an already checked clean IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - -`Cache configuration → Bad IPs cache duration` (`global` scope) - -The duration between re-asking Local API about an already checked bad IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - - -`Cache configuration → Captcha flow cache duration` (`global` scope) - -The lifetime of cached captcha flow for some IP. If a user has to interact with a captcha wall, we store in cache some values in order to know if he has to resolve or not the captcha again. - -Minimum 1 second. - -*** - -`Cache configuration → Geolocation cache duration` (`global` scope) - -The lifetime of cached country result for some IP. Note that this setting can not be apply only if the -`Geolocation → Save geolocation country result in cache` below is enabled. - -Minimum 1 second. - -*** - -Geolocation - -*** - -`Geolocation → Enable geolocation feature` (`global` scope) - -Enable if you want to handle CrowdSec country scoped decisions. - -*** - -`Geolocation → Save geolocation country result in cache` (`global` scope) - -Enabling this option will avoid multiple call to the geolocation system (e.g. MaxMind database). - -*** - -`Geolocation → Geolocation type` (`global` scope) - -At this time, only MaxMind type is allowed. - -*** - -`Geolocation → MaxMind database type` (`global` scope) - -Choose between `Country` and `City` depending on your MaxMind database. - -*** - -`Geolocation → MaxMind database path` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -*** - -**N.B** : There is also a test button if you want to test your geolocation settings. - -Remediations - - -*** - -`Remediations → Fallback to` (`global` scope) - -Choose which remediation to apply when CrowdSec advises unhandled remediation. - -*** - - -`Remediations → Trust these CDN Ips` (`global` scope) - -If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate in the bouncer settings the IP ranges of these devices in order to be able to check the IP of your users. For other IPs, the bouncer will not trust the X-Forwarded-For header. - -*** - -`Remediations → Hide CrowdSec mentions` (`global` scope) - -Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls. -*** - -Debug - -*** - -`Configure the debug mode → Enable debug log` (`global` scope) - -Enable if you want to see some debug information in a specific log file. - -*** - -`Configure the debug mode → Display bouncings errors` (`global` scope) - -When this mode is enabled, you will see every unexpected bouncing errors in the browser. - -*** - -`Configure the debug mode → Disable prod log` (`global` scope) - -The prod log is lighter than the debug log. But you can disable it here. - -*** - -`Configure the debug mode → Forced test IP` (`global` scope) - -For test purpose only. If not empty, this IP will be used for all remediations and geolocation processes. - -*** - -`Configure the debug mode → Forced test forwarded IP` (`global` scope) - -For test purpose only. This IP will be used instead of the current `X-Forwarded-For` IP if any. - -*** - -#### Events - - -In the `Events` part, you can enable business events logging. Using it in combination to a specific CrowdSec -scenario allows detecting suspicious behavior as credential or credit card stuffing. - -Events - -*** - -`Logging → Enable events log` (`global` scope) - -If enabled, logs will be written in a `var/log/crowdsec-events.log` file. - -*** - -`Logging → Track customer registration` (`global` scope) - -Will be used to detect suspicious account creation. - -*** - -`Logging → Track customer login` (`global` scope) - -Will be used to detect credential stuffing. - -*** - -`Logging → Track admin user login` (`global` scope) - -Will be used to detect admin brute attacks. - -*** - -`Logging → Track add to cart process` (`global` scope) - -Will be used to detect suspicious behaviour with add to cart action. - -*** - -`Logging → Track order process` (`global` scope) - -Will be used to detect suspicious behaviour, as credit card stuffing, on order action. - -### Auto Prepend File mode - -By default, this extension will bounce every web requests: e.g requests called from webroot `index.php`. -This implies that if another php public script is called (`cron.php` if accessible for example, or any of your -custom public php script) bouncing will not be effective. -To ensure that any php script will be bounced if called from a browser, you should try the `auto prepend file` mode. - -In this mode, every browser access to a php script will be bounced. - -To enable the `auto prepend file` mode, you have to: - -- copy the `crowdsec-prepend.php.example` file in your Magento 2 `app/etc` folder and rename it `crowdsec-prepend.php` -- configure your server by adding an `auto_prepend_file` directive for your php setup. - -**N.B:** -- Beware that you have to copy the file before modifying your PHP configuration,or you will get a PHP fatal error. -- Note that if you upgrade the bouncer module, you should have to copy the file again. To make this copy - automatically, you should modify the root `composer.json` of your Magento 2 projects by adding `post-install-cmd` - and `post-update-cmd` to the scripts parts: - -``` -"scripts": { - "post-install-cmd": [ - "php -r \"copy('vendor/crowdsec/magento2-module-bouncer/crowdsec-prepend.php.example','app/etc/crowdsec-prepend.php');\"" - ], - "post-update-cmd": [ - "php -r \"copy('vendor/crowdsec/magento2-module-bouncer/crowdsec-prepend.php.example','app/etc/crowdsec-prepend.php');\"" - ] -} -``` - - -Adding an `auto_prepend_file` directive can be done in different ways: - -#### PHP - -You should add this line to a `.ini` file : - - auto_prepend_file = /magento2-root-directory/app/etc/crowdsec-prepend.php - - -#### Nginx - - -If you are using Nginx, you should modify your Magento 2 nginx configuration file by adding a `fastcgi_param` -directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "/magento2-root-directory/app/etc/crowdsec-prepend.php"; -} -``` - -#### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/magento2-root-directory/app/etc/crowdsec-prepend.php" - - - - -## Installation - -### Requirements - -- Magento >= 2.3 - -### Composer installation - -Use `Composer` by simply adding `crowdsec/magento2-module-bouncer` as a dependency: - - composer require crowdsec/magento2-module-bouncer - -### Post Installation - -#### Enable the module - -After the installment of the module source code, the module has to be enabled by the Magento 2 CLI. - - bin/magento module:enable CrowdSec_Bouncer - -#### System Upgrade - -After enabling the module, the Magento 2 system must be upgraded. - -If the system mode is set to production, run the compile command first. This is not necessary for the developer mode. - - - bin/magento setup:di:compile - -Then run the upgrade command: - - - bin/magento setup:upgrade - - -#### Clear Cache - -The Magento 2 cache should be cleared by running the flush command. - - bin/magento cache:flush - -#### Deploy static content - -At last, you have to deploy the static content: - - bin/magento setup:static-content:deploy -f - - -### Troubleshooting - -#### Higher matching error - -If a new version `y.y.y` has been published in Packagist and the Marketplace review process of this version is still in progress, -you could encounter the following error during installation on update: - -> Higher matching version y.y.y of crowdsec/magento2-module-bouncer was found in public repository packagist.org -> than x.x.x in private https://repo.magento.com. Public package might've been taken over by a malicious entity, -> please investigate and update package requirement to match the version from the private repository - -This error is due to the `magento/composer-dependency-version-audit-plugin` composer plugin introduced in Magento `2.4.3` as a security measure [against Dependency Confusion attacks](https://support.magento.com/hc/en-us/articles/4410675867917-Composer-plugin-against-Dependency-Confusion-attacks). - -##### Install the latest Marketplace release - -To avoid this error and install the latest known Marketplace release `x.x.x`, you could run: - -```bash -composer require crowdsec/magento2-module-bouncer --no-plugins -``` - -##### Install the latest Packagist release - -To avoid this error and install the latest known Packagist release `y.y.y`, you could modify the root `composer.json` of your Magento project by setting the `repo.magento.com` repository as non-canonical: - -``` -"repositories": { - "0": { - "type": "composer", - "url": "https://repo.magento.com/", - "canonical": false - } -}, -``` -And then run the same command: -```bash -composer require crowdsec/magento2-module-bouncer --no-plugins -``` - -As an alternative, you can also exclude the `crowdsec/magento2-module-bouncer` from the `repo.magento.com` repository: -``` -"repositories": { - "0": { - "type": "composer", - "url": "https://repo.magento.com/", - "exclude": ["crowdsec/magento2-module-bouncer"] - } -}, -``` - -Thus, running `composer require crowdsec/magento2-module-bouncer` will always pick up the latest `y.y.y` Packagist release. - - - - - - - - - - - - - - - - -## Technical notes - -See [Technical notes](https://github.com/crowdsecurity/cs-magento-bouncer/blob/main/doc/TECHNICAL_NOTES.md) - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-magento-bouncer/blob/main/doc/DEVELOPER.md) \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/nginx.mdx deleted file mode 100644 index d92d9ea2..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/nginx.mdx +++ /dev/null @@ -1,421 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base lua-cjson -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - lua-cjson: JSON parser/encoder for Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your Nginx Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/openresty.mdx deleted file mode 100644 index f666824d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/openresty.mdx +++ /dev/null @@ -1,425 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - reCAPTCHA v2 remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# reCAPTCHA Secret Key -SECRET_KEY= -# reCAPTCHA Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, only reCAPTCHA v2 is supported. - -If you want to use reCAPTCHA with your OpenResty Bouncer, you must provide a reCAPTCHA Site key and Secret key in your bouncer configuration ([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -Edit `etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to query `google.com` for the reCAPTCHA verification, we need to set a resolver and a SSL certificate in our OpenResty configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -REQUEST_TIMEOUT=1000 -``` - -Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The reCAPTCHA v2 secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The reCAPTCHA v2 site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer will try to replace `{{recaptcha_site_key}}` in the template with `SITE_KEY` parameter. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/captcha.html`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/php-lib.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/php-lib.mdx deleted file mode 100644 index 24b9f670..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/php-lib.mdx +++ /dev/null @@ -1,431 +0,0 @@ ---- -id: php-lib -title: PHP Bouncer Library -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-💠 Hub -💬 Discourse -

- -## Overview - -This library allows you to create CrowdSec bouncers for PHP applications or frameworks like e-commerce, blog or other exposed applications. - -## Installation - -### Requirements - -- PHP >= 7.2.5 -- required PHP extensions: `ext-curl`, `ext-gd`, `ext-json`, `ext-mbstring` - -### Installation - -Use `Composer` by simply adding `crowdsec/bouncer` as a dependency: - -```shell -composer require crowdsec/bouncer -``` - -## Usage - -### Prerequisites - -To be able to use a bouncer based on this library, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost a CrowdSec agent must be installed on a server that is accessible by this library. - -### Features - -- CrowdSec Local API support - - Handle `ip`, `range` and `country` scoped decisions - - `Live mode` or `Stream mode` -- Support IpV4 and Ipv6 (Ipv6 range decisions are yet only supported in `Live mode`) -- Large PHP matrix compatibility: 7.2, 7.3, 7.4, 8.0, 8.1 and 8.2 -- Built-in support for the most known cache systems Redis, Memcached and PhpFiles - - Clear, prune and refresh the bouncer cache -- Cap remediation level (ex: for sensitives websites: ban will be capped to captcha) - -### Ban and captcha walls - -When a user is suspected by CrowdSec to be malevolent, a bouncer would either display a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he/she will access the page -as normal. - -A ban wall could look like: - -Ban wall - -A captcha wall could look like: - -Ban wall - -Please note that it is possible to customize all the colors of these pages so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users' language. - -## Create your own bouncer - -### Implementation - -You can use this library to develop your own PHP application bouncer. Any custom bouncer should extend the [`AbstractBouncer`](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/src/AbstractBouncer.php) class. - -```php -namespace MyNameSpace; - -use CrowdSecBouncer\AbstractBouncer; - -class MyCustomBouncer extends AbstractBouncer -{ -} -``` - -Then, you will have to implement all necessary methods : - -```php -namespace MyNameSpace; - -use CrowdSecBouncer\AbstractBouncer; - -class MyCustomBouncer extends AbstractBouncer -{ - /** - * Get current http method - */ - public function getHttpMethod(): string - { - // Your implementation - } - - /** - * Get value of an HTTP request header. Ex: "X-Forwarded-For" - */ - public function getHttpRequestHeader(string $name): ?string - { - // Your implementation - } - - /** - * Get the value of a posted field. - */ - public function getPostedVariable(string $name): ?string - { - // Your implementation - } - - /** - * Get the current IP, even if it's the IP of a proxy - */ - public function getRemoteIp(): string - { - // Your implementation - } - - /** - * Get current request uri - */ - public function getRequestUri(): string - { - // Your implementation - } - -} -``` - - -Once you have implemented these methods, you could retrieve all required configurations to instantiate your bouncer -and then call the `run` method to apply a bounce for the current detected IP. Please [see below](#configurations) for -the list of -available configurations. - -In order to instantiate the bouncer, you will have to create at least a `CrowdSec\RemediationEngine\LapiRemediation` -object too. - - -```php -use MyNameSpace\MyCustomBouncer; -use CrowdSec\RemediationEngine\LapiRemediation; -use CrowdSec\LapiClient\Bouncer as BouncerClient; -use CrowdSec\RemediationEngine\CacheStorage\PhpFiles; - -$configs = [...]; -$client = new BouncerClient($configs);// @see AbstractBouncer::handleClient method for a basic client creation -$cacheStorage = new PhpFiles($configs);// @see AbstractBouncer::handleCache method for a basic cache storage creation -$remediationEngine = new LapiRemediation($configs, $client, $cacheStorage); - -$bouncer = new MyCustomBouncer($configs, $remediationEngine); - -$bouncer->run(); -``` - - -### Test your bouncer - -To test your bouncer, you could add decision to ban your own IP for 5 minutes for example: - -```bash -cscli decisions add --ip --duration 5m --type ban -``` - -You can also test a captcha: - -```bash -cscli decisions delete --all # be careful with this command! -cscli decisions add --ip --duration 15m --type captcha -``` - - -To go further and learn how to include this library in your project, you should follow the [`DEVELOPER GUIDE`](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/DEVELOPER.md). - - -## Configurations - -The first parameter of the `AbstractBouncer` class constructor method is an array of settings. - -Below is the list of available settings: - -### Bouncer behavior - -- `bouncing_level`: Select from `bouncing_disabled`, `normal_bouncing` or `flex_bouncing`. Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This mode makes it possible to never ban an IP but only to offer a captcha, in the worst-case scenario. - - -- `fallback_remediation`: Select from `bypass` (minimum remediation), `captcha` or `ban` (maximum remediation). Default to 'captcha'. Handle unknown remediations as. - - -- `trust_ip_forward_array`: If you use a CDN, a reverse proxy or a load balancer, set an array of comparable IPs arrays: - (example: `[['001.002.003.004', '001.002.003.004'], ['005.006.007.008', '005.006.007.008']]` for CDNs with IPs `1.2.3.4` and `5.6.7.8`). For other IPs, the bouncer will not trust the X-Forwarded-For header. - - -- `excluded_uris`: array of URIs that will not be bounced. - - -- `stream_mode`: true to enable stream mode, false to enable the live mode. Default to false. By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -### Local API Connection - -- `auth_type`: Select from `api_key` and `tls`. Choose if you want to use an API-KEY or a TLS (pki) authentification. - TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. - - -- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add bouncer-php-library`. - Only required if you choose `api_key` as `auth_type`. - - -- `tls_cert_path`: absolute path to the bouncer certificate (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_key_path`: Absolute path to the bouncer key (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_verify_peer`: This option determines whether request handler verifies the authenticity of the peer's certificate. - Only required if you choose `tls` as `auth_type`. - When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. - If `tls_verify_peer` is set to true, request handler verifies whether the certificate is authentic. - This trust is based on a chain of digital signatures, - rooted in certification authority (CA) certificates you supply using the `tls_ca_cert_path` setting below. - - -- `tls_ca_cert_path`: Absolute path to the CA used to process peer verification. - Only required if you choose `tls` as `auth_type` and `tls_verify_peer` is set to true. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `api_url`: Define the URL to your Local API server, default to `http://localhost:8080`. - - -- `api_timeout`: In seconds. The timeout when calling Local API. Default to 120 sec. If set to a negative value, - timeout will be unlimited. - - -### Cache - - -- `fs_cache_path`: Will be used only if you choose PHP file cache as cache storage. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `redis_dsn`: Will be used only if you choose Redis cache as cache storage. - - -- `memcached_dsn`: Will be used only if you choose Memcached as cache storage. - - -- `clean_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5. - - -- `bad_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20. - - -- `captcha_cache_duration`: Set the duration we keep in cache the captcha flow variables for an IP. In seconds. - Defaults to 86400.. In seconds. Defaults to 20. - - -### Geolocation - -- `geolocation`: Settings for geolocation remediation (i.e. country based remediation). - - - `geolocation[enabled]`: true to enable remediation based on country. Default to false. - - - `geolocation[type]`: Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`. - - - `geolocation[cache_duration]`: This setting will be used to set the lifetime (in seconds) of a cached country - associated to an IP. The purpose is to avoid multiple call to the geolocation system (e.g. maxmind database). Default to 86400. Set 0 to disable caching. - - - `geolocation[maxmind]`: MaxMind settings. - - - `geolocation[maxmind][database_type]`: Select from `country` or `city`. Default to `country`. These are the two available MaxMind database types. - - - `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (e.g. mmdb file) - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -### Captcha and ban wall settings - - -- `hide_mentions`: true to hide CrowdSec mentions on ban and captcha walls. - - -- `custom_css`: Custom css directives for ban and captcha walls - - -- `color`: Array of settings for ban and captcha walls colors. - - - `color[text][primary]` - - - `color[text][secondary]` - - - `color[text][button]` - - - `color[text][error_message]` - - - `color[background][page]` - - - `color[background][container]` - - - `color[background][button]` - - - `color[background][button_hover]` - - -- `text`: Array of settings for ban and captcha walls texts. - - - `text[captcha_wall][tab_title]` - - - `text[captcha_wall][title]` - - - `text[captcha_wall][subtitle]` - - - `text[captcha_wall][refresh_image_link]` - - - `text[captcha_wall][captcha_placeholder]` - - - `text[captcha_wall][send_button]` - - - `text[captcha_wall][error_message]` - - - `text[captcha_wall][footer]` - - - `text[ban_wall][tab_title]` - - - `text[ban_wall][title]` - - - `text[ban_wall][subtitle]` - - - `text[ban_wall][footer]` - - -### Debug -- `debug_mode`: `true` to enable verbose debug log. Default to `false`. - - -- `disable_prod_log`: `true` to disable prod log. Default to `false`. - - -- `log_directory_path`: Absolute path to store log files. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `display_errors`: true to stop the process and display errors on browser if any. - - -- `forced_test_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used instead of the - real remote ip. - - -- `forced_test_forwarded_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used - instead of the real forwarded ip. If set to `no_forward`, the x-forwarded-for mechanism will not be used at all. - -### Security note - -Some files should not be publicly accessible because they may contain sensitive data: - -- Log files -- Cache files of the File system cache -- TLS authentication files -- Geolocation database files - -If you define publicly accessible folders in the settings, be sure to add rules to deny access to these files. - -In the following example, we will suppose that you use a folder `crowdsec` with sub-folders `logs`, `cache`, `tls` and `geolocation`. - -If you are using Nginx, you could use the following snippet to modify your website configuration file: - -```nginx -server { - ... - ... - ... - # Deny all attempts to access some folders of the crowdsec bouncer lib - location ~ /crowdsec/(logs|cache|tls|geolocation) { - deny all; - } - ... - ... -} -``` - -If you are using Apache, you could add this kind of directive in a `.htaccess` file: - -```htaccess -Redirectmatch 403 crowdsec/logs/ -Redirectmatch 403 crowdsec/cache/ -Redirectmatch 403 crowdsec/tls/ -Redirectmatch 403 crowdsec/geolocation/ -``` - -**N.B.:** -- There is no need to protect the `cache` folder if you are using Redis or Memcached cache systems. -- There is no need to protect the `logs` folder if you disable debug and prod logging. -- There is no need to protect the `tls` folder if you use Bouncer API key authentication type. -- There is no need to protect the `geolocation` folder if you don't use the geolocation feature. - - -## Other ready to use PHP bouncers - -To have a more concrete idea on how to develop a bouncer from this library, you may look at the following bouncers : -- [CrowdSec Bouncer extension for Magento 2](https://github.com/crowdsecurity/cs-magento-bouncer) -- [CrowdSec Bouncer plugin for WordPress ](https://github.com/crowdsecurity/cs-wordpress-bouncer) -- [CrowdSec Standalone Bouncer ](https://github.com/crowdsecurity/cs-standalone-php-bouncer) - - -## Technical notes - -See [Technical notes](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/TECHNICAL_NOTES.md) - - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/DEVELOPER.md) \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/php.mdx deleted file mode 100644 index 28e6e017..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/php.mdx +++ /dev/null @@ -1,539 +0,0 @@ ---- -id: php -title: PHP Standalone Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -## Overview - -This bouncer allows you to protect your PHP application from IPs that have been detected by CrowdSec. Depending on -the decision taken by CrowdSec, user will either get denied (403) or have to fill a captcha (401). - -It uses the [PHP `auto_prepend_file` mechanism](https://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file) and -the [Crowdsec php bouncer library](https://github.com/crowdsecurity/php-cs-bouncer) to provide bouncer/IPS capability -directly in your PHP application. - -It supports "ban" and "captcha" remediations, and all decisions of type Ip, Range or Country (geolocation). - - -### Prerequisites - -- This is a PHP library, so you must have a working PHP (>= 7.2.5) installation. -- Requires PHP extensions : `ext-curl`, `ext-gd`, `ext-json`, `ext-mbstring`. -- Code sources are dealt with via `composer` and `git`. -- Have CrowdSec on the same machine, or at least be able to reach LAPI. - - -## Installation - -### Preparation - -#### Install composer - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - -#### Install GIT - -Please follow [this documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install GIT. - -#### Install CrowdSec - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost a CrowdSec agent must be installed on a server that is accessible by this bouncer. - -### Server and bouncer setup - -Once you set up your server as below, every browser access to a PHP script will be bounced by the standalone bouncer. - -You will have to : - -- retrieve sources of the bouncer in some `/path/to/the/crowdsec-standalone-bouncer` folder -- give the correct permission for the folder that contains the bouncer -- copy the `scripts/settings.php.dist` file to a `scripts/settings.php` file and edit it. -- set an `auto_prepend_file` directive in your PHP setup. -- Optionally, if you want to use the standalone bouncer in stream mode, you will have to set a cron task to refresh - cache periodically. - -#### Bouncer sources copy - -- Create a folder that will contain the project sources: - -```bash -sudo mkdir -p /var/www/crowdsec-standalone-bouncer -``` - -We use here `/var/www/crowdsec-standalone-bouncer` but you can choose the path that suits your needs. - -- Change permission to allow composer to be run in this folder. As you should run composer with your user, this - can be done with: - -```bash -sudo chown -R $(whoami):$(whoami) /var/www/crowdsec-standalone-bouncer -``` - -- Retrieve the last version of the bouncer: - -```bash -composer create-project crowdsec/standalone-bouncer /var/www/crowdsec-standalone-bouncer --keep-vcs -``` - -Note that we have to keep the vcs data as we will use it to update the bouncer when a new version is available. - -#### Files permission - -The owner of the `/var/www/crowdsec-standalone-bouncer` folder should be your web-server owner (e.g. `www-data`) and the group should have the write permission on this folder. - -You can achieve it by running commands like: - -```bash -sudo chown -R www-data /var/www/crowdsec-standalone-bouncer -sudo chmod g+w /var/www/crowdsec-standalone-bouncer -``` - -#### Settings file - -Please copy the `scripts/settings.php.dist` file to a `scripts/settings.php` file and fill the necessary settings in it -(see [Configurations settings](#configurations) for more details). - -For a quick start, simply search for `YOUR_BOUNCER_API_KEY` in the `settings.php` file and set the bouncer key. -To obtain a bouncer key, you can run the `cscli` bouncer creation command: - -``` -sudo cscli bouncers add standalone-bouncer -``` - -#### `auto_prepend_file` directive - -We will now describe how to set an `auto_prepend_file` directive in order to call the `scripts/bounce.php` for each php access. - -Adding an `auto_prepend_file` directive can be done in different ways: - -###### `.ini` file - -You should add this line to a `.ini` file : - - auto_prepend_file = /var/www/crowdsec-standalone-bouncer/scripts/bounce.php - -###### Nginx - -If you are using Nginx, you should modify your Nginx configuration file by adding a `fastcgi_param` directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/crowdsec-standalone-bouncer/scripts/bounce.php"; -} -``` - -###### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/var/www/crowdsec-standalone-bouncer/scripts/bounce.php" - -or modify your `Virtual Host` accordingly: - -``` - - ... - ... - php_value auto_prepend_file "/var/www/crowdsec-standalone-bouncer/scripts/bounce.php" - - -``` - -#### Stream mode cron task - -To use the stream mode, you first have to set the `stream_mode` setting value to `true` in your `script/settings.php` file. - -Then, you could edit the web server user (e.g. `www-data`) crontab: - -```shell -sudo -u www-data crontab -e -``` - -and add the following line - -```shell -*/15 * * * * /usr/bin/php /var/www/crowdsec-standalone-bouncer/scripts/refresh-cache.php -``` - -In this example, cache is refreshed every 15 minutes, but you can modify the cron expression depending on your needs. - -#### Cache pruning cron task - -If you use the PHP file system as cache, you should prune the cache with a cron job: - -```shell -sudo -u www-data crontab -e -``` - -and add the following line - -```shell -0 0 * * * /usr/bin/php /var/www/crowdsec-standalone-bouncer/scripts/prune-cache.php -``` - -In this example, cache is pruned at midnight every day, but you can modify the cron expression depending on your needs. - - - -## Upgrade - -When a new release of the bouncer is available, you may want to update sources to the last version. - -### Before upgrading - -**Please look at the [CHANGELOG](https://github.com/crowdsecurity/cs-standalone-php-bouncer/blob/main/CHANGELOG.md) before upgrading in order to see the list of changes that could break your application.** - -To limit the risk of breaking your web application during upgrade, you can perform the following actions to disable bouncing: - -- Remove the `auto_prepend_file` directive that point to the `bounce.php` file and restart your web server -- Disable any scheduled cron task linked to bouncer feature - -Alternatively, but a little more risky, you could disable bouncing by editing the `scripts/settings.php` file and set the value `'bouncing_disabled'` for the `'bouncing_level'` parameter. - -Once the update is done, you can reactivate the bounce. You could look at the `/var/www/crowdsec-standalone-bouncer/scripts/.logs` to see if all is working as expected. - -Below are the steps to take to upgrade your current bouncer: - -### Retrieve the last tag - -As we kept the vcs data during installation (with the `--keep-vcs` flag), we can use git to get the last tagged sources: - -```bash -cd /var/www/crowdsec-standalone-bouncer -git fetch -``` - -If you get an error message about "detected dubious ownership", you can run - -```bash -git config --global --add safe.directory /var/www/crowdsec-standalone-bouncer -``` - -You should see a list of tags (`vX.Y.Z` format )that have been published after your initial installation. - -### Checkout to last tag and update sources - -Once you have picked up the `vX.Y.Z` tag you want to try, you could switch to it and update composer dependencies: - -```bash -git checkout vX.Y.Z && composer update -``` - - -## Usage - -### Features - -- CrowdSec Local API Support - - Handle `ip`, `range` and `country` scoped decisions - - `Live mode` or `Stream mode` -- Support IpV4 and Ipv6 (Ipv6 range decisions are yet only supported in `Live mode`) -- Large PHP matrix compatibility: 7.2, 7.3, 7.4, 8.0, 8.1 and 8.2 -- Built-in support for the most known cache systems Redis, Memcached and PhpFiles - - Clear, prune and refresh the bouncer cache -- Cap remediation level (ex: for sensitives websites: ban will be capped to captcha) - -### Ban and captcha walls - -When a user is suspected by CrowdSec to be malevolent, the bouncer would either display a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he/she will access the page -as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users' language. - -### Configurations - -Here is the list of available settings that you could define in the `scripts/settings.php` file: - -#### Bouncer behavior - -- `bouncing_level`: Select from `bouncing_disabled`, `normal_bouncing` or `flex_bouncing`. Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This mode makes it possible to never ban an IP but only to offer a captcha, in the worst-case scenario. - - -- `fallback_remediation`: Select from `bypass` (minimum remediation), `captcha` or `ban` (maximum remediation). Default to 'captcha'. Handle unknown remediations as. - - -- `trust_ip_forward_array`: If you use a CDN, a reverse proxy or a load balancer, set an array of IPs. For other IPs, the bouncer will not trust the X-Forwarded-For header. - - -- `excluded_uris`: array of URIs that will not be bounced. - - -- `stream_mode`: true to enable stream mode, false to enable the live mode. Default to false. By default, the `live mode` is enabled. The first time a user connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -#### Local API Connection - -- `auth_type`: Select from `api_key` and `tls`. Choose if you want to use an API-KEY or a TLS (pki) authentification. - TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. - - -- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add standlone-php-bouncer`. - Only required if you choose `api_key` as `auth_type`. - - -- `tls_cert_path`: absolute path to the bouncer certificate (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_key_path`: Absolute path to the bouncer key (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_verify_peer`: This option determines whether request handler verifies the authenticity of the peer's certificate. - Only required if you choose `tls` as `auth_type`. - When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. - If `tls_verify_peer` is set to true, request handler verifies whether the certificate is authentic. - This trust is based on a chain of digital signatures, - rooted in certification authority (CA) certificates you supply using the `tls_ca_cert_path` setting below. - - -- `tls_ca_cert_path`: Absolute path to the CA used to process peer verification. - Only required if you choose `tls` as `auth_type` and `tls_verify_peer` is set to true. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `api_url`: Define the URL to your Local API server, default to `http://localhost:8080`. - - -- `api_timeout`: In seconds. The timeout when calling Local API. Default to 120 sec. If set to a negative value, - timeout will be unlimited. - - -- `use_curl`: By default, this lib call the REST Local API using `file_get_contents` method (`allow_url_fopen` is required). - You can set `use_curl` to `true` in order to use `cURL` request instead (`ext-curl` is in then required) - -#### Cache - -- `cache_system`: Select from `phpfs` (PHP file cache), `redis` or `memcached`. - - -- `fs_cache_path`: Will be used only if you choose PHP file cache as `cache_system`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `redis_dsn`: Will be used only if you choose Redis cache as `cache_system`. - - -- `memcached_dsn`: Will be used only if you choose Memcached as `cache_system`. - - -- `clean_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5. - - -- `bad_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20. - - -- `captcha_cache_duration`: Set the duration we keep in cache the captcha flow variables for an IP. In seconds. - Defaults to 86400.. In seconds. Defaults to 20. - - -#### Geolocation - -- `geolocation`: Settings for geolocation remediation (i.e. country based remediation). - - - `geolocation[enabled]`: true to enable remediation based on country. Default to false. - - - `geolocation[type]`: Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`. - - - `geolocation[cache_duration]`: This setting will be used to set the lifetime (in seconds) of a cached country - associated to an IP. The purpose is to avoid multiple call to the geolocation system (e.g. maxmind database). Default to 86400. Set 0 to disable caching. - - - `geolocation[maxmind]`: MaxMind settings. - - - `geolocation[maxmind][database_type]`: Select from `country` or `city`. Default to `country`. These are the two available MaxMind database types. - - - `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (e.g. mmdb file) - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -#### Captcha and ban wall settings - - -- `hide_mentions`: true to hide CrowdSec mentions on ban and captcha walls. - - -- `custom_css`: Custom css directives for ban and captcha walls - - -- `color`: Array of settings for ban and captcha walls colors. - - - `color[text][primary]` - - - `color[text][secondary]` - - - `color[text][button]` - - - `color[text][error_message]` - - - `color[background][page]` - - - `color[background][container]` - - - `color[background][button]` - - - `color[background][button_hover]` - - -- `text`: Array of settings for ban and captcha walls texts. - - - `text[captcha_wall][tab_title]` - - - `text[captcha_wall][title]` - - - `text[captcha_wall][subtitle]` - - - `text[captcha_wall][refresh_image_link]` - - - `text[captcha_wall][captcha_placeholder]` - - - `text[captcha_wall][send_button]` - - - `text[captcha_wall][error_message]` - - - `text[captcha_wall][footer]` - - - `text[ban_wall][tab_title]` - - - `text[ban_wall][title]` - - - `text[ban_wall][subtitle]` - - - `text[ban_wall][footer]` - - -#### Debug -- `debug_mode`: `true` to enable verbose debug log. Default to `false`. - - -- `disable_prod_log`: `true` to disable prod log. Default to `false`. - - -- `log_directory_path`: Absolute path to store log files. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `display_errors`: true to stop the process and display errors on browser if any. - - -- `forced_test_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used instead of the - real remote ip. - - -- `forced_test_forwarded_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used - instead of the real forwarded ip. If set to `no_forward`, the x-forwarded-for mechanism will not be used at all. - -#### Security note - -Some files should not be publicly accessible because they may contain sensitive data: - -- Log files -- Cache files of the File system cache -- TLS authentication files -- Geolocation database files - -If you define publicly accessible folders in the settings, be sure to add rules to deny access to these files. - -In the following example, we will suppose that you use a folder `crowdsec` with sub-folders `logs`, `cache`, `tls` and `geolocation`. - -If you are using Nginx, you could use the following snippet to modify your website configuration file: - -```nginx -server { - ... - ... - ... - # Deny all attempts to access some folders of the crowdsec standalone bouncer - location ~ /crowdsec/(logs|cache|tls|geolocation) { - deny all; - } - ... - ... -} -``` - -If you are using Apache, you could add this kind of directive in a `.htaccess` file: - -```htaccess -Redirectmatch 403 crowdsec/logs/ -Redirectmatch 403 crowdsec/cache/ -Redirectmatch 403 crowdsec/tls/ -Redirectmatch 403 crowdsec/geolocation/ -``` - -**N.B.:** -- There is no need to protect the `cache` folder if you are using Redis or Memcached cache systems. -- There is no need to protect the `logs` folder if you disable debug and prod logging. -- There is no need to protect the `tls` folder if you use Bouncer API key authentication type. -- There is no need to protect the `geolocation` folder if you don't use the geolocation feature. - -## Testing & Troubleshooting - -### Logs - -Enable `debug_mode` in the (`scripts/settings.php`) file to enable debug logging. By default, logs will be -located in the scripts path, i.e. `/var/www/crowdsec-standalone-bouncer/scripts/.logs`. - -### Testing ban remediation - -To test the ban remediation : -- identify or create simple php file (even a `` would do) -- add a decision on your crowdsec agent (`sudo cscli decisions add -i `) -- try to access the php file, and you should see the HTML forbidden ban page - - -### Testing the captcha feature - -To test the captcha remediation : -- identify or create simple php file (even a `` would do) -- add a decision on your crowdsec agent (`cscli decisions add -i -t captcha`) -- try to access the php file, and you should see the captcha page - - - -### Testing geolocation remediation - -The bouncer is expecting decisions with a scope of `Country`, and 2-letters code value. - -To test the geolocation remediation : -- identify or create simple php file (even a `` would do) -- add a decision on your crowdsec agent (`cscli decisions add --scope Country --value FR -t captcha`) -- try to access the php file, and you should see the captcha page - - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-standalone-php-bouncer/blob/main/doc/DEVELOPER.md) - diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/windows-firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/windows-firewall.mdx deleted file mode 100644 index d468251b..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/windows-firewall.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -id: windows_firewall -title: Windows Firewall Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -The windows firewall bouncer interacts with the Windows Firewall to block IPs banned by CrowdSec. - -It will create multiple rules in the firewall (one rule will contains 1000 IPs) and will manage their lifecycle. - -The rules are created on startup and automatically deleted when the bouncer stops. - -## Installation - -:::warning - -The .NET 6 runtime is required for the bouncer to work ! - -::: - -You can download either a MSI (containing only the bouncer) or a setup bundle (containing the bouncer and the .NET 6 runtime) from the github releases: https://github.com/crowdsecurity/cs-windows-firewall-bouncer/releases - -You can also install the bouncer with [Chocolatey](https://chocolatey.org/) (this will automatically install the .NET runtime): - -```powershell -choco install crowdsec-windows-firewall-bouncer -``` - -## Configuration - -The configuration is stored in `C:\Program Files\CrowdSec\bouncers\cs-windows-firewall-bouncer\cs-windows-firewall-bouncer.yaml` - -### Example configuration - -```yaml -api_key: -api_url: http://127.0.0.1:8080 -log_level: info -update_frequency: 10s -log_media: file -log_dir: C:\ProgramData\CrowdSec\log\ -fw_profiles: - - domain -``` - ---- - -#### `api_key` - -API key to use for communication with LAPI. - -#### `api_url` - -URL of LAPI. - -#### `update_frequency` - -How often the bouncer will contact LAPI to update its content in seconds. - -Defaults to `10`. - -#### `log_media` - -Wether to log to file or to the console. - -Defaults to file when running as service and console when running in interactive mode. - -#### `log_dir` - -Location of the log file. - -Defaults to `C:\ProgramData\CrowdSec\log\`. - -#### `log_level` - -Log level. - -Can be one of: - - `trace` - - `debug` - - `info` - - `warn` - - `error` - - `fatal` - -Defaults to `info`. - -#### fw_profiles - -The firewall profile the rules will be associated with. - -The bouncer automatically select the current profile, but you can override this behaviour with this parameter. - -Allowed values are: - - `domain` - - `private` - - `public` - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/wordpress.mdx deleted file mode 100644 index a759634b..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.4.0/bouncers/wordpress.mdx +++ /dev/null @@ -1,496 +0,0 @@ ---- -id: wordpress -title: WordPress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## Usage - -### Description - -The `CrowdSec Bouncer` plugin for WordPress has been designed to protect WordPress websites from all kinds of -attacks by using [CrowdSec](https://crowdsec.net/) technology. - -### Prerequisites - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). -CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost CrowdSec must be installed on a server that is accessible via the WordPress site. - - -### Features - -When a user is suspected by CrowdSec to be malevolent, this bouncer will either send him/her a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he will access the page as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages in a few clicks so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users’ language. - - -### Configurations - -This plugin comes with configurations that you will find under `CrowdSec` admin section. - -These configurations are divided in three main parts : `CrowdSec`, `Theme customization` and `Advanced`. - -#### General settings - -In the `CrowdSec` part, you will set your connection details and refine bouncing according to your needs. You will -also be able to test your settings. - -*** - -Connection details - -*** - -`Connection details → Local API URL` - -Url to join your CrowdSec Local API. - -If the CrowdSec Agent is installed on this server, you could set this field to `http://localhost:8080`. - -*** - -`Connection details → Authentication type` - -Choose between `Bouncer API key` and `TLS certificates` (pki) authentication. - -TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. -Please see [CrowdSec documentation](https://docs.crowdsec.net/docs/local_api/tls_auth/). - -*** - -`Connection details → Bouncer API key` - -Key generated by the cscli command. - -Only if you chose `Bouncer API key` as authentication type. - -*** - -`Connection details → Path to the bouncer certificate` - -Relative path to the `wp-content/plugins/crowdsec/tls` folder of your WordPress instance. - -Example: `bouncer.pem`. - -Only if you chose `TLS certificates` as authentication type. - -*** - -`Connection details → Path to the bouncer key` - -Relative path to the `wp-content/plugins/crowdsec/tls` folder of your WordPress instance. - -Example: `bouncer-key.pem`. - -Only if you chose `TLS certificates` as authentication type. - -*** - -`Connection details → Verify peer` - -This option determines whether request handler verifies the authenticity of the peer's certificate. - -Only if you chose `TLS certificates` as authentication type. - -When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. -If `Verify peer` is checked, request handler verifies whether the certificate is authentic. -This trust is based on a chain of digital signatures, -rooted in certification authority (CA) certificate you supply using the `Path to the CA used to process for peer -verification` setting below. - -*** - -`Connection details → Path to the CA certificate used to process peer verification` - -Relative path to the `wp-content/plugins/crowdsec/tls` folder of your WordPress instance. - -Example: `ca-chain.pem`. - -Only if you chose `TLS certificates` as authentication type. - - -*** - -`Connection details → Use cURL to call Local API` - -By default, `file_get_contents` method is used to call Local API. This method requires to have enabled the option -`allow_url_fopen`. -Here, you can choose to use `cURL` requests instead. Beware that in this case, you need to have php `cURL` extension -installed and enabled on your system. - -Bouncing - -*** - -`Bouncing → Bouncing level` - -Choose if you want to apply CrowdSec directives (`Normal bouncing`) or be more permissive (`Flex bouncing`). - -With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This -mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario. - -*** - -`Bouncing → Public website only` - -If enabled, the admin is not bounced. - -*** - -Test your settings - -`Test your settings → Test bouncing` - -Click the "Test bouncing" button and the configured bouncer will try to get the remediation (bypass, captcha or ban) -for -the IP entered in the text field. By default, tested IP is the current detected remote IP. - -This test allows you to know if your connection, bouncing and cache settings are correct. - - -*** - -`Test your settings → Test geolocation` - -Click the "Test geolocation" button to try getting country for the IP entered in the text field. - -This test allows you to know if your geolocation settings are correct. - - -#### Theme customization - -In the `Theme customization` part, you can modify texts and colors of ban and captcha walls. - -Captcha wall customization - -Ban wall customization - -Wall CSS - - -#### Advanced settings - -In the `Advanced` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec -Local API, handle your remediation policy, manage geolocation feature, adjust some debug parameters and testing parameters. - -Communication mode - - -*** - -`Communication mode to the API → Enable the "Stream mode"` - -Choose if you want to enable the `stream mode` or stay in `live mode`. - - -By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. - -But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -*** - -`Communication mode to the API → Resync decisions each (stream mode only)` - -With the stream mode, every decision is retrieved in an asynchronous way. Here you can define the frequency of this -cache refresh. - -**N.B** : There is also a refresh button if you want to refresh the cache manually. - -*** - -Cache - -*** - -`Caching configuration → Technology` - -Choose the cache technology that will use your CrowdSec Local API. - -The File system cache is faster than calling Local API. Redis or Memcached is faster than the File System cache. - -**N.B** : There are also a `Clear now` button fo all cache technologies and a `Prune now` button dedicated to the -file system cache. - -*** - -`Caching configuration → Recheck clean IPs each (live mode only)` - -The duration between re-asking Local API about an already checked clean IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - -`Caching configuration → Recheck bad IPs each (live mode only)` - -The duration between re-asking Local API about an already checked bad IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - - -*** - -`Caching configuration → Captcha flow cache lifetime` - -The lifetime of cached captcha flow for some IP. - -If a user has to interact with a captcha wall, -we store in cache some values in order to know if he has to resolve or not the captcha again. - -Minimum 1 second. Default: 86400 seconds. - -*** - -`Caching configuration → Geolocation cache lifetime` - -The lifetime of cached country geolocation result for some IP. - -Minimum 1 second. Default: 86400 seconds. - - -*** - - -Remediations - -*** - -`Remediations → Fallback to` - -Choose which remediation to apply when CrowdSec advises unhandled remediation. - -*** - -`Remediations → Trust these CDN IPs (or Load Balancer, HTTP Proxy)` - -If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate in the bouncer settings the IP ranges of these devices in order to be able to check the IP of your users. For other IPs, the bouncer will not trust the X-Forwarded-For header. -*** - -`Remediations → Hide CrowdSec mentions` - -Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls. -*** - -Geolocation - -*** - -`Geolocation → Enable geolocation feature` - -Enable if you want to use also CrowdSec country scoped decisions. -If enabled, bounced IP will be geolocalized and the final remediation will take into account any country related decision. - -*** - -`Geolocation → Geolocation type` - - -For now, only `Maxmind database` type is allowed - -*** - -`Geolocation → MaxMind database type` - -Choose between `Country` and `City`. - - -*** - -`Geolocation → Path to the MaxMind database` - -Relative path from `wp-content/plugins/crowdsec/geolocation` folder. - -*** - -`Geolocation → Save geolocalized country in cache` - -Enabling this will avoid multiple call to the geolocation system (e.g. MaxMind database) -If enabled, the geolocalized country associated to the IP will be saved in cache. -See the `Geolocation cache lifetime` setting above to set the lifetime of this result. -*** - -Debug - -*** - -`Debug mode → Enable debug mode` - -Enable if you want to see some debug information in a specific log file. - -*** - -`Debug mode → Disable prod log` - -By default, a `prod.log` file will be written in `wp-content/plugins/crowdsec/logs` folder. - -You can disable this log here. - -*** - -`Display errors → Enable errors display` - -When this mode is enabled, you will see every unexpected bouncing errors in the browser. -Should be disabled in production. - -*** - -Test - -*** - -`Test settings → Forced test IP` - -This Ip will be used instead of the current detected browser IP. -**Must be empty in production.** - -*** - -`Test settings → Forced test X-Forwarded-For IP` - -This Ip will be used instead of the current X-Forwarded-For Ip if any. -**Must be empty in production.** - - -### Auto Prepend File mode - -By default, this extension will bounce every web requests that pass through the classical process of WordPress core loading. -This implies that if another php public script is called (any of your custom public php script for example) -or if you are using some plugin that bypass the WordPress core load process -(as the [WP Super Cache plugin](https://wordpress.org/plugins/wp-super-cache/) in Simple mode for example), bouncing will not be effective. - -To ensure that any php script will be bounced if called from a browser, you should try the `auto prepend file` mode. - -In this mode, every browser access to a php script will be bounced. - -To enable the `auto prepend file` mode, you have to configure your server by adding an `auto_prepend_file` directive -for your php setup. - -**N.B:** -- In this mode, a setting file `inc/standalone-settings.php` will be generated each time you save the - CrowdSec plugin configuration from the WordPress admin. - - -Adding an `auto_prepend_file` directive can be done in different ways: - -#### PHP - -You should add this line to a `.ini` file : - - auto_prepend_file = /wordpress-root-directory/wp-content/plugins/crowdsec/inc/standalone-bounce.php - - -#### Nginx - - -If you are using Nginx, you should modify your Magento 2 nginx configuration file by adding a `fastcgi_param` -directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "/wordpress-root-directory/wp-content/plugins/crowdsec/inc/standalone-bounce.php"; -} -``` - -#### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/wordpress-root-directory/wp-content/plugins/crowdsec/inc/standalone-bounce.php" - - - -### Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - - -## Installation - - -### Add the plugin - -The bouncer itself can be installed from the marketplace in WordPress back-office. - -Installing the CrowdSec WordPress plugin is as easy as installing any other WordPress plugin: - -- Click `Plugins` in the left navigation on your site’s dashboard. -- Type `CrowdSec` in the text field to the right. Hit enter. -- In the CrowdSec plugin click `Install Now` -- Once installed click `Activate`. - - -### WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Technical notes - -We explain here each important technical decision used to design this -plugin. - - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the WordPress host command -line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - http://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace `` with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/docs/DEVELOPER.md) - -## License - -[MIT](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/LICENSE) - - - - - - - - - - - - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers new file mode 120000 index 00000000..442e5a9d --- /dev/null +++ b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers @@ -0,0 +1 @@ +../../docs/bouncers/ \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/aws-waf.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/aws-waf.mdx deleted file mode 100644 index cf5d0211..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/aws-waf.mdx +++ /dev/null @@ -1,269 +0,0 @@ ---- -id: aws_waf -title: AWS WAF Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -The `crowdsec-awf-waf-bouncer` automatically adds rules to an AWS WAF ACL and manages IPSets content to apply decisions taken by crowdsec. - -This allows to protect the following AWS resources with crowdsec: - - AWS REST API Gateway - - Cloudfront distribution - - AWS Application LoadBalancer - - AWS AppSync GraphQL API - -As the bouncer does not manage your WAF ACLs, you will need to have existing ACLs already associated with your AWS resources for the bouncer to work properly. -The bouncer supports the `ban` and `captcha` decisions type and can be configured to fall back to one of those for decisions of unknown type. - -It can block at the IP (using `ip` scope in CrowdSec), range (using `range` scope in CrowdSec) or country level (using `country` scope in CrowdSec). - -The bouncer will create all required resources and associate them with your existing ACLs based on your provided configuration. - -As the resources will incur an AWS cost, the bouncer will remove everything it created when stopping. - -If you do not have an existing AWS WAF configuration, you can refer to the [official documentation](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to get started. - -## Installation - -### Using packages - -Packages for crowdsec-aws-waf-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-aws-waf-bouncer -``` - - - - -```bash -sudo yum install crowdsec-aws-waf-bouncer -``` - - - - -### Docker - -```shell -docker run -v $(PWD)/config.yaml:/cs-aws-waf-bouncer.yaml crowdsecurity/aws-waf-bouncer -``` - -## Configuration - -You will need to edit `/etc/crowdsec/bouncers/crowdsec-aws-waf-bouncer.yaml` to configure the ACLs you want the bouncer to use. - -```yaml -api_key: XXXX -api_url: "http://127.0.0.1:8080/" -update_frequency: 10s -waf_config: - - web_acl_name: mywebacl - fallback_action: ban - rule_group_name: crowdsec-rule-group-eu-west-1 - scope: REGIONAL - region: eu-west-1 - ipset_prefix: crowdsec-ipset-a - ip_header: X-Forwarded-For - ip_header_position: LAST - aws_profile: myprofile - - web_acl_name: test-cloudfront - fallback_action: captcha - rule_group_name: crowdsec-rule-group-cloudfront - scope: CLOUDFRONT - ipset_prefix: crowdsec-ipset-cf -``` - -Optionally, the bouncer can also be configured using only environment variables. - -Environment variables will take priority over values defined in the configuration file, in which case the suggested approach is via `systemctl edit crowdsec-aws-waf-bouncer`: - -``` -[Service] -Environment="BOUNCER_API_KEY=XXXXX" -``` - -AWS authentication is handled with the standard environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE) or instance role. - -You can also use the `aws_profile` directive to specify a profile to use for a specific waf configuration. - ---- -#### `api_key` -##### Environment variable: `BOUNCER_API_KEY` - -API key to use for communication with LAPI. - -#### `api_url` -##### Environment variable: `BOUNCER_API_URL` - -URL of LAPI. - -#### `update_frequency` -##### Environment variable: `BOUNCER_UPDATE_FREQUENCY` - -How often the bouncer will contact LAPI to update its content. - -The format must be supported by [golang ParseDuration](https://pkg.go.dev/time#ParseDuration). - -#### `supported_actions` -##### Environment variable: `BOUNCER_SUPPORTED_ACTIONS` - -Which actions (ie, remediation type) the bouncer supports. - -List with any of the following: `ban`, `captcha`, `count`. - -Default to `ban`, `captcha` and `count`. - -If set from the environment, provide a comma-separated list: `ban,captcha,count`. - ---- -### `waf_config` -##### Environment variable: `BOUNCER_WAF_CONFIG_` - - -List of object with the following properties: - -``` -waf_config: - - web_acl_name: mywebacl - fallback_action: ban - rule_group_name: crowdsec-rule-group-XXX - scope: REGIONAL - region: eu-west-1 - ipset_prefix: crowdsec-ipset- -``` - -When configuring via environment variables, you can pass multiple `BOUNCER_WAF_CONFIG_X_` variables, with `X` being a unique identifier (eg, `0`, `1`, `2`, ...). - -#### `web_acl_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_WEB_ACL_NAME` - - -Name of the WAF ACL in which the rule group will be added - -#### `fallback_action` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_FALLBACK_ACTION` - -Action to use if the type of a decision is not in the list defined by `supported_actions`. - -Must be one of `captcha`, `ban` or `count`. - -#### `rule_group_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_RULE_GROUP_NAME` - - -Name of the rule group the bouncer will create and add to the WAF ACL. - -Must be unique across all the configuration. - -2 rules can be created: - - crowdsec-rule-ban - - crowdsec-rule-captcha - -Those rules are automatically deleted if no decisions of the associated type exist. - -If a decision for a country is received, the following rules will be created: - - crowdsec-rule-ban-country: Contains a geomatch statement for banned countries - - crowdsec-rule-captcha-country: Contains a geomatch statement for captcha'ed countries - -Those rules will be deleted on shutdown and recreated on startup if they already exist. - -#### `scope` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_SCOPE` - - -Scope of the rule group and ipset. Can be `REGIONAL` or `CLOUDFRONT`. - -Must match the scope of the WAF ACL. - -#### `region` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_REGION` - - -Region where all resources will be created. - -No required when scope is `CLOUDFRONT` - -#### `ipset_prefix` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IPSET_PREFIX` - -Prefix for all the ipsets the bouncer will create. - -One ipset will be created per 10k IPs, and will be automatically deleted if it becomes empty. - -Differents ipsets are used for ban and captcha. - -All ipsets are deleted on shutdown. - -#### `aws_profile` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_AWS_PROFILE` - -Name of the AWS profile (defined in ~/.aws/config) to use. - -#### `ip_header` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IP_HEADER` - -Name of the header to use to get the source IP. -If not defined, the actual source IP will be used. - -The request will be allowed if the header is not present or contains no valid IP. - -#### `ip_header_position` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_IP_HEADER_POSITION` - -If the header used to get the source IP is a comma-separated list, this parameter can be used to specify which part of the list should be used. - -Must be one of `FIRST`, `LAST`, `ANY`. - -Required when `ip_header` is defined. - -#### `capacity` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_CAPACITY` - -Capacity of the rule group created by the bouncer. - -If not set, default to 300 (this value is way higher than it needs to be, but this prevents any kind of issue regarding capacity of the rule group). - -For reference, a simple match on a IP with no custom header will cost 1 WCU per IPSet created by the bouncer, or 5 WCU if you are getting the source IP from a header. - -See [AWS WAF documentation](https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works.html#aws-waf-capacity-units) for more information. - -#### `cloudwatch_enabled` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_CLOUDWATCH_ENABLED` - -Whether or not AWS WAF will send metrics to CloudWatch for the rule group. - -#### `cloudwatch_metric_name` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_CLOUDWATCH_METRIC_NAME` - -Name of the cloudwatch metric. Default to the rule group name. - -#### `sample_requests` -##### Environment variable: `BOUNCER_WAF_CONFIG_X_SAMPLE_REQUESTS` - -Whether or not to sample requests from the rule groups created by the bouncer. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/blocklist-mirror.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/blocklist-mirror.mdx deleted file mode 100644 index c5d44ba2..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/blocklist-mirror.mdx +++ /dev/null @@ -1,306 +0,0 @@ ---- -id: blocklist-mirror -title: Blocklist mirror -sidebar_position: 7 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

-

- - -This bouncer exposes CrowdSec's active decisions via provided HTTP endpoints in pre-defined formats. It can be used by network appliances which support consumption of blocklists via HTTP. - - -## Installation from packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```console -$ sudo apt install crowdsec-blocklist-mirror -``` - - - - -```console -$ sudo yum install crowdsec-blocklist-mirror -``` - - - - - -## Installation using docker: - -Refer to docker [hub docs](https://hub.docker.com/r/crowdsecurity/blocklist-mirror) - - - -## Manual installation via script - -First, download the latest [`crowdsec-blocklist-mirror` release](https://github.com/crowdsecurity/cs-blocklist-mirror/releases). - -```console -$ tar xzvf crowdsec-blocklist-mirror.tgz -$ sudo ./install.sh -``` - -## From source - -Run the following commands: - -```console -$ git clone https://github.com/crowdsecurity/cs-blocklist-mirror.git -$ cd cs-blocklist-mirror/ -$ make release -$ cd crowdsec-blocklist-mirror-v*/ -$ sudo ./install.sh -``` - -# Configuration - -Before starting the `crowdsec-blocklist-mirror` service, please edit the configuration file to add your API URL and key. -The default configuration file is located under : `/etc/crowdsec/bouncers/` - -```console -$ vim /etc/crowdsec/bouncers/crowdsec-blocklist-mirror.yaml -``` - -```yaml -config_version: v1.0 -crowdsec_config: - lapi_key: ${API_KEY} - lapi_url: http://127.0.0.1:8080/ - update_frequency: 10s - include_scenarios_containing: [] - exclude_scenarios_containing: [] - only_include_decisions_from: [] - insecure_skip_verify: false - -blocklists: - - format: plain_text # Supported formats are either of "plain_text" - endpoint: /security/blocklist - authentication: - type: none # Supported types are either of "none", "ip_based", "basic" - user: - password: - trusted_ips: # IP ranges, or IPs which don't require auth to access this blocklist - - 127.0.0.1 - - ::1 - -listen_uri: 127.0.0.1:41412 -tls: - cert_file: - key_file: - -metrics: - enabled: true - endpoint: /metrics - -log_media: file -log_dir: /var/log/ -log_level: info -log_max_size: 40 -log_max_age: 30 -log_max_backups: 3 -enable_access_logs: true -compress_logs: true -``` - -### `crowdsec_config` - -#### `lapi_url`: - -The URL of CrowdSec LAPI. It should be accessible from whichever network the bouncer has access. - -#### `lapi_key`: - -It can be obtained by running the following on the machine CrowdSec LAPI is deployed on. -```bash - -sudo cscli -oraw bouncers add blocklistMirror # -oraw flag can discarded for human friendly output. - -``` - -#### `update_frequency`: - -The bouncer will poll the CrowdSec every `update_frequency` interval. - -#### `include_scenarios_containing`: - -Ignore IPs banned for triggering scenarios not containing either of provided word. - -#### `exclude_scenarios_containing`: - -Ignore IPs banned for triggering scenarios containing either of provided word. - -#### `only_include_decisions_from`: - -Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -#### `insecure_skip_verify`: - -Set to true to skip verifying certificate. - -#### `listen_uri`: - -Location where the mirror will start server. - -### `tls_config` - -#### `cert_file`: - -Path to certificate to use if TLS is to be enabled on the mirror server. - -#### `key_file`: - -Path to certificate key file. - -### `metrics`: - -#### `enabled`: - -Boolean (true|false). Set to true to enable serving and collecting metrics. - -#### `endpoint`: - -Endpoint to serve the metrics on. - -### `blocklists`: - -List of blocklists to serve. Each blocklist has the following configuration. - -#### `format`: - -Format of the blocklist. Currently only `plain_text` and `mikrotik` are supported. - -#### `endpoint`: - -Endpoint to serve the blocklist on. - -### `authentication`: - -Authentication related config. - -#### `type`: - -Currently "basic" and "ip_based" authentication is supported. You can disable authentication completely by setting this to 'none'. - -- `basic`: It's Basic HTTP Authentication. Only requests with valid `user` and `password` as specified in below config would pass through - -- `ip_based`: Only requests originating from `trusted_ips` would be allowed. - -#### `user`: - -Valid username if using `basic` authentication. - -#### `password`: - -Password for the provided user and using `basic` authentication. - -#### `trusted_ips`: - -List of valid IPv4 and IPv6 IPs and ranges which have access to blocklist. It's only applicable when authentication `type` is `ip_based`. - -## Global RunTime Query Parameters - -`?ipv4only` - Only return IPv4 addresses - -Example usage -``` -http://localhost:41412/security/blocklist?ipv4only -``` - -`?ipv6only` - Only return IPv6 addresses - -Example usage -``` -http://localhost:41412/security/blocklist?ipv6only -``` -`?nosort` - Do not sort IP's - -> Only use if you do not care about the sorting of the list, can result in average 1ms improvement - -Example usage -``` -http://localhost:41412/security/blocklist?nosort -``` - -`?origin=` - Only return IP's by origin - -Example usage -``` -http://localhost:41412/security/blocklist?origin=cscli -``` - -You can then start the service via: - -```bash -sudo systemctl start crowdsec-blocklist-mirror -``` - -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.2 you can write them in a `crowdsec-blocklist-mirror.yaml.local` file as described in -[Overriding values](https://docs.crowdsec.net/docs/next/configuration/crowdsec_configuration#overriding-values). -Package upgrades may have good reasons to modify the configuration, so be careful if you use a `.local` file. - -## 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. - -### plain_text - -Example: - -```text -1.2.3.4 -4.3.2.1 -``` - -### mikrotik - -If your mikrotik router does not support ipv6, then you can use the global query parameters to only return ipv4 addresses. - -Example: - -```text -/ip firewall address-list remove [find list=CrowdSec] -/ipv6 firewall address-list remove [find list=CrowdSec] -/ip firewall address-list add list=CrowdSec address=1.2.3.4 comment="crowdsecurity/ssh-bf for 152h40m24.308868973s" -/ip firewall address-list add list=CrowdSec address=4.3.2.1 comment="crowdsecurity/postfix-spam for 166h40m25.280338424s"/ipv6 firewall address-list add list=CrowdSec address=2001:470:1:c84::17 comment="crowdsecurity/ssh-bf for 165h13m42.405449876s" -``` - -#### mikrotik query parameters - -`?listname=foo` - Set the list name to `foo`, by default `listname` is set to `CrowdSec` - -example output: -```text -/ip firewall address-list remove [find list=foo] -/ipv6 firewall address-list remove [find list=foo] -/ip firewall address-list add list=foo address=1.2.3.4 comment="crowdsecurity/ssh-bf for 152h40m24.308868973s" -/ip firewall address-list add list=foo address=4.3.2.1 comment="crowdsecurity/postfix-spam for 166h40m25.280338424s"/ipv6 firewall address-list add list=foo address=2001:470:1:c84::17 comment="crowdsecurity/ssh-bf for 165h13m42.405449876s" -``` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/cloudflare.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/cloudflare.mdx deleted file mode 100644 index 7c57064e..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/cloudflare.mdx +++ /dev/null @@ -1,442 +0,0 @@ ---- -id: cloudflare -title: Cloudflare Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A bouncer that syncs the decisions made by CrowdSec with CloudFlare's firewall. Manages multi user, multi account, multi zone setup. Supports IP, Country and AS scoped decisions. - -## Installation - -### Using packages - -Packages for crowdsec-cloudflare-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package accord to your firewall system : - - - - -```bash -sudo apt install crowdsec-cloudflare-bouncer -``` - - - - -```bash -sudo yum install crowdsec-cloudflare-bouncer -``` - - - - - -Then run the following commands to setup your bouncer: - - -```bash -sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided space separated tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -:::warning - -Please configure your server to emit real IPs rather than cloudflare IPs in logs, so crowdsec can function properly. See how to [here](https://support.cloudflare.com/hc/en-us/articles/200170786-Restoring-original-visitor-IPs) - -::: - -:::info - -If your bouncer is not installed on the same machine than LAPI, don't forget to set the `crowdsec_lapi_url` and `crowdsec_lapi_key` in the configuration file `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -::: - -:::note - -You need to run `sudo crowdsec-cloudflare-bouncer -d` to cleanup exisiting cloudflare components created by bouncer before editing the config files. - -::: - -:::note - -You can run `sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` to generate the configuration by discovering all the accounts and the zones associated with the provided tokens. - -::: - - -## Manual Installation - -### Assisted - -Download the [latest release](https://github.com/crowdsecurity/cs-cloudflare-bouncer/releases). - -```bash -tar xzvf crowdsec-cloudflare-bouncer.tgz -cd crowdsec-cloudflare-bouncer/ -sudo ./install.sh -sudo crowdsec-cloudflare-bouncer -g , -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml # auto-generate cloudflare config for provided tokens -sudo crowdsec-cloudflare-bouncer -s # this sets up IP lists and firewall rules at cloudflare for the provided config. -sudo systemctl start crowdsec-cloudflare-bouncer # the bouncer now syncs the crowdsec decisions with cloudflare components. -``` - -### From source - -:warning: requires go >= 1.16 - -```bash -make release -cd crowdsec-cloudflare-bouncer-vX.X.X -sudo ./install.sh -``` -Rest of the steps are same as of the above method. - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/cloudflare-bouncer \ - -g , > cfg.yaml # auto-generate cloudflare config for provided space separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -``` - -The `crowdsec_lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. -``` - -The `crowdsec_lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml \ - -p 2112:2112 \ - crowdsecurity/cloudflare-bouncer -``` - - -## Configuration - -Configuration file can be found at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` - -```yaml -# CrowdSec Config -crowdsec_lapi_url: http://localhost:8080/ -crowdsec_lapi_key: ${API_KEY} -crowdsec_update_frequency: 10s -include_scenarios_containing: [] # ignore IPs banned for triggering scenarios not containing either of provided word, eg ["ssh", "http"] -exclude_scenarios_containing: [] # ignore IPs banned for triggering scenarios containing either of provided word -only_include_decisions_from: [] # only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -#Cloudflare Config. -cloudflare_config: - accounts: - - id: - token: - ip_list_prefix: crowdsec - default_action: managed_challenge - total_ip_list_capacity: # only this many latest ip scoped decisions would be kept - - zones: - - actions: - - managed_challenge # valid choices are either of managed_challenge, js_challenge, block - zone_id: - - update_frequency: 30s # the frequency to update the cloudflare IP list - -# Bouncer Config -daemon: true -log_mode: file -log_dir: /var/log/ -log_level: info # valid choices are either debug, info, error -log_max_size: 40 -log_max_age: 30 -log_max_backups: 3 -compress_logs: true - -prometheus: - enabled: true - listen_addr: 127.0.0.1 - listen_port: 2112 -``` - -## Making changes to configuration - -The bouncer creates Cloudflare infra (IP lists, rules etc) according to your config file. - -Before changing the config, always run the following command to clear old infra: - -``` -sudo crowdsec-cloudflare-bouncer -d -``` - -### Upgrading from v0.0.X to v0.1.Y - -During v0.0.X there was no `managed_challenge` action, instead `challenge` action was used by bouncer. This is deprecated since v0.1.0 . - -This section assumes you used the default config (generated via `crowdsec-cloudflare-bouncer -g ,` ) - -After upgrading the bouncer from v0.0.X to v0.1.Y , run the following commands to migrate to `managed_challenge`. - -```bash -sudo crowdsec-cloudflare-bouncer -d -sudo crowdsec-cloudflare-bouncer -g , -o -sudo systemctl restart crowdsec-cloudflare-bouncer -``` - - -## Cloudflare Configuration - -**Background:** In Cloudflare, each user can have access to multiple accounts. Each account can own/access multiple zones. In this context a zone can be considered as a domain. Each domain registered with cloudflare gets a distinct `zone_id`. - - -For obtaining the `token`: -1. Sign in as a user who has access to the desired account. -2. Go to [Tokens](https://dash.cloudflare.com/profile/api-tokens) and create the token. The bouncer requires the follwing permissions to function. -![image](https://raw.githubusercontent.com/crowdsecurity/cs-cloudflare-bouncer/main/docs/assets/token_permissions.png) - -To automatically generate config for cloudflare check the helper section below. - - -:::note -If the zone is subscribed to a paid Cloudflare plan then it can be configured to support multiple types of actions. For free plan zones only one action is supported. The first action is applied as default action. -::: - -## Helpers - -The bouncer's 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. - -Example Usage: - -```bash -sudo crowdsec-cloudflare-bouncer -g ,... -o cfg.yaml -cat cfg.yaml > /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml -``` - -:::note -This script only generates cloudflare related config. By default it refers to the config at `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml` for crowdsec configuration. -::: - -Using custom config: -```bash -sudo crowdsec-cloudflare-bouncer -c ./cfg.yaml -g ,... -``` - -### Cloudflare Setup - -This only creates the required IP lists and firewall rules at cloudflare and exits. - -Example Usage: -```bash -sudo crowdsec-cloudflare-bouncer -s -``` - -### Cloudflare Cleanup - -This deletes all IP lists and firewall rules at cloudflare which were created by the bouncer. - -Example Usage: -```bash -sudo crowdsec-cloudflare-bouncer -d -``` - -## How it works - -The service polls the CrowdSec Local API for new decisions. It then makes API calls to Cloudflare -to update IP lists and firewall rules depending upon the decision. - -## Configuration Reference - -### `crowdsec_lapi_url` - -The URL of CrowdSec LAPI. It should be accessible from the bouncer. - -### `crowdsec_lapi_key` - -It can be obtained by running the following on the machine CrowdSec LAPI is deployed on. -```bash - -sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output. - -``` - -### `crowdsec_update_frequency` - -The bouncer will poll the CrowdSec every `update_frequency` interval. - -### `include_scenarios_containing` - -Ignore IPs banned for triggering scenarios not containing either of provided word. Example value ["ssh", "http"] - -### `exclude_scenarios_containing` - -Ignore IPs banned for triggering scenarios containing either of provided word. Example value ["ssh", "http"] - - -### `only_include_decisions_from` - -Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"] - -### `cloudflare_config` - -This block contains cloudflare specific config. - -#### `update_frequency` - -The frequency at which to update the cloudflare resources. eg values include `5s` or `1m` etc. - -#### `accounts` - -List of account of configs - -##### `id` - -id of cloudflare account - -##### `token` - -cloudflare token to use to access the account. - -##### `ip_list_prefix` - -The prefix to use for naming the IP lists created by the bouncer. The name of IP list will be of the form `ip_list_prefix`+`action`. - -##### `total_ip_list_capacity` - -Limit the number of items in IP lists by this number. This is required for avoiding limit of 10k items for lists. - -##### `default_action` - -The action to be applied for a decision, if the decision's action is not supported by a zone. - -`default_action` must be supported by all zones. - -Valid choice includes either of 'managed_challenge', 'block', 'js_challenge', 'challenge' or 'none' to ignore unsupported decision. - -**Example:** - -Consider your zone config supports the actions `managed_challenge` and `js_challenge`. Your `default_action` is `managed_action`. If you create the following decision: - -``` -sudo cscli decisions add --ip 1.2.3.4 --type ban -``` - -Since the zone doesn't support `ban` decision type, it'll be inserted into the IP list given by `default_action`. In this case it'll be the list for `managed_challenge`. - -You can completely ignore such decisions by setting `default_action` to `none`. It won't be inserted into any list then. - -**Note:** - -Following table is mapping of decision type to it's destination IP list. - -| Decision Type | Default Action | -| -------------------| ----------- | -| captcha | managed_challenge | -| ban | block | -| js_challenge | js_challenge | - - -:::warning -`challenge` action is deprecated in favour of `managed_challenge`. -::: - -#### `zones` - -This block contains config for each zone to be managed by the bouncer. The zone must be accessible from the parent account. - -##### `zone_id` - -The id of the zone. - -##### `actions` - -List of actions to be supported by this zone. If the zone is not subscribed to premium plan, then only a single action can be given. - -The supported action must include the `default_action` of the parent account. - -Valid choice includes either of -- `block` -- `js_challenge` -- `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. - -:::warning -`challenge` action is deprecated in favour of `managed_challenge` -::: - -**Note:** - -Following table is mapping of decision type to it's destination IP list, which are created according to zone actions - - -| Decision Type | Zone Action | -| -------------------| ----------- | -| captcha | managed_challenge | -| ban | block | -| js_challenge | js_challenge | - - - -### `daemon` - -Boolean (true|false). Set to true if the bouncer is being run as background daemon service. - -### `log_mode` - -Valid values are `stdout` or `file` - -### `log_dir` - -Relevant if `log_mode` is `file`. This determines where to create log file. - -### `log_level` - -Valid choices are either debug, info, error - -### `log_max_size`, `log_max_age`, `log_max_backups`, `compress_logs` - -Log rotation releated config. - - -## Troubleshooting - - Metrics can be seen at http://localhost:2112/metrics - - Logs are in `/var/log/crowdsec-cloudflare-bouncer.log` - - You can view/interact directly in the ban list either with `cscli` - - Service can be started/stopped with `systemctl start/stop crowdsec-cloudflare-bouncer` \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/custom.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/custom.mdx deleted file mode 100644 index 52e351fe..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/custom.mdx +++ /dev/null @@ -1,152 +0,0 @@ ---- -id: custom -title: Custom Bouncer -sidebar_position: 5 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -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 - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-custom-bouncer -``` - - - - -```bash -sudo yum install crowdsec-custom-bouncer -``` - - - - - - - - -## 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 - -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/` - -```sh -$ vim /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml -``` - -```yaml -bin_path: -piddir: /var/run/ -update_frequency: 10s -daemonize: true -log_mode: file -log_dir: /var/log/ -log_level: info -api_url: # when install, default is "localhost:8080" -api_key: # Add your API key generated with `cscli bouncers add --name ` -cache_retention_duration: 10s -``` - -`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: - -```sh -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](https://docs.crowdsec.net/docs/next/configuration/crowdsec_configuration#overriding-values). -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 - -The custom binary will be called with the following arguments : - -```bash - add # to add an IP address - del # to del an IP address -``` - -- `ip` : ip address to block `/` -- `duration`: duration of the remediation in seconds -- `reason` : reason of the decision -- `json_object`: the serialized decision - -: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: - -```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" -``` - diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/fastly.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/fastly.mdx deleted file mode 100644 index 6f27909d..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/fastly.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -id: fastly -title: Fastly Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

- -

- -

- - -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -# 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. -To learn how to setup crowdsec to consume fastly logs see [this](/docs/next/user_guides/consuming_fastly_logs) - - -# Installation: - -## Using pip - -Make sure you have python3.8+ installed. Now in a virtual environment run the following: - -```bash -pip install crowdsec-fastly-bouncer -crowdsec-fastly-bouncer -g , > config.yaml # generate config -vim config.yaml # Set crowdsec LAPI key, url, recaptcha keys, logging etc -crowdsec-fastly-bouncer -c config.yaml # Run it ! -``` - -See how to obtain fastly account tokens [here](https://docs.fastly.com/en/guides/using-api-tokens). The tokens must have write access for the configured services. - -**Note:** If your bouncer is not installed on the same machine than LAPI, don't forget to set the `lapi_url` and `lapi_key` in the configuration file /etc/crowdsec/bouncers/crowdsec-fastly-bouncer.yaml - -**Note:** For captcha to work you must provide the `recaptcha_site_key` and `recaptcha_secret_key` for each service. Learn how [here](http://www.google.com/recaptcha/admin) - - -## Using Docker - -Make sure you have docker or podman installed. In this guide we will use docker, but podman would work as a drop in replacement too. - -### Initial Setup - -```bash -docker run crowdsecurity/fastly-bouncer \ - -g , > cfg.yaml # auto-generate fastly config for provided comma separated tokens -vi cfg.yaml # review config and set `crowdsec_lapi_key` -touch fastly-cache.json -``` - -The `lapi_key` can be obtained by running the following: -```bash -sudo cscli -oraw bouncers add fastlybouncer # -oraw flag can discarded for human friendly output. -``` - -The `lapi_url` must be accessible from the container. - -### Run the bouncer - -```bash - docker run \ - -v $PWD/cfg.yaml:/etc/crowdsec/bouncers/crowdsec-fastly-bouncer.yaml \ - -v $PWD/fastly-cache.json:/var/lib/crowdsec/crowdsec-fastly-bouncer/cache/fastly-cache.json \ - crowdsecurity/fastly-bouncer -``` - -## 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 ! - -# Configuration: - -```yaml -crowdsec_config: - lapi_key: ${LAPI_KEY} - lapi_url: "http://localhost:8080/" - -fastly_account_configs: - - account_token: # Obtain this from fastly - services: - - id: # The id of the service - recaptcha_site_key: # Required for captcha support - recaptcha_secret_key: # Required for captcha support - max_items: 20000 # max_items refers to the capacity of IP/IP ranges to ban/captcha. - activate: false # # Set to true, to activate the new config in production - reference_version: # version to clone/use - clone_reference_version: true # whether to clone the "reference_version". - captcha_cookie_expiry_duration: '1800' # Duration to persist the cookie containing proof of solving captcha - -bouncer_version: -update_frequency: 10 # Duration in seconds to poll the crowdsec API -log_level: info # Valid choices are either of "debug","info","warning","error" -log_mode: stdout # Valid choices are "file" or "stdout" or "stderr" -log_file: /var/log/crowdsec-fastly-bouncer.log # Ignore if logging to stdout or stderr -``` - -# Helpers: - -The bouncer has few builtin helper features: - -## Auto config generator: - -**Usage:** - -```bash -crowdsec-fastly-bouncer -c \ - -g , -``` - -This will print boilerplate config with sane defaults for the provided comma separted fastly tokens. -Always review the generated config before proceeding further. - -Crowdsec config is copied from the config at `PATH_TO_BASE_CONFIG`. - -## Cleaner: - -**Usage:** - -```bash -sudo crowdsec-fastly-bouncer -c -d -``` - -This deletes the fastly resources created by the bouncer. -It only works if the configured service version is not locked. -It is useful for quick iteration before activateing the new service. \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/firewall.mdx deleted file mode 100644 index 92de5570..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/firewall.mdx +++ /dev/null @@ -1,332 +0,0 @@ ---- -id: firewall -title: Firewall Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - - -

- -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -CrowdSec bouncer written in golang for firewalls. - -crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API and add them to a blocklist used by supported firewalls. - -Supported firewalls: - - iptables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - nftables (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - ipset only (IPv4 :heavy_check_mark: / IPv6 :heavy_check_mark: ) - - pf (IPV4 :heavy_check_mark: / IPV6 :heavy_check_mark: ) - -## Installation - -Packages for crowdsec-firewall-bouncer [are available on our repositories](/getting_started/install.mdx##install-our-repositories). You need to pick the package according to your firewall system : - -### IPTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-iptables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -### NFTables - - - - -```bash -sudo apt install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo yum install crowdsec-firewall-bouncer-nftables -``` - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - -### pf - - - - -```bash -sudo pkg install crowdsec-firewall-bouncer -``` - - - - - -See as well [Manual Installation documentation below](/docs/bouncers/firewall#manual-installation) - - - -## Configuration - -There are two primary ways to use the firewall bouncer: - - **managed** (default): cs-firewall-bouncer will create ipset/nft sets, insert the associated firewall rules and manage the set contents - - **set only**: you already have a (complex) firewall setup, cs-firewall-bouncer will only manage the _content_ of existing specified sets - - -### Managed mode : Iptables/ipset or Nftables - -__This is the default behaviour__ - -In "managed" mode (mode `nftables` or `iptables`), bouncer creates all the needed elements (rules, sets) and insert the appropriate rules in nftables or iptables. - -:::warning - -IPSet (when using `iptables` mode) does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds. - -::: - -### Set Only : Iptables/Ipset table - -In iptable set-only mode (mode `ipset`), the bouncer only handles the **contents** of sets that are specified by `blacklists_ipv4` and `blacklists_ipv6`. -These sets must be created before starting the bouncer, and it is the user's responsibility to create the associated iptables rules. - -:::warning - -IPSet does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds. - -::: - -### Set Only : nftables - -In nftables set only mode (mode `nftables` with `nftables.{ipv4,ipv6}.set-only` set to `true`), the bouncer only manages the **contents** of the sets. -It's the user's responsibility to create the associated chains and sets : - -```yaml title="/tmp/bouncer.nft" -table ip crowdsec { - set crowdsec-blacklists { - type ipv4_addr - flags timeout - } - - chain crowdsec-chain { - type filter hook input priority filter; policy accept; - ip saddr @crowdsec-blacklists drop - } -} -table ip6 crowdsec6 { - set crowdsec6-blacklists { - type ipv6_addr - flags timeout - } - - chain crowdsec6-chain { - type filter hook input priority filter; policy accept; - ip6 saddr @crowdsec6-blacklists drop - } -} -``` - - -## Configuration directives - - - - `mode` : can be set to `iptables`, `nftables` , `ipset` or `pf` - - `pid_dir` : directory to drop pid file - - `update_frequency` controls how often the bouncer is going to query the local API - - `daemonize` : for systemd unit - - `log_mode` : can be `file` or `stdout` - - `log_dir` : log directory - - `log_level` : can be `trace`, `debug`, `info`, or `error` - - `log_compression` : compress logs on rotation, `true` or `false` - - `log_max_size` : maximum file size before rotation - - `log_max_backups` : how many backup log files to keep - - `log_max_age` : oldest backup log file before deletion - - `api_url` and `api_key` control local API parameters. - - `insecure_skip_verify` : allow self-signed certificates for LAPI, `false` or `true` - - `disable_ipv6` : disable ipv6 support, defaults to `false` - - `deny_action` : firewall action to apply, defaults to `DROP`, but can be `REJECT` - - `deny_log` : if set to `true`, enables logging of dropped packets (ie. `-j LOG`) - - `deny_log_prefix` : if logging is true, this sets the log prefix, defaults to "crowdsec: " - -### Iptables/Ipset specific directives - - - - `iptables_chains` : specify a list of chains to insert rules (only relevant in `iptables` mode) : - - `blacklists_ipv4` and `blacklists_ipv6` : names of ipv4 and ipv6 sets - - `ipset_size`: maximum number of entries in the ipset (default: 65536) - - `ipset_type`: type to use for the set (default: `nethash`) - -```yaml -iptables_chains: - - INPUT -# - FORWARD -# - DOCKER-USER -``` - -### Nftables specific directives - -Nftables mode has its own `nftables` section, with sub-section of ipv4 and ipv6 : - -```yaml -## nftables -nftables: - ipv4: - enabled: true - set-only: false - table: crowdsec - chain: crowdsec-chain - ipv6: - enabled: true - set-only: false - table: crowdsec6 - chain: crowdsec6-chain -``` - -if `set-only` is set to true, the bouncer will only manage the set contents. - -## Manual installation - -### Assisted - -First, download the latest [`crowdsec-firewall-bouncer` release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases). - -```bash -$ tar xzvf crowdsec-firewall-bouncer.tgz -$ sudo ./install.sh -``` - -### From source - -Run the following commands: - -```bash -git clone https://github.com/crowdsecurity/cs-firewall-bouncer.git -cd cs-firewall-bouncer/ -make release -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./install.sh -``` - -### Upgrade - -If you already have `crowdsec-firewall-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-firewall-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-firewall-bouncer.tgz -cd crowdsec-firewall-bouncer-v*/ -sudo ./upgrade.sh -``` - - -### Configuration for manual installation - -To be functional, the `crowdsec-firewall-bouncer` service must be able to authenticate with the local API. -The `install.sh` script will take care of it (it will call `cscli bouncers add` on your behalf). -If it was not the case, the default configuration is in `/etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml`. - - -You can then start the service: - -```bash -sudo systemctl start crowdsec-firewall-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.25 you can write them in a `crowdsec-firewall-bouncer.yaml.local` file as described in -[Overriding values](https://docs.crowdsec.net/docs/next/configuration/crowdsec_configuration#overriding-values). -Package upgrades may have good reasons to modify the configuration, so be careful if you use a `.local` file. - - -### logs - -logs can be found in `/var/log/crowdsec-firewall-bouncer.log` - -### modes - - - mode `nftables` relies on github.com/google/nftables to create table, chain and set. - - mode `iptables` relies on `iptables` and `ipset` commands to insert `match-set` directives and maintain associated ipsets - - mode `ipset` relies on `ipset` and only manage contents of the sets (they need to exist at startup and will be flushed rather than created) - - mode `pf` relies on `pfctl` command to alter the tables. You are required to create the following tables on your `pf.conf` configuration: - -```bash - # create crowdsec ipv4 table -table persist - -# create crowdsec ipv6 table -table persist -``` - - You can refer to the step-by-step instructions of the [user tutorial on - FreeBSD](/blog/crowdsec_firewall_freebsd) - to setup crowdsec-firewall-bouncer with pf. - - ### ipset - - ipset lists have to exist before crowdsec-firewall-bouncer starts - you can create them and add them to your iptables like this: - -```console -ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000 -ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000 -iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP -ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP -``` diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/haproxy.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/haproxy.mdx deleted file mode 100644 index 10c54927..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/haproxy.mdx +++ /dev/null @@ -1,402 +0,0 @@ ---- -id: haproxy -title: HAProxy Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for haproxy. - -:::warning -This bouncer 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. - -Supported features: - - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - Captcha remediation (can return a captcha) - - Works with IPv4/IPv6 - - Support IP ranges (can apply a remediation on an IP range) - - -## Installation - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -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. -::: - -### Manual installation - -:::warning -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-haproxy-bouncer/releases) - -```bash -tar xvzf crowdsec-haproxy-bouncer.tgz -cd crowdsec-haproxy-bouncer-v*/ -./install.sh -``` -If you are on a mono-machine setup, the `crowdsec-haproxy-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-haproxy-bouncer -``` - -### Manual Upgrade - -If you already have `crowdsec-haproxy-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-haproxy-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-haproxy-bouncer.tgz -cd crowdsec-haproxy-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart haproxy -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-haproxy-bouncer.conf" -API_KEY= -MAP_PATH= # path to community_blocklist.map -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/haproxy/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -# Captcha Secret Key -SECRET_KEY= -# Captcha Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/haproxy/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### HAProxy Configuration - -HAProxy must be amended with following configuration : - -/!\ Be careful to the actual lua scripts location after install (/usr/lib or /usr/lib64 or /usr/local ...) - -```bash title="/etc/haproxy/haproxy.cfg" -global - ... - # Crowdsec bouncer >>> - lua-prepend-path /usr/lib/crowdsec/lua/haproxy/?.lua - lua-load /usr/lib/crowdsec/lua/haproxy/crowdsec.lua # path to crowdsec.lua - setenv CROWDSEC_CONFIG /etc/crowdsec/bouncers/crowdsec-haproxy-bouncer.conf # path to crowdsec bouncer configuration file - # Crowdsec bouncer <<< - ... -frontend myApp - ... - # Crowdsec bouncer >>> - stick-table type ip size 10k expire 30m # declare a stick table to cache captcha verifications - http-request lua.crowdsec_allow # action to identify crowdsec remediation - http-request track-sc0 src if { var(req.remediation) -m str "captcha-allow" } # cache captcha allow decision - http-request redirect location %[var(req.redirect_uri)] if { var(req.remediation) -m str "captcha-allow" } # redirect to initial url - http-request use-service lua.reply_captcha if { var(req.remediation) -m str "captcha" } # serve captcha template if remediation is captcha - http-request use-service lua.reply_ban if { var(req.remediation) -m str "ban" } # serve ban template if remediation is ban - # Crowdsec bouncer <<< - ... -# Crowdsec bouncer >>> -# define a backend for the captcha provider to allow DNS resolution -backend captcha_verifier - server captcha_verifier www.recaptcha.net:443 check - #server hcaptcha_verifier hcaptcha.com:443 check - #server turnstile_verifier challenges.cloudflare.com:443 check -# this is a little bit magic the server name is used to inform which captcha service you are using - -# define a backend for crowdsec to allow DNS resolution -# replace 127.0.0.1:8080 by the listen URI of the crowdsec local API -backend crowdsec - server crowdsec 127.0.0.1:8080 check -# Crowdsec bouncer <<< -``` - -#### Common haproxy issues - -If you are facing errors where haproxy 503's when trying to reach out for captcha verification backend, you can try: - -```bash title="/etc/haproxy/haproxy.cfg" -global - #Beware that this is disabling http client ssl verification and is only a temp workaround - httpclient.ssl.verify none - httpclient.resolvers.id my_resolver - -#8.8.8.8 is just an example -resolvers my_resolver - nameserver ns1 8.8.8.8:53 - -``` - -#### Crowdsec backend - -You must declare a backend for Crowdsec so we're able to resolve it's address during the refresh task. the backend and the server both must be named `crowdsec`. - -The decisions are stored in a [Map file](https://www.haproxy.com/blog/introduction-to-haproxy-maps/), the location of the map file is configured with `MAP_PATH` parameter. - -#### When using captcha remediation - -Using captcha, You must declare a backend for the captcha provider so we're able to resolve it's address during captcha verification. - -Validated ips are cached in a [Stick table](https://www.haproxy.com/blog/introduction-to-haproxy-stick-tables/) to avoid too many requests to captcha verification endpoint. - -### 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 wish to use any other provider than recaptcha you **MUST** adapt the server name in the backend: - - - recaptcha - -([captcha_verifier documentation](https://developers.google.com/recaptcha/intro)). - -```yaml -backend captcha_verifier - mode http - server captcha_verifier www.google.com:443 check -``` - - - hcaptcha - -([hcaptcha_verifier documentation](https://docs.hcaptcha.com/)) - -```yaml -backend captcha_verifier - mode http - server hcaptcha_verifier hcaptcha.com:443 -``` - - - turnstile - -([turnstile_verifier documentation](https://developers.cloudflare.com/turnstile/)). - -```yaml -backend captcha_verifier - mode http - server turnstile_verifier challenges.cloudflare.com:443 -``` - - - - -Edit `etc/crowdsec/bouncers/crowdsec-haproxy-bouncer.conf` and configure the following options: - -```bash -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart HAProxy. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### SSL and certificates - -In order to query captcha provider for verification, you need SSL certificates. Make sure you have root certificates installed on your system. You can also install `ca-certificates`. - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `REQUEST_TIMEOUT` -```bash -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). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The captcha secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The captcha site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer 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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/ingress-nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/ingress-nginx.mdx deleted file mode 100644 index f55a41be..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/ingress-nginx.mdx +++ /dev/null @@ -1,306 +0,0 @@ ---- -id: ingress-nginx -title: Ingress Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua plugin bouncer 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). - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - CAPTCHA remediation (can return a captcha) - - 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/). - -## Installation - -:::caution Before installation -The Ingress nginx controller should be installed using the [official helm chart](https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx) -::: - -### Using Helm - -First you need to create new ingress-nginx chart values file (`crowdsec-ingress-bouncer.yaml`) to upgrade the ingress controller with the crowdsec plugin. - -```yaml -controller: - extraVolumes: - - name: crowdsec-bouncer-plugin - emptyDir: {} - extraInitContainers: - - name: init-clone-crowdsec-bouncer - image: crowdsecurity/lua-bouncer-plugin - imagePullPolicy: IfNotPresent - env: - - name: API_URL - value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name - - name: API_KEY - value: "" # generated with `cscli bouncers add -n - - name: BOUNCER_CONFIG - value: "/crowdsec/crowdsec-bouncer.conf" - - name: CAPTCHA_PROVIDER - value: "recaptcha" # valid providers are recaptcha, hcaptcha, turnstile - - name: SECRET_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: SITE_KEY - value: "" # If you want captcha support otherwise remove this ENV VAR - - name: BAN_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html - - name: CAPTCHA_TEMPLATE_PATH - value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html - command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"] - volumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /lua_plugins - extraVolumeMounts: - - name: crowdsec-bouncer-plugin - mountPath: /etc/nginx/lua/plugins/crowdsec - subPath: crowdsec - config: - plugins: "crowdsec" - lua-shared-dicts: "crowdsec_cache: 50m" - server-snippet : | - lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line - resolver local=on ipv6=off; -``` - -This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. -It used [this docker image](https://hub.docker.com/r/crowdsecurity/lua-bouncer-plugin) to copy the crowdsec lua library. - -Once you have this patch we can upgrade the ingress-nginx chart. - -```bash -helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx -``` - -And then check if the ingress controller is running well. - -```bash -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. -::: - -### 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. - -If you want to increase the cache size you need to change this value : - -```yaml -controller: - config: - lua-shared-dicts: "crowdsec_cache: 50m" -```` - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -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). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/etc/nginx/lua/plugins/crowdsec/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - -### `CAPTCHA_PROVIDER` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_PROVIDER= -``` - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The captcha secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The captcha site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer 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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/intro.md b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/intro.md deleted file mode 100644 index db291101..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/intro.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: intro -title: Introduction -sidebar_position: 1 ---- - -# Remediation Components - -:::info -You may see Remediation Components referred to as "bouncers" in the documentation and/or within cscli commands. -::: -## Introduction - -Remediation Components are software packages in charge of acting upon decision's provided by the Security Engine. - -- [nginx bouncer](/bouncers/nginx.mdx) will check requester IP against the local API before granting or denying access. -- [firewall bouncer](/bouncers/firewall.mdx) will add IPs to nftables/ipset set. -- [cloudflare bouncer](/bouncers/cloudflare.mdx) will add IPs to the Cloudflare firewall. -- [blocklist mirror](/bouncers/blocklist-mirror.mdx) will serve the blocklist to a appliance such as pfsense, fortinet, untangle via a http server. - -Remediation Components interact with [crowdsec's Local API](/local_api/intro.md) to retrieve active decisions and remediate appropriately. - -You can explore [available remediation components on the hub](https://hub.crowdsec.net/browse/#bouncers). - -For your remediation components to communicate with the local API, you have to generate an API token with `cscli` and put it in the associated configuration file: - -```bash -sudo cscli bouncers add testBouncer -Api key for 'testBouncer': - - 6dcfe93f18675265e905aef390330a35 - -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. -::: - -If you wish to create your own remediation component, look at [this section](/local_api/bouncers-api.md) of the local API documentation. - - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/magento.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/magento.mdx deleted file mode 100644 index e2193e37..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/magento.mdx +++ /dev/null @@ -1,623 +0,0 @@ ---- -id: magento -title: Magento 2 Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-💠 Hub -💬 Discourse -

- - - -## Introduction - -The `CrowdSec Bouncer` extension for Magento 2 has been designed to protect Magento 2 websites from all kinds of attacks by using [CrowdSec](https://www.crowdsec.net/) technology. - -### Prerequisites - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). -CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost CrowdSec must be installed on a server that is accessible via the Magento 2 site. - - -## Usage - -### Features - -When a user is suspected by CrowdSec to be malevolent, this bouncer will either send him/her a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he will access the page as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages in a few clicks so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users’ language. - - -### Configurations - -This module comes with configurations that you will find under `Stores → Configurations → Security → CrowdSec Bouncer` admin section. - -These configurations are divided in four main parts : `General Settings`, `Theme customizations`, `Advanced settings` and `Events`. - - -#### General Settings - -In the `General settings` part, you will set your connection details and refine bouncing according to your needs. - -Connection details - -*** - -`Connection details → Your Local API Url` (`global` scope) - -Url to join your CrowdSec Local API. - -If the CrowdSec Agent is installed on this server, you could set this field to `http://localhost:8080`. - - -*** - -`Connection details → Authentication type` (`global` scope) - -Choose between API key and TLS (pki) authentication. - -TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. -Please see [CrowdSec documentation](https://docs.crowdsec.net/docs/local_api/tls_auth/). - - -*** - -`Connection details → Your bouncer key` (`global` scope) - -Key generated by the cscli command. - -Only if you chose `Api key` as authentication type. - -*** - -`Connection details → Path to the bouncer certificate` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -Example: `crowdsec/tls/bouncer.pem`. - -Only if you chose `TLS` as authentication type. - -*** - -`Connection details → Path to the bouncer key` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -Example: `crowdsec/tls/bouncer-key.pem`. - -Only if you chose `TLS` as authentication type. - -*** - -`Connection details → Enable TLS peer verification` (`global` scope) - -This option determines whether request handler verifies the authenticity of the peer's certificate. - -Only if you chose `TLS` as authentication type. - -When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. -If `Enable TLS peer verification` is set to true, request handler verifies whether the certificate is authentic. -This trust is based on a chain of digital signatures, -rooted in certification authority (CA) certificate you supply using the `Path to the CA certificate for peer verification` setting below. - -*** - -`Connection details → Path to the CA certificate for peer verification` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -Example: `crowdsec/tls/ca-chain.pem`. - -Only if you chose `TLS` as authentication type. - -*** - -`Connection details → Use cURL` (`global` scope) - -By default, `file_get_contents` method is used to call Local API. This method requires to have enabled the option -`allow_url_fopen`. -Here, you can choose to use `cURL` requests instead. Beware that in this case, you need to have php `cURL` extension installed and enabled on your system. - - -**N.B** : Even before saving configuration, you can check if your settings are correct by clicking on the test button. - - *** - -Bouncing - - -*** - -`Bouncing → Enable bouncer on Frontend area` (`store view` scope) - -Choose which store views you want to protect. - -*** - -`Bouncing → Enable bouncer on Adminhtml area` (`global` scope) - -Choose if you want to protect admin too. - -*** - -`Bouncing → Enable bouncer on API areas` (`global` scope) - -Choose if you want to protect REST, SOAP and GraphQL endpoints. - - -**N.B** : For API calls, there will be no ban or captcha wall. User will receive a `401` (ban) or `403` (captcha) response code. - -*** - -`Bouncing → Bouncing level` (`store view` scope) - -Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). - -With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This -mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario. - -*** - - - -#### Theme customizations - -In the `Theme customizations` part, you can modify texts and colors of ban and captcha walls. All fields here are -store view scoped, so you can use different languages and designs. - -Captcha wall customization - -Ban wall customization - -Wall CSS - - -#### Advanced settings - - -In the `Advanced settings` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec -Local API, handle your remediation policy and adjust some debug and log parameters. - -Communication mode - -*** - -`Communication mode to the API → Enable the stream mode` (`global` scope) - -Choose if you want to enable the `stream mode` or stay in `live mode`. - - -By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. - -But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -*** - -`Communication mode to the API → Cron expression for cache refresh` (`global` scope) - -With the stream mode, every decision is retrieved in an asynchronous way. Here you can define the frequency of this -cache refresh. - -**N.B** : There is also a refresh button if you want to refresh the cache manually. - - -*** - -Cache - -*** - -`Cache configuration → Technology` (`global` scope) - -Choose the cache technology that will use your CrowdSec Local API. - -The File system cache is faster than calling Local API. Redis or Memcached is faster than the File System cache. - -**N.B** : There are also a clear cache button fo all cache technologies and a prune cache button dedicated to the -file system cache. - -*** - -`Cache configuration → Cron expression for file system cache pruning` (`global` scope) - -If you chose file system as cache technology, you can schedule here an automatic cache pruning cron task. - -*** - - -`Cache configuration → Redis DSN` (`global` scope) - -Only if you choose Redis cache as technology. Example of DSN: redis://localhost:6379. - -*** - - -`Cache configuration → Memcached DSN` (`global` scope) - -Only if you choose Memcached cache as technology. Example of DSN: memcached://localhost:11211. - -*** - - -`Cache configuration → Clean IPs cache duration` (`global` scope) - -The duration between re-asking Local API about an already checked clean IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - -`Cache configuration → Bad IPs cache duration` (`global` scope) - -The duration between re-asking Local API about an already checked bad IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - - -`Cache configuration → Captcha flow cache duration` (`global` scope) - -The lifetime of cached captcha flow for some IP. If a user has to interact with a captcha wall, we store in cache some values in order to know if he has to resolve or not the captcha again. - -Minimum 1 second. - -*** - -`Cache configuration → Geolocation cache duration` (`global` scope) - -The lifetime of cached country result for some IP. Note that this setting can not be apply only if the -`Geolocation → Save geolocation country result in cache` below is enabled. - -Minimum 1 second. - -*** - -Geolocation - -*** - -`Geolocation → Enable geolocation feature` (`global` scope) - -Enable if you want to handle CrowdSec country scoped decisions. - -*** - -`Geolocation → Save geolocation country result in cache` (`global` scope) - -Enabling this option will avoid multiple call to the geolocation system (e.g. MaxMind database). - -*** - -`Geolocation → Geolocation type` (`global` scope) - -At this time, only MaxMind type is allowed. - -*** - -`Geolocation → MaxMind database type` (`global` scope) - -Choose between `Country` and `City` depending on your MaxMind database. - -*** - -`Geolocation → MaxMind database path` (`global` scope) - -Relative path to the `var` folder of your Magento 2 instance. - -*** - -**N.B** : There is also a test button if you want to test your geolocation settings. - -Remediations - - -*** - -`Remediations → Fallback to` (`global` scope) - -Choose which remediation to apply when CrowdSec advises unhandled remediation. - -*** - - -`Remediations → Trust these CDN Ips` (`global` scope) - -If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate in the bouncer settings the IP ranges of these devices in order to be able to check the IP of your users. For other IPs, the bouncer will not trust the X-Forwarded-For header. - -*** - -`Remediations → Hide CrowdSec mentions` (`global` scope) - -Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls. -*** - -Debug - -*** - -`Configure the debug mode → Enable debug log` (`global` scope) - -Enable if you want to see some debug information in a specific log file. - -*** - -`Configure the debug mode → Display bouncings errors` (`global` scope) - -When this mode is enabled, you will see every unexpected bouncing errors in the browser. - -*** - -`Configure the debug mode → Disable prod log` (`global` scope) - -The prod log is lighter than the debug log. But you can disable it here. - -*** - -`Configure the debug mode → Forced test IP` (`global` scope) - -For test purpose only. If not empty, this IP will be used for all remediations and geolocation processes. - -*** - -`Configure the debug mode → Forced test forwarded IP` (`global` scope) - -For test purpose only. This IP will be used instead of the current `X-Forwarded-For` IP if any. - -*** - -#### Events - - -In the `Events` part, you can enable business events logging. Using it in combination to a specific CrowdSec -scenario allows detecting suspicious behavior as credential or credit card stuffing. - -Events - -*** - -`Logging → Enable events log` (`global` scope) - -If enabled, logs will be written in a `var/log/crowdsec-events.log` file. - -*** - -`Logging → Track customer registration` (`global` scope) - -Will be used to detect suspicious account creation. - -*** - -`Logging → Track customer login` (`global` scope) - -Will be used to detect credential stuffing. - -*** - -`Logging → Track admin user login` (`global` scope) - -Will be used to detect admin brute attacks. - -*** - -`Logging → Track add to cart process` (`global` scope) - -Will be used to detect suspicious behaviour with add to cart action. - -*** - -`Logging → Track order process` (`global` scope) - -Will be used to detect suspicious behaviour, as credit card stuffing, on order action. - -### Auto Prepend File mode - -By default, this extension will bounce every web requests: e.g requests called from webroot `index.php`. -This implies that if another php public script is called (`cron.php` if accessible for example, or any of your -custom public php script) bouncing will not be effective. -To ensure that any php script will be bounced if called from a browser, you should try the `auto prepend file` mode. - -In this mode, every browser access to a php script will be bounced. - -To enable the `auto prepend file` mode, you have to: - -- copy the `crowdsec-prepend.php.example` file in your Magento 2 `app/etc` folder and rename it `crowdsec-prepend.php` -- configure your server by adding an `auto_prepend_file` directive for your php setup. - -**N.B:** -- Beware that you have to copy the file before modifying your PHP configuration,or you will get a PHP fatal error. -- Note that if you upgrade the bouncer module, you should have to copy the file again. To make this copy - automatically, you should modify the root `composer.json` of your Magento 2 projects by adding `post-install-cmd` - and `post-update-cmd` to the scripts parts: - -``` -"scripts": { - "post-install-cmd": [ - "php -r \"copy('vendor/crowdsec/magento2-module-bouncer/crowdsec-prepend.php.example','app/etc/crowdsec-prepend.php');\"" - ], - "post-update-cmd": [ - "php -r \"copy('vendor/crowdsec/magento2-module-bouncer/crowdsec-prepend.php.example','app/etc/crowdsec-prepend.php');\"" - ] -} -``` - - -Adding an `auto_prepend_file` directive can be done in different ways: - -#### PHP - -You should add this line to a `.ini` file : - - auto_prepend_file = /magento2-root-directory/app/etc/crowdsec-prepend.php - - -#### Nginx - - -If you are using Nginx, you should modify your Magento 2 nginx configuration file by adding a `fastcgi_param` -directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "/magento2-root-directory/app/etc/crowdsec-prepend.php"; -} -``` - -#### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/magento2-root-directory/app/etc/crowdsec-prepend.php" - - - - -## Installation - -### Requirements - -- Magento >= 2.3 - -### Composer installation - -Use `Composer` by simply adding `crowdsec/magento2-module-bouncer` as a dependency: - - composer require crowdsec/magento2-module-bouncer - -### Post Installation - -#### Enable the module - -After the installment of the module source code, the module has to be enabled by the Magento 2 CLI. - - bin/magento module:enable CrowdSec_Bouncer - -#### System Upgrade - -After enabling the module, the Magento 2 system must be upgraded. - -If the system mode is set to production, run the compile command first. This is not necessary for the developer mode. - - - bin/magento setup:di:compile - -Then run the upgrade command: - - - bin/magento setup:upgrade - - -#### Clear Cache - -The Magento 2 cache should be cleared by running the flush command. - - bin/magento cache:flush - -#### Deploy static content - -At last, you have to deploy the static content: - - bin/magento setup:static-content:deploy -f - - -### Troubleshooting - -#### Higher matching error - -If a new version `y.y.y` has been published in Packagist and the Marketplace review process of this version is still in progress, -you could encounter the following error during installation on update: - -> Higher matching version y.y.y of crowdsec/magento2-module-bouncer was found in public repository packagist.org -> than x.x.x in private https://repo.magento.com. Public package might've been taken over by a malicious entity, -> please investigate and update package requirement to match the version from the private repository - -This error is due to the `magento/composer-dependency-version-audit-plugin` composer plugin introduced in Magento `2.4.3` as a security measure [against Dependency Confusion attacks](https://support.magento.com/hc/en-us/articles/4410675867917-Composer-plugin-against-Dependency-Confusion-attacks). - -##### Install the latest Marketplace release - -To avoid this error and install the latest known Marketplace release `x.x.x`, you could run: - -```bash -composer require crowdsec/magento2-module-bouncer --no-plugins -``` - -##### Install the latest Packagist release - -To avoid this error and install the latest known Packagist release `y.y.y`, you could modify the root `composer.json` of your Magento project by setting the `repo.magento.com` repository as non-canonical: - -``` -"repositories": { - "0": { - "type": "composer", - "url": "https://repo.magento.com/", - "canonical": false - } -}, -``` -And then run the same command: -```bash -composer require crowdsec/magento2-module-bouncer --no-plugins -``` - -As an alternative, you can also exclude the `crowdsec/magento2-module-bouncer` from the `repo.magento.com` repository: -``` -"repositories": { - "0": { - "type": "composer", - "url": "https://repo.magento.com/", - "exclude": ["crowdsec/magento2-module-bouncer"] - } -}, -``` - -Thus, running `composer require crowdsec/magento2-module-bouncer` will always pick up the latest `y.y.y` Packagist release. - - - - - - - - - - - - - - - - -## Technical notes - -See [Technical notes](https://github.com/crowdsecurity/cs-magento-bouncer/blob/main/doc/TECHNICAL_NOTES.md) - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-magento-bouncer/blob/main/doc/DEVELOPER.md) \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/nginx.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/nginx.mdx deleted file mode 100644 index d695f217..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/nginx.mdx +++ /dev/null @@ -1,437 +0,0 @@ ---- -id: nginx -title: Nginx Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - -A lua bouncer for nginx. - -## How does it work ? - -This bouncer leverages nginx lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - Captcha remediation (can return a captcha) - - 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/). - - -## Installation - -### Dependencies - -Install the following packages: - -```bash -sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base lua-cjson -``` - -### Using packages - -First, [setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-nginx-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. -::: - -### Manual installation - -:::warning -CrowdSec NGINX Bouncer depends on `nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base`. - -It has been tested only on Debian/Ubuntu based distributions. -::: - -Download the latest release [here](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) - -```bash -tar xvzf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -./install.sh -``` -Note: Don't run the script with `sudo` (the script already use `sudo` to install dependencies). - -If you are on a mono-machine setup, the `crowdsec-nginx-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - libnginx-mod-http-lua : nginx lua support - - lua5.1: Lua - - lua-cjson: JSON parser/encoder for Lua - - luarocks : Lua package manager - - gettext-base: for the installation script - -
- - -## Upgrade - -### From package - -```bash -sudo apt-get update -sudo apt-get install crowdsec-nginx-bouncer -``` - -:::warning -Upgrade from v0 to v1 introduce many changes. Pick up the maintainer configuration to avoid anything breaking. Configuration migration might not be trivial. -::: - - -### Manual Upgrade - -If you already have `crowdsec-nginx-bouncer` installed, please download the [latest release](https://github.com/crowdsecurity/cs-nginx-bouncer/releases) and run the following commands: - -```bash -tar xzvf crowdsec-nginx-bouncer.tgz -cd crowdsec-nginx-bouncer-v*/ -sudo ./upgrade.sh -sudo systemctl restart nginx -``` - -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -#valid providers are recaptcha, hcaptcha, turnstile -CAPTCHA_PROVIDER= -# default is recaptcha to ensure backwards compatibility -# Captcha Secret Key -SECRET_KEY= -# Captcha Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - - -### NGINX Configuration - - -The bouncer NGINX configuration is located in `/etc/nginx/conf.d/crowdsec_nginx.conf` : - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -lua_package_path '/usr/lib/crowdsec/lua/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf", "crowdsec-nginx-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer will not work anymore. - -#### When using captcha remediation - -To make HTTP request in the bouncer, you need to configure a resolver and ssl certifcates. Here is a [our example](#resolver-and-certificates). - -To make secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, we have support for 3 providers: recaptcha, hcaptcha or turnstile - -If you want to use captcha with your Nginx Bouncer, you must provide a Site key and Secret key in your bouncer configuration. If you wish to use any other provider than recaptcha you must also provide a Captcha provider. - -([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -([tunstile documentation](https://developers.cloudflare.com/turnstile/)). - -([hcaptcha documentation](https://docs.hcaptcha.com/)) - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -CAPTCHA_PROVIDER= -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart Nginx. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to resolve the captcha provider you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/etc/nginx/conf.d/crowdsec_nginx.conf" -resolver 8.8.8.8 ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart Nginx. - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - - 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). - -### `REQUEST_TIMEOUT` -```bash -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). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - -### `CAPTCHA_PROVIDER` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_PROVIDER= -``` - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The captcha secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The captcha site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer 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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/openresty.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/openresty.mdx deleted file mode 100644 index 885f1194..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/openresty.mdx +++ /dev/null @@ -1,441 +0,0 @@ ---- -id: openresty -title: OpenResty Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

-

- - -

-

-📚 Documentation -💠 Hub -💬 Discourse -

- - - -A lua bouncer for OpenResty. - -## How does it work ? - -This bouncer leverages OpenResty lua's API, namely `access_by_lua_block` to check e IP address against the local API. - -Supported features: - - - Live mode (query the local API for each request) - - Stream mode (pull the local API for new/old decisions every X seconds) - - Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page) - - Captcha remediation (can return a captcha) - - 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/). - -:::warning -If you need to upgrade the bouncer from v0.X to v1.X, please follow [this migration process](#migrate-from-v0-to-v1) -::: - -## Installation - -:::caution Before installation -openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. -You can install openresty and openresty-opm from [openresty linux packages](https://openresty.org/en/linux-packages.html). -::: - -Install the following packages: - -```bash -sudo apt install openresty openresty-opm gettext-base -``` - -### Using packages - -[Setup crowdsec repositories](/getting_started/install.mdx#install-our-repositories). - - - - -```bash -sudo apt install crowdsec-openresty-bouncer -``` - - - - -```bash -sudo yum install crowdsec-openresty-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. -::: - -:::caution After installation - -[The openresty linux packages](https://openresty.org/en/linux-packages.html) doesn't include any `conf.d/` directory for custom configurations. -::: - -You need to add `include /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf; -` in nginx config file `/usr/local/openresty/nginx/conf/nginx.conf` in the **http** section. - -### Manual installation - -Download the latest release [here](https://github.com/crowdsecurity/cs-openresty-bouncer/releases) - -```bash -tar xvzf crowdsec-openresty-bouncer.tgz -cd crowdsec-openresty-bouncer-v*/ -sudo ./install.sh -``` - -If you are on a mono-machine setup, the `crowdsec-openresty-bouncer` install script will register directly to the local crowdsec, so you're good to go ! - -:warning: the installation script will take care of dependencies for Debian/Ubuntu - -
- non-debian based dependencies - - - openresty-opm : OpenResty Package Manager - - pintsized/lua-resty-http : lua lib managed by openresty-opm - -
- -## Configuration - -### Bouncer configuration - -```bash title="/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf" -API_URL= -API_KEY= -# bounce for all type of remediation that the bouncer can receive from the local API -BOUNCING_ON_TYPE=all -# when the bouncer receive an unknown remediation, fallback to this remediation -FALLBACK_REMEDIATION=ban -MODE=stream -REQUEST_TIMEOUT=1000 -# exclude the bouncing on those location -EXCLUDE_LOCATION= -# Cache expiration in live mode, in second -CACHE_EXPIRATION=1 -# Update frequency in stream mode, in second -UPDATE_FREQUENCY=10 -#those apply for "ban" action -# /!\ REDIRECT_LOCATION and BAN_TEMPLATE_PATH/RET_CODE can't be used together. REDIRECT_LOCATION take priority over RET_CODE AND BAN_TEMPLATE_PATH -BAN_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/ban.html -REDIRECT_LOCATION= -RET_CODE= -#those apply for "captcha" action -#valid providers are recaptcha, hcaptcha, turnstile -CAPTCHA_PROVIDER= -# default is recaptcha to ensure backwards compatibility -# Captcha Secret Key -SECRET_KEY= -# Captcha Site key -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -### OpenResty Configuration - -The bouncer OpenResty configuration is located in `/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf` : - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -lua_package_path '$prefix/../lualib/plugins/crowdsec/?.lua;;'; -lua_shared_dict crowdsec_cache 50m; -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -init_by_lua_block { - cs = require "crowdsec" - local ok, err = cs.init("/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf", "crowdsec-openresty-bouncer/v0.0.7") - if ok == nil then - ngx.log(ngx.ERR, "[Crowdsec] " .. err) - error() - end - ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done") -} - -access_by_lua_block { - local cs = require "crowdsec" - cs.Allow(ngx.var.remote_addr) -} -``` - - -The bouncer uses [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict) to share cache between all workers. - -If you want to increase the cache size you need to change this value `lua_shared_dict crowdsec_cache 50m;`. - -:warning: Do not rename the `crowdsec_cache` shared dict, else the bouncer 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 secure HTTP request in the bouncer, 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) - - /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) - - /etc/ssl/ca-bundle.pem (OpenSUSE) - - /etc/pki/tls/cacert.pem (OpenELEC) - - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) - - /etc/ssl/cert.pem (OpenBSD, Alpine) -``` - - -### Setup captcha -> Currently, we have support for 3 providers: recaptcha, hcaptcha or turnstile - -If you want to use captcha with your Nginx Bouncer, you must provide a Site key and Secret key in your bouncer configuration. If you wish to use any other provider than recaptcha you must also provide a Captcha provider. - -([recaptcha documentation](https://developers.google.com/recaptcha/intro)). - -([tunstile documentation](https://developers.cloudflare.com/turnstile/)). - -([hcaptcha documentation](https://docs.hcaptcha.com/)) - -Edit `etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf` and configure the following options: - -```bash -CAPTCHA_PROVDER= -SECRET_KEY= -SITE_KEY= -CAPTCHA_TEMPLATE_PATH=/var/lib/crowdsec/lua/templates/captcha.html -CAPTCHA_EXPIRATION=3600 -``` - -Restart OpenResty. - -You can add a decisions with a type `captcha` to check if it works correctly: - -```bash -sudo cscli decisions add -i -t captcha -``` - -## FAQ - -### 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. - -### Resolver and certificates - -In order to resolve the captcha provider you need to set a resolver and a SSL certificate in your nginx configuration. -If you already have a resolver set in nginx configuration, you don't need to add another one. -Here is a config example, but you can change values: - -```bash title="/usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf" -resolver local=on ipv6=off; -lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; -``` - -And restart OpenResty. - - -### Migrate from v0 to v1 - -The best way to migrate from the crowdsec-openresty-bouncer v0.* to v1 is to reinstall the bouncer. Indeed, many new configurations options are now available and some has been removed. - -- Backup your CrowdSec Local API key from your configuration file (`/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf`) -- Remove the old bouncer: - -```bash -sudo apt-get remove --purge crowdsec-openresty-bouncer -``` - -- Install the new bouncer: -```bash -sudo apt-get update -sudo apt-get install crowdsec-openresty-bouncer -``` - -- Configure the bouncer in `/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf` - - -## References - -### `API_KEY` -```bash -API_KEY= -``` - -CrowdSec Local API key. - -Generated with [`sudo cscli bouncers add`](../cscli/cscli_bouncers_add) command. - -### `API_URL` -```bash -API_URL=http://: -``` - -CrowdSec local API URL. - - -### `BOUNCING_ON_TYPE` -```bash -BOUNCING_ON_TYPE=all|ban|captcha -``` - -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. - -### `FALLBACK_REMEDIATION` -```bash -FALLBACK_REMEDIATION=ban -``` - -The fallback remediation is applied if the bouncer receives a decision with an unknown remediation. - -### `MODE` -```bash -MODE=stream|live -``` - -The default mode is `live`. - -The bouncer mode: - - stream: The bouncer will pull new/old decisions from the local API every X seconds (`UPDATE_FREQUENCY` parameter). - -Note: The timer that pull the local API will be triggered after the first request. - - 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). - -### `REQUEST_TIMEOUT` -```bash -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). - -### `EXCLUDE_LOCATION` -```bash -EXCLUDE_LOCATION=/,/ -``` - -The locations to exclude while bouncing. It is a list of location, separated by commas. - -:warning: It is not recommended to put `EXCLUDE_LOCATION=/`. - - -### `CACHE_EXPIRATION` -> This option is only for the `live` mode. - -```bash -CACHE_EXPIRATION=1 -``` - -The cache expiration, in second, for IPs that the bouncer store in cache in `live` mode. - -### `UPDATE_FREQUENCY` -> This option is only for the `stream` mode. - -```bash -UPDATE_FREQUENCY=10 -``` - -The frequency of update, in second, to pull new/old IPs from the CrowdSec local API. - - -### `REDIRECT_LOCATION` -> This option is only for the `ban` remediation. - -```bash -REDIRECT_LOCATION=/ -``` - -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). - -### `BAN_TEMPLATE_PATH` -> This option is only for the `ban` remediation. - -```bash -BAN_TEMPLATE_PATH= -``` - -The path to a HTML page to return to IPs that trigger `ban` remediation. - -By default, the HTML template is located in `/var/lib/crowdsec/lua/templates/ban.html`. - - -### `RET_CODE` -> This option is only for the `ban` remediation. - -```bash -RET_CODE=403 -``` - -The HTTP code to return for IPs that trigger a `ban` remediation. -If nothing specified, it will return a 403. - -### `CAPTCHA_PROVIDER` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_PROVIDER= -``` - -### `SECRET_KEY` -> This option is only for the `captcha` remediation. - -```bash -SECRET_KEY= -``` - -The captcha secret key. - - -### `SITE_KEY` -> This option is only for the `captcha` remediation. - -```bash -SITE_KEY= -``` - -The captcha site key. - - -### `CAPTCHA_TEMPLATE_PATH` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_TEMPLATE_PATH= -``` - -The path to a captcha HTML template. - -The bouncer 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`. - - -### `CAPTCHA_EXPIRATION` -> This option is only for the `captcha` remediation. - -```bash -CAPTCHA_EXPIRATION=3600 -``` - - -The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again. diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/php-lib.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/php-lib.mdx deleted file mode 100644 index 464f443b..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/php-lib.mdx +++ /dev/null @@ -1,432 +0,0 @@ ---- -id: php-lib -title: PHP Bouncer Library -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -This library allows you to create CrowdSec bouncers for PHP applications or frameworks like e-commerce, blog or other exposed applications. - -## Installation - -### Requirements - -- PHP >= 7.2.5 -- required PHP extensions: `ext-curl`, `ext-gd`, `ext-json`, `ext-mbstring` - -### Installation - -Use `Composer` by simply adding `crowdsec/bouncer` as a dependency: - -```shell -composer require crowdsec/bouncer -``` - -## Usage - -### Prerequisites - -To be able to use a bouncer based on this library, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost a CrowdSec agent must be installed on a server that is accessible by this library. - -### Features - -- CrowdSec Local API support - - Handle `ip`, `range` and `country` scoped decisions - - `Live mode` or `Stream mode` -- Support IpV4 and Ipv6 (Ipv6 range decisions are yet only supported in `Live mode`) -- Large PHP matrix compatibility: 7.2, 7.3, 7.4, 8.0, 8.1 and 8.2 -- Built-in support for the most known cache systems Redis, Memcached and PhpFiles - - Clear, prune and refresh the bouncer cache -- Cap remediation level (ex: for sensitives websites: ban will be capped to captcha) - -### Ban and captcha walls - -When a user is suspected by CrowdSec to be malevolent, a bouncer would either display a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he/she will access the page -as normal. - -A ban wall could look like: - -Ban wall - -A captcha wall could look like: - -Ban wall - -Please note that it is possible to customize all the colors of these pages so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users' language. - -## Create your own bouncer - -### Implementation - -You can use this library to develop your own PHP application bouncer. Any custom bouncer should extend the [`AbstractBouncer`](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/src/AbstractBouncer.php) class. - -```php -namespace MyNameSpace; - -use CrowdSecBouncer\AbstractBouncer; - -class MyCustomBouncer extends AbstractBouncer -{ -} -``` - -Then, you will have to implement all necessary methods : - -```php -namespace MyNameSpace; - -use CrowdSecBouncer\AbstractBouncer; - -class MyCustomBouncer extends AbstractBouncer -{ - /** - * Get current http method - */ - public function getHttpMethod(): string - { - // Your implementation - } - - /** - * Get value of an HTTP request header. Ex: "X-Forwarded-For" - */ - public function getHttpRequestHeader(string $name): ?string - { - // Your implementation - } - - /** - * Get the value of a posted field. - */ - public function getPostedVariable(string $name): ?string - { - // Your implementation - } - - /** - * Get the current IP, even if it's the IP of a proxy - */ - public function getRemoteIp(): string - { - // Your implementation - } - - /** - * Get current request uri - */ - public function getRequestUri(): string - { - // Your implementation - } - -} -``` - - -Once you have implemented these methods, you could retrieve all required configurations to instantiate your bouncer -and then call the `run` method to apply a bounce for the current detected IP. Please [see below](#configurations) for -the list of -available configurations. - -In order to instantiate the bouncer, you will have to create at least a `CrowdSec\RemediationEngine\LapiRemediation` -object too. - - -```php -use MyNameSpace\MyCustomBouncer; -use CrowdSec\RemediationEngine\LapiRemediation; -use CrowdSec\LapiClient\Bouncer as BouncerClient; -use CrowdSec\RemediationEngine\CacheStorage\PhpFiles; - -$configs = [...]; -$client = new BouncerClient($configs);// @see AbstractBouncer::handleClient method for a basic client creation -$cacheStorage = new PhpFiles($configs);// @see AbstractBouncer::handleCache method for a basic cache storage creation -$remediationEngine = new LapiRemediation($configs, $client, $cacheStorage); - -$bouncer = new MyCustomBouncer($configs, $remediationEngine); - -$bouncer->run(); -``` - - -### Test your bouncer - -To test your bouncer, you could add decision to ban your own IP for 5 minutes for example: - -```bash -cscli decisions add --ip --duration 5m --type ban -``` - -You can also test a captcha: - -```bash -cscli decisions delete --all # be careful with this command! -cscli decisions add --ip --duration 15m --type captcha -``` - - -To go further and learn how to include this library in your project, you should follow the [`DEVELOPER GUIDE`](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/DEVELOPER.md). - - -## Configurations - -The first parameter of the `AbstractBouncer` class constructor method is an array of settings. - -Below is the list of available settings: - -### Bouncer behavior - -- `bouncing_level`: Select from `bouncing_disabled`, `normal_bouncing` or `flex_bouncing`. Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This mode makes it possible to never ban an IP but only to offer a captcha, in the worst-case scenario. - - -- `fallback_remediation`: Select from `bypass` (minimum remediation), `captcha` or `ban` (maximum remediation). Default to 'captcha'. Handle unknown remediations as. - - -- `trust_ip_forward_array`: If you use a CDN, a reverse proxy or a load balancer, set an array of comparable IPs arrays: - (example: `[['001.002.003.004', '001.002.003.004'], ['005.006.007.008', '005.006.007.008']]` for CDNs with IPs `1.2.3.4` and `5.6.7.8`). For other IPs, the bouncer will not trust the X-Forwarded-For header. - - -- `excluded_uris`: array of URIs that will not be bounced. - - -- `stream_mode`: true to enable stream mode, false to enable the live mode. Default to false. By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -### Local API Connection - -- `auth_type`: Select from `api_key` and `tls`. Choose if you want to use an API-KEY or a TLS (pki) authentification. - TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. - - -- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add bouncer-php-library`. - Only required if you choose `api_key` as `auth_type`. - - -- `tls_cert_path`: absolute path to the bouncer certificate (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_key_path`: Absolute path to the bouncer key (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_verify_peer`: This option determines whether request handler verifies the authenticity of the peer's certificate. - Only required if you choose `tls` as `auth_type`. - When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. - If `tls_verify_peer` is set to true, request handler verifies whether the certificate is authentic. - This trust is based on a chain of digital signatures, - rooted in certification authority (CA) certificates you supply using the `tls_ca_cert_path` setting below. - - -- `tls_ca_cert_path`: Absolute path to the CA used to process peer verification. - Only required if you choose `tls` as `auth_type` and `tls_verify_peer` is set to true. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `api_url`: Define the URL to your Local API server, default to `http://localhost:8080`. - - -- `api_timeout`: In seconds. The timeout when calling Local API. Default to 120 sec. If set to a negative value, - timeout will be unlimited. - - -### Cache - - -- `fs_cache_path`: Will be used only if you choose PHP file cache as cache storage. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `redis_dsn`: Will be used only if you choose Redis cache as cache storage. - - -- `memcached_dsn`: Will be used only if you choose Memcached as cache storage. - - -- `clean_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5. - - -- `bad_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20. - - -- `captcha_cache_duration`: Set the duration we keep in cache the captcha flow variables for an IP. In seconds. - Defaults to 86400.. In seconds. Defaults to 20. - - -### Geolocation - -- `geolocation`: Settings for geolocation remediation (i.e. country based remediation). - - - `geolocation[enabled]`: true to enable remediation based on country. Default to false. - - - `geolocation[type]`: Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`. - - - `geolocation[cache_duration]`: This setting will be used to set the lifetime (in seconds) of a cached country - associated to an IP. The purpose is to avoid multiple call to the geolocation system (e.g. maxmind database). Default to 86400. Set 0 to disable caching. - - - `geolocation[maxmind]`: MaxMind settings. - - - `geolocation[maxmind][database_type]`: Select from `country` or `city`. Default to `country`. These are the two available MaxMind database types. - - - `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (e.g. mmdb file) - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -### Captcha and ban wall settings - - -- `hide_mentions`: true to hide CrowdSec mentions on ban and captcha walls. - - -- `custom_css`: Custom css directives for ban and captcha walls - - -- `color`: Array of settings for ban and captcha walls colors. - - - `color[text][primary]` - - - `color[text][secondary]` - - - `color[text][button]` - - - `color[text][error_message]` - - - `color[background][page]` - - - `color[background][container]` - - - `color[background][button]` - - - `color[background][button_hover]` - - -- `text`: Array of settings for ban and captcha walls texts. - - - `text[captcha_wall][tab_title]` - - - `text[captcha_wall][title]` - - - `text[captcha_wall][subtitle]` - - - `text[captcha_wall][refresh_image_link]` - - - `text[captcha_wall][captcha_placeholder]` - - - `text[captcha_wall][send_button]` - - - `text[captcha_wall][error_message]` - - - `text[captcha_wall][footer]` - - - `text[ban_wall][tab_title]` - - - `text[ban_wall][title]` - - - `text[ban_wall][subtitle]` - - - `text[ban_wall][footer]` - - -### Debug -- `debug_mode`: `true` to enable verbose debug log. Default to `false`. - - -- `disable_prod_log`: `true` to disable prod log. Default to `false`. - - -- `log_directory_path`: Absolute path to store log files. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `display_errors`: true to stop the process and display errors on browser if any. - - -- `forced_test_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used instead of the - real remote ip. - - -- `forced_test_forwarded_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used - instead of the real forwarded ip. If set to `no_forward`, the x-forwarded-for mechanism will not be used at all. - -### Security note - -Some files should not be publicly accessible because they may contain sensitive data: - -- Log files -- Cache files of the File system cache -- TLS authentication files -- Geolocation database files - -If you define publicly accessible folders in the settings, be sure to add rules to deny access to these files. - -In the following example, we will suppose that you use a folder `crowdsec` with sub-folders `logs`, `cache`, `tls` and `geolocation`. - -If you are using Nginx, you could use the following snippet to modify your website configuration file: - -```nginx -server { - ... - ... - ... - # Deny all attempts to access some folders of the crowdsec bouncer lib - location ~ /crowdsec/(logs|cache|tls|geolocation) { - deny all; - } - ... - ... -} -``` - -If you are using Apache, you could add this kind of directive in a `.htaccess` file: - -```htaccess -Redirectmatch 403 crowdsec/logs/ -Redirectmatch 403 crowdsec/cache/ -Redirectmatch 403 crowdsec/tls/ -Redirectmatch 403 crowdsec/geolocation/ -``` - -**N.B.:** -- There is no need to protect the `cache` folder if you are using Redis or Memcached cache systems. -- There is no need to protect the `logs` folder if you disable debug and prod logging. -- There is no need to protect the `tls` folder if you use Bouncer API key authentication type. -- There is no need to protect the `geolocation` folder if you don't use the geolocation feature. - - -## Other ready to use PHP bouncers - -To have a more concrete idea on how to develop a bouncer from this library, you may look at the following bouncers : -- [CrowdSec Bouncer extension for Magento 2](https://github.com/crowdsecurity/cs-magento-bouncer) -- [CrowdSec Bouncer plugin for WordPress ](https://github.com/crowdsecurity/cs-wordpress-bouncer) -- [CrowdSec Standalone Bouncer ](https://github.com/crowdsecurity/cs-standalone-php-bouncer) - - -## Technical notes - -See [Technical notes](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/TECHNICAL_NOTES.md) - - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/DEVELOPER.md) \ No newline at end of file diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/php.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/php.mdx deleted file mode 100644 index faf83bbb..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/php.mdx +++ /dev/null @@ -1,537 +0,0 @@ ---- -id: php -title: PHP Standalone Bouncer -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- - -## Overview - -This bouncer allows you to protect your PHP application from IPs that have been detected by CrowdSec. Depending on -the decision taken by CrowdSec, user will either get denied (403) or have to fill a captcha (401). - -It uses the [PHP `auto_prepend_file` mechanism](https://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file) and -the [Crowdsec php bouncer library](https://github.com/crowdsecurity/php-cs-bouncer) to offer bouncer/IPS capability directly in your PHP application. - -It supports "ban" and "captcha" remediations, and all decisions of type Ip, Range or Country (geolocation). - - -### Prerequisites - -- This is a PHP library, so you must have a working PHP (>= 7.2.5) installation. -- Requires PHP extensions : `ext-curl`, `ext-gd`, `ext-json`, `ext-mbstring`. -- Code sources are dealt with via `composer` and `git`. -- Have CrowdSec on the same machine, or at least be able to reach LAPI. - - -## Installation - -### Preparation - -#### Install composer - -Please follow [this documentation](https://getcomposer.org/download/) to install composer. - -#### Install GIT - -Please follow [this documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install GIT. - -#### Install CrowdSec - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost a CrowdSec agent must be installed on a server that is accessible by this bouncer. - -### Server and bouncer setup - -Once you set up your server as below, every browser access to a PHP script will be bounced by the standalone bouncer. - -You will have to : - -- retrieve sources of the bouncer in some `/path/to/the/crowdsec-standalone-bouncer` folder -- give the correct permission for the folder that contains the bouncer -- copy the `scripts/settings.php.dist` file to a `scripts/settings.php` file and edit it. -- set an `auto_prepend_file` directive in your PHP setup. -- Optionally, if you want to use the standalone bouncer in stream mode, you will have to set a cron task to refresh - cache periodically. - -#### Bouncer sources copy - -- Create a folder that will contain the project sources: - -```bash -sudo mkdir -p /var/www/crowdsec-standalone-bouncer -``` - -We use here `/var/www/crowdsec-standalone-bouncer` but you can choose the path that suits your needs. - -- Change permission to allow composer to be run in this folder. As you should run composer with your user, this - can be done with: - -```bash -sudo chown -R $(whoami):$(whoami) /var/www/crowdsec-standalone-bouncer -``` - -- Retrieve the last version of the bouncer: - -```bash -composer create-project crowdsec/standalone-bouncer /var/www/crowdsec-standalone-bouncer --keep-vcs -``` - -Note that we have to keep the vcs data as we will use it to update the bouncer when a new version is available. - -#### Files permission - -The owner of the `/var/www/crowdsec-standalone-bouncer` folder should be your web-server owner (e.g. `www-data`) and the group should have the write permission on this folder. - -You can achieve it by running commands like: - -```bash -sudo chown -R www-data /var/www/crowdsec-standalone-bouncer -sudo chmod g+w /var/www/crowdsec-standalone-bouncer -``` - -#### Settings file - -Please copy the `scripts/settings.php.dist` file to a `scripts/settings.php` file and fill the necessary settings in it -(see [Configurations settings](#configurations) for more details). - -For a quick start, simply search for `YOUR_BOUNCER_API_KEY` in the `settings.php` file and set the bouncer key. -To obtain a bouncer key, you can run the `cscli` bouncer creation command: - -``` -sudo cscli bouncers add standalone-bouncer -``` - -#### `auto_prepend_file` directive - -We will now describe how to set an `auto_prepend_file` directive in order to call the `scripts/bounce.php` for each php access. - -Adding an `auto_prepend_file` directive can be done in different ways: - -###### `.ini` file - -You should add this line to a `.ini` file : - - auto_prepend_file = /var/www/crowdsec-standalone-bouncer/scripts/bounce.php - -###### Nginx - -If you are using Nginx, you should modify your Nginx configuration file by adding a `fastcgi_param` directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/crowdsec-standalone-bouncer/scripts/bounce.php"; -} -``` - -###### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/var/www/crowdsec-standalone-bouncer/scripts/bounce.php" - -or modify your `Virtual Host` accordingly: - -``` - - ... - ... - php_value auto_prepend_file "/var/www/crowdsec-standalone-bouncer/scripts/bounce.php" - - -``` - -#### Stream mode cron task - -To use the stream mode, you first have to set the `stream_mode` setting value to `true` in your `script/settings.php` file. - -Then, you could edit the web server user (e.g. `www-data`) crontab: - -```shell -sudo -u www-data crontab -e -``` - -and add the following line - -```shell -*/15 * * * * /usr/bin/php /var/www/crowdsec-standalone-bouncer/scripts/refresh-cache.php -``` - -In this example, cache is refreshed every 15 minutes, but you can modify the cron expression depending on your needs. - -#### Cache pruning cron task - -If you use the PHP file system as cache, you should prune the cache with a cron job: - -```shell -sudo -u www-data crontab -e -``` - -and add the following line - -```shell -0 0 * * * /usr/bin/php /var/www/crowdsec-standalone-bouncer/scripts/prune-cache.php -``` - -In this example, cache is pruned at midnight every day, but you can modify the cron expression depending on your needs. - - - -## Upgrade - -When a new release of the bouncer is available, you may want to update sources to the last version. - -### Before upgrading - -**Please look at the [CHANGELOG](https://github.com/crowdsecurity/cs-standalone-php-bouncer/blob/main/CHANGELOG.md) before upgrading in order to see the list of changes that could break your application.** - -To limit the risk of breaking your web application during upgrade, you can perform the following actions to disable bouncing: - -- Remove the `auto_prepend_file` directive that point to the `bounce.php` file and restart your web server -- Disable any scheduled cron task linked to bouncer feature - -Alternatively, but a little more risky, you could disable bouncing by editing the `scripts/settings.php` file and set the value `'bouncing_disabled'` for the `'bouncing_level'` parameter. - -Once the update is done, you can reactivate the bounce. You could look at the `/var/www/crowdsec-standalone-bouncer/scripts/.logs` to see if all is working as expected. - -Below are the steps to take to upgrade your current bouncer: - -### Retrieve the last tag - -As we kept the vcs data during installation (with the `--keep-vcs` flag), we can use git to get the last tagged sources: - -```bash -cd /var/www/crowdsec-standalone-bouncer -git fetch -``` - -If you get an error message about "detected dubious ownership", you can run - -```bash -git config --global --add safe.directory /var/www/crowdsec-standalone-bouncer -``` - -You should see a list of tags (`vX.Y.Z` format )that have been published after your initial installation. - -### Checkout to last tag and update sources - -Once you have picked up the `vX.Y.Z` tag you want to try, you could switch to it and update composer dependencies: - -```bash -git checkout vX.Y.Z && composer update -``` - - -## Usage - -### Features - -- CrowdSec Local API Support - - Handle `ip`, `range` and `country` scoped decisions - - `Live mode` or `Stream mode` -- Support IpV4 and Ipv6 (Ipv6 range decisions are yet only supported in `Live mode`) -- Large PHP matrix compatibility: 7.2, 7.3, 7.4, 8.0, 8.1 and 8.2 -- Built-in support for the most known cache systems Redis, Memcached and PhpFiles - - Clear, prune and refresh the bouncer cache -- Cap remediation level (ex: for sensitives websites: ban will be capped to captcha) - -### Ban and captcha walls - -When a user is suspected by CrowdSec to be malevolent, the bouncer would either display a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he/she will access the page -as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users' language. - -### Configurations - -Here is the list of available settings that you could define in the `scripts/settings.php` file: - -#### Bouncer behavior - -- `bouncing_level`: Select from `bouncing_disabled`, `normal_bouncing` or `flex_bouncing`. Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This mode makes it possible to never ban an IP but only to offer a captcha, in the worst-case scenario. - - -- `fallback_remediation`: Select from `bypass` (minimum remediation), `captcha` or `ban` (maximum remediation). Default to 'captcha'. Handle unknown remediations as. - - -- `trust_ip_forward_array`: If you use a CDN, a reverse proxy or a load balancer, set an array of IPs. For other IPs, the bouncer will not trust the X-Forwarded-For header. - - -- `excluded_uris`: array of URIs that will not be bounced. - - -- `stream_mode`: true to enable stream mode, false to enable the live mode. Default to false. By default, the `live mode` is enabled. The first time a user connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -#### Local API Connection - -- `auth_type`: Select from `api_key` and `tls`. Choose if you want to use an API-KEY or a TLS (pki) authentification. - TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. - - -- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add standlone-php-bouncer`. - Only required if you choose `api_key` as `auth_type`. - - -- `tls_cert_path`: absolute path to the bouncer certificate (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_key_path`: Absolute path to the bouncer key (e.g. pem file). - Only required if you choose `tls` as `auth_type`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `tls_verify_peer`: This option determines whether request handler verifies the authenticity of the peer's certificate. - Only required if you choose `tls` as `auth_type`. - When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. - If `tls_verify_peer` is set to true, request handler verifies whether the certificate is authentic. - This trust is based on a chain of digital signatures, - rooted in certification authority (CA) certificates you supply using the `tls_ca_cert_path` setting below. - - -- `tls_ca_cert_path`: Absolute path to the CA used to process peer verification. - Only required if you choose `tls` as `auth_type` and `tls_verify_peer` is set to true. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `api_url`: Define the URL to your Local API server, default to `http://localhost:8080`. - - -- `api_timeout`: In seconds. The timeout when calling Local API. Default to 120 sec. If set to a negative value, - timeout will be unlimited. - - -- `use_curl`: By default, this lib call the REST Local API using `file_get_contents` method (`allow_url_fopen` is required). - You can set `use_curl` to `true` in order to use `cURL` request instead (`ext-curl` is in then required) - -#### Cache - -- `cache_system`: Select from `phpfs` (PHP file cache), `redis` or `memcached`. - - -- `fs_cache_path`: Will be used only if you choose PHP file cache as `cache_system`. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `redis_dsn`: Will be used only if you choose Redis cache as `cache_system`. - - -- `memcached_dsn`: Will be used only if you choose Memcached as `cache_system`. - - -- `clean_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5. - - -- `bad_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20. - - -- `captcha_cache_duration`: Set the duration we keep in cache the captcha flow variables for an IP. In seconds. - Defaults to 86400.. In seconds. Defaults to 20. - - -#### Geolocation - -- `geolocation`: Settings for geolocation remediation (i.e. country based remediation). - - - `geolocation[enabled]`: true to enable remediation based on country. Default to false. - - - `geolocation[type]`: Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`. - - - `geolocation[cache_duration]`: This setting will be used to set the lifetime (in seconds) of a cached country - associated to an IP. The purpose is to avoid multiple call to the geolocation system (e.g. maxmind database). Default to 86400. Set 0 to disable caching. - - - `geolocation[maxmind]`: MaxMind settings. - - - `geolocation[maxmind][database_type]`: Select from `country` or `city`. Default to `country`. These are the two available MaxMind database types. - - - `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (e.g. mmdb file) - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -#### Captcha and ban wall settings - - -- `hide_mentions`: true to hide CrowdSec mentions on ban and captcha walls. - - -- `custom_css`: Custom css directives for ban and captcha walls - - -- `color`: Array of settings for ban and captcha walls colors. - - - `color[text][primary]` - - - `color[text][secondary]` - - - `color[text][button]` - - - `color[text][error_message]` - - - `color[background][page]` - - - `color[background][container]` - - - `color[background][button]` - - - `color[background][button_hover]` - - -- `text`: Array of settings for ban and captcha walls texts. - - - `text[captcha_wall][tab_title]` - - - `text[captcha_wall][title]` - - - `text[captcha_wall][subtitle]` - - - `text[captcha_wall][refresh_image_link]` - - - `text[captcha_wall][captcha_placeholder]` - - - `text[captcha_wall][send_button]` - - - `text[captcha_wall][error_message]` - - - `text[captcha_wall][footer]` - - - `text[ban_wall][tab_title]` - - - `text[ban_wall][title]` - - - `text[ban_wall][subtitle]` - - - `text[ban_wall][footer]` - - -#### Debug -- `debug_mode`: `true` to enable verbose debug log. Default to `false`. - - -- `disable_prod_log`: `true` to disable prod log. Default to `false`. - - -- `log_directory_path`: Absolute path to store log files. - **Make sure this path is not publicly accessible.** [See security note below](#security-note). - - -- `display_errors`: true to stop the process and display errors on browser if any. - - -- `forced_test_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used instead of the - real remote ip. - - -- `forced_test_forwarded_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used - instead of the real forwarded ip. If set to `no_forward`, the x-forwarded-for mechanism will not be used at all. - -#### Security note - -Some files should not be publicly accessible because they may contain sensitive data: - -- Log files -- Cache files of the File system cache -- TLS authentication files -- Geolocation database files - -If you define publicly accessible folders in the settings, be sure to add rules to deny access to these files. - -In the following example, we will suppose that you use a folder `crowdsec` with sub-folders `logs`, `cache`, `tls` and `geolocation`. - -If you are using Nginx, you could use the following snippet to modify your website configuration file: - -```nginx -server { - ... - ... - ... - # Deny all attempts to access some folders of the crowdsec standalone bouncer - location ~ /crowdsec/(logs|cache|tls|geolocation) { - deny all; - } - ... - ... -} -``` - -If you are using Apache, you could add this kind of directive in a `.htaccess` file: - -```htaccess -Redirectmatch 403 crowdsec/logs/ -Redirectmatch 403 crowdsec/cache/ -Redirectmatch 403 crowdsec/tls/ -Redirectmatch 403 crowdsec/geolocation/ -``` - -**N.B.:** -- There is no need to protect the `cache` folder if you are using Redis or Memcached cache systems. -- There is no need to protect the `logs` folder if you disable debug and prod logging. -- There is no need to protect the `tls` folder if you use Bouncer API key authentication type. -- There is no need to protect the `geolocation` folder if you don't use the geolocation feature. - -## Testing & Troubleshooting - -### Logs - -Enable `debug_mode` in the (`scripts/settings.php`) file to enable debug logging. By default, logs will be -located in the scripts path, i.e. `/var/www/crowdsec-standalone-bouncer/scripts/.logs`. - -### Testing ban remediation - -To test the ban remediation : -- identify or create simple php file (even a `` would do) -- add a decision on your crowdsec agent (`sudo cscli decisions add -i `) -- try to access the php file, and you should see the HTML forbidden ban page - - -### Testing the captcha feature - -To test the captcha remediation : -- identify or create simple php file (even a `` would do) -- add a decision on your crowdsec agent (`cscli decisions add -i -t captcha`) -- try to access the php file, and you should see the captcha page - - - -### Testing geolocation remediation - -The bouncer is expecting decisions with a scope of `Country`, and 2-letters code value. - -To test the geolocation remediation : -- identify or create simple php file (even a `` would do) -- add a decision on your crowdsec agent (`cscli decisions add --scope Country --value FR -t captcha`) -- try to access the php file, and you should see the captcha page - - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-standalone-php-bouncer/blob/main/doc/DEVELOPER.md) diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/windows-firewall.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/windows-firewall.mdx deleted file mode 100644 index 013ce9ec..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/windows-firewall.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -id: windows_firewall -title: Windows Firewall Bouncer ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- -

-📚 Documentation -💠 Hub -💬 Discourse -

- -## Overview - -The Windows firewall bouncer interacts with the Windows Firewall to block IPs banned by CrowdSec. - -It will create multiple rules in the firewall (one rule will contain 1000 IPs) and will manage their lifecycle. - -The rules are created on startup and automatically deleted when the bouncer stops. - -## Installation - -:::warning - -The .NET 6 runtime is required for the bouncer to work ! - -::: - -You can download either a MSI (containing only the bouncer) or a setup bundle (containing the bouncer and the .NET 6 runtime) from the github releases: https://github.com/crowdsecurity/cs-windows-firewall-bouncer/releases - -You can also install the bouncer with [Chocolatey](https://chocolatey.org/) (this will automatically install the .NET runtime): - -```powershell -choco install crowdsec-windows-firewall-bouncer -``` - -## Configuration - -The configuration is stored in `C:\Program Files\CrowdSec\bouncers\cs-windows-firewall-bouncer\cs-windows-firewall-bouncer.yaml` - -### Example configuration - -```yaml -api_key: -api_url: http://127.0.0.1:8080 -log_level: info -update_frequency: 10s -log_media: file -log_dir: C:\ProgramData\CrowdSec\log\ -fw_profiles: - - domain -``` - ---- - -#### `api_key` - -API key to use for communication with LAPI. - -#### `api_url` - -URL of LAPI. - -#### `update_frequency` - -How often the bouncer will contact LAPI to update its content in seconds. - -Defaults to `10`. - -#### `log_media` - -Wether to log to file or to the console. - -Defaults to file when running as service and console when running in interactive mode. - -#### `log_dir` - -Location of the log file. - -Defaults to `C:\ProgramData\CrowdSec\log\`. - -#### `log_level` - -Log level. - -Can be one of: - - `trace` - - `debug` - - `info` - - `warn` - - `error` - - `fatal` - -Defaults to `info`. - -#### fw_profiles - -The firewall profile the rules will be associated with. - -The bouncer automatically select the current profile, but you can override this behaviour with this parameter. - -Allowed values are: - - `domain` - - `private` - - `public` - - - diff --git a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/wordpress.mdx deleted file mode 100644 index 3effbb40..00000000 --- a/crowdsec-docs/versioned_docs/version-v1.5.0/bouncers/wordpress.mdx +++ /dev/null @@ -1,496 +0,0 @@ ---- -id: wordpress -title: WordPress Bouncer ---- - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -

-CrowdSec -

- - -## Usage - -### Description - -The `CrowdSec Bouncer` plugin for WordPress has been designed to protect WordPress websites from all kinds of -attacks by using [CrowdSec](https://crowdsec.net/) technology. - -### Prerequisites - -To be able to use this bouncer, the first step is to install [CrowdSec v1](https://doc.crowdsec.net/docs/getting_started/install_crowdsec/). -CrowdSec is only in charge of the "detection", and won't block anything on its own. You need to deploy a bouncer to "apply" decisions. - -Please note that first and foremost CrowdSec must be installed on a server that is accessible via the WordPress site. - - -### Features - -When a user is suspected by CrowdSec to be malevolent, this bouncer will either send him/her a captcha to resolve or -simply a page notifying that access is denied. If the user is considered as a clean user, he will access the page as normal. - -By default, the ban wall is displayed as below: - -Ban wall - -By default, the captcha wall is displayed as below: - -Captcha wall - -Please note that it is possible to customize all the colors of these pages in a few clicks so that they integrate best with your design. - -On the other hand, all texts are also fully customizable. This will allow you, for example, to present translated pages in your users’ language. - - -### Configurations - -This plugin comes with configurations that you will find under `CrowdSec` admin section. - -These configurations are divided in three main parts : `CrowdSec`, `Theme customization` and `Advanced`. - -#### General settings - -In the `CrowdSec` part, you will set your connection details and refine bouncing according to your needs. You will -also be able to test your settings. - -*** - -Connection details - -*** - -`Connection details → Local API URL` - -Url to join your CrowdSec Local API. - -If the CrowdSec Agent is installed on this server, you could set this field to `http://localhost:8080`. - -*** - -`Connection details → Authentication type` - -Choose between `Bouncer API key` and `TLS certificates` (pki) authentication. - -TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0. -Please see [CrowdSec documentation](https://docs.crowdsec.net/docs/local_api/tls_auth/). - -*** - -`Connection details → Bouncer API key` - -Key generated by the cscli command. - -Only if you chose `Bouncer API key` as authentication type. - -*** - -`Connection details → Path to the bouncer certificate` - -Relative path to the `wp-content/plugins/crowdsec/tls` folder of your WordPress instance. - -Example: `bouncer.pem`. - -Only if you chose `TLS certificates` as authentication type. - -*** - -`Connection details → Path to the bouncer key` - -Relative path to the `wp-content/plugins/crowdsec/tls` folder of your WordPress instance. - -Example: `bouncer-key.pem`. - -Only if you chose `TLS certificates` as authentication type. - -*** - -`Connection details → Verify peer` - -This option determines whether request handler verifies the authenticity of the peer's certificate. - -Only if you chose `TLS certificates` as authentication type. - -When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. -If `Verify peer` is checked, request handler verifies whether the certificate is authentic. -This trust is based on a chain of digital signatures, -rooted in certification authority (CA) certificate you supply using the `Path to the CA used to process for peer -verification` setting below. - -*** - -`Connection details → Path to the CA certificate used to process peer verification` - -Relative path to the `wp-content/plugins/crowdsec/tls` folder of your WordPress instance. - -Example: `ca-chain.pem`. - -Only if you chose `TLS certificates` as authentication type. - - -*** - -`Connection details → Use cURL to call Local API` - -By default, `file_get_contents` method is used to call Local API. This method requires to have enabled the option -`allow_url_fopen`. -Here, you can choose to use `cURL` requests instead. Beware that in this case, you need to have php `cURL` extension -installed and enabled on your system. - -Bouncing - -*** - -`Bouncing → Bouncing level` - -Choose if you want to apply CrowdSec directives (`Normal bouncing`) or be more permissive (`Flex bouncing`). - -With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This -mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario. - -*** - -`Bouncing → Public website only` - -If enabled, the admin is not bounced. - -*** - -Test your settings - -`Test your settings → Test bouncing` - -Click the "Test bouncing" button and the configured bouncer will try to get the remediation (bypass, captcha or ban) -for -the IP entered in the text field. By default, tested IP is the current detected remote IP. - -This test allows you to know if your connection, bouncing and cache settings are correct. - - -*** - -`Test your settings → Test geolocation` - -Click the "Test geolocation" button to try getting country for the IP entered in the text field. - -This test allows you to know if your geolocation settings are correct. - - -#### Theme customization - -In the `Theme customization` part, you can modify texts and colors of ban and captcha walls. - -Captcha wall customization - -Ban wall customization - -Wall CSS - - -#### Advanced settings - -In the `Advanced` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec -Local API, handle your remediation policy, manage geolocation feature, adjust some debug parameters and testing parameters. - -Communication mode - - -*** - -`Communication mode to the API → Enable the "Stream mode"` - -Choose if you want to enable the `stream mode` or stay in `live mode`. - - -By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. - -But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance. - -*** - -`Communication mode to the API → Resync decisions each (stream mode only)` - -With the stream mode, every decision is retrieved in an asynchronous way. Here you can define the frequency of this -cache refresh. - -**N.B** : There is also a refresh button if you want to refresh the cache manually. - -*** - -Cache - -*** - -`Caching configuration → Technology` - -Choose the cache technology that will use your CrowdSec Local API. - -The File system cache is faster than calling Local API. Redis or Memcached is faster than the File System cache. - -**N.B** : There are also a `Clear now` button fo all cache technologies and a `Prune now` button dedicated to the -file system cache. - -*** - -`Caching configuration → Recheck clean IPs each (live mode only)` - -The duration between re-asking Local API about an already checked clean IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - -*** - -`Caching configuration → Recheck bad IPs each (live mode only)` - -The duration between re-asking Local API about an already checked bad IP. - -Minimum 1 second. Note that this setting can not be apply in stream mode. - - -*** - -`Caching configuration → Captcha flow cache lifetime` - -The lifetime of cached captcha flow for some IP. - -If a user has to interact with a captcha wall, -we store in cache some values in order to know if he has to resolve or not the captcha again. - -Minimum 1 second. Default: 86400 seconds. - -*** - -`Caching configuration → Geolocation cache lifetime` - -The lifetime of cached country geolocation result for some IP. - -Minimum 1 second. Default: 86400 seconds. - - -*** - - -Remediations - -*** - -`Remediations → Fallback to` - -Choose which remediation to apply when CrowdSec advises unhandled remediation. - -*** - -`Remediations → Trust these CDN IPs (or Load Balancer, HTTP Proxy)` - -If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate in the bouncer settings the IP ranges of these devices in order to be able to check the IP of your users. For other IPs, the bouncer will not trust the X-Forwarded-For header. -*** - -`Remediations → Hide CrowdSec mentions` - -Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls. -*** - -Geolocation - -*** - -`Geolocation → Enable geolocation feature` - -Enable if you want to use also CrowdSec country scoped decisions. -If enabled, bounced IP will be geolocalized and the final remediation will take into account any country related decision. - -*** - -`Geolocation → Geolocation type` - - -For now, only `Maxmind database` type is allowed - -*** - -`Geolocation → MaxMind database type` - -Choose between `Country` and `City`. - - -*** - -`Geolocation → Path to the MaxMind database` - -Relative path from `wp-content/plugins/crowdsec/geolocation` folder. - -*** - -`Geolocation → Save geolocalized country in cache` - -Enabling this will avoid multiple call to the geolocation system (e.g. MaxMind database) -If enabled, the geolocalized country associated to the IP will be saved in cache. -See the `Geolocation cache lifetime` setting above to set the lifetime of this result. -*** - -Debug - -*** - -`Debug mode → Enable debug mode` - -Enable if you want to see some debug information in a specific log file. - -*** - -`Debug mode → Disable prod log` - -By default, a `prod.log` file will be written in `wp-content/plugins/crowdsec/logs` folder. - -You can disable this log here. - -*** - -`Display errors → Enable errors display` - -When this mode is enabled, you will see every unexpected bouncing errors in the browser. -Should be disabled in production. - -*** - -Test - -*** - -`Test settings → Forced test IP` - -This Ip will be used instead of the current detected browser IP. -**Must be empty in production.** - -*** - -`Test settings → Forced test X-Forwarded-For IP` - -This Ip will be used instead of the current X-Forwarded-For Ip if any. -**Must be empty in production.** - - -### Auto Prepend File mode - -By default, this extension will bounce every web requests that pass through the classical process of WordPress core loading. -This implies that if another php public script is called (any of your custom public php script for example) -or if you are using some plugin that bypass the WordPress core load process -(as the [WP Super Cache plugin](https://wordpress.org/plugins/wp-super-cache/) in Simple mode for example), bouncing will not be effective. - -To ensure that any php script will be bounced if called from a browser, you should try the `auto prepend file` mode. - -In this mode, every browser access to a php script will be bounced. - -To enable the `auto prepend file` mode, you have to configure your server by adding an `auto_prepend_file` directive -for your php setup. - -**N.B:** -- In this mode, a setting file `inc/standalone-settings.php` will be generated each time you save the - CrowdSec plugin configuration from the WordPress admin. - - -Adding an `auto_prepend_file` directive can be done in different ways: - -#### PHP - -You should add this line to a `.ini` file : - - auto_prepend_file = /wordpress-root-directory/wp-content/plugins/crowdsec/inc/standalone-bounce.php - - -#### Nginx - - -If you are using Nginx, you should modify your Magento 2 nginx configuration file by adding a `fastcgi_param` -directive. The php block should look like below: - -``` -location ~ \.php$ { - ... - ... - ... - fastcgi_param PHP_VALUE "/wordpress-root-directory/wp-content/plugins/crowdsec/inc/standalone-bounce.php"; -} -``` - -#### Apache - -If you are using Apache, you should add this line to your `.htaccess` file: - - php_value auto_prepend_file "/wordpress-root-directory/wp-content/plugins/crowdsec/inc/standalone-bounce.php" - - - -### Resources - -Feel free to look at the [associated article](https://crowdsec.net/wordpress-bouncer/) for more configuration options and tweaks. - - -## Installation - - -### Add the plugin - -The bouncer itself can be installed from the marketplace in WordPress back-office. - -Installing the CrowdSec WordPress plugin is as easy as installing any other WordPress plugin: - -- Click `Plugins` in the left navigation on your site’s dashboard. -- Type `CrowdSec` in the text field to the right. Hit enter. -- In the CrowdSec plugin click `Install Now` -- Once installed click `Activate`. - - -### WordPress Marketplace - -You can find this plugin on the [WordPress Plugins Marketplace](https://wordpress.org/plugins/crowdsec/). - - -## Technical notes - -We explain here each important technical decision used to design this -plugin. - - -### How to use system CRON instead of wp-cron? - -Add `define('DISABLE_WP_CRON', true);` in `wp-config.php` then enter this command line on the WordPress host command -line: - -```bash -(crontab -l && echo "* * * * * wget -q -O - http://:/wp-cron.php?doing_wp_cron >/dev/null 2>&1") | crontab - -``` - -> Note: replace `` with the local url of your website - -More info [here](https://developer.wordpress.org/plugins/cron/hooking-wp-cron-into-the-system-task-scheduler/). - -## Developer guide - -See [Developer guide](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/docs/DEVELOPER.md) - -## License - -[MIT](https://github.com/crowdsecurity/cs-wordpress-bouncer/blob/main/LICENSE) - - - - - - - - - - - - - - -