patterns/docs/traefik.md

Traefik Integration

This guide explains how to consume the generated WAF middleware in Traefik v2 / v3.

Quick start

1. Download traefik_waf.zip from the latest release.
2. Drop the TOML files into your dynamic configuration directory.
3. Reference the middleware from each router that should be protected.

Files in the archive

File	Purpose
middleware.toml	WAF middleware definition (regex patterns per category)
bots.toml	Bad-bot User-Agent middleware

Step 1 — Enable the file provider

::: code-group

[providers]
  [providers.file]
    directory = "/etc/traefik/dynamic"
    watch = true

providers:
  file:
    directory: /etc/traefik/dynamic
    watch: true

:::

Step 2 — Drop the TOML files in

sudo cp waf_patterns/traefik/*.toml /etc/traefik/dynamic/

Traefik picks them up automatically because watch = true.

Step 3 — Reference the middleware

::: code-group

[http.routers.app]
  rule = "Host(`example.com`)"
  service = "app"
  middlewares = ["waf-protection", "bot-blocker"]

http:
  routers:
    app:
      rule: "Host(`example.com`)"
      service: app
      middlewares:
        - waf-protection
        - bot-blocker

:::

The middleware names (waf-protection, bot-blocker) are the keys defined inside middleware.toml and bots.toml.

Docker labels

For Docker / Compose deployments, attach the middleware via labels:

services:
  app:
    image: my-app:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host(`example.com`)"
      - "traefik.http.routers.app.middlewares=waf-protection@file,bot-blocker@file"

The @file suffix tells Traefik to resolve the middleware from the file provider.

Plugin compatibility

middleware.toml is generated against Traefik's built-in middleware primitives. If you prefer a dedicated WAF plugin (e.g. one of the community plugins on Traefik Plugins), you can declare it side-by-side and chain both:

experimental:
  plugins:
    waf:
      moduleName: "github.com/example/traefik-waf-plugin"
      version: "v1.0.0"

Customization

Add custom patterns

Edit middleware.toml to extend the regex set:

[[http.middlewares.waf-protection.plugin.rewriteHeaders.replacements]]
  regex = "your-custom-pattern"
  replacement = "BLOCKED"

Logging

Enable structured access logs to track middleware decisions:

[accessLog]
  filePath = "/var/log/traefik/access.log"
  format = "json"
  [accessLog.fields]
    [accessLog.fields.headers]
      defaultMode = "keep"

Testing

curl -H "Host: example.com" "http://localhost/?id=1' OR '1'='1"
docker logs traefik 2>&1 | grep -i blocked

Troubleshooting

• Middleware never loads — check that the file provider directory matches and that watch = true. traefik logs -f shows hot-reload events.
• Router does not apply the middleware — the middleware name must match exactly (case-sensitive) between router declaration and middleware definition.
• Latency — regex middleware adds per-request overhead. Profile with traefik access logs and consider scoping the middleware to specific routers rather than applying globally.