Skip to main content

Trishula

An eBPF-native, developer-first Web Application and API Firewall for Kubernetes

Licence: MIT Latest OpenSSF Scorecard OpenSSF Best Practices

What Trishula is

Trishula is a web application and API firewall for Kubernetes. The install is three workloads, driven by Helm and kubectl apply:

  1. 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.
  2. trishula-engine — a Deployment, a plain Service behind an HTTPRoute. 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.
  3. 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:

  • no service mesh.
  • no secrets vault.
  • no endpoint picker.
  • no web console: the OTel backend is the console.
  • no HTTP/3 claim (TR-29).
  • performance numbers carry the “target” label until the benchmark plan (TR-24) measures them.

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

  1. Adoptability first — policy lives in CRDs. Per-route promotion gates run learn → shadow → enforce. The developer reads the verdict record directly.
  2. Kernel-altitude enforcement — signatures, positive security, bot detection and behaviour bans. eBPF holds the enforcement point. A middleware chain cannot hold that position.
  3. Parity before novelty — CRS runs as the reference evaluator. The CI-blocking differential suite verifies verdict parity.
  4. 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/BanPolicy CRs 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.

  1. The client sends TCP. XDP at the NIC reads the IP allow/deny list and the flood state (the kernel plane).
  2. The ban table drops repeat offenders at line rate, about 1 µs per packet. The verdict cache answers known flows without engine work.
  3. The gateway terminates TLS, matches the HTTPRoute, and steers trishula-engine (the gateway figure). Any conformant gateway steers the same way.
  4. Engine-node veths carry the flow. TC tags the flow and publishes ring-buffer events. The events carry metadata only.
  5. The engine reconstructs HTTP/1.1, h2, gRPC and WebSocket. The output is the structured request view.
  6. 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.
  7. allow forwards upstream. block answers a local 403. A ban answers 429 with Retry-After plus an evidence record. challenge issues a 429 with a signed redirect (the challenge ships TR-197). log and shadow mark and continue (the verdict figure).
  8. The response chain re-inspects: CRS phase 4, exfiltration checks, streaming-aware.
  9. ScoredWindowBan watches score breaches. The promotion path runs shadow first.
  10. 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.
  11. Every step emits one OTel span. The verdict record carries rule IDs, phase and the score ladder (the state figure).
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"
Figure 1: The kernel plane: the packet filter on the network card. The checks cost about 1 µs per packet. A known flow never reaches the gateway.
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"
Figure 2: The gateway and the engine node: the gateway ends TLS and steers protected routes. The tap classifies the flow and streams metadata to the engine; the request view enters the ladder.
# 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
Figure 3: The first decisive verdict short-circuits the walk; the action order: block, challenge, log, pass (2.3). Most requests pass at the kernel or matcher stage. The verdicts carry the outcomes.
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"
Figure 4: The verdicts and the response: allow forwards; block, ban and challenge answer locally; log and shadow mark and continue. State returns follow in the state figure.
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"
Figure 5: The state returns: bans travel kernel-ward; verdicts backfill the cache; every step records telemetry; the operator supplies bundles and seeds the maps. Back to the edge.

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. The ext_proc wire-contract variant for Envoy-family estates is planned, not shipped.
  • Fail-open by default: the inline shaper never becomes the outage. failureMode is 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_proc variant 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 — failureMode is 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.