CrowdSec WAF QuickStart for Traefik

Objectives

This quickstart walks you through pairing the CrowdSec AppSec Component with the Traefik reverse proxy across three deployment models: a single Docker container, a Docker Compose stack, and the official Helm chart on Kubernetes. You'll install the required AppSec collections, configure the acquisition endpoint that exposes the inspection service, and wire the Traefik plugin so requests are evaluated before reaching your applications. We'll finish by pointing you to the Stack health check so you can validate the bouncer and AppSec stack end to end.

Pre-requisites

1. If you're new to the AppSec Component or Web Application Firewalls, start with the Introduction for a better understanding.

2. It's assumed that you have already installed:

   • CrowdSec Security Engine: for installation, refer to the QuickStart guide. The AppSec Component, which analyzes HTTP requests, is included within the security engine as a Acquisition.
   • Traefik Plugin Remediation Component: Thanks to maxlerebourg and team they created a Traefik Plugin that allows you to block requests directly from Traefik.

Prior to starting the guide ensure you are using the Traefik Plugin and NOT the older and deprecated traefik-crowdsec-bouncer as it hasnt received updates to use the new AppSec Component.

This guide will assume you already have a working Traefik setup using the Traefik Plugin. If you need help setting up Traefik, refer to the official documentation and the Traefik Plugin documentation.

AppSec Component Setup

Collection installation

To begin setting up the AppSec Component, the initial step is to install a relevant set of rules.

We will utilize the crowdsecurity/appsec-virtual-patching collection, which offers a wide range of rules aimed at identifying and preventing the exploitation of known vulnerabilities.

This collection is regularly updated to include protection against newly discovered vulnerabilities. Upon installation, it receives automatic daily updates to ensure your protection is always current.

Furthermore we also install the crowdsecurity/appsec-generic-rules collection. This collection contains detection scenarios for generic attack vectors. It provides some protection in cases where specific scenarios for vulnerabilities do not exist (yet).

You can always view the content of a collection on the hub

Docker

## This command should be used when you are persisting /etc/crowdsec/ on the host
docker exec -it crowdsec cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules

This command installs the needed appsec hub configuration items.

Docker Compose

values.yaml

services:
  crowdsec:
    environment:
      - 'COLLECTIONS=crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules'

Please note the spaces between the collection names (hence why the quotes are needed).

This compose configuration file will add some needed hub configuration items.

Kubernetes (Helm)

Please add this in your values.yaml for your CrowdSec release.

values.yaml

appsec:
  env:
    - name: COLLECTIONS
      value: "[...] crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules [...]"

Please note the spaces between the collection names (hence why the double quotes are needed).

Now you can apply it with:

helm upgrade crowdsec crowdsec/crowdsec -n crowdsec --create-namespace -f ./crowdsec-values.yaml

This values.yaml modification will add some needed hub configuration items.

Those needed hub configuration items are:

• The AppSec Rules contain the definition of malevolent requests to be matched and stopped.
• The AppSec Configuration links together a set of rules to provide a coherent set.
• The CrowdSec Parser and CrowdSec Scenario(s) are used to detect and remediate persistent attacks.

Once you have updated your compose or installed via the command line, will we need to restart the container. However, before we do that, we need to setup the acquisition for the AppSec Component.

Setup the Acquisition

You now need to setup the acquisition for AppSec. The way it's done highly depends on how you run CrowdSec.

Docker

In the directory where you persist configuration files, create an appsec.yaml file and mount it into the container.

Steps

Create a file named appsec.yaml with the following content

appsec.yaml

appsec_config: crowdsecurity/appsec-desfault
labels:
  type: appsec
listen_addr: 0.0.0.0:7422
source: appsec

You can either create the file under /etc/crowdsec/acquis.d, following the existing directory structure in which case the run command remains unchanged, or you can create the file elsewhere and mount it using the following method:

docker run -d --name crowdsec \
  -v /etc/crowdsec:/etc/crowdsec \
  -v /elsewhere/appsec.yaml:/etc/crowdsec/acquis.d/appsec.yaml \
  crowdsecurity/crowdsec

Because CrowdSec runs inside a container, set listen_addr to 0.0.0.0 instead of 127.0.0.1 so it can accept connections from outside the container.

If a crowdsec container is already running, stop/remove it before re-running with the updated acquisition.

Docker Compose

In the directory where you store CrowdSec configuration files (for example, ./crowdsec/acquis.d, if you’re following the recommended directory structure, create a file named appsec.yaml and mount it into the container.

appsec.yaml

appsec_config: crowdsecurity/appsec-default
labels:
  type: appsec
listen_addr: 0.0.0.0:7422
source: appsec

Since CrowdSec runs inside a container, make sure to set listen_addr to 0.0.0.0 (instead of 127.0.0.1) so it listens on the container’s network interface.

Then, update your Docker Compose service to mount the file:

services:
  crowdsec:
    volumes:
    - ./crowdsec/acquis.yaml:/etc/crowdsec/acquis.yaml
    - logs:/var/log/nginx
    - crowdsec-db:/var/lib/crowdsec/data/
    - crowdsec-config:/etc/crowdsec/
    - ./crowdsec/acquis.d/appsec.yaml:/etc/crowdsec/acquis.d/appsec.yaml

Once you have updated the compose file to include the volume mount and the updated environment variable, you can restart the container.

docker compose down crowdsec
docker compose rm crowdsec
docker compose up -d crowdsec

The previous compose commands presume the container is named crowdsec. If you have named the container something else, you will need to replace crowdsec with the name of your container.

Kubernetes (Helm)

With kubernetes the acquisition setup is twofolds: We have to add

values.yaml

appsec:
  acquisitions:
    - appsec_config: crowdsecurity/appsec-default
      labels:
        type: appsec
      listen_addr: 0.0.0.0:7422
      path: /
      source: appsec
  enabled: true

Remediation Component Setup

As stated previously this guide already presumes you have the Traefik Plugin installed. If you do not have the Traefik Plugin installed, please refer to the official documentation for installation instructions.

Configuration

Depending on how you configured the Traefik Plugin, you will need to update the configuration to include the AppSec configuration.

Currently AppSec does not support mTLS authentication for the AppSec Component. If you have mTLS enabled, and wish to use the AppSec Component, you can define seperate middlewares for the AppSec Component.

Traefik dynamic configuration

If you have defined a dynamic configuration file for Traefik, you can add the following configuration to the file.

traefik_dynamic.yaml

# Dynamic configuration
http:
  routers:
    my-router:
      rule: host(`whoami.localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - crowdsec

  services:
    service-foo:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000
  
  middlewares:
    crowdsec:
      plugin:
        bouncer:
          enabled: true
          crowdsecAppsecEnabled: true
          crowdsecAppsecHost: crowdsec:7422
          crowdsecAppsecFailureBlock: true
          crowdsecAppsecUnreachableBlock: true
          crowdsecLapiKey: privateKey-foo

Instead if you define the configuration using labels on the containers you can add the following labels to the Traefik Plugin container.

  labels:
      - "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.enabled=true"
      - "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.crowdsecAppsecEnabled=true"
      - "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.crowdsecAppsecHost=crowdsec:7422"
      - "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.crowdsecLapiKey=privateKey-foo"

Traefik middleware (Kubernetes)

Here's a Traefik Middleware ressource you can apply with

kubectl apply -f traefik-middleware.yaml

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: crowdsec
  namespace: traefik
spec:
  plugin:
    crowdsec-bouncer-traefik-plugin:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiScheme: http
      crowdsecLapiHost: crowdsec-service.crowdsec.svc.cluster.local:8080
      crowdsecLapiKey: <shadowed>
      htttTimeoutSeconds: 60
      crowdsecAppsecEnabled: false
      crowdsecAppsecHost: crowdsec:7422
      crowdsecAppsecFailureBlock: true
      crowdsecAppsecUnreachableBlock: true

You can still add some route configuration through IngressRoute and attach the middleware to those routes.

For more comprehensive documentation on the Traefik Plugin configuration, please refer to the official documentation.

The traefik configuration for testing this quickstart guide has been done with the following values.yaml

values.yaml

deployment:
  kind: DaemonSet  # run on each node so a sidecar crowdsec can tail Traefik logs

service:
  type: LoadBalancer  # expose Traefik entrypoints through your cloud LB
  annotations:
    service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol: "true"  # forward client IPs via DigitalOcean proxy protocol
  spec:
    externalTrafficPolicy: Local  # keep original source IPs for CrowdSec decisions

# Make Traefik actually write a file that can be parsed
logs:
  access:
    enabled: true  # ensure access logs are produced
    format: json  # structured logs expected by the bouncer parser
    fields:
      defaultMode: keep
      names:
        ServiceName: keep  # keep service name for troubleshooting
  general:
    level: INFO  # avoid noisy debug output in production 
    format: json  # align general logs with access log format

# Proxy Protocol needs “enabled”, not only trustedIPs
additionalArguments:
  - --accesslog=true  # double-check logging stays on even if values drift
  - --accesslog.format=json  # enforce JSON formatting at the CLI level
  - --entrypoints.web.proxyProtocol=true  # enable Proxy Protocol on the HTTP entrypoint
  - --entrypoints.websecure.proxyProtocol=true  # enable Proxy Protocol on the HTTPS entrypoint
  - --entrypoints.web.proxyProtocol.trustedIPs=10.0.0.0/8,192.168.0.0/16  # trust proxy headers from your internal ranges
  - --entrypoints.websecure.proxyProtocol.trustedIPs=10.0.0.0/8,192.168.0.0/16  # same trust list for HTTPS
  - --providers.kubernetesingress  # watch standard Ingress resources
  - --providers.kubernetescrd  # watch Traefik CRD resources

# Traefik middleware configuration 
experimental:
  plugins:
    crowdsec-bouncer-traefik-plugin:
      moduleName: "github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
      version: "v1.4.5"  # pin plugin release for deterministic behaviour

Directives

The following directives are available for the Traefik Plugin:

crowdsecAppsecEnabled

bool

Enable or disable the AppSec Component.

crowdsecAppsecHost

string

The host and port where the AppSec Component is running.

crowdsecAppsecFailureBlock

bool

If the AppSec Component returns 500 status code should the request be blocked.

crowdsecAppsecUnreachableBlock

bool

If the AppSec Component is unreachable should the request be blocked.

Validate the stack

Follow the Stack health check to confirm the CrowdSec engine, AppSec Component, and Traefik bouncer are working together as expected.

Integration with the console

If you haven't yet, follow the guide about how to enroll your Security Engine in the console.

Once done, all your alerts, including the ones generated by the AppSec Component, are going to appear in the console:

Next steps

You are now running the AppSec Component on your Crowdsec Security Engine, congrats!

As the next steps, you can:

• Explore the hub to find more rules for your use case
• Look at the Rules syntax and creation process to create your own and contribute
• Take a look at the benchmarks