Architecture

kubeWAF is a Kubernetes operator that turns structured security CRDs into live WAF configuration on Envoy-based data planes. Evaluation runs in modsecurity-proxy-wasm; you can optionally put pow-proxy-wasm (PoW challenge) in front via spec.challenge.

Configuration is pushed over Envoy’s Extension Config Discovery Service (ECDS); each gateway product only receives a thin filter slot.

Big picture

Control plane vs data plane

kubeWAF does not replace the gateway’s ADS (LDS/RDS/CDS). It only owns extension config (ECDS) and installs a small filter that points at that ECDS resource.

Operator internals

Why this split?

Envoy (and Envoy Gateway) load-balance against the operator Service. If only the leader held ECDS config, non-leader pods would return empty snapshots and requests would fail or bypass WAF randomly. Dataplane servers and the sync controller therefore run on every pod; Kubernetes writes stay on the leader.

Portable config artifact

After rule resolution, every path produces the same intermediate object — now with an ordered filter list (optional Challenge, then WAF engine):

The ECDS resource type is always:

type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm

with modsecurity-proxy-wasm plugin JSON of the form (see schemas/waf-plugin-config.json):

{
  "mode": "kubewaf",
  "config_id": "kubewaf/shop/shop-waf",
  "allow_fallback": false,
  "default_directives": "default",
  "directives_map": {
    "default": [
      "Include @kubewaf-defaults",
      "SecRuleEngine On",
      "SecDebugLogLevel 3",
      "Include @crs-setup-conf",
      "Include @owasp_crs/*.conf",
      "..."
    ]
  },
  "metric_labels": {
    "waf_namespace": "shop",
    "waf_name": "shop-waf",
    "engine": "modsecurity",
    "owner": "modsecurity-proxy-wasm",
    "team": "payments"
  },
  "metrics": { "enabled": true, "per_rule_id": true, "rule_tags": true },
  "block": { "message": "blocked by kubeWAF" }
}

End-to-end request path

Multi-provider slots

See Data plane (ECDS) for configuration details.

Core CRDs

Data flow (lifecycle)

1. Author — SecRule / SecAction (or CRS converter).
2. Aggregate — RuleSet selects rules (names or labels).
3. Attach — WAF references RuleSets and a provider.
4. Resolve — flatten graph, enforce namespace policy, back-references (leader).
5. Publish — every pod updates its ECDS snapshot.
6. Slot — leader ensures EnvoyFilter / CEC / EG index.
7. Enforce — modsecurity-proxy-wasm evaluates traffic.

Rule content changes bump the ECDS snapshot only; platform slots are not rewritten unless provider or ECDS endpoint settings change.

Operator ports and Service

Security model

• Rules are namespaced.
• RuleSet.allowedRules controls who may contribute rules (Same / All / Selector).
• Only RuleSets attach to a WAF (not raw SecRules).
• Platform teams own RuleSets + WAF attachment; app teams own SecRules in their namespace.

Status and conditions

kubectl get waf -o wide
kubectl describe waf shop-waf

Current limitations

• WAFInstance does not yet deploy proxies.
• No validating admission webhooks yet.
• Cilium full L7 filter-chain merge depends on the cluster’s Envoy build (CEC slot is always created).
• Envoy Gateway requires extensionManager configured to call kubeWAF.

Related projects

• WAF engine (kubeWAF) · modsecurity-proxy-wasm
• PoW challenge (kubeWAF) · pow-proxy-wasm
• Envoy Gateway
• Istio EnvoyFilter
• Cilium Envoy
• OWASP CRS

Next

• Guides
• Data plane (ECDS)
• Envoy Gateway · Istio · Cilium