Skip to main content

CrowdSec

📚 Documentation 💠 Hub 💬 Discourse

AppSecSupported
ModeLive & Stream
MetricsSupported
MTLSSupported
PrometheusUnsupported

CrowdSec Remediation QuickStart for NGINX

Objectives​

This quickstart shows how to deploy the CrowdSec NGINX bouncer on a Linux host and protect traffic served through NGINX using the Lua remediation component.

At the end, you will have:

  • A working NGINX bouncer querying CrowdSec LAPI
  • The bouncer loaded in NGINX request processing
  • A dedicated bouncer API key registered in CrowdSec
  • A safer secret-management pattern that keeps the API key in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local

This bouncer is a Lua remediation component for NGINX.

After installing the bouncer, enable the AppSec (WAF) Component to get virtual patching and defense against known CVEs, SQL injection, XSS, and other application-layer attacks.

Follow the dedicated AppSec Quickstart for Nginx/OpenResty — it picks up right where this page ends.

Prerequisites​

  1. It is assumed that you already have:
    • A working CrowdSec Security Engine installation. For a Linux install quickstart, refer to /u/getting_started/installation/linux.
    • A working NGINX installation serving traffic on this host.
    • NGINX access logs acquired by CrowdSec, so remediation decisions are created from the real traffic hitting NGINX.

This bouncer depends on the NGINX Lua module and has only been tested on Debian/Ubuntu based distributions.

How does it work?​

This component leverages nginx lua's API, namely access_by_lua_block to check the 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)
  • Application Security Component (forward request to CrowdSec Application Security Engine and block is necessary)

At the back, this component uses crowdsec lua lib.

Source IPs​

For remediation to work correctly, CrowdSec must detect and decide on the same client IP that NGINX evaluates at request time.

If NGINX is behind a load balancer, CDN, or another reverse proxy, configure the real IP module so remote_addr is rewritten to the original client IP before the CrowdSec Lua hook runs:

/etc/nginx/conf.d/realip.conf
set_real_ip_from 10.0.0.0/8;
set_real_ip_from 192.168.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Replace the trusted ranges and header with the values used by your upstream.

If NGINX only sees the proxy IP, CrowdSec will create decisions for the wrong source and bouncing will not work as expected.

Install the NGINX bouncer​

Dependencies​

Install the following packages:

sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base lua-cjson

If you have Ubuntu 22.xx, you may have an issue with lua module in nginx.
Look at FAQ for more information.

Using packages​

First, setup CrowdSec repositories.

sudo apt install crowdsec-nginx-bouncer

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

Manual installation​

CrowdSec NGINX component 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

tar xvzf crowdsec-nginx-bouncer.tgz
cd crowdsec-nginx-bouncer-v*/
./install.sh

Note: Don't run the script with sudo (the script already uses sudo to install dependencies).

If you are on a mono-machine setup, the crowdsec-nginx-bouncer install script can register directly to the local CrowdSec LAPI. The safer operational pattern is still to manage the API key explicitly as shown below.

⚠️ 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

Register the bouncer key and store it outside the base config​

As with the Envoy and Traefik guides, the practical approach is to choose a fixed key, register it in CrowdSec, and keep it in a dedicated secret location instead of editing the package-managed base file.

Generate a key and register the bouncer:

BOUNCER_KEY="$(openssl rand -hex 32)"
sudo cscli bouncers add nginx-bouncer --key "$BOUNCER_KEY"

Then store only the override in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local:

sudo install -m 600 /dev/null /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local
sudo tee /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local > /dev/null <<EOF
API_KEY=$BOUNCER_KEY
EOF
unset BOUNCER_KEY

/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local takes precedence over /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.

Use this .local file for secrets and local overrides. Avoid committing a real API_KEY= value in automation, Git repositories, or image templates.

If your NGINX host does not talk to a local LAPI, also override API_URL in the same file:

/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local
API_URL=http://<lapi-host>:8080
API_KEY=<your-fixed-bouncer-key>

Verify CrowdSec LAPI access​

Make sure the bouncer appears in CrowdSec and that NGINX can load the bouncer configuration:

sudo cscli bouncers list
sudo nginx -t
sudo systemctl restart nginx

You should see:

  • An nginx-bouncer entry in cscli bouncers list
  • nginx -t returning a successful configuration test
  • NGINX restarting cleanly

Validate remediation​

Create a temporary decision for your client IP and confirm NGINX enforces it:

sudo cscli decisions add -i <IP_TO_TEST> -t ban
curl -I http://<your-nginx-host>/

You should get a ban response, typically 403 Forbidden, or your configured redirect/custom ban page.

NGINX bouncer configuration​

Component configuration​

The main bouncer configuration is located in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.

/etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf
API_URL=<CROWDSEC_LAPI_URL>
API_KEY=<CROWDSEC_LAPI_KEY>
# bounce for all type of remediation that the remediation can receive from the local API
BOUNCING_ON_TYPE=all
# when the remediation receive an unknown remediation, fallback to this remediation
FALLBACK_REMEDIATION=ban
MODE=stream
REQUEST_TIMEOUT=1000
# exclude the bouncing on those location
EXCLUDE_LOCATION=
# process internal request (eg, rewrite)
ENABLE_INTERNAL=false
# 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

# mTLS Configuration
USE_TLS_AUTH=false
TLS_CLIENT_CERT=
TLS_CLIENT_KEY=

## Application Security Component Configuration
APPSEC_URL=
#### default ###
APPSEC_FAILURE_ACTION=passthrough
APPSEC_CONNECT_TIMEOUT=100
APPSEC_SEND_TIMEOUT=100
APPSEC_PROCESS_TIMEOUT=1000
ALWAYS_SEND_TO_APPSEC=false
APPSEC_DROP_UNREADABLE_BODY=false
SSL_VERIFY=true
################

Any /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local content will take precedence over /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf. All fields don't have to be present in this .local. file.

NGINX configuration​

The remediation component NGINX configuration is located in /etc/nginx/conf.d/crowdsec_nginx.conf:

/etc/nginx/conf.d/crowdsec_nginx.conf
lua_package_path '/usr/local/lua/crowdsec/?.lua;;';
lua_shared_dict crowdsec_cache 50m;
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/v1.1.3")
        if ok == nil then
                ngx.log(ngx.ERR, "[Crowdsec] " .. err)
                error()
        end
        ngx.log(ngx.ALERT, "[Crowdsec] Initialisation done")
}

map $server_addr $unix {
	default       0;
	"~unix:" 1;
}

access_by_lua_block {
	local cs = require "crowdsec"
	if ngx.var.unix == "1" then
		ngx.log(ngx.DEBUG, "[Crowdsec] Unix socket request ignoring...")
	else
		cs.Allow(ngx.var.remote_addr)
	end
}

init_worker_by_lua_block {
        cs = require "crowdsec"
        local mode = cs.get_mode()
        if string.lower(mode) == "stream" then
           ngx.log(ngx.INFO, "Initializing stream mode for worker " .. tostring(ngx.worker.id()))
           cs.SetupStream()
        end

        if ngx.worker.id() == 0 then
           ngx.log(ngx.INFO, "Initializing metrics for worker " .. tostring(ngx.worker.id()))
           cs.SetupMetrics()
        end
}

The component uses 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;.

⚠️ Do not rename the crowdsec_cache shared dict, else the component will not work anymore.

When using captcha remediation​

To make HTTP request in the component, you need to configure a resolver and ssl certifcates. Here is a our example.

To make secure HTTP request in the component, 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)

Enable the WAF (AppSec Component)​

For real-time WAF protection — virtual patching, defense against known CVEs, SQLi, XSS, and other application-layer attacks — turn on the AppSec Component after installing the bouncer.

Follow the AppSec Quickstart for Nginx/OpenResty to enable the WAF. It's a few copy-paste commands and picks up right where this installation ends.

The AppSec-related knobs in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf are documented in the Configuration Reference below (all APPSEC_* entries).

Upgrade​

From package​

sudo apt-get update
sudo apt-get install crowdsec-nginx-bouncer

Upgrade from v0 to v1 introduces 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, download the latest release and run:

tar xzvf crowdsec-nginx-bouncer.tgz
cd crowdsec-nginx-bouncer-v*/
sudo ./upgrade.sh
sudo systemctl restart nginx

FAQ​

Why aren't decisions applied instantly​

In stream mode, the component 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:

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

Ubuntu 22.xx getting lua error​

On Ubuntu 22.xx, the default NGINX package does not include the lua module due to compatibility issues with other modules. This has been resolved in later versions of Ubuntu.

How to fix it​

You have a few options to resolve this issue:

  • Upgrade to Ubuntu 24.04 or later
    The lua module is included again in newer Ubuntu releases.

  • Use OpenResty instead of NGINX
    OpenResty is a drop-in replacement for NGINX that includes the lua module by default.

    Note: OpenResty uses slightly different service names and paths, but configuration remains compatible with standard NGINX.

  • Manually compile the lua module
    This is a more advanced approach and requires manual steps to build and install the module yourself.

Configuration Reference​

API_KEY​

string

API_KEY=<API_KEY>

CrowdSec Local API key.

Generated with sudo cscli bouncers add command.

For secret-management best practice, keep the real key in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf.local rather than modifying the package-managed base file.

API_URL​

string

API_URL=http://<ip>:<port>

CrowdSec local API URL.

USE_TLS_AUTH​

boolean

USE_TLS_AUTH=false  # default

Enable mutual TLS (mTLS) authentication for secure communication with CrowdSec Local API. When enabled, the bouncer will use client certificates for authentication instead of API keys.

TLS_CLIENT_CERT​

string (path to file)

TLS_CLIENT_CERT=<path_to_cert>

Path to the client certificate file for mTLS authentication. This option is only used when USE_TLS_AUTH is set to true.

TLS_CLIENT_KEY​

string (path to file)

TLS_CLIENT_KEY=<path_to_key>

Path to the client certificate's private key file for mTLS authentication. This option is only used when USE_TLS_AUTH is set to true.

BOUNCING_ON_TYPE​

all | ban | captcha

BOUNCING_ON_TYPE=all

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

FALLBACK_REMEDIATION​

ban | captcha

FALLBACK_REMEDIATION=ban

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

MODE​

stream | live

MODE=stream

The default mode is live.

The component mode:

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

The timer that pull the local API will be triggered after the first request.

REQUEST_TIMEOUT​

int

REQUEST_TIMEOUT=1000

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

EXCLUDE_LOCATION​

string (comma separated)

EXCLUDE_LOCATION=/<path1>,/<path2>

The locations to exclude while bouncing. It is a list of location, separated by commas.

⚠️ It is not recommended to put EXCLUDE_LOCATION=/.

ENABLE_INTERNAL​

bool

ENABLE_INTERNAL=true

Whether to process internal requests or not (after a rewrite for example).

Disabled by default.

CACHE_EXPIRATION​

int

This option is only for the live mode.

CACHE_EXPIRATION=1

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

UPDATE_FREQUENCY​

int

This option is only for the stream mode.

UPDATE_FREQUENCY=10

The frequency of update, in second, to pull new/old IPs from the CrowdSec local API.

REDIRECT_LOCATION​

string

This option is only for the ban remediation.

REDIRECT_LOCATION=/<path>

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

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

BAN_TEMPLATE_PATH​

string (path to file)

This option is only for the ban remediation.

BAN_TEMPLATE_PATH=<path_to_html_template>

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​

int

This option is only for the ban remediation.

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​

recaptcha | hcaptcha | turnstile

This option is only for the captcha remediation.

CAPTCHA_PROVIDER=<recaptcha

For backwards compatibility reasons recaptcha is the default if no value is set.

SECRET_KEY​

string

This option is only for the captcha remediation.

SECRET_KEY=<captcha_secret_key>

The captcha secret key.

SITE_KEY​

string

This option is only for the captcha remediation.

SITE_KEY=<captcha_site_key>

The captcha site key.

CAPTCHA_TEMPLATE_PATH​

string (path to file)

This option is only for the captcha remediation.

CAPTCHA_TEMPLATE_PATH=<path_to_html_template>

The path to a captcha HTML template.

The component 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​

int

This option is only for the captcha remediation.

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.

CAPTCHA_RET_CODE​

int

This option is only for the captcha remediation.

CAPTCHA_RET_CODE=200

Specifies the HTTP status code that should be returned to the client when a CAPTCHA challenge is required. This is especially useful when your traffic is routed through a CDN (like Cloudflare), where you may want to avoid triggering caching based on non-200 status codes. By default if no value is provided it will use 200 status code.

APPSEC_URL​

string

URL of the Application Security Component

APPSEC_URL=http://127.0.0.1:7422

APPSEC_FAILURE_ACTION​

passthrough | deny

APPSEC_FAILURE_ACTION=passthrough  # default

Behavior when the AppSec Component return a 500. Can let the request passthrough or deny it.

ALWAYS_SEND_TO_APPSEC​

boolean

ALWAYS_SEND_TO_APPSEC=false  # default

Send the request to the AppSec Component even if there is a decision for the IP.

SSL_VERIFY​

boolean

SSL_VERIFY=false  # default

Verify the AppSec Component SSL certificate validity.

APPSEC_CONNECT_TIMEOUT​

int (milliseconds)

APPSEC_CONNECT_TIMEOUT=100  # default

The timeout of the connection between the Remediation Component and AppSec Component.

APPSEC_SEND_TIMEOUT​

int (milliseconds)

APPSEC_SEND_TIMEOUT=100  # default

The timeout to send data from the Remediation Component to the AppSec Component.

APPSEC_PROCESS_TIMEOUT​

int (milliseconds)

APPSEC_PROCESS_TIMEOUT=500  # default

The timeout to process the request from the Remediation Component to the AppSec Component.

APPSEC_DROP_UNREADABLE_BODY​

bool

APPSEC_DROP_UNREADABLE_BODY=false #default

If the bouncer cannot read the request body (eg, HTTP2 without Content-Length header), drop or not the request without forwarding it to the WAF.

If set to false (the default), the request will be evaluated by the WAF without the body content. If set to true, the request will be blocked directly by nginx.

Nginx variables​

Nginx variables can be used to adapt behaviour and or more flexible configurations:

  • ngx.var.crowdsec_disable_bouncer: set to 1, it will disable the bouncer
  • ngx.var.crowdsec_enable_bouncer: set to 1, it will disable the bouncer
  • ngx.var.crowdsec_enable_appsec: set to 1, it will enable the appsec even if it's disabled by configuration or if bouncer is disabled
  • ngx.var.crowdsec_disable_appsec: set to 1, it will disable the appsec
  • ngx.var.crowdsec_always_send_to_appsec: set 1, it will always send the request to appsec, even if a decision already exist for the ip requesting

If both ngx.var.crowdsec_disable_bouncer and ngx.var.crowdsec_enable_bouncer, or both ngx.var.crowdsec_disable_appsec and ngx.var.crowdsec_enable_appsec are set to 1, it's the disable configuration that prevails.