Contributing

Thank you for your interest in improving kubeWAF!

Ways to Contribute

The platform spans three repositories:

Repository	Focus
kubewaf-io/kubewaf	Operator, CRDs, docs site, Helm chart
kubewaf-io/modsecurity-proxy-wasm	ModSecurity Wasm engine + CRS embedding
kubewaf-io/pow-proxy-wasm	PoW challenge filter

Report bugs and feature requests on the relevant repo’s Issues
Improve documentation (this site lives in kubewaf)
Add CRS conversions or example rules
Implement missing controller logic (especially WAFInstance)
Write tests (unit + e2e)
Review pull requests

Development Environment

Prerequisites

Go 1.26+
make, docker
kubectl + a local cluster (kind, minikube, or k3d recommended)
helm

Setup

git clone https://github.com/kubewaf-io/kubewaf.git
cd kubewaf

make manifests generate fmt vet
make install          # installs CRDs into your cluster
make run              # runs the operator locally against your kubeconfig

Useful Make Targets

Target	Description
`make test`	Run unit tests
`make test-e2e`	Run end-to-end tests (requires a real cluster)
`make lint-fix`	Auto-fix lint issues
`make crs-converter`	Build the CRS conversion tool
`make docker-build`	Build the operator image

Documentation Contributions

The documentation site is built with Fumadocs (Next.js + MDX) in the website/ directory.

To preview locally:

make docs-serve
# or:
cd website && npm install && npm run dev

Then open http://localhost:3000 (docs at ``).

Content lives in website/content. When adding pages, update the nearest meta.json sidebar file.

Docs layout:

Path	Content
`operator/`	kubeWAF guides (rules, CRS, challenge CR fields, providers)
`concepts/`, `getting-started/`, `reference/`	kubeWAF concepts and CRDs
`modsecurity-proxy-wasm/`	Related project: engine internals / standalone
`pow-proxy-wasm/`	Related project: filter internals / standalone

Style Guidelines

Keep examples copy-pasteable
Prefer "real" YAML over abstract snippets
Use <Callout type="info|warn|error"> for important caveats
Use <Cards> / <Card> for navigation grids
Use fenced mermaid code blocks for diagrams (rendered via fumadocs-mermaid / same as Gryt docs)
Link liberally to other pages

Submitting Changes

Create a topic branch from main
Make focused commits with clear messages
Run make lint-fix test before pushing
Open a Pull Request

We use conventional commit style where possible (feat:, fix:, docs:, chore:).

Code of Conduct

We follow the CNCF Code of Conduct.

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License that covers the project.

Recognition

All contributors are listed in Git history. Significant contributions may also be highlighted in release notes.

Thank you for helping make Kubernetes applications safer!

On this page