CrowdSec Protection

CrowdSec generates remediation decisions for client IP addresses based on security events. Gateway nodes retrieve and enforce those decisions through a bouncer. In Edge Admin, call crowdsec-enforce() from a custom EdgeLang rule to run the check.

This feature was first introduced in OpenResty Edge 26.12.1-1 and applies only to HTTP applications.

# Prerequisites

• Run OpenResty Edge 26.12.1-1 or later on Edge Admin and the gateway nodes in the target partition.
• Deploy CrowdSec first. Every gateway node must be able to connect and authenticate to the CrowdSec LAPI (Local API), on the same host or another server.
• oredge-crowdsec-bouncer is installed automatically. If CrowdSec is already configured on the same host, installation configures the local bouncer automatically. Configure it manually when using a remote LAPI or when automatic configuration has not completed.

When configuring an API key manually, register the bouncer on the CrowdSec server to obtain the key. See CrowdSec bouncer registration. Prepare the credentials for each node. Do not put real API keys in page rules or version control.

# Configure the bouncer

# Configuration file location

The configuration file is located at /usr/local/oredge-node/conf/oredge-crowdsec-bouncer.conf.

The file uses KEY=value entries, lowercase true or false for booleans, and separate comment lines starting with #. Enter real values instead of leaving installation placeholders such as ${API_KEY}.

sudoedit /usr/local/oredge-node/conf/oredge-crowdsec-bouncer.conf

Gateway nodes read conf/oredge-crowdsec-bouncer.conf under their Nginx startup prefix. The standard oredge-node service uses the path above. Adjust the path if the node uses another startup prefix. When upgrading an existing installation, migrate its settings to the oredge-crowdsec-bouncer.conf file the node reads.

The bouncer also reads oredge-crowdsec-bouncer.conf.local next to its active configuration. Entries in that file override the same keys in the main file. Check any existing override file as well.

# IP ban configuration example

Use this example as a reference for manual configuration. It authenticates to a LAPI on the same host with an API key and enforces only ban decisions. Replace API_KEY with the actual key. For a remote LAPI, change API_URL to an address reachable from the node. If installation configured the file automatically, keep the generated API_URL and API_KEY and adjust other settings as needed.

ENABLED=true
API_URL=http://127.0.0.1:8080
API_KEY=replace-with-your-bouncer-api-key
USE_TLS_AUTH=false
SSL_VERIFY=true
MODE=live
CACHE_EXPIRATION=1
REQUEST_TIMEOUT=3000
STREAM_REQUEST_TIMEOUT=15000
UPDATE_FREQUENCY=10
BOUNCING_ON_TYPE=ban
FALLBACK_REMEDIATION=ban
ENABLE_INTERNAL=false
EXCLUDE_LOCATION=
BAN_TEMPLATE_PATH=/usr/local/openresty-plus/crowdsec/templates/ban.html
REDIRECT_LOCATION=
RET_CODE=403

These are example values, not defaults for every installed version. When using templates supplied by the package, verify that BAN_TEMPLATE_PATH points to an existing file readable by the node.

# Configuration settings

CAPTCHA remediation additionally requires CAPTCHA_PROVIDER, SITE_KEY, SECRET_KEY, CAPTCHA_TEMPLATE_PATH, and CAPTCHA_EXPIRATION (the validity period after successful verification, in seconds). Validate the chosen provider and template before setting BOUNCING_ON_TYPE to captcha or all.

TLS client certificate authentication also requires TLS_CLIENT_CERT and TLS_CLIENT_KEY. APPSEC_URL and other APPSEC_* options configure a separately deployed CrowdSec AppSec service. This example does not enable AppSec. For advanced settings, consult the installed bouncer’s configuration template and the CrowdSec configuration reference.

After configuring a standard node managed by systemd, reload its service:

sudo systemctl reload oredge-node

Reload the node after changing its local file or installing the bouncer. Saving or publishing Edge Admin rules alone does not reread this file. Restrict access to configuration files and private keys. For non-root deployments, ensure that the account loading the configuration can read those files.

# Call the action in Edge Admin

1. Verify that each node in the partition has loaded its configuration and can access the LAPI.

2. Set the target partition’s enable_crowdsec switch to true, save, and publish the configuration.

3. Open the HTTP application’s Page Rules page and click Add Edge Language Rules at the Beginning of This Page. Enter the following rule directly:

   true =>
       crowdsec-enforce();
   

4. Save and publish the application configuration.

true invokes the check for every request that reaches this point. You can also restrict its scope, for example:

uri-prefix("/protected/") =>
    crowdsec-enforce();

The action takes no arguments and runs during HTTP request rewriting. Allowed requests continue through subsequent actions. Ban, CAPTCHA, or redirect responses can terminate the request. Repeated calls in the same request check only once.

The check uses the trusted client IP identified by Edge. If a load balancer or proxy precedes the node, configure trusted proxies and real IP handling first to avoid treating the proxy address as the client’s address.

See Write Custom Edge Rules for rule editing and EdgeLang crowdsec-enforce() for the action syntax.

# Verify and disable

In an isolated test environment, check allowed requests, a banned client, and requests after removing the ban. Allow time for synchronization in stream mode or cache expiry in live mode. A running node or successful publication does not prove enforcement is active. Check responses and node error logs.

CrowdSec checks are skipped in any of these cases:

• The bouncer is not configured: the configuration file the node reads is absent.
• The local bouncer is disabled with ENABLED=false in that file.
• Bouncer initialization fails, including a missing component or an unreadable configuration file.

Even if the partition switch is on, these conditions do not interrupt requests; subsequent Edge actions continue. Initialization failures are logged but do not prevent the node from starting. Correct the configuration or install the missing component, then reload the node. Requests also skip checks when the partition switch is off.

After successful bouncer initialization, ordinary LAPI connection failures or timeouts are handled as follows when AppSec is disabled:

• In live mode, cached decisions take precedence. On a cache miss, a failed query is logged and the request is allowed to continue through subsequent Edge actions. The request may wait for the timeout specified by REQUEST_TIMEOUT.
• In stream mode, failed background synchronization is logged and existing cached decisions remain in use. Requests without a matching cached remediation are allowed; request checks do not wait for LAPI synchronization.

Cached remediations, including bans, remain in effect while valid; losing access to the LAPI does not remove them immediately. Ordinary LAPI network failures do not directly cause 500 responses. Unhandled check exceptions can still return 500 and stop subsequent actions. When AppSec is enabled, its checks also affect the final remediation.

To disable enforcement, turn off and publish the partition’s enable_crowdsec switch, then verify that all nodes have applied it. To stop background synchronization too, set ENABLED=false in the configuration each node actually uses and reload the node.