WAF engine

A kubeWAF WAF resource always evaluates traffic with a Proxy-Wasm WAF engine. The supported product engine is ModSecurity via modsecurity-proxy-wasm (OWASP CRS embedded in the binary).

This page is operator-facing: which CR fields select the engine, enable CRS, and override wasm delivery. For standalone Envoy use, metrics series, and build details, see modsecurity-proxy-wasm.

Select the engine

apiVersion: waf.kubewaf.io/v1beta1
kind: WAF
metadata:
  name: shop-waf
  namespace: shop
spec:
  engine: ModSecurity
  crsEnable: true
  provider:
    type: EnvoyGateway
  parentRefs:
    targetRef:
      group: gateway.networking.k8s.io
      kind: Gateway
      name: external
  ruleRefs:
  - kind: RuleSet
    name: shop-rules

Field	Description
`engine`	`ModSecurity` — product engine (`modsecurity-proxy-wasm`)
`crsEnable`	When `true`, include embedded OWASP CRS with correct directive order
`crs`	Optional declarative CRS tuning (paranoia, exclusions, …) — see Using CRS
`logLevel`	Filter log verbosity (`0`–`7`)
`ruleRefs`	RuleSets to append as SecLang after defaults/CRS

Optional PoW challenge before this engine: Proof-of-Work challenge.

How config reaches Envoy

Operator resolves RuleSets → SecLang directives
Builds plugin JSON (directives_map, metrics labels, block message, …)
Publishes ECDS resource kubewaf/<namespace>/<waf-name>
Envoy loads modsecurity-proxy-wasm from the operator wasm server (or your URL)

Default serve path:

GET /wasm/modsecurity-proxy-wasm.wasm

You do not hand-author the plugin JSON for normal GitOps use — the controller owns that mapping.

Override the wasm binary

Per-WAF (on the CR):

Field	Description
`wasmHTTP`	HTTPS URL Envoy uses to fetch the WAF `.wasm`
`wasmSHA256`	Optional content pin
`wasmImage`	Optional OCI reference (documentation / future fetchers)

spec:
  engine: ModSecurity
  wasmHTTP: https://cdn.example.com/modsecurity-proxy-wasm.wasm
  wasmSHA256: "abcdef..."

Cluster defaults (Helm / operator flags):

Helm / flag	Purpose
`dataplane.modsecurityWasmFile` / `--modsecurity-wasm-file`	Path inside operator image
`dataplane.modsecurityWasmSourceURL` / `--modsecurity-wasm-source-url`	Download at operator startup

# values.yaml excerpt
dataplane:
  modsecurityWasmFile: /wasm/modsecurity-proxy-wasm.wasm

Status

kubectl get waf shop-waf -o jsonpath='{.status.engine}{"\n"}'
# ModSecurity

When challenge is also enabled: status.challengeEnabled=true (see challenge).

Using CRS — paranoia and exclusions on the WAF CR
Writing rules — custom SecRules
Data plane (ECDS) — how filters attach
modsecurity-proxy-wasm — engine project docs

Select the engine

How config reaches Envoy

Override the wasm binary

Status

Related

On this page