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

DriverConfig

DriverConfig defines the driver configuration for the Engine.

Exactly one driver must be specified.

Validation:

MinProperties: 0

Appears in:

EngineSpec

Field	Description	Default	Validation
`istio` IstioDriverConfig	istio configures the Engine to integrate with Istio service mesh.		MinProperties: 0 Optional: {}

Engine

Engine represents an instance of a Web Application Firewall (WAF) engine.

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:

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

Add the Helm Repository

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

Install with Default Values

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

Customize the Installation

Override default values by passing a values file or individual settings:

Install on OpenShift via OperatorHub

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

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

Prerequisites

OpenShift Container Platform v4.20 or later
Cluster administrator privileges
OpenShift Service Mesh or Istio installed with Gateway API support

Install from OperatorHub (Web Console)

Log in to the OpenShift web console as a cluster administrator.
Navigate to Operators > OperatorHub.
Search for Coraza Kubernetes Operator.
Select the operator tile and click Install.
Choose the update channel, installation mode, and approval strategy.
Click Install and wait for the operator to reach the Succeeded phase.

Install from OperatorHub (CLI)

If the operator is available in your cluster’s default catalog, create a Subscription resource:

Creating Firewall Rules

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

Firewall rules in the Coraza Kubernetes Operator are written using ModSecurity SecLang syntax, stored in ConfigMaps, and aggregated by a RuleSet resource.

Writing Rules in ConfigMaps

Each ConfigMap must contain a key named rules with SecLang directives as its value.

A basic ConfigMap with Coraza engine configuration:

apiVersion: v1
kind: ConfigMap
metadata:
 name: base-rules
data:
 rules: |
 SecRuleEngine On
 SecRequestBodyAccess On
 SecResponseBodyAccess Off
 SecAuditLog /dev/stdout
 SecAuditLogFormat JSON
 SecAuditEngine RelevantOnly

A ConfigMap 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
OpenShift Service Mesh or Istio installed with Gateway API support
The oc CLI configured to access your cluster
Cluster administrator privileges

Step 1: Install the Operator

You can install the Coraza Kubernetes Operator using either the OpenShift web console or the CLI.

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.istio.wasm.image`. When empty, uses the operator’s built-in default.
`createNamespace`	bool	`true`	Create the release namespace as a chart-managed resource with Pod Security Standard labels.
`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 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.

Deploying a WAF Engine

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

An Engine resource references a RuleSet and attaches the Coraza WAF to one or more Gateways via an Istio WasmPlugin.

Creating an Engine

The minimum Engine configuration requires a RuleSet reference and a workload selector that matches your Gateway:

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: Engine
metadata:
 name: my-engine
spec:
 ruleSet:
 name: my-ruleset
 driver:
 istio:
 wasm:
 mode: gateway
 workloadSelector:
 matchLabels:
 gateway.networking.k8s.io/gateway-name: my-gateway
 ruleSetCacheServer:
 pollIntervalSeconds: 15

Selecting a Gateway

The workloadSelector determines which Gateway pods the WAF attaches to. Kubernetes Gateway API implementations typically label Gateway pods with gateway.networking.k8s.io/gateway-name. Use the label that matches your Gateway:

kubectl-coraza CLI

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

kubectl-coraza is a kubectl plugin for generating Kubernetes manifests from OWASP CoreRuleSet files.

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 Kubernetes ConfigMaps, a Secret, and a RuleSet resource from CoreRuleSet rule files.

Required Flags

Flag	Description
`--rules-dir`	Directory containing CoreRuleSet `.conf` and optional `.data` files. The directory is not traversed recursively.
`--version`	CoreRuleSet version (e.g., `4.24.1` or `v4.24.1`). The leading `v` is normalized automatically.

Optional Flags

Flag	Default	Description
`-n`, `--namespace`	(none)	Set `metadata.namespace` on all generated objects.
`--ruleset-name`	`default-ruleset`	Name of the generated RuleSet resource.
`--data-secret-name`	`coreruleset-data`	Name of the generated Secret for `*.data` files.
`--ignore-rules`	(none)	Comma-separated rule IDs to exclude from generated output.
`--ignore-unsupported-rules`	`wasm`	Unsupported-rule profile to exclude. Set to `none` to include all rules.
`--ignore-pmFromFile`	`false`	Strip SecRule lines that use the `@pmFromFile` directive.
`--include-test-rule`	`false`	Append the X-CRS-Test rule block to the base-rules ConfigMap. Used by conformance tests.
`--name-prefix`	(none)	Prefix for generated ConfigMap names.
`--name-suffix`	(none)	Suffix for generated ConfigMap names.
`--dry-run`	(none)	Set to `client` for preview output without cluster access.
`--skip-size-check`	`false`	Allow oversized payloads. Not recommended – etcd may still reject large objects.

Output

The command writes YAML to stdout. Each generated object is separated by ---.

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 Kubernetes ConfigMaps and RuleSet resources 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

Ready

The Engine is deployed and attached to one or more Gateways.

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 supports this through Secrets of type coraza/data.

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. To make this file available to the operator, store it in a Secret.

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
 driver:
 istio:
 wasm:
 mode: gateway
 workloadSelector:
 matchLabels:
 gateway.networking.k8s.io/gateway-name: my-gateway
 ruleSetCacheServer:
 pollIntervalSeconds: 15

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
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.

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

DriverConfig

Engine

Architecture

High-Level Overview

Getting Started on Kubernetes

Prerequisites

Step 1: Install the Operator

Install on Kubernetes with Helm

Prerequisites

Add the Helm Repository

Install with Default Values

Customize the Installation

Install on OpenShift via OperatorHub

Prerequisites

Install from OperatorHub (Web Console)

Install from OperatorHub (CLI)

Creating Firewall Rules

Writing Rules in ConfigMaps

Getting Started on OpenShift

Prerequisites

Step 1: Install the Operator

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

Required Flags

Optional Flags

Output

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

Ready

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

`kubectl coraza generate coreruleset`

Use `fail` when:

Use `allow` when: