Documentation
How to run, configure and operate Light WAF — from a single waf binary in front of one backend to a governed fleet with a control plane. These docs cover version 1.0.2(changelog).
Start here
- Quickstart — install the
wafbinary, point it at your backend, and see it block. - Concepts — how a request is judged: the anomaly score, the block threshold, verdicts.
- Full stack — run the WAF, the control plane and the node agent together.
The three services
A single node needs only the WAF. A fleet adds up to two more services, neither of them on the request path:
| Service | Binary | Role | Request path? |
|---|---|---|---|
| WAF proxy | waf or waf-enterprise | Terminates traffic, inspects every request, allows or blocks. waf is the core; waf-enterprise adds the at-scale components. | Yes |
| Control plane | waf-controlplane | Collects telemetry, serves the dashboard and API, governs rules and users. | No |
| Node agent | waf-node-agent | Pulls published rulesets onto each WAF node and triggers a reload. | No |
Reference
- Configuration — the core config file, section by section.
- Detection modules — what each module catches, and how requests are scored.
- At-scale components — the
[enterprise.*]tables: Redis state, managed TLS, reputation, curated rules, schema enforcement, bot detection, signed plugins, request capture.
Operate
- Control plane & dashboard — configuration, telemetry, the dashboard tour, alerting, the API.
- Rule management — publish and roll back ruleset versions, the node agent, convergence.
- Governance — RBAC, users, service tokens, sessions, OIDC SSO, the signed audit log.
- Compliance & SIEM — signed SOC2/PCI evidence bundles and the SIEM feed.
- Operations — reloads, the failure posture, monitoring, backups, troubleshooting.
- Kubernetes — Helm charts, the
WafProxyoperator, capture on k8s.
Secrets
Every service reads its secrets from environment variables that override the config file, so the .toml files can be committed safely.
| Env var | Used by | What it is |
|---|---|---|
WAF_REDIS_URL | proxy | Redis connection for cluster-wide rate limit / reputation |
WAF_CERT_STORE_KEY | proxy | encrypts the ACME private key at rest (clustered DNS-01) |
WAF_CAPTURE_TOKEN | proxy | ingest bearer for shipping captured requests (matches WAF_CP_API_TOKEN) |
CF_API_TOKEN, AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | proxy | DNS-01 provider credentials |
WAF_CP_DATABASE_URL | control plane | Postgres connection string |
WAF_CP_API_TOKEN | control plane | static bearer token (governance off) |
WAF_CP_AUDIT_KEY | control plane | Ed25519 seed (64 hex) signing the audit chain — must persist |
WAF_CP_BOOTSTRAP_ADMIN_PASSWORD | control plane | initial admin password, used once |
WAF_CP_OIDC_CLIENT_SECRET | control plane | OIDC client secret |
WAF_CP_SIEM_AUTH_<NAME> | control plane | auth header for SIEM destination <name> |
WAF_AGENT_TOKEN | node agent | control-plane service token |
Crates
Fourteen crates are published on crates.io, all on version 1.0.2; API docs are on docs.rs.
| Crate | What it is | Links |
|---|---|---|
| waf-proxy | The reverse-proxy binary — cargo install it and run it as waf. | docs.rs · crates.io |
| waf-core | Base types, config, and client-IP resolution. | docs.rs · crates.io |
| waf-normalizer | Decoding, NFKC, and request parsing (anti-evasion). | docs.rs · crates.io |
| waf-pipeline | Phased orchestration and anomaly scoring. | docs.rs · crates.io |
| waf-detection | Detection modules, the CRS engine, and the fast-path prefilter. | docs.rs · crates.io |
| waf-wasm | The Proxy-Wasm plugin runtime (wasmi). | docs.rs · crates.io |
| waf-enterprise | The data-plane binary with every component wired in. | docs.rs · crates.io |
| waf-state-redis | Redis state store: cluster-wide rate limiting and shared certificates. | docs.rs · crates.io |
| waf-tls-managed | Managed TLS: ACME (TLS-ALPN-01, DNS-01), hitless rotation, mutual TLS. | docs.rs · crates.io |
| waf-threatintel | IP reputation module and the single-writer threat-intel feed. | docs.rs · crates.io |
| waf-crs-curated | Curated SecRule content: CVE, application and evasion signatures. | docs.rs · crates.io |
| waf-schema-enforcement | GraphQL, gRPC and OpenAPI schema enforcement, and bot detection. | docs.rs · crates.io |
| waf-wasm-signing | Minisign verification of WASM plugins before they load. | docs.rs · crates.io |
| waf-capture | Off-path capture of full denied requests for the drill-down. | docs.rs · crates.io |
Container images
Multi-arch (amd64 + arm64) images on the GitHub Container Registry. They run as a non-root user on a distroless base.
| Image | What it runs |
|---|---|
ghcr.io/0x00spor3/waf-enterprise:1.0.2 | The data plane: the WAF proxy with every component wired in. |
ghcr.io/0x00spor3/waf-controlplane:1.0.2 | The control plane: API, embedded dashboard and governance. |
ghcr.io/0x00spor3/waf-node-agent:1.0.2 | Pulls published rulesets onto a WAF node and triggers a reload. |
ghcr.io/0x00spor3/waf-operator:1.0.2 | The Kubernetes operator for the WafProxy custom resource. |
Verify an image
Every image is signed with cosign by the release workflow, keyless: the signature is bound to that workflow's identity and logged in the public Sigstore transparency log, and each image carries a signed SBOM. Check one before you run it:
$ cosign verify ghcr.io/0x00spor3/waf-enterprise:1.0.2 \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp '^https://github\.com/0x00spor3/Light-WAF/\.github/workflows/images\.yml@refs/(tags/v.+|heads/main)$'The SBOM attestation, and admission policies that enforce the signature in Kubernetes, are in the security policy.
Source on GitHub → · Architecture notes → · Per-feature runbooks →