CrowdSec WAF General Setup

This guide covers the core AppSec Component setup that applies to all web servers and reverse proxies. After completing these steps, configure your remediation component (bouncer) to forward requests to the AppSec Component.

Prerequisites

• CrowdSec Security Engine (>= 1.5.6) installed and running
• A compatible remediation component (bouncer) for your web server or reverse proxy

AppSec Component Setup

AppSec setup has two steps:

• Download rules and configuration collections.
• Configure AppSec as a new acquisition datasource (AppSec datasource).

The following sections will guide you through the default setup.

After installation, verify everything works with the 🩺 Health Check.

Collection Installation

Install the essential AppSec collections that provide virtual patching rules and generic attack detection:

SH

sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules

These collections include:

• Virtual Patching Rules: Protection against known vulnerabilities (CVEs)
• Generic Attack Detection: Common web attack patterns
• AppSec Configuration: Default AppSec configuration file linking rules together
• CrowdSec Parsers & Scenarios: For processing AppSec events and creating alerts

Acquisition Configuration

Configure CrowdSec to expose the AppSec Component by creating an acquisition file (AppSec datasource).

1. Create the acquisition directory (if it doesn't exist):

SH

sudo mkdir -p /etc/crowdsec/acquis.d/

2. Create the AppSec acquisition configuration:

SH

sudo cat > /etc/crowdsec/acquis.d/appsec.yaml << EOF
appsec_configs:
  - crowdsecurity/appsec-default
labels:
  type: appsec
listen_addr: 127.0.0.1:7422
source: appsec
name: myAppSecComponent
EOF

Configuration explained:

• appsec_configs: Uses the AppSec configuration(s) from the installed collections
• listen_addr: IP and port where the AppSec Component listens (default: 127.0.0.1:7422)
• source: Identifies this as an AppSec data source
• name: A friendly name for your AppSec component

Security Note

Do not expose the AppSec Component to the internet. It should only be accessible from your web server or reverse proxy.

Start the AppSec Component

Restart CrowdSec to activate the AppSec Component:

SH

sudo systemctl restart crowdsec

Testing WAF Component

Testing Configuration

Check that the AppSec Component is running:

Netstat

SH

sudo netstat -tlpn | grep 7422

SS

SH

sudo ss -tlpn | grep 7422

Output example

SH

tcp        0      0 127.0.0.1:7422            0.0.0.0:*               LISTEN      12345/crowdsec

note

The output may look differently depending on which command you used but as long as you see the port and the process crowdsec, it means the AppSec Component is running.

Check CrowdSec logs for successful startup:

SH

sudo tail -f /var/log/crowdsec.log

Look for messages like:

TEXT

INFO[...] Starting Appsec server on 127.0.0.1:7422/
INFO[...] Appsec Runner ready to process event

Next steps

Now that the AppSec Component is configured and running, you need to:

1. Configure your remediation component to forward requests to http://127.0.0.1:7422
2. Test the setup by triggering a rule
3. Monitor alerts with sudo cscli alerts list or in the CrowdSec Console

For specific remediation component configuration, see:

• Nginx/OpenResty Setup
• OpenResty Setup
• Traefik Setup
• HAProxy (SPOA) Setup
• WordPress Setup
• Check the hub for other remediation components supporting AppSec

Once your remediation component is in place, continue with:

• Reviewing the AppSec troubleshooting guide if you need to investigate or refine the deployment.
• Exploring WAF deployment strategies when you are ready to expand beyond the initial setup.

Testing Detection

If you've enabled an WAF-capable bouncer with CrowdSec WAF, you can trigger the crowdsecurity/appsec-generic-test dummy scenario. This scenario does not lead to a decision, but it is a good way to confirm the setup is working.

Trigger the dummy scenario by accessing a probe path on your web server:

1️⃣ Access your service URL with this path: /crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl

SH

curl -I https://<your-service-url>/crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl

2️⃣ Confirm the alert has triggered for crowdsecurity/appsec-generic-test

SH

sudo cscli alerts list | grep crowdsecurity/appsec-generic-test

3️⃣ The alert will also appear in the Console alerts

info

This scenario can only be triggered again after a 1-minute delay.

Optional: Advanced Configuration

Multiple AppSec Configurations

You can load multiple AppSec configurations for different rule sets:

YAML

# /etc/crowdsec/acquis.d/appsec.yaml
appsec_configs:
  - crowdsecurity/appsec-default    # Virtual patching rules (in-band)
  - crowdsecurity/crs               # OWASP CRS rules (out-of-band)
labels:
  type: appsec
listen_addr: 127.0.0.1:7422
source: appsec
name: myAppSecComponent

Custom Port Configuration

To use a different port, update the listen_addr in your acquisition file and ensure your remediation component points to the same address.

Troubleshooting

If the AppSec Component fails to start:

1. Check port availability: Ensure port 7422 isn't already in use
2. Verify collections: Run sudo cscli collections list to confirm installation
3. Check configuration syntax: Validate your appsec.yaml file
4. Review logs: Check /var/log/crowdsec.log for error messages

For detailed troubleshooting, see the AppSec Troubleshooting Guide.