flowchart LR
C["Client"] -->|"1 · TCP SYN"| XDP
XDP["XDP at NIC:<br/>allow/deny + flood check"] --> BT{"Ban table:<br/>repeat offender?"}
BT -->|hit| DROP["Drop, ~1 µs"]
BT -->|miss| VC{"Verdict cache:<br/>verdict known?"}
VC -->|"known or new"| PASS["Pass — flow marked"]
click PASS "#fig-gateway" "On to the gateway"
Trishula
An eBPF-native, developer-first Web Application and API Firewall for Kubernetes
What Trishula is
Trishula is a web application and API firewall for Kubernetes. The install is three workloads, driven by Helm and kubectl apply:
trishula-shield— a DaemonSet. It attaches eBPF programs at two kernel altitudes:- XDP runs on every node NIC. It drops L3/L4 abuse: IP ACLs, SYN/UDP-flood tarpits, repeat-offender bans, cached verdicts. The decision cost is about 1 µs per packet.
- TC runs on the engine-node interfaces. It classifies flows, counts rate windows and publishes ring-buffer events. The events carry metadata only.
trishula-engine— a Deployment, a plain Service behind anHTTPRoute. It runs the full HTTP inspection ladder in userspace:- OWASP CRS via embedded Coraza.
- developer-written CEL rules, cost-budgeted.
- OpenAPI positive security: blocks what the route schema does not declare.
- JA4 + header + behavioural bot detection.
- per-route rate limits.
- the scored temporary-ban engine: the fail2ban model, re-specified for HTTP, kernel-enforced.
trishula-operator— a Deployment. It reads the four CRDs (WAFPolicy,APISpec,RuleSet,BanPolicy). It compiles signed bundles: evaluator chains, a Vectorscan matcher DB for the hot regex subset. The bundles carry kernel map values and ban thresholds. Hot reload runs within 5 s. Rollback re-pins the previous bundle and records the re-pin in the CRD.
What the developer writes: a CEL rule over the structured request view. Example: request.method == "POST" && path.matches("/v1/chat/*") && size(request.body.?json.messages) > 128. Also the OpenAPI spec the API already has. Also the 4 YAML CRDs. No proprietary rule language. No vendor console. No sidecar config files.
What it stops:
- credential stuffing: auth-failure ratios + JA4 spread → scored bans.
- request smuggling: strict normalization + the differential corpus (11.8).
- slowloris and connection starvation: kernel flow counters; per-request WAFs cannot see them.
- DoS on expensive AI endpoints: per-route rate ladders + ban escalation.
- prompt-injection payload abuse: the ML scorer cascade + the async judge.
- known bot and tooling masquerades: JA4 + header-order fingerprints against the pinned tooling DB.
- the OWASP Top-10: CRS 4.x, with the CI-blocking verdict-parity gate.
What it does not do:
Why this project
A web application firewall inspects HTTP traffic and decides: allow, block, rate-suppress or tag. It is also the last major security control outside developer hands. Three developments make the shift feasible now. Each alone is an optimisation. Together they open the edge:
- Gateway API consolidation. Kubernetes ingress standardises on the Gateway API. The edge is re-plumbed. The WAF integration point is open.
- eBPF maturity. Kernel-altitude packet processing is dependable, inspectable and CO-RE-portable. The cheapest decisions run where the packet arrives.
- Machine-generated traffic at the edge. Agents, scrapers and automated abuse arrive faster than hand-written signatures follow. Their fingerprints resist imitation.
Negative signatures alone cannot carry this load: the good-traffic risk is high, and hand maintenance is slow. The premise is therefore positive security, fingerprinting and behaviour analysis. Signatures are one stage among several.
Objectives
- Adoptability first — policy lives in CRDs. Per-route promotion gates run learn → shadow → enforce. The developer reads the verdict record directly.
- Kernel-altitude enforcement — signatures, positive security, bot detection and behaviour bans. eBPF holds the enforcement point. A middleware chain cannot hold that position.
- Parity before novelty — CRS runs as the reference evaluator. The CI-blocking differential suite verifies verdict parity.
- Honest engineering — fail-open defaults. An evidence record per ban. Exit criteria report pass/fail as measured.
How Trishula works
The design has two planes and one control plane. The kernel plane answers the cheap decisions. The userspace plane runs the deep checks. The operator compiles policy into both planes.
- Shield (DaemonSet, XDP/TC): ACL, verdict cache and ban table, enforced where the packet arrives; fail-open by default.
- Engine (Deployment): the detection ladder S0–S7 (2.3). The stages in walk order: kernel verdict hits; the Vectorscan hot subset; OWASP CRS via embedded Coraza. Then: CEL rules under cost budgets; OpenAPI positive security; bot fingerprints and behaviour. Last: rate limits with kernel-enforced bans; the ML scorer.
- Operator (Deployment): compiles
WAFPolicy/BanPolicyCRs into engine bundles and pre-seeds the shield maps. Rollback is a CRD-recorded re-pin.
Each verdict is a correlated OpenTelemetry record (trishula.verdict.v2). Dashboards ship in-repo.
The packet path, end to end
Five views follow one request from the wire to the app pool and back. The views: the kernel plane, the gateway and the engine node, the ladder, the verdicts and the state returns. The canonical records: the request lifecycle, the ladder semantics, the two-plane principle, the ban algorithm and the telemetry contract.
- The client sends TCP. XDP at the NIC reads the IP allow/deny list and the flood state (the kernel plane).
- The ban table drops repeat offenders at line rate, about 1 µs per packet. The verdict cache answers known flows without engine work.
- The gateway terminates TLS, matches the HTTPRoute, and steers
trishula-engine(the gateway figure). Any conformant gateway steers the same way. - Engine-node veths carry the flow. TC tags the flow and publishes ring-buffer events. The events carry metadata only.
- The engine reconstructs HTTP/1.1, h2, gRPC and WebSocket. The output is the structured request view.
- The ladder walks S0 to S7 over one compiled bundle (the ladder table). The first decisive verdict short-circuits the walk. The action order: block, challenge, log, pass.
allowforwards upstream.blockanswers a local 403. A ban answers 429 withRetry-Afterplus an evidence record.challengeissues a 429 with a signed redirect (the challenge ships TR-197).logandshadowmark and continue (the verdict figure).- The response chain re-inspects: CRS phase 4, exfiltration checks, streaming-aware.
- ScoredWindowBan watches score breaches. The promotion path runs shadow first.
- A promoted ban lands in the kernel ban table. The next packet pays the kernel price. The engine also back-fills verdicts to the cache.
- Every step emits one OTel span. The verdict record carries rule IDs, phase and the score ladder (the state figure).
flowchart LR
PASS["Pass — flow marked"] -->|"2 · TCP continues"| GW["NGF Gateway:<br/>TLS ends, steers"]
GW -->|"plaintext hop"| ENG["trishula-engine:<br/>transparent proxy"]
subgraph EN["4 · Engine node"]
TC["TC tap at veth:<br/>classify + counters"] -.->|events| RB["Ring buffer:<br/>flow events"]
end
RB -.->|drain| ENG
ENG -->|"5 · reconstruct<br/>HTTP/1.1 · h2 · gRPC · WS"| RV["Structured<br/>request view"]
click RV "#fig-ladder" "On to the ladder walk"
click PASS "#fig-kernel" "Back to the edge"
| # | Stage | What it reads | Source |
|---|---|---|---|
| S0 | kernel hits | the ban table + the verdict cache; a hit settles at ~1 µs | kernel maps |
| S1 | Vectorscan | the compiled hot-subset matcher | the operator’s bundle |
| S2 | CRS | the OWASP Core Rule Set through embedded Coraza | the CRS bundle |
| S3 | CEL rules | the developer’s rules over the structured request view | RuleSet CR |
| S4 | OpenAPI schema | the route’s declared shapes only (positive security) | APISpec CR |
| S5 | bots | JA4 + header fingerprints + behavioural windows | the shield + TLS hop |
| S6 | rate windows | per-route counters; breaches + ban events | the kernel counters |
| S7 | ML scorer | the local ONNX score + the async judge | MLModel bundle |
flowchart LR
VD{"Verdict"} -->|allow| VA["Forward"] --> POOL["App + model pools"]
POOL -->|"8 · response"| RP["Response:<br/>phase 4 + exfil"] -->|to client| OUT["Back to client"]
VD -->|block| VB["Local 403"]
VD -->|ban| VN["429 + Retry-After"]
VD -->|challenge| VCh["Challenge:<br/>429 + signed redirect"]
VD -->|"log / shadow"| VL["Continue"]
VB -->|respond| OUT
VN -->|respond| OUT
VCh -->|respond| OUT
VL -.->|continue| VA
click OUT "#fig-kernel" "Back to the edge"
click VD "#fig-ladder" "Back to the ladder"
flowchart LR
subgraph SRC["9–11 · every verdict writes state"]
S6X["S6 · score breach"]
VX["Verdict node"]
LDX["Every step"]
end
SWB["ScoredWindowBan v1:<br/>shadow, then enforce"]
S6X -.->|breach| SWB
DOS["Shield runner<br/>(flow_stats sweep → cue)"] -.->|"cues"| SWB
SWB -.->|"10 · ban push"| KB["Kernel ban<br/>table"]
VX -.->|"10 · backfill"| KC["Kernel verdict<br/>cache"]
LDX -.->|"11 · records"| TEL[("OTel:<br/>trishula.verdict.v2")]
subgraph CP["trishula-operator"]
CRD["CRDs: WAFPolicy · APISpec<br/>RuleSet · BanPolicy"] --> COMP["Compiler:<br/>bundles + map values"]
end
COMP -->|"reload, 5 s"| ENG["Engine"]
COMP -.->|"map pre-seed"| KB
click KB "#fig-kernel" "The kernel plane"
click ENG "#fig-gateway" "The engine"
Deployment model
flowchart TB
subgraph cluster["Kubernetes cluster"]
subgraph gwplane["gateway plane"]
ngf["NGF (Gateway API)"]
end
subgraph wafplane["Trishula"]
eng["engine deployment<br/>(plain backend Service)"]
opr["operator<br/>(WAFPolicy / BanPolicy CRDs)"]
sh["shield DaemonSet<br/>(XDP/TC eBPF)"]
end
app["application pods"]
end
clients["clients"] --> ngf
ngf -- HTTPRoute --> eng
eng --> sh
eng --> app
opr -- bundles + map pre-seed --> eng
opr -- pinned maps --> sh
- Install order: operator → shield (DaemonSet) → engine. The operator compiles the CRs into engine bundles (double-buffered) and pre-seeds the shield maps.
- Gateway API integration: the gateway steers to the engine as a plain backend (
HTTPRoute). NGF is the reference data plane; the whole reference stack is OSS. Conformant alternatives (Envoy Gateway, Istio, Traefik, Emissary, kgateway) attach the same way. Theext_procwire-contract variant for Envoy-family estates is planned, not shipped. - Fail-open by default: the inline shaper never becomes the outage.
failureModeis explicit and audited per policy. - Rollback: a CRD-recorded re-pin of the previous bundle. The operation needs no manual intervention.
- Node requirements: kernel 5.8+; the shield is CO-RE and verifier-checked in CI.
- Telemetry: every verdict is one OTLP span + metric + log on
trishula.verdict.v2; dashboards ship in-repo.
Detection ladder (2.3; short-circuit on the first decisive verdict). The stages: S0 kernel hits (bans + cached verdicts) → S1 Vectorscan hot subset → S2 CRS via embedded Coraza. Later: S3 CEL rules → S4 OpenAPI positive security → S5 bot evidence. Last: S6 rate windows + ban events → S7 ML scorer (local ONNX + async judge). ScoredWindowBan turns repeated abuse into kernel-enforced temporary bans. The bans carry evidence records. Prefix escalation stays off by default.
Design rationale
- eBPF, XDP first — the only mechanism with kernel-altitude, programmable and verifiable packet policy on stock Kubernetes nodes. CO-RE keeps builds portable. Enforcement runs where the packet arrives; a middleware chain cannot reach that position.
- Gateway API, NGF as the reference — NGF keeps the whole reference deployment OSS. Envoy-family estates get the
ext_procvariant later. Single-data-plane lock-in is a non-goal. - Embedded Coraza — CRS compatibility is the adoption surface. Embedding gives parity by construction. The differential suite keeps the fast path honest.
- CEL as the first-class DSL — typed, cost-budgeted evaluation; Kubernetes-native tools read it natively. The compiler gates on cost before load. A general regex DSL cannot bound evaluation cost.
- OpenAPI positive security with promotion gates — the specs already exist in application repositories. The learn → shadow → enforce path makes adoption incremental.
- ScoredWindowBan over naive counters — fail2ban-style bans with an algorithmic score window and an evidence record per ban. Prefix escalation stays off by default; shared-egress false positives are the ban-tooling failure to avoid.
- OpenTelemetry as the verdict contract — every verdict is a correlated span + metric + log. Security that cannot show its work does not gain developer adoption.
- Fail-open by default —
failureModeis explicit and audited per policy.
Education and adoption
Security technology spreads when adoption gets simpler, not when tooling grows more powerful. The precedents:
| Precedent | What was hard | What carried adoption |
|---|---|---|
| Let’s Encrypt | PKI was expert work; certificates cost time and money | One command (certbot); automation; free certificates |
| fail2ban | log analysis and blocking were manual work | One daemon watched logs and banned offenders automatically |
| Caddy / nginx + cert-manager | TLS termination was hand-configured per service | Convention-first configs made correct TLS the default |
| OWASP CRS | WAF rules lived inside vendor products | An open, community rule set made signature quality inspectable |
| Kubernetes Gateway API | every edge carried its own config dialect | Standard CRDs made edge policy portable and reviewable |
The education programme is the adoption mechanism:
- Academy modules with runnable labs (TR-27, TR-28) — the wire, TLS, eBPF, security modeling. Each module is a hands-on lab against a live cluster.
- The 15-minute gate (TR-23, metric M3) — clone → first enforced rule in ≤ 15 minutes, timed nightly in CI. A regression stops the release.
- Copy-paste-first policy recipes — every lab ships the exact YAML a developer would commit.
- Promotion gates as the adoption path — learn → shadow → enforce is a safety mechanism and the adoption journey together. Each stage has a lab.
- Verdict telemetry a developer reads — one correlated OTel record per request. The schema (
trishula.verdict.v2) is documented like the API it is. - Honest exit criteria — every release states what works and what does not.
The audience: the application developer and platform engineer who runs Kubernetes. Documentation, labs and error messages read at that level first.
Adversarial test coverage
The adversarial program runs the CRS corpus, the evasion batteries and the engine-differential at two stages. Every merge runs the per-PR gate. The release cut runs the release suite (TR-205). Each number in the table cites its recorded run; the verbatim receipts sit on the TR-205 record. The numbers re-read at each release.
| Layer | Coverage | Verdict |
|---|---|---|
| CRS parity (the differential gate) | 20/20 rows, two runs | pass |
| Enforcement pin (WH-SQLI-001) | 403 + the rule id on the wire | pass |
| waf-bypass battery | 756 legs passed of 6789, 0 bypassed, 0 falsed | pass |
| CRS detection record (the shadow stage) | 160/182 block rows detected | record |
| Shield hook loads (the spike) | 4/4 hook classes loaded on the runner kernel | pass |
| goTestWAF full corpus + sqlmap + open-appsec | pending the first rehearsal (#293) | pending |
The live table lives on the repo README; this index carries the summary.
Roadmap
Work is tracked on the Trishula — Roadmap board as issues in the trishula repo. Every issue lands a runnable artefact with an exit criterion. The records prove the ladder end to end.
| Milestone | Items |
|---|---|
| 2026.01-rc1 | TR-01–TR-14: repo seed, CEL seed, shield PoC, ingest, ladder slice, NGF lab, CRS differential, operator/CRD, ban shadow + enforce, OTel, bots v0, positive v0, honest exit |
| 2026.01-rc2 | TR-15–TR-26: HTTP/2+gRPC, Vectorscan, CEL hot reload, OpenAPI learn, behavioural bots, rate limits, ONNX scorer, ext_proc, DX gate, bench, multi-tenancy, Envoy lane |
| 2026.01-rc3 | TR-27–TR-36: academy, HTTP/3 + PQ posture (evaluation only), behavioural DoS, DPU, multi-arch, residue gate, composition watch |
| 2026.01 (GA) (release) | TR-194–TR-203: the TLS-termination lane — the QUIC kernel abuse class (PR), the QUIC-ingress lab (PR), the inline H3 listener (PR), the X25519MLKEM768 profile (PR), the JA4/PQC corpus (PR); the stage stamps (PRs #245, #274); the JWT stage (PR #269); the protocol conformance rejects (PR #267); the manual ban rule (PR #248); the shield DoS runner (PR #249); the DoS signature (PR #250); the consult signals (PR #252); the challenge hop (PRs #256, #258) |
| post-GA — in progress | TR-205: the WAF adversarial test program — the harness (PR), the libinjection record (PR), the shield hook spike (PR), the per-PR gate (PR), the release suite (PR), the README ledger (PR); the release-suite rows read pending until their first release-cut run. Also: TR-201 — kTLS Mode A, and TR-202 — the DPU shape (both carry the 2026.03 ruling) |
| research | TR-39–TR-41: the socket-plane L7 fast path study (Beeline), the WAFPolicy→eBPF compiler spike, the kernel-altitude TLS posture (§9.7, §9.9) |
Contributions follow the contributing guide. Pick an issue labelled complexity:starter, or any area:* that fits. The issue body carries the design source. Branch + PR against trishula-dev/trishula (MIT).
Project documents
The security policy covers vulnerability reporting, supported versions and disclosure. The contributing guide covers branching, commit conventions, signing and CI gates. The code of conduct governs participation. The coding-agents guide mirrors AGENTS.md; it is the source of truth for humans and coding agents on the repo. The full product specification is the spec in the main repo.
Paper
Download the research paper (PDF) — 19 pp (abstract, keywords, contents, numbered references). The arXiv link lands here when the paper is archived.
The site’s research companion = the research paper (*“Trishula: An eBPF-Native, Developer-First Web Application and API Firewall for Kubernetes”). It carries the adoptability thesis, the field survey and the adoption plan. The survey covers Coraza, ModSecurity, SafeLine, open-appsec, CrowdSec, fail2ban and the eBPF cousins, with the feature-coverage matrix. A public link lands here when the paper is archived; until then the paper lives in the project docs.



