traefik-coraza

A Traefik middleware plugin that integrates with coraza-server to provide WAF (Web Application Firewall) protection for your services.

This plugin does not contain any WAF logic itself. It acts as a bridge between Traefik and an external coraza-server instance, which is responsible for running Coraza WAF rules. For every incoming request, the plugin forwards it to coraza-server and blocks or allows it based on the response.

Traefik → traefik-coraza (this plugin) → coraza-server (WAF) → upstream service

Logging: the plugin only logs when coraza-server is unreachable (network/timeout/circuit breaker). Request deny details are logged by coraza-server.

How it works

For every incoming request:

1. Send the same method, path, query, headers, and body to serverURL (your coraza-server instance).
2. If the request body exceeds maxBodyBytes, return 413 Payload Too Large.
3. If coraza-server returns 2xx, forward the request to the next middleware/service.
4. If coraza-server returns non-2xx, block the request with that status (and body when present).
5. If coraza-server fails repeatedly, open the circuit breaker for circuitBreakerDurationMillis and short-circuit validation during that window.
6. If coraza-server is unreachable (including while the circuit is open), either fail-open or fail-closed depending on configuration.

Requirements

• A running coraza-server instance reachable from Traefik.

Configuration

Option	Required	Default	Description
serverURL	yes	—	Base URL of your coraza-server instance (e.g. http://coraza-server:8080).
maxBodyBytes	no	1048576	Maximum request body size (bytes) forwarded to coraza-server.
timeoutMillis	no	2000	Timeout in milliseconds for each call to coraza-server.
circuitBreakerDurationMillis	no	5000	How long (ms) to keep the circuit open after repeated coraza-server failures.
failOpen	no	false	If true, allow traffic through when coraza-server is unreachable.
rejectStatusCode	no	403	Fallback status code when coraza-server denies a request without a body.
errorStatusCode	no	503	Status code returned when coraza-server is unreachable and failOpen=false.
rejectBody	no	—	Custom response body sent when a request is denied by coraza-server.
errorBody	no	—	Custom response body sent when coraza-server is unreachable and failOpen=false.

Example dynamic config (Traefik)

http:
  middlewares:
    remote-waf:
      plugin:
        coraza-plugin:
          serverURL: http://coraza-server:8080
          timeoutMillis: 2000
          circuitBreakerDurationMillis: 5000
          failOpen: false

Tests

go test ./...

Benchmarks

go test -run '^$' -bench . -benchmem