Coraza WAF

​

Overview

​

Architecture

• WAF Workload — Coraza and CRS on Caddy, listening on WAFPort and proxying to targetWorkload:targetPort. A standard workload that autoscales on CPU between one and three replicas.
• Startup Hook — A postStart hook that points the image’s Caddy reverse-proxy handler at your target workload. It resolves the handler by name, waits for the Caddy admin API with a bounded timeout, reads the result back, and fails closed: a WAF that cannot configure itself refuses to serve rather than passing traffic through uninspected.
• Custom Rules — Your own seclang rules, loaded after the Core Rule Set.

​

What Gets Created

• Standard Workload — (RELEASE_NAME-coraza-waf): the Coraza container, listening on WAFPort, publicly reachable and reachable from the same GVC.
• Startup Secret — (RELEASE_NAME-coraza-startup): an opaque secret holding the startup hook script, mounted into the container.
• Custom Rules Secret — (RELEASE_NAME-coraza-custom-rules): an opaque secret holding your rules, mounted at /opt/coraza/rules.d/custom.conf. It ships with one example rule.
• Identity & Policy — An identity for the WAF workload with reveal scoped to exactly those two secrets. No cloud bindings are attached.

​

Prerequisites

• Set targetWorkload to that workload’s fully qualified internal address, WORKLOAD_NAME.GVC_NAME.cpln.local, and targetPort to the port it serves.
• Set that workload’s internal firewall to same-gvc, same-org, or a workload-list that includes RELEASE_NAME-coraza-waf. The internal default is none, which blocks the WAF from reaching it.

​

Installation

​

Configuration

# Pinned by digest = tag 4.28-caddy-alpine-202608260808 (OWASP CRS 4.28.0, Caddy v2.11.3).
# Only the *-caddy-alpine-* variants work with this template, and only a datecode or a
# digest is safe to pin — moving tags such as -lts get repointed upstream.
image: ghcr.io/coreruleset/coraza-crs@sha256:ed1e4a656e83f1ba17d629f30de0910d491b1cc13e5e8e7e9b9f2ac9a35bac1b

# MUST BE CHANGED
targetWorkload: my-workload.my-gvc.cpln.local # Workload internal name of the workload to proxy traffic to

targetPort: 8080 # Port of the workload to proxy traffic to

WAFPort: 80 # Port on the WAF workload to expose to the internet

# Coraza inspects request bodies on the CPU, so these size the largest body the WAF
# can inspect inside timeoutSeconds. See "Request size, CPU and timeout" in the README
# before lowering them — 50m/128Mi, the pre-1.2.0 defaults, 504 on any body over ~30 KB.
resources:
  cpu: 500m
  memory: 512Mi

# Request timeout, in seconds, for everything passing through the WAF. It caps both the
# time Coraza spends inspecting a request body and the time the upstream has to answer;
# anything slower gets a 504 from the WAF, not from your application.
timeoutSeconds: 30

multiZone: false

​

Proxy Target

• targetWorkload — The internal DNS name of the workload to proxy traffic to, in the form WORKLOAD_NAME.GVC_NAME.cpln.local. This must be changed before deploying. The short workload name alone is not reliable; always use the fully qualified form.
• targetPort — The port the target workload serves on.
• WAFPort — The port the WAF workload exposes, and the port clients connect to (default 80).

​

Choosing an Image Tag

​

Request Body Size and Timeout

largest inspected body ≈ 120 KB × cpu-cores × timeoutSeconds

​

Resources and Placement

• resources.cpu / resources.memory — CPU and memory for the WAF container. These are the limits, and they size request-body inspection — see Request Body Size and Timeout.
• multiZone — When true, deploys replicas across multiple zones for higher availability.

​

Custom Rules

SecRule REQUEST_URI "@rx attack" "id:1001,phase:1,deny,msg:'Blocked attack attempt'"

SecRuleRemoveById 920450

​

Logging

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-coraza-waf"}' --limit 100 --since 30m

​

Connecting

​

Important Notes

• This only protects traffic that goes through it. The WAF is a proxy, so the workload behind it must not remain publicly reachable on its own endpoint, or requests bypass inspection entirely.
• Only *-caddy-alpine-* images work, and only a digest or a datecode is safe to pin. Moving tags such as -lts change the image under a running deployment. See Choosing an Image Tag.
• CRS rule updates require a deliberate image change. That is the right default for a security control, but new CRS releases are not picked up on their own.
• A request body too large to inspect inside timeoutSeconds returns 504 from the WAF, not from your application. Size resources.cpu and timeoutSeconds together — see Request Body Size and Timeout.
• CRS blocks any request carrying an Expect: 100-continue header (rule 920450), which some HTTP clients add for large uploads. Switch that one rule off in the custom rules secret if your clients send it.
• timeoutSeconds also caps how long the protected workload may take to answer, not only how long inspection may take.
• Custom rules layer on top of CRS, so a rule ID that collides with a CRS rule silently overrides it, and rule changes take effect only after the replicas restart.
• The WAF fails closed. If the startup hook cannot configure the reverse proxy, the container restarts rather than serving uninspected traffic. If the workload does not start, check cpln logs for a [FATAL] line naming the failed check; an incompatible non-Caddy image instead exits immediately with exitCode: 127 after logging Launching caddy run ….
• Do not override the container’s command or args. They run the image’s own entrypoint behind a tail that forwards the startup hook’s output onto the container log; replacing them leaves a failed hook with no diagnosis.

​

External References