Cloudflare

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

warning

Currently use of this bouncer is discouraged if you are on free plan with Cloudflare due to rate limitations. We are working to resolve this with Cloudflare support.

If you are on a premium plan with Cloudflare contact thier support to ask about increasing your rate limit.

Installation

Using packages

Packages for crowdsec-cloudflare-bouncer are available on our repositories. You need to pick the package accord to your firewall system :

Debian/Ubuntu
RHEL/Centos/Fedora

sudo apt install crowdsec-cloudflare-bouncer

sudo yum install crowdsec-cloudflare-bouncer

Then run the following commands to setup your bouncer:

sudo crowdsec-cloudflare-bouncer -g <CLOUDFLARE_TOKEN1>,<CLOUDFLARE_TOKEN2> -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

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 <CLOUDFLARE_TOKEN1>,<CLOUDFLARE_TOKEN2> -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.

tar xzvf crowdsec-cloudflare-bouncer.tgz
cd crowdsec-cloudflare-bouncer/
sudo ./install.sh
sudo crowdsec-cloudflare-bouncer -g <CLOUDFLARE_TOKEN1>,<CLOUDFLARE_TOKEN2> -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

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

docker run crowdsecurity/cloudflare-bouncer \
 -g <CLOUDFLARE_TOKEN1>,<CLOUDFLARE_TOKEN2> > 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:

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

  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

# 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 <TOKEN_1>,<TOKEN_2> )

After upgrading the bouncer from v0.0.X to v0.1.Y , run the following commands to migrate to managed_challenge.

sudo crowdsec-cloudflare-bouncer -d
sudo crowdsec-cloudflare-bouncer -g <TOKEN_1>,<TOKEN_2> -o <path_to_config_file>
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:

Sign in as a user who has access to the desired account.
Go to Tokens and create the token. The bouncer requires the follwing permissions to function.

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:

sudo crowdsec-cloudflare-bouncer -g <TOKEN_1>,<TOKEN_2>...  -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:

sudo crowdsec-cloudflare-bouncer -c ./cfg.yaml -g <TOKEN_1>,<TOKEN_2>... 

Cloudflare Setup

This only creates the required IP lists and firewall rules at cloudflare and exits.

Example Usage:

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:

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.

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

Installation​

Using packages​

Manual Installation​

Assisted​

From source​

Using Docker​

Initial Setup​

Run the bouncer​

Configuration​

Making changes to configuration​

Upgrading from v0.0.X to v0.1.Y​

Cloudflare Configuration​

Helpers​

Auto config generator​

Cloudflare Setup​

Cloudflare Cleanup​

How it works​

Configuration Reference​

crowdsec_lapi_url​

crowdsec_lapi_key​

crowdsec_update_frequency​

include_scenarios_containing​

exclude_scenarios_containing​

only_include_decisions_from​

cloudflare_config​

update_frequency​

accounts​

id​

token​

ip_list_prefix​

total_ip_list_capacity​

default_action​

zones​

zone_id​

actions​

daemon​

log_mode​

log_dir​

log_level​

log_max_size, log_max_age, log_max_backups, compress_logs​

Troubleshooting​

Installation

Using packages

Manual Installation

Assisted

From source

Using Docker

Initial Setup

Run the bouncer

Configuration

Making changes to configuration

Upgrading from v0.0.X to v0.1.Y

Cloudflare Configuration

Helpers

Auto config generator

Cloudflare Setup

Cloudflare Cleanup

How it works

Configuration Reference

`crowdsec_lapi_url`

`crowdsec_lapi_key`

`crowdsec_update_frequency`

`include_scenarios_containing`

`exclude_scenarios_containing`

`only_include_decisions_from`

`cloudflare_config`

`update_frequency`

`accounts`

`id`

`token`

`ip_list_prefix`

`total_ip_list_capacity`

`default_action`

`zones`

`zone_id`

`actions`

`daemon`

`log_mode`

`log_dir`

`log_level`

`log_max_size`, `log_max_age`, `log_max_backups`, `compress_logs`

Troubleshooting