Protecting Traefik

1. The principle #

One plugin and two roles.

Two separate integrations #

Traefik and CrowdSec work together in two ways:

• Detection: CrowdSec reads Traefik access logs thanks to the crowdsecurity/traefik collection.
• Blocking: the community plugin crowdsec-bouncer-traefik-plugin queries the LAPI and returns 403 to banned addresses.

2. Setting it up #

Static and dynamic configuration.

The key #

docker compose exec crowdsec cscli bouncers add traefik
# ou, côté image CrowdSec : BOUNCER_KEY_traefik=une-cle-longue-et-aleatoire

Static configuration #

entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      trustedIPs:          # only if a proxy or CDN is in front of Traefik
        - 10.0.0.0/8
accessLog:
  filePath: /var/log/traefik/access.log
providers:
  file:
    filename: /etc/traefik/dynamic.yml
experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: v1.8.1

Restart Traefik: it downloads the plugin at startup, so it needs Internet access at that point.

Dynamic configuration #

http:
  middlewares:
    crowdsec:
      plugin:
        bouncer:
          enabled: true
          crowdsecMode: stream
          updateIntervalSeconds: 15
          crowdsecLapiScheme: http
          crowdsecLapiHost: crowdsec:8080
          crowdsecLapiKey: YOUR_KEY
          forwardedHeadersTrustedIPs:
            - 10.0.0.0/8
  routers:
    app:
      rule: "Host(`app.example.com`)"
      entryPoints: [web]
      service: app
      middlewares: [crowdsec]
  services:
    app:
      loadBalancer:
        servers:
          - url: "http://app:8080"

With Docker labels:

services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"
      - "traefik.http.routers.whoami.middlewares=crowdsec@docker"
      - "traefik.http.middlewares.crowdsec.plugin.bouncer.enabled=true"
      - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdsecmode=stream"
      - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapihost=crowdsec:8080"
      - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapikey=YOUR_KEY"

The plugin modes #

3. The real IP trap #

Behind a CDN or load balancer.

The symptom #

Everything seems to work, but a banned IP keeps passing. We reproduced it: without entrypoint trust, Traefik overwrites X-Forwarded-For. The plugin sees the proxy's address, never the client's.

The fix #

You must declare the trusted proxy in two places: forwardedHeaders.trustedIPs on the entrypoint, and forwardedHeadersTrustedIPs in the plugin. Limit these ranges to your real proxies: a client must not be able to spoof its address.

To exclude your internal network from checks, use clientTrustedIPs.

4. Going further #

Detection and WAF.

Reading Traefik logs #

filenames:
  - /var/log/traefik/access.log
labels:
  type: traefik

docker compose exec crowdsec cscli collections install crowdsecurity/traefik
docker compose exec crowdsec cscli metrics show acquisition parsers

Enabling AppSec #

crowdsecAppsecEnabled: true
crowdsecAppsecHost: crowdsec:7422
crowdsecAppsecFailureBlock: true
crowdsecAppsecUnreachableBlock: true

Mind availability. With crowdsecAppsecUnreachableBlock: true (the default), the site is blocked if AppSec is unreachable. Choose this behavior knowingly.

Sources #

• Traefik Plugin Catalog : crowdsec-bouncer
• CrowdSec : Traefik

Blocking verified on Traefik 3.7.17, plugin 1.8.1 and CrowdSec 1.8.2.