By Muhammad Dava Pasha — 15 May 2025

CrowdSec Remediation Components: Installation Guides and Configuration Reference for Linux, Firewalls, Apache, AWS WAF, Blocklist Mirror, Cloudflare, and Custom Bouncers

Securing your systems from malicious actors requires a robust and adaptable defense mechanism. CrowdSec, with its collaborative and community-driven approach, offers a powerful intrusion prevention system. A core part of CrowdSec's architecture are its Remediation Components (formerly known as "Bouncers"). These components act as the enforcers of CrowdSec's decisions, translating threat intelligence into real-world actions.

This comprehensive guide provides detailed installation instructions and configuration references for various CrowdSec Remediation Components, enabling you to deploy the right defenses for your specific environment.

Supported Remediation Components

This article covers the following Remediation Components:

Linux Firewall Bouncer (iptables, nftables, ipset, pf): Integrates with your system's firewall to block malicious IP addresses.
Apache Bouncer: Protects your Apache web server by denying access to identified threats.
AWS WAF Bouncer: Leverages AWS Web Application Firewall (WAF) to mitigate threats targeting your AWS resources.
Blocklist Mirror: Exposes CrowdSec decisions as a readily consumable blocklist for network devices and other security tools.
Cloudflare Worker Bouncer: Deploys a Cloudflare Worker to protect your website by blocking malicious traffic at the edge.
Cloudflare Bouncer (Deprecated): Legacy component. Use the Cloudflare Worker Bouncer instead.
Custom Bouncer: Provides a flexible framework to integrate CrowdSec decisions with any system via custom scripts.

Prerequisites

Before installing any Remediation Component, ensure you have CrowdSec installed and configured. It's also important to have a general understanding of how CrowdSec operates and the concepts of detections, scenarios, and decisions. See prerequisites documentation for more details.

Installation and Configuration Guides

Each of the following sections provides a step-by-step guide to installing and configuring a specific Remediation Component.

1. Linux Firewall Bouncer

This Remediation Component integrates CrowdSec with your Linux system's firewall, allowing you to block malicious IP addresses identified by CrowdSec. It supports iptables, nftables, ipset (as a backend), and pf.

Repository Installation

The recommended way to install the Linux Firewall Bouncer is through the CrowdSec repository.

curl -s https://install.crowdsec.net | sudo sh

Installation

Install the appropriate package based on your firewall system:

iptables: sudo apt install crowdsec-firewall-bouncer-iptables (Debian/Ubuntu) or sudo yum install crowdsec-firewall-bouncer-iptables (RHEL/CentOS/Fedora)
nftables: sudo apt install crowdsec-firewall-bouncer-nftables (Debian/Ubuntu) or sudo yum install crowdsec-firewall-bouncer-nftables (RHEL/CentOS/Fedora)

:::info
To determine if your system uses iptables or nftables, run iptables -V. If the output mentions 'nt_tables', you are using nftables.
:::

pf (FreeBSD)

Install crowdsec-firewall-bouncer using package manager :

sudo pkg install crowdsec-firewall-bouncer

Configuration

The Linux Firewall Bouncer supports two primary modes:

Managed (default): The bouncer creates and manages ipset/nft sets, inserts firewall rules, and manages the set contents.
Set Only: The bouncer only manages the content of existing, user-defined sets. You must create the sets and associated firewall rules manually.

The default configuration file is located at /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.

Important configuration parameters:

mode: Set to iptables, nftables, ipset, or pf depending on your preferred firewall backend.
update_frequency: How often the bouncer checks for new/deleted decisions.
iptables_chains (iptables mode): List of chains where rules should be inserted.
blacklists_ipv4 and blacklists_ipv6 (ipset mode): Names of the IPv4 and IPv6 sets to manage.
nftables.ipv4.table, nftables.ipv4.chain, etc. (nftables mode): Define table and chain names.
deny_action: Action to take for blocked packets (DROP or REJECT).

Metrics

The Linux Firewall Bouncer exposes metrics via cscli metrics show bouncers. These metrics provide insights into blocked traffic and the sources of decisions.

Origin: Source of blocked IPs (e.g., CAPI, crowdsec (security engine)).
active_decisions IPs: Number of IPs currently blocked.
dropped bytes & packets: Number of bytes and packets dropped.
processed bytes & packets (Total line only): Total processed traffic.

Example for pf configuration

In /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml

mode: pf
  api_url: http://127.0.0.1:8080/
  api_key: <GENERATED-API-KEY>
  update_frequency: 10s
  log_level: info

The pf modes rely on pfctl commands to alter the tables. you are required to create the following tables on your pf.conf configuration:

 # create crowdsec ipv4 table
table <crowdsec-blacklists> persist

# create crowdsec ipv6 table
table <crowdsec6-blacklists> persist

You can refer to the step-by-step instructions of the user tutorial on
FreeBSD
to setup crowdsec-firewall-bouncer with pf.

2. Apache Bouncer

The Apache Bouncer integrates with your Apache web server, allowing you to block malicious IP addresses identified by CrowdSec.

Repository Installation

The Apache Bouncer uses a different repository than CrowdSec's main packages:

curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec-apache/script.deb.sh | sudo bash

Then install:

sudo apt-get install crowdsec-apache2-bouncer

Manual Installation (From Source)

If packages aren't available for your system, you can build the bouncer from source:

git clone https://github.com/crowdsecurity/cs-apache2-bouncer
cd cs-apache2-bouncer/
aclocal
autoconf
autoheader
automake --add-missing
./configure
make
sudo make install
sudo cp config/mod_crowdsec.* /etc/apache2/mods-available/
sudo mkdir  -p /etc/crowdsec/bouncers/
sudo cp ./config/crowdsec-apache2-bouncer.conf  /etc/crowdsec/bouncers/

Configuration

Enable the module: sudo a2enmod mod_crowdsec
Generate an API key: sudo cscli bouncers add apache2
Edit the configuration file: /etc/crowdsec/bouncers/crowdsec-apache2-bouncer.conf. Replace CrowdsecAPIKey with the generated key and set CrowdsecURL to your LAPI address.
Restart Apache: sudo systemctl restart apache2

Configuration Directives

Crowdsec: Enables/disables the module globally (on or off). Can be overridden per location.
CrowdsecFallback: How to respond if LAPI is unavailable (fail, block, or allow).
CrowdsecBlockedHTTPCode: HTTP code to return when blocking (500, 403, or 429).
CrowdsecLocation: URL to redirect to when banned.
CrowdsecURL: URL of the CrowdSec API (LAPI).
CrowdsecAPIKey: API key for LAPI authentication.
CrowdsecCache: Enables caching of decisions (none, dbm, shmcb, or memcache). See Apache documentation for details.
CrowdsecCacheTimeout: Cache timeout in seconds.

Overriding HTTP Response

You can customize the HTTP response using CrowdsecLocation and RewriteRules.

3. AWS WAF Bouncer

This Remediation Component integrates CrowdSec with AWS Web Application Firewall (WAF) to protect your AWS resources.

Installation

Install the package from the CrowdSec repository:

sudo apt install crowdsec-aws-waf-bouncer` (Debian/Ubuntu) or `sudo yum install crowdsec-aws-waf-bouncer` (RHEL/CentOS/Fedora)

Configuration

Edit the configuration file at /etc/crowdsec/bouncers/crowdsec-aws-waf-bouncer.yaml.

Key parameters:

api_key: API key for LAPI.
api_url: LAPI URL.
update_frequency: How often to update WAF rules.
waf_config: List of WAF ACL configurations. Each ACL config includes:
- web_acl_name: Name of the WAF ACL.
- fallback_action: Action if a decision type is unsupported (captcha, ban, or count).
- rule_group_name: Name of the rule group to create.
- scope: REGIONAL or CLOUDFRONT.
- region: AWS region.
- ipset_prefix: Prefix for IP sets.

You can also configure the bouncer using environment variables.

IAM Permissions

The bouncer requires specific IAM permissions to interact with AWS WAF. The minimum required permissions are:

{
    "Statement": [
        {
            "Action": [
                "wafv2:UpdateWebACL",
                "wafv2:UpdateRuleGroup",
                "wafv2:UpdateIPSet",
                "wafv2:TagResource",
                "wafv2:GetWebACL",
                "wafv2:GetRuleGroup",
                "wafv2:GetIPSet",
                "wafv2:DeleteRuleGroup",
                "wafv2:DeleteIPSet",
                "wafv2:CreateRuleGroup",
                "wafv2:CreateIPSet"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:wafv2:*:*:global/webacl/*/*",
                "arn:aws:wafv2:*:*:global/rulegroup/*/*",
                "arn:aws:wafv2:*:*:global/managedruleset/*/*",
                "arn:aws:wafv2:*:*:*/ipset/*/*"
            ],
            "Sid": "WAF1"
        },
        {
            "Action": [
                "wafv2:ListWebACLs",
                "wafv2:ListRuleGroups",
                "wafv2:ListIPSets"
            ],
            "Effect": "Allow",
            "Resource": "*",
            "Sid": "WAF2"
        }
    ],
    "Version": "2012-10-17"
}

4. Blocklist Mirror

This Remediation Component exposes CrowdSec decisions as an HTTP blocklist, allowing other network devices and security tools to consume CrowdSec's threat intelligence.

Installation

Install from the CrowdSec repository:

sudo apt install crowdsec-blocklist-mirror` (Debian/Ubuntu) or `sudo yum install crowdsec-blocklist-mirror` (RHEL/CentOS/Fedora)

Configuration

The main configuration file is located at /etc/crowdsec/bouncers/crowdsec-blocklist-mirror.yaml.

Key parameters:

crowdsec_config:
- lapi_url: LAPI URL.
- lapi_key: API key.
- update_frequency: How often to poll LAPI.
blocklists: List of blocklist configurations. Each blocklist config includes:
- format: Format of the blocklist (plain_text, mikrotik, or F5).
- endpoint: HTTP endpoint for the blocklist.
- authentication: Authentication settings (none, basic, or ip_based).
tls: TLS configuration for HTTPS.

Formats

The component supports the following blocklist formats:

plain_text: One IP address per line.
mikrotik: Mikrotik firewall rules.
F5: F5 appliance configuration lines.

5. Cloudflare Worker Bouncer

This Remediation Component deploys a Cloudflare Worker to protect your website by blocking malicious traffic at the edge.

Installation

Install from the CrowdSec repository:

sudo apt install crowdsec-cloudflare-worker-bouncer` (Debian/Ubuntu) or `sudo yum install crowdsec-cloudflare-worker-bouncer` (RHEL/CentOS/Fedora)

Configuration

Auto-generate the configuration:

sudo crowdsec-cloudflare-worker-bouncer -g <CLOUDFLARE_TOKEN1>,<CLOUDFLARE_TOKEN2> -o /etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml

Review and edit: /etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml

Key parameters:

crowdsec_config:
- lapi_url: LAPI URL.
- lapi_key: API key.
- update_frequency: How often to poll LAPI.
cloudflare_config:
- accounts: List of Cloudflare account configurations.
  - id: Cloudflare account ID.
  - zones: List of zone configurations.
    - zone_id: Cloudflare zone ID.
    - actions: Supported actions (captcha, ban).
    - default_action: Default action to take (captcha, ban, or none).
    - routes_to_protect: List of routes to protect.
      *accounts[].zones[].turnstile.mode - Mode for turnstile. Supported values ["managed", "invisible", "non-interactive"]. See cloudflare-docs for more details.

Start the bouncer: sudo systemctl start crowdsec-cloudflare-worker-bouncer

Important Considerations

Cloudflare's free worker limits apply
set the failmode to Fail Open to ensure requests are not blocked in case of reaching quota
Test the integration with manual decision creation

Setting up the worker route fail mode

Please see the setting up worker fail mode section.

6. Cloudflare Bouncer (Deprecated)

:::danger
This bouncer isn't actively supported anymore, due to changes to Cloudflare's API rate limitations.

You should instead look at the Cloudflare Workers Bouncer.
:::

Installation

Install from the CrowdSec repository:

sudo apt install crowdsec-cloudflare-bouncer` (Debian/Ubuntu) or `sudo yum install crowdsec-cloudflare-bouncer` (RHEL/CentOS/Fedora)

Configuration

Auto-generate the configuration:

sudo crowdsec-cloudflare-bouncer -g <CLOUDFLARE_TOKEN1>,<CLOUDFLARE_TOKEN2> -o /etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml

Set up ip lists and firewall rules:

sudo crowdsec-cloudflare-bouncer -s


3.  **Review and edit:** `/etc/crowdsec/bouncers/crowdsec-cloudflare-bouncer.yaml`

Key parameters:

*   `crowdsec_lapi_url`: LAPI URL.
*   `crowdsec_lapi_key`: API key.
*   `crowdsec_update_frequency`:  How often to poll LAPI.
*   `cloudflare_config`:
    *   `accounts`: List of Cloudflare account configurations.
        *   `id`: Cloudflare account ID.
        *   `token`: The token associated with this account, it require the following permissions:
           -   Zone: Read
           -   DNS: Read
           -   Account Settings: Read
           -   Workers KV Storage: Edit
           -   Challenge Widgets: Edit
        *   `ip_list_prefix`: Prefix for IP lists.
        *   `default_action`: Default action to take (`managed_challenge`, `block`, `js_challenge`).
    *   `zones`: List of zone configurations.
        *   `zone_id`: Cloudflare zone ID.
        *   `actions`: Supported actions (`managed_challenge`, `block`, `js_challenge`).

4.   **Start the bouncer:** `sudo systemctl start crowdsec-cloudflare-bouncer`

---

## 7. Custom Bouncer

The Custom Bouncer provides a generic interface to execute custom scripts based on CrowdSec decisions, enabling integration with any system.

### Installation

Install from the CrowdSec repository:

```bash
sudo apt install crowdsec-custom-bouncer` (Debian/Ubuntu) or `sudo yum install crowdsec-custom-bouncer` (RHEL/CentOS/Fedora)

Configuration

Edit the configuration file at /etc/crowdsec/bouncers/crowdsec-custom-bouncer.yaml.

Key parameters:

bin_path: Path to the custom script or binary.
bin_args: Arguments to pass to the script.
feed_via_stdin: Whether to pass decisions via stdin (true) or arguments (false).
total_retries: Number of retries if the script fails.
scenarios_containing: Only process decisions for scenarios containing these words.
scenarios_not_containing: Ignore decisions for scenarios containing these words.
scopes: Filter decisions based on scope (e.g., Ip, Range).
origins: Filter decisions based on origin (e.g., cscli, crowdsec).
api_url: LAPI URL.
api_key: API key.

Usage

The Custom Bouncer can operate in two modes:

Invoke mode (default): The script is called for each decision with add or del actions and parameters.
Stdin mode: The script is started once and receives decisions as JSON objects on stdin.

Best Practices

Use scopes to filter decisions for specific types of actions.
Ensure your script is executable and has appropriate permissions.
Carefully validate input data to prevent unexpected behavior.

Conclusion

By strategically deploying these CrowdSec Remediation Components, you can effectively translate threat intelligence into real-time protection, enhancing your system's security posture and mitigating potential risks. Remember to consult the official CrowdSec documentation and community resources for the most up-to-date information and best practices.

Supported Remediation Components

Prerequisites

Installation and Configuration Guides

1. Linux Firewall Bouncer

Repository Installation

Installation

pf (FreeBSD)

Configuration

Metrics

Example for pf configuration

2. Apache Bouncer

Repository Installation

Manual Installation (From Source)

Configuration

Configuration Directives

Overriding HTTP Response

3. AWS WAF Bouncer

Installation

Configuration

IAM Permissions

4. Blocklist Mirror

Installation

Configuration

Formats

5. Cloudflare Worker Bouncer

Installation

Configuration

Important Considerations

Setting up the worker route fail mode

6. Cloudflare Bouncer (Deprecated)

Installation

Configuration

Configuration

Usage

Best Practices

Conclusion

Subscribe to TheProCat