Explanation on Coraza Kubernetes Operator

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

The Coraza Kubernetes Operator uses a two-controller architecture with a shared in-memory cache to deliver firewall rules to WASM plugins running in Envoy sidecars.

High-Level Overview

The operator manages two custom resources:

RuleSet – Aggregates SecLang rules from ConfigMaps and compiles them into a cached, validated ruleset.
Engine – Attaches a RuleSet to one or more Gateways by deploying a Coraza WASM plugin into Envoy.

The data flows through these components:

Rule Processing

Mon, 01 Jan 0001 00:00:00 +0000

This page explains the lifecycle of firewall rules from ConfigMap to enforcement in the WASM plugin.

Rule Aggregation

A RuleSet references an ordered list of ConfigMaps. Each ConfigMap must contain a key named rules with SecLang directives as its value. The operator reads these ConfigMaps in the specified order and concatenates their contents to form a single rule body.

The order matters because SecLang directives are evaluated sequentially. Engine configuration directives (such as SecRuleEngine On) must appear before detection rules.

Istio WASM Integration

Mon, 01 Jan 0001 00:00:00 +0000

The Coraza Kubernetes Operator integrates with Istio by deploying a WebAssembly (WASM) plugin into Envoy proxies attached to Kubernetes Gateways. This page explains how that integration works.

How Istio WasmPlugin Works

Istio provides a WasmPlugin resource that instructs Envoy to load and execute a WASM module. The operator creates WasmPlugin resources to inject the Coraza WAF into the request processing pipeline.

When a WasmPlugin is applied, Istio:

Downloads the WASM binary from the specified OCI registry.
Loads it into the Envoy proxy as a filter.
Routes HTTP requests through the WASM filter before forwarding them to the backend.

The coraza-proxy-wasm Plugin

The WASM module used by the operator is coraza-proxy-wasm. It is a purpose-built Envoy WASM filter that:

Known Limitations

Mon, 01 Jan 0001 00:00:00 +0000

This page describes known limitations when running the Coraza WAF with Istio using WASM mode. These limitations are specific to the WASM execution environment and do not apply to all deployment modes.

Overview

Out of approximately 3,300 OWASP CoreRuleSet conformance tests, 190 tests (6%) are currently excluded, resulting in a 94% pass rate. The excluded tests fall into four categories:

Category	Tests	Impact
Enhanced Security	45	Positive – Envoy provides additional protection.
Tool Limitations	113	Requires alternative controls or monitoring.
Coraza/WASM Bugs	13	Requires fixes in Coraza or coraza-proxy-wasm.
Under Investigation	19	Requires further analysis.

Operator Behavior

The RuleSet controller automatically detects and rejects any RuleSet containing rules listed in this document. When unsupported rules are found:

Security Model

Mon, 01 Jan 0001 00:00:00 +0000

This page describes the security model of the Coraza Kubernetes Operator, including RBAC permissions, network security, and authentication mechanisms.

RBAC Permissions

The operator requires two sets of RBAC permissions:

Cluster-Scoped Permissions (ClusterRole)

Resource	Verbs	Purpose
ConfigMaps, Secrets	get, list, watch	Read firewall rules and data files.
Pods	list, watch	Discover Gateway pods matching Engine workload selectors.
ServiceAccounts	create, get, list, patch, update, watch	Manage service accounts for cache authentication.
ServiceAccounts/token	create	Issue tokens for WASM plugin authentication.
Events	create, patch	Record events on managed resources.
Deployments	get	Read operator deployment metadata.
TokenReviews, SubjectAccessReviews	create	Authenticate and authorize metrics endpoint access.
Leases	create, delete, get, list, patch, update, watch	Leader election.
WasmPlugins (Istio)	create, delete, get, list, patch, update, watch	Manage Istio WASM plugin resources.
Gateways (Gateway API)	list, watch	Discover Gateways for Engine status reporting.
ServiceEntries, DestinationRules (Istio)	create, get, patch, update	Create Istio prerequisites for cache server mesh connectivity.

Namespace-Scoped Permissions (Role)

Resource	Verbs	Purpose
NetworkPolicies	create, delete, get, list, patch, update, watch	Manage network policies for cache server access.

The operator follows the principle of least privilege. It does not request permissions beyond what is needed for its controllers.