Skip to main content

CrowdSec

📚 Documentation 💠

Source

💬 Discourse

ModeStream only
MetricsSupported
MTLSSupported
PrometheusSupported
AppSec Support

This bouncer supports the AppSec Component for real-time WAF protection. Enable crowdsecAppsecEnabled: true in your middleware configuration to get virtual patching and defense against known CVEs, SQL injection, XSS, and other application-layer attacks.

For a full walkthrough, see the AppSec Quickstart for Traefik.

Traefik on kubernetes

important

This remediation component is community developed and maintained. You can see all the configuration options in the bouncer documentation. You can also refer to a full traefik and CrowdSec stack on kubernetes or our Appsec Traefik Quickstart.

Objectives​

This quickstart shows how to deploy the CrowdSec Traefik bouncer in Kubernetes and protect workloads exposed through Traefik using a middleware plugin.

At the end, you will have:

  • CrowdSec LAPI running in-cluster and reachable from Traefik
  • A Traefik middleware enforcing CrowdSec remediation decisions
  • A Kubernetes secret storing the shared bouncer key
  • The bouncer key mounted into the Traefik pod as a file
  • An operational pattern that avoids committing the LAPI key in plaintext

Prerequisites​

It is assumed that you already have:

warning

This integration currently relies on a community Traefik plugin, not on a first-party CrowdSec remediation component.

The upstream project used in this guide is:

  • maxlerebourg/crowdsec-bouncer-traefik-plugin

Store the Traefik bouncer key in a Kubernetes secret​

The practical approach is to choose a fixed shared key and store it in Kubernetes secrets instead of hardcoding it in Helm values.

Two secrets are needed because CrowdSec and Traefik run in different namespaces:

  • In the crowdsec namespace, CrowdSec LAPI reads BOUNCER_KEY_traefik from the crowdsec-keys secret.
  • In the traefik namespace, Traefik mounts the same key from the crowdsec-bouncer-key secret as a file.

Both secrets must contain the same BOUNCER_KEY_traefik value.

Create or update the secrets used by CrowdSec LAPI and Traefik:

crowdsec-keys.yaml
YAMLcrowdsec-keys.yaml
apiVersion: v1
kind: Secret
metadata:
  name: crowdsec-keys
  namespace: crowdsec
type: Opaque
stringData:
  ENROLL_KEY: "<your-existing-enroll-key>"
  BOUNCER_KEY_traefik: "<your-shared-traefik-bouncer-key>"
---
apiVersion: v1
kind: Secret
metadata:
  name: crowdsec-bouncer-key
  namespace: traefik
type: Opaque
stringData:
  BOUNCER_KEY_traefik: "<your-shared-traefik-bouncer-key>"

Apply it:

SH
kubectl apply -f crowdsec-keys.yaml

Then reference BOUNCER_KEY_traefik from the CrowdSec Helm values:

crowdsec-values.yaml
YAMLcrowdsec-values.yaml
lapi:
  env:
    - name: BOUNCER_KEY_traefik
      valueFrom:
        secretKeyRef:
          name: crowdsec-keys
          key: BOUNCER_KEY_traefik

Apply the CrowdSec release again:

SH
helm upgrade --install crowdsec crowdsec/crowdsec --namespace crowdsec --create-namespace -f crowdsec-values.yaml

The crowdsec-bouncer-key secret in the traefik namespace is used later when mounting the key into the Traefik pod.

Required traefik configuration items​

Traefik configuration's on source IPs​

To ensure remediation works correctly, Traefik must receive the real client IP for each request. When Traefik is deployed behind a load balancer, CDN, or another reverse proxy, the source IP may otherwise be replaced with the upstream address.

Traefik must first trust the upstream IP ranges. This is done with:

The CrowdSec middleware must then trust the same ranges:

YAML
spec:
  plugin:
    bouncer:
      forwardedHeadersTrustedIps: <trusted-cidr>

If the client IP is forwarded through a header other than X-Forwarded-For, set it explicitly:

YAML
spec:
  plugin:
    bouncer:
      forwardedHeadersCustomName: X-Real-Ip

Correctly forwarding and trusting these headers ensures that both Traefik and CrowdSec operate on the same client IP, which is required for IP-based remediation.

Side note about source IP with CrowdSec and Kubernetes

Source IP addresses are essential in a CrowdSec deployment for two reasons. First, the log processor must know which IPs are responsible for triggering scenarios. Second, the remediation component needs to identify the originating IP of incoming requests in order to apply the appropriate action.

In a Kubernetes environment, this requires disabling source NAT on nodes so that the CrowdSec-monitored service pods receive the real client IP. As a consequence, the Service's externalTrafficPolicy must be set to Local, and the workload must run either as a DaemonSet or as a Deployment ensuring one pod per node. This guarantees that no traffic, and therefore no security events, is missed.

Traefik Custom Resource Definitions​

Traefik's CRDs provide the custom resource types, such as Middleware, that are required to configure Traefik through the Kubernetes CRD provider. CrowdSec remediation relies on one of these resources to declare the middleware. Without the CRDs, this middleware cannot be created or used.

Install the Traefik CRDs via Helm:

SH
helm repo add traefik https://traefik.github.io/charts
helm repo update
helm upgrade --install traefik-crds traefik/traefik-crds -n traefik --create-namespace

Enable experimental plugin loading​

The CrowdSec Traefik plugin cannot be enabled only through CLI flags. You must also enable experimental plugin loading in the Traefik chart values:

traefik-values.yaml
YAMLtraefik-values.yaml
experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: v1.4.5
volumes:
  - name: crowdsec-bouncer-key
    mountPath: /etc/traefik/crowdsec
    type: secret
    secretName: crowdsec-bouncer-key

Apply or upgrade your Traefik release:

SH
helm upgrade --install traefik traefik/traefik -n traefik --create-namespace -f traefik-values.yaml

Verify CrowdSec LAPI access​

The Traefik middleware only needs access to CrowdSec LAPI. Make sure the CrowdSec release exposes the LAPI service, that the bouncer key is available through lapi.env, and that Traefik has the same key mounted from the crowdsec-bouncer-key secret.

Verify the CrowdSec pods and services:

SH
kubectl -n crowdsec get pods
kubectl -n crowdsec get svc crowdsec-service

You should see:

  • crowdsec-lapi in Running
  • crowdsec-service exposing port 8080

Deploy the Traefik middleware​

To achieve remediation in a Traefik environment, create a Middleware resource.

important

The Traefik Middleware CRD does not have a native secretKeyRef field for the plugin configuration. In Kubernetes, the key can be mounted from a Secret into the Traefik pod and reference it with crowdsecLapiKeyFile.

Mount the Traefik-side secret into the pod and let the middleware read it from a file.

Use a Traefik chart values file like this:

traefik-values.yaml
YAMLtraefik-values.yaml
experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: v1.4.5
volumes:
  - name: crowdsec-bouncer-key
    mountPath: /etc/traefik/crowdsec
    type: secret
    secretName: crowdsec-bouncer-key

Apply or upgrade your Traefik release:

SH
helm upgrade --install traefik traefik/traefik -n traefik --create-namespace -f traefik-values.yaml

Then create the middleware:

bouncer-middleware.yaml
YAMLbouncer-middleware.yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: bouncer
  namespace: traefik
spec:
  plugin:
    bouncer:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiScheme: http
      crowdsecLapiHost: crowdsec-service.crowdsec.svc.cluster.local:8080
      crowdsecLapiPath: /
      crowdsecLapiKeyFile: /etc/traefik/crowdsec/BOUNCER_KEY_traefik

Apply it:

SH
kubectl apply -f bouncer-middleware.yaml

This keeps the source-of-truth key in Kubernetes secrets and avoids storing the literal key in the middleware manifest.

Show direct crowdsecLapiKey example

You can apply a middleware manifest with an inline key as well:

bouncer-middleware.yaml
YAMLbouncer-middleware.yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: bouncer
  namespace: traefik
spec:
  plugin:
    bouncer:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiScheme: http
      crowdsecLapiHost: crowdsec-service.crowdsec.svc.cluster.local:8080
      crowdsecLapiPath: /
      crowdsecLapiKey: <your-shared-traefik-bouncer-key>

Apply it:

SH
kubectl apply -f bouncer-middleware.yaml

This is useful for quick validation, but crowdsecLapiKeyFile with a mounted Kubernetes secret seems to be a more secure approach.

Once the middleware exists, attach it to your IngressRoute or other Traefik route resources.

Traefik with WAF (AppSec) on Kubernetes​

If you want remediation and WAF protection together, first enable AppSec in the CrowdSec chart while still sourcing the bouncer key from the Kubernetes secret:

crowdsec-values.yaml
YAMLcrowdsec-values.yaml
config:
  config.yaml.local: |
    api:
      server:
        auto_registration:
          enabled: true
          token: "${REGISTRATION_TOKEN}"
          allowed_ranges:
            - "127.0.0.1/32"
            - "192.168.0.0/16"
            - "10.0.0.0/8"
            - "172.16.0.0/12"
appsec:
  enabled: true
  acquisitions:
    - source: appsec
      listen_addr: "0.0.0.0:7422"
      path: /
      appsec_configs:
        - crowdsecurity/appsec-default
        - crowdsecurity/crs
      labels:
        type: appsec
  env:
    - name: COLLECTIONS
      value: "crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-crs crowdsecurity/appsec-generic-rules"
lapi:
  env:
    - name: BOUNCER_KEY_traefik
      valueFrom:
        secretKeyRef:
          name: crowdsec-keys
          key: BOUNCER_KEY_traefik

If you add this config to the CrowdSec values, don't forget to upgrade the release:

SH
helm upgrade --install crowdsec crowdsec/crowdsec \
  --namespace crowdsec \
  --create-namespace \
  -f crowdsec-values.yaml

Traefik must also mount the crowdsec-bouncer-key secret so the middleware can read the bouncer key from a file:

traefik-values.yaml
YAMLtraefik-values.yaml
experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: v1.4.5
volumes:
  - name: crowdsec-bouncer-key
    mountPath: /etc/traefik/crowdsec
    type: secret
    secretName: crowdsec-bouncer-key

If needed, upgrade the Traefik release as well:

SH
helm upgrade --install traefik traefik/traefik -n traefik --create-namespace -f traefik-values.yaml

Then use an AppSec-enabled middleware:

bouncer-middleware.yaml
YAMLbouncer-middleware.yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: bouncer
  namespace: traefik
spec:
  plugin:
    bouncer:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiScheme: http
      crowdsecLapiHost: crowdsec-service.crowdsec.svc.cluster.local:8080
      crowdsecLapiPath: /
      crowdsecLapiKeyFile: /etc/traefik/crowdsec/BOUNCER_KEY_traefik
      crowdsecAppsecEnabled: true
      crowdsecAppsecHost: crowdsec-appsec-service.crowdsec.svc.cluster.local:7422
      crowdsecAppsecPath: /
      crowdsecAppsecFailureBlock: true
      crowdsecAppsecUnreachableBlock: true
      crowdsecAppsecBodyLimit: 10485760

Apply it:

SH
kubectl apply -f bouncer-middleware.yaml

Validate AppSec​

Test that malicious requests are blocked:

SH
curl -I http://<your-ingress-ip>/.env
# Expected: HTTP/1.1 403 Forbidden
Monitoring AppSec

Once AppSec is enabled, use cscli metrics show appsec to view processed vs. blocked requests and individual rule triggers. These metrics also appear in the CrowdSec Console after enrollment.

CrowdSec Docs
We use cookies

This site uses cookies to help us improve your experience. You can accept or decline below.