Skip to main content

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 :

sudo apt 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:

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

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 TypeDefault Action
captchamanaged_challenge
banblock
js_challengejs_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 TypeZone Action
captchamanaged_challenge
banblock
js_challengejs_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