README
¶
Coraza Kubernetes Operator
Web Application Firewall (WAF) support for Kubernetes Gateways.
About
The Coraza Kubernetes Operator (CKO) enables declarative management of Web
Application Firewalls (WAF) on Kubernetes clusters. Users can deploy
firewall engines which are attached to Gateways, and rules which those
engines enforce.
Coraza is used as the firewall engine.
Key Features
EngineAPI - declaratively manage WAF instancesRuleSetAPI - declaratively manage firewall rules (via orderedRuleSourceandRuleDatareferences)RuleSourceAPI - store SecLang rules consumed by aRuleSetRuleDataAPI - store data files (e.g. for@pmFromFile) consumed by aRuleSet- ModSecurity Seclang compatibility
Supported Platforms
The operator is designed to run on:
- Kubernetes: v1.32+
- OpenShift Container Platform (OCP): v4.20+
Supported Integrations
The operator integrates with other tools to attach WAF instances to their gateways/proxies:
istio- Istio integration ✅ Currently Supported (ingress Gateway only)wasm- WebAssembly deployment ✅ Currently Supported
Note: Only Istio+WASM is supported currently.
Architecture
RuleSet resources list named RuleSource objects in spec.sources (order
matters) for Seclang rule text, and optional RuleData objects in spec.data
for data files used with @pmFromFile. The reconciler emits the merged result
to the RuleSet cache server.
Note: Currently, only Seclang rules are supported.
The RuleSet cache contains the compiled and validated set of rules, which
is pulled by Engines.
Engine resources pick a RuleSet to enforce, and attach the Coraza WAF
to a Gateway, which will then enforce the configured RuleSet.
Warning: Hosting or providing any packaged rules is an explicit non-goal of this project. Users must supply their own rules.
The keys for the cache are the namespace/name of the RuleSet, allowing the
compiled set of rules to be polled from a cache server hosting the cache.
Note: All
RuleSetsand rules are restricted to same-namespace currently.
The engine controller responds to Engine resources by deploying the Coraza
engine according to the type and mode provided, and attaching it to a Gateway.
Note: For example: if the type is
istioand the mode iswasm, it will attach Coraza to an IstioGateway, loading it via a WASM module.
Engine resources target a RuleSet to indicate the firewall rules that will
be applied to all Gateway traffic. Poll intervals for RuleSets can be set
to enable automatic and live rule updates on running Engines.
Documentation
Documentation is available at the project documentation site.
Development
See DEVELOPMENT.md for build instructions, test suites, and the source-of-truth / generation pipeline reference.
Contributing
Contributions are welcome!
Please see the CONTRIBUTING.md guide before you get started.
License
Apache License 2.0 - see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
v1alpha1
Package v1alpha1 contains API Schema definitions for the waf v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the waf v1alpha1 API group. |
|
cmd
|
|
|
kubectl-coraza
command
kubectl-coraza is a kubectl plugin (kubectl coraza …) for generating RuleSet-related manifests from OWASP CoreRuleSet files on disk.
|
kubectl-coraza is a kubectl plugin (kubectl coraza …) for generating RuleSet-related manifests from OWASP CoreRuleSet files on disk. |
|
manager
command
|
|
|
internal
|
|
|
controller
Package controller implements Kubernetes controllers for WAF resources.
|
Package controller implements Kubernetes controllers for WAF resources. |
|
defaults
Package defaults holds operator-wide default values (e.g.
|
Package defaults holds operator-wide default values (e.g. |
|
rulesets
Package rulesets provides rule analysis utilities for the operator.
|
Package rulesets provides rule analysis utilities for the operator. |
|
rulesets/cache
Package cache provides in-memory caching for WAF rulesets.
|
Package cache provides in-memory caching for WAF rulesets. |
|
rulesets/memfs
Package memfs implements a simple, thread-safe in-memory filesystem
|
Package memfs implements a simple, thread-safe in-memory filesystem |
|
test
|
|
|
framework
Package framework provides integration test utilities for the Coraza Kubernetes Operator.
|
Package framework provides integration test utilities for the Coraza Kubernetes Operator. |
|
utils
Package utils provides testing utilities for integration and unit tests.
|
Package utils provides testing utilities for integration and unit tests. |
|
tools
|
|
|
corerulesetgen
Package corerulesetgen turns OWASP CoreRuleSet rule files on disk into Kubernetes RuleSource (SecLang rules), RuleData (data files), and RuleSet manifests matching the operator's v1alpha1 API.
|
Package corerulesetgen turns OWASP CoreRuleSet rule files on disk into Kubernetes RuleSource (SecLang rules), RuleData (data files), and RuleSet manifests matching the operator's v1alpha1 API. |