Core Concepts

This page explains the fundamental building blocks of kubeWAF.

SecRule

A SecRule is the atomic unit of protection. It describes a single security check using ModSecurity SecLang concepts:

• Variables (what to inspect)
• Operator (how to compare)
• Actions (what to do on match)
• Metadata (id, phase, message, tags, severity)

Example (simplified):

spec:
  secLangRules:
  - metadata:
      id: 100100
      phase: "2"
    conditions:
    - variables: [{ name: ARGS_GET }]
      operator: { name: rx, value: <script> }
    actions:
      disruptive: { disruptiveActionType: deny }

See the full SecLang YAML structure reference.

RuleSet

A RuleSet is a named, reusable collection of rules.

Instead of listing hundreds of individual rules on every policy attachment, you create a RuleSet once and reference it from WAF.

Key capabilities:

• Direct name references
• Label selector references (matchLabels)
• Cross-namespace references (subject to allowedRules policy)
• Recursive RuleSet references (RuleSet → RuleSet)

spec:
  ruleRefs:
  - kind: SecRule
    selector:
      matchLabels:
        app: payment-waf
        version: v2
  allowedRules:
    from: Same          # or "All" or "Selector"

WAF

WAF is the primary way to enforce rules on live traffic.

It:

1. Resolves ruleRefs into SecLang
2. Runs modsecurity-proxy-wasm (optional pow-proxy-wasm challenge first)
3. Publishes ECDS resources
4. Installs a provider-specific slot so Envoy loads those configs

Important fields:

See WAF CRD, engine, challenge, Data plane.

WAFInstance (Future)

WAFInstance is intended for a standalone WAF proxy or sidecar, independent of an external gateway product.

Today the controller only performs reference resolution. Full workload deployment is under development.

Rule reference resolution

When you reference a RuleSet, the resolver:

1. Recursively expands nested RuleSets
2. Collects matching SecRule / SecAction resources
3. Validates namespace policies (allowedRules)
4. Creates back-references (leader path)
5. Sets ReferencesResolved

Non-leader pods use a read-only resolve path to keep ECDS warm without fighting over finalizers.

Phases

Like classic ModSecurity, rules run in phases:

• Phase 1 — Request headers (very early)
• Phase 2 — Request body
• Phase 3 — Response headers
• Phase 4 — Response body
• Phase 5 — Logging

Most application-level rules live in phase 2.

Portable config

Authors never write Envoy JSON. The operator builds a PortableConfig with an ordered Filters list (optional challenge, then WAF) shared by every provider. That is what ECDS serves and what slots point at.

Engines (monorepo)

Next

• Architecture
• Guides
• Writing rules
• Providers: Envoy Gateway · Istio · Cilium