Coraza Kubernetes Operator

API Reference

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

Packages

waf.k8s.coraza.io/v1alpha1

waf.k8s.coraza.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the waf v1alpha1 API group.

Resource Types

DataReference

DataReference is a reference to a RuleData object in the same namespace as the RuleSet.

Appears in:

RuleSetSpec

Field	Description	Default	Validation
`name` string	name is the name of the RuleData in the same namespace as the RuleSet.		MaxLength: 253 MinLength: 1 Required: {}

DriverConfig

DriverConfig configures how the WAF filter is deployed into the target. When omitted from the Engine spec, the operator uses a default driver (currently wasm for Istio).

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 from RuleSource resources (and optional RuleData for @pmFromFile files) 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:

Getting Started on Kubernetes

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

This tutorial walks you through installing the Coraza Kubernetes Operator on a Kubernetes cluster, creating firewall rules, and verifying that the WAF is filtering traffic.

By the end, you will have a working WAF protecting a sample application behind a Kubernetes Gateway.

Prerequisites

Before you begin, ensure you have:

A Kubernetes cluster running v1.32 or later
Istio installed with Gateway API CRDs
Helm 3 installed
kubectl configured to access your cluster

Step 1: Install the Operator

Add the Helm repository and install the operator:

Install on Kubernetes with Helm

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

This guide covers installing the Coraza Kubernetes Operator using Helm on a standard Kubernetes cluster.

Prerequisites

Kubernetes cluster running v1.32 or later
Istio installed with Gateway API CRDs
Helm 3 installed

Install from the Helm Repository

Add the Helm repository hosted on GitHub Pages and install:

helm repo add coraza-kubernetes-operator \
 https://networking-incubator.github.io/coraza-kubernetes-operator/
helm repo update

helm upgrade --install coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system \
 --create-namespace

Pin a Specific Version

helm upgrade --install coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system \
 --create-namespace \
 --version <chart-version>

Replace <chart-version> with the desired version (e.g. 0.1.0). Available versions are listed on the releases page.

Install on OpenShift

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

This guide covers installing the Coraza Kubernetes Operator on OpenShift Container Platform.

Prerequisites

OpenShift Container Platform v4.20 or later
Cluster administrator privileges
Gateway API enabled on your cluster (see Enable Gateway API below)
OpenShift Service Mesh or Istio installed with Gateway API support

Enable Gateway API

On OpenShift 4.20 and later, the Gateway API CRDs are included by default. You must create the openshift-default GatewayClass, which is the officially supported GatewayClass provided by the OpenShift Ingress Operator:

Creating Firewall Rules

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

Firewall rules in the Coraza Kubernetes Operator are written using ModSecurity SecLang syntax. Rule text is stored in RuleSource resources; a RuleSet lists RuleSource (and optional RuleData) names in order and drives compilation and caching.

Writing rules in RuleSources

Each RuleSource has spec.rules: a string containing SecLang directives (use a | block scalar in YAML for multiline text).

A basic RuleSource with Coraza engine configuration:

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: RuleSource
metadata:
 name: base-rules
spec:
 rules: |
 SecRuleEngine On
 SecRequestBodyAccess On
 SecResponseBodyAccess Off
 SecAuditLog /dev/stdout
 SecAuditLogFormat JSON
 SecAuditEngine RelevantOnly

A RuleSource with a SQL injection detection rule:

Getting Started on OpenShift

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

This tutorial walks you through installing the Coraza Kubernetes Operator on OpenShift Container Platform, creating firewall rules, and verifying that the WAF is filtering traffic.

By the end, you will have a working WAF protecting a sample application behind an OpenShift Gateway.

Prerequisites

Before you begin, ensure you have:

An OpenShift Container Platform cluster running v4.20 or later
Gateway API enabled on your cluster (see Enable Gateway API below)
OpenShift Service Mesh or Istio installed with Gateway API support
Helm 3 installed
The oc CLI configured to access your cluster
Cluster administrator privileges

Enable Gateway API

On OpenShift 4.19 and later, the Gateway API CRDs are included by default. You must create the openshift-default GatewayClass, which is the officially supported GatewayClass provided by the OpenShift Ingress Operator:

Helm Chart Values

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

The Coraza Kubernetes Operator Helm chart is located at charts/coraza-kubernetes-operator/.

Values Reference

Key	Type	Default	Description
`replicas`	int	`1`	Number of operator replicas. A PodDisruptionBudget with `minAvailable: 1` is created automatically when greater than 1.
`image.repository`	string	`ghcr.io/networking-incubator/coraza-kubernetes-operator`	Container image repository.
`image.tag`	string	`latest`	Container image tag.
`image.pullPolicy`	string	`IfNotPresent`	Image pull policy.
`imagePullSecrets`	list	`[]`	Image pull secrets for private registries.
`resources.requests.cpu`	string	`10m`	CPU request.
`resources.requests.memory`	string	`128Mi`	Memory request.
`resources.limits.cpu`	string	`500m`	CPU limit.
`resources.limits.memory`	string	`256Mi`	Memory limit.
`metrics.enabled`	bool	`true`	Enable the controller-runtime metrics endpoint (HTTPS on port 8443).
`metrics.certSecret`	string	`""`	Name of a Secret with TLS cert/key for metrics. When empty, a self-signed certificate is generated.
`metrics.certName`	string	`tls.crt`	Key name of the certificate file inside `certSecret`.
`metrics.keyName`	string	`tls.key`	Key name of the private key file inside `certSecret`.
`metrics.caName`	string	`""`	Key name of a CA certificate inside `certSecret` for ServiceMonitor TLS verification.
`metrics.serviceMonitor.enabled`	bool	`false`	Create a Prometheus ServiceMonitor resource.
`logging.development`	bool	`false`	Use console encoder with debug level (development mode). When false, the production settings below apply.
`logging.encoder`	string	`json`	Log encoding format (`json` or `console`). Only used when `development` is false.
`logging.level`	string	`info`	Minimum log level (`debug`, `info`, `error`). Only used when `development` is false.
`logging.stacktraceLevel`	string	`error`	Minimum level for stack traces (`info`, `error`, `panic`). Only used when `development` is false.
`logging.timeEncoding`	string	`rfc3339nano`	Timestamp format (`epoch`, `millis`, `nano`, `iso8601`, `rfc3339`, `rfc3339nano`). Only used when `development` is false.
`istio.revision`	string	`""`	Istio control plane revision label. When empty, no revision label is set on managed resources.
`defaultWasmImage`	string	`""`	Default WASM plugin OCI URL when an Engine omits `spec.driver.wasm.image`. When empty, uses the operator’s built-in default.
`createNamespace`	bool	`true`	Manage the release namespace with Pod Security Standard labels. Requires `--create-namespace` on first install.
`openshift.enabled`	bool	`false`	Omit `runAsUser`, `fsGroup`, and `fsGroupChangePolicy` from the pod security context for OpenShift SCC compatibility.
`podSecurityStandard.version`	string	`latest`	Kubernetes version for Pod Security Standard labels (`latest` or `vX.YZ`).
`nodeSelector`	object	`{}`	Node selector constraints.
`tolerations`	list	`[]`	Tolerations.
`affinity`	object	`{}`	Affinity rules.
`topologySpreadConstraints`	list	`[]`	Topology spread constraints for pod scheduling.

Platform Requirements

Platform	Minimum Version
Kubernetes	v1.32+
OpenShift Container Platform	v4.20+

OpenShift Values Example

For OpenShift installations, use the following values overlay:

Rule Processing

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

This page explains the lifecycle of firewall rules from RuleSource / RuleData to enforcement in the WASM plugin.

Rule aggregation

A RuleSet lists RuleSource names in spec.sources. Each RuleSource stores SecLang in spec.rules. The operator fetches each RuleSource in list order and concatenates the strings into one aggregate body (with newlines between fragments).

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

Deploying a WAF Engine

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

An Engine resource references a RuleSet and attaches the Coraza WAF to a Gateway via an Istio WasmPlugin.

Creating an Engine

The minimum Engine configuration requires a RuleSet reference and a target that identifies your Gateway:

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: Engine
metadata:
 name: my-engine
spec:
 ruleSet:
 name: my-ruleset
 target:
 type: Gateway
 name: my-gateway
 provider: Istio

Selecting a Gateway

The target.name identifies the Gateway resource in the same namespace. The operator derives the workload label selector using the GEP-1762 convention (gateway.networking.k8s.io/gateway-name label).

kubectl-coraza CLI

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

kubectl-coraza is a kubectl plugin for generating Kubernetes manifests (RuleSource, RuleData, RuleSet) from OWASP CoreRuleSet files.

The operator validates and compiles rules after you apply manifests; this tool does not compile Coraza rules.

Installation

Build from source:

git clone https://github.com/networking-incubator/coraza-kubernetes-operator.git
cd coraza-kubernetes-operator
make build

Copy bin/kubectl-coraza to a directory on your PATH:

cp bin/kubectl-coraza /usr/local/bin/

Once installed, the plugin is available as kubectl coraza.

Commands

`kubectl coraza generate coreruleset`

Generate RuleSource resources (one per *.conf file), an optional RuleData resource for *.data files, and a RuleSet that references them.

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:

Operator CLI Flags

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

The operator manager binary accepts the following command-line flags. When deployed via Helm, these are configured through the chart values and passed as container arguments.

Flags

Core

Flag	Default	Description
`--metrics-bind-address`	`0`	Address for the metrics endpoint. Use `:8443` for HTTPS or `0` to disable.
`--health-probe-bind-address`	`:8081`	Address for the health and readiness probe endpoint.
`--leader-elect`	`false`	Enable leader election for controller manager. Required for running multiple replicas.
`--operator-name`	(none)	Helm release name. When set, the operator creates Istio ServiceEntry and DestinationRule prerequisites at startup.

TLS Certificates

Flag	Default	Description
`--metrics-cert-path`	(none)	Directory containing the metrics server TLS certificate.
`--metrics-cert-name`	`tls.crt`	Filename of the metrics certificate.
`--metrics-cert-key`	`tls.key`	Filename of the metrics private key.

RuleSet Cache

Flag	Default	Description
`--cache-gc-interval`	`5m`	How often to check for and remove stale cache entries.
`--cache-max-age`	`24h`	Maximum age before a cache entry is considered stale.
`--cache-max-size`	`104857600` (100 MB)	Maximum total size of all cached rules in bytes.
`--cache-server-port`	`18080`	Port for the RuleSet cache HTTP server.
`--envoy-cluster-name`	(required)	Envoy cluster name pointing to the cache server.

Istio Integration

Flag	Default	Description
`--istio-revision`	(none)	Istio revision label value for managed Istio resources.
`--default-wasm-image`	Built-in default	OCI reference for the Coraza WASM plugin used when an Engine omits the `image` field. Can also be set via the `CORAZA_DEFAULT_WASM_IMAGE` environment variable.

Environment Variables

Variable	Required	Description
`POD_NAMESPACE`	Yes	The namespace in which the operator is running. Typically set via the Kubernetes downward API.
`CORAZA_DEFAULT_WASM_IMAGE`	No	Override the default WASM plugin OCI image. Equivalent to `--default-wasm-image`.

Logging

The operator uses Zap via controller-runtime. Logging behavior is controlled through Helm values rather than direct CLI flags:

Using the OWASP CoreRuleSet

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

The OWASP CoreRuleSet (CRS) is a widely used set of attack detection rules for ModSecurity-compatible WAFs. The kubectl-coraza plugin can generate RuleSource, RuleData, and RuleSet manifests from CRS rule files.

Important

This project does not provide, maintain, or support CoreRuleSet rules. Users must supply their own rules. The tools described here are provided for convenience.

Install the kubectl-coraza Plugin

Build the plugin from the operator repository:

git clone https://github.com/networking-incubator/coraza-kubernetes-operator.git
cd coraza-kubernetes-operator
make build

This produces bin/kubectl-coraza. Copy it to a directory on your PATH:

Status Conditions and Troubleshooting

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

Both Engine and RuleSet resources report their state through standard Kubernetes conditions. This page describes each condition type and provides troubleshooting guidance.

Condition Types

Type	Meaning
`Ready`	The resource has been successfully processed and is operational.
`Progressing`	The resource is being created or updated.
`Degraded`	The resource failed to reach or maintain its desired state.

Each condition includes:

status: True, False, or Unknown
reason: A programmatic identifier (CamelCase) explaining the condition.
message: A human-readable description.
lastTransitionTime: When the condition last changed.
observedGeneration: The resource generation that was observed.

Engine Conditions

Accepted

The Engine’s target Gateway has been validated. Only one Engine may target a given Gateway at a time. When multiple Engines reference the same Gateway, the oldest one (by creation timestamp) wins; if timestamps are equal, the lexicographically first name wins. The losing Engines receive Accepted=False.

Using Data Files with Rules

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

Some SecLang rules use the @pmFromFile directive to match against patterns stored in external data files. The Coraza Kubernetes Operator provides these files from RuleData resources, referenced by the RuleSet spec.data list.

When to use data files

Use data files when your rules reference @pmFromFile. For example:

SecRule ARGS "@pmFromFile bad-patterns.data" \
 "id:3001,phase:2,deny,status:403,msg:'Blocked pattern detected'"

This rule reads patterns from a file named bad-patterns.data. Store that file in a RuleData spec.files map (filename → content).

Configuring Failure Policies

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

The Engine failurePolicy field determines how traffic is handled when the WAF is not ready or encounters an error during rule evaluation.

Available Policies

Policy	Behavior
`fail` (default)	Block all traffic when the WAF is not ready or encounters an error. This prioritizes security.
`allow`	Allow traffic through when the WAF is not ready or encounters an error. This prioritizes availability.

Setting the Failure Policy

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: Engine
metadata:
 name: my-engine
spec:
 failurePolicy: fail
 ruleSet:
 name: my-ruleset
 target:
 type: Gateway
 name: my-gateway
 provider: Istio

When to Use Each Policy

Use `fail` when:

Security is the highest priority.
You prefer to block traffic rather than risk allowing unfiltered requests.
The application behind the Gateway can tolerate brief outages during WAF startup or rule updates.

Use `allow` when:

Availability is the highest priority.
You prefer to serve traffic unfiltered rather than block it during WAF startup.
The WAF provides defense-in-depth alongside other security controls.

Changing the Policy

You can change the failure policy on an existing Engine at any time:

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:

Monitoring with Prometheus

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

The Coraza Kubernetes Operator exposes Prometheus metrics over HTTPS for monitoring the RuleSet cache server.

Enabling the Metrics Endpoint

Metrics are enabled by default. The endpoint is served over HTTPS on port 8443 with TLS 1.3 and requires authentication via a Kubernetes ServiceAccount token.

To disable metrics:

# values.yaml
metrics:
 enabled: false

Enabling the ServiceMonitor

If you use the Prometheus Operator, enable the ServiceMonitor to automatically discover the metrics endpoint:

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
`waf.k8s.coraza.io` rulesources, ruledata	get, list, watch	Read SecLang and data file content for RuleSet reconciliation.
Pods	list, watch	Discover Gateway pods matching Engine target names.
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)	get, list, watch	Discover and validate Gateways for Engine target resolution.
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.

Upgrading the Operator

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

Upgrading with Helm

To upgrade to the latest version:

helm repo update
helm upgrade coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system

To upgrade to a specific version:

helm upgrade coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system \
 --version 0.3.0

Helm automatically applies any CRD changes included in the new chart version.

Upgrading on OpenShift (OLM)

If you installed the operator through OperatorHub with automatic approval, OLM handles upgrades automatically when new versions are published to the catalog.

Coraza Kubernetes Operator

API Reference

Packages

waf.k8s.coraza.io/v1alpha1

Resource Types

DataReference

DriverConfig

Architecture

High-Level Overview

Getting Started on Kubernetes

Prerequisites

Step 1: Install the Operator

Install on Kubernetes with Helm

Prerequisites

Install from the Helm Repository

Pin a Specific Version

Install on OpenShift

Prerequisites

Enable Gateway API

Creating Firewall Rules

Writing rules in RuleSources

Getting Started on OpenShift

Prerequisites

Enable Gateway API

Helm Chart Values

Values Reference

Platform Requirements

OpenShift Values Example

Rule Processing

Rule aggregation

Deploying a WAF Engine

Creating an Engine

Selecting a Gateway

kubectl-coraza CLI

Installation

Commands

kubectl coraza generate coreruleset

Istio WASM Integration

How Istio WasmPlugin Works

The coraza-proxy-wasm Plugin

Operator CLI Flags

Flags

Core

TLS Certificates

RuleSet Cache

Istio Integration

Environment Variables

Logging

Using the OWASP CoreRuleSet

Install the kubectl-coraza Plugin

Status Conditions and Troubleshooting

Condition Types

Engine Conditions

Accepted

Using Data Files with Rules

When to use data files

Configuring Failure Policies

Available Policies

Setting the Failure Policy

When to Use Each Policy

Use fail when:

Use allow when:

Changing the Policy

Known Limitations

Overview

Operator Behavior

Monitoring with Prometheus

Enabling the Metrics Endpoint

Enabling the ServiceMonitor

Security Model

RBAC Permissions

Cluster-Scoped Permissions (ClusterRole)

Namespace-Scoped Permissions (Role)

Upgrading the Operator

Upgrading with Helm

Upgrading on OpenShift (OLM)

`kubectl coraza generate coreruleset`

Use `fail` when:

Use `allow` when: