HTTP

An http lane inspects requests and responses. Envoy’s ext_authz already hands OPA the method, path and headers of a request, and the lane keeps that arrangement. It adds two things ext_authz cannot do by construction: it reads the response, which is where data leaves the building, and it keys policy on a stable resource identity instead of raw paths.

config.yaml

listeners:
  - name: httpbin
    protocol: http
    listen: 127.0.0.1:18080
    upstream: httpbin:8080
    identity_header: x-hoop-user      # trust only behind an authenticating proxy
    guardrails:
      rules:
        - name: no-admin-api
          type: http_resource
          resources: ["/admin/**"]
          message: the admin API is not reachable through this proxy
        - name: no-upstream-5xx
          type: http_status           # response-side, so ext_authz cannot ask it
          statuses: ["5xx"]
          message: upstream failure suppressed by policy

The normalized resource

Policy keyed on raw paths needs a regex per endpoint. The codec collapses dynamic segments to *, so /users/12345/orders/98765 becomes /users/*/orders/* and one http_resource rule covers the endpoint:

Segment	Collapses
All digits (`/users/12345`)	yes
A UUID	yes
A hex string of 12+ characters	yes
A long opaque token (JWT/base64url shapes, 24+ chars)	yes
A short slug (`/users/alice`)	no

The slug survives on purpose: nothing distinguishes /users/alice from /users/settings, and collapsing it would widen every rule written against either without warning. In doubt the codec keeps the segment, so a policy can end up too narrow but never too broad. File extensions survive too (/reports/12345.pdf → /reports/*.pdf), because a policy may allow *.csv and deny *.sql.

The `http` block

The defaults expose nothing: no bodies, no headers. Everything you capture reaches the policy engine, the audit trail and, where an analyzer is configured, a third party, so capture is opt-in per field.

listeners:
  - name: httpbin
    protocol: http
    listen: 127.0.0.1:18080
    upstream: httpbin:8080
    http:
      capture_body: true
      max_body_bytes: 65536       # the default
      headers: [Content-Type]     # allowlist; there is no capture-all

Field	Meaning
`capture_body`	Includes request and response bodies in the statement. A `pii` or `pattern_match` rule that reads payloads needs it. It is optional for the analyzer, which judges a request from its request line and headers without it. A lane that holds for review captures request bodies without it; response bodies still need it.
`max_body_bytes`	Truncates a captured body. Default 64 KiB.
`headers`	Headers exposed to policy, the audit trail and the analyzer, matched case-insensitively. An `http_header` rule may name only headers listed here. `authorization`, `cookie`, `proxy-authorization` and `set-cookie` can never be listed.

Identity

identity_header names the header your authenticating proxy sets. The lane reads it on every request, because Envoy pools upstream connections and sends requests from different callers down one keep-alive connection. The first request names the first session before it opens, so the session_start audit row already carries the subject. A later request that names a different principal ends that session (session_end) and opens a new one on the same connection (session_start), so each request’s statement row and input.context.principal for OPA carry its own caller. A caller change while an earlier response on the connection is still outstanding is refused with a 403 under rule identity: that response belongs to the session that sent its request. A request without the header runs as anonymous and is forwarded, so a policy that requires a caller must deny input.context.principal == "anonymous" itself. The header value reaches policy input and the audit trail only when http.headers names it. A client that connects and sends no request within ten seconds is closed with no session and no session_start, the way a pgwire client that abandons its handshake is; HTTP has no server greeting, so waiting on the client’s first bytes is the protocol’s own ordering. Trusting a header is safe only when nothing but that proxy can reach the listener, so bind loopback or a unix socket. On a listener reachable from anywhere else, a caller can assert any identity.

Google identity

google_identity names the caller from Google’s own bearer, for a lane with no authenticating proxy in front. kubectl through GKE Connect Gateway sends a Google OAuth2 access token on every request; without this block, Envoy would need ext_authz only to learn the name the token already holds.

listeners:
  - name: gke
    protocol: http
    google_identity: {}         # the caller is whoever holds the request's Google bearer
    # google_identity:
    #   tokeninfo_url: https://...   # Private Service Connect or a private.googleapis.com VIP; https only

The lane verifies the request’s Authorization: Bearer token with a POST to https://oauth2.googleapis.com/tokeninfo. It never sends the token in a query string, because proxies log URLs.
The principal is the verified email, else the account’s Google sub.
A verified answer is cached under the token’s SHA-256 for the token’s lifetime, at most five minutes. A rejected token is cached for 30 seconds. An unreachable Google is never cached.
Any failure (no bearer, a token Google rejects, Google unreachable) refuses that request with a 403. A caller that cannot be verified is never served under the identity the connection had before.
The token reaches no audit row, no policy input and no analyzer prompt.
http lanes only, and exclusive with identity_header: startup refuses a lane that sets both.

The result names who holds the token, not what it may do. The upstream still checks the same token against its own IAM and RBAC. The tokeninfo call trusts the trust.ca_file bundle, so it works through a proxy that re-signs egress TLS.

h2 and h2c

An http lane accepts HTTP/2 beside HTTP/1.1:

Lane	Client can send
No `downstream_tls`	HTTP/1.1, or h2c by prior knowledge: a connection that opens with the HTTP/2 preface is HTTP/2, so Envoy can forward h2 without downgrading it. `Upgrade: h2c` is not honoured.
`downstream_tls`	`h2` or `http/1.1`, chosen by ALPN. kubectl picks h2 from anything that offers it.

Each h2 stream is bridged into the unchanged HTTP/1.1 relay as one request, so policy, the per-stream 403, masking, audit, per-request identity and Via apply to it exactly as to an HTTP/1.1 client. The upstream hop stays HTTP/1.1. Streams do not count toward max_conns: the client connection was admitted once, and HTTP/2’s concurrent-stream limit bounds its streams. An h2 CONNECT, extended CONNECT included, gets 501. A request with an Upgrade header (kubectl exec, attach, port-forward) must reach the lane as HTTP/1.1. kubectl already does that when it talks to the lane directly; an Envoy with an h2 cluster to the lane needs a route that sends Upgrade requests to a second, HTTP/1.1 cluster. See The Envoy lane.

Via and loop detection

Every http lane appends Via: <request version> hoop-<16 hex> as the last request header, so the upstream sees one extra header. The pseudonym is random per process. A request that already carries this process’s pseudonym is refused with a 403 whose message starts request loop:. That catches a transparent MITM proxy that routes the Sidecar’s own upstream traffic back into its listener, where each lap would otherwise look like a fresh client. After a request with Upgrade, or a CONNECT, the rest of that connection is another protocol and is no longer marked.

Masking

The codec rebuilds the response around the masked values. A JSON body is walked value by value, and each string or number reaches the masker under its dotted key path (data.password, items.metadata.name), so a columns rule names a JSON key the way it names a result-set column and masks it whatever it holds. A text body (text/*, XML, YAML, form data, or no Content-Type) is masked as text. Binary types pass through untouched. Content-Length is corrected. A chunked body is re-chunked and streams: each complete top-level JSON value, or each line of text, goes out as soon as it is whole, so a watch or a log follow is not held to its end and a value split across two chunks is still masked whole. A gzip or deflate body is undone around the masker and compressed again. A text or JSON body under an encoding the codec cannot undo (zstd, br, lz4) is refused with a 403 and an error audit row rather than forwarded unmasked; a binary body under such an encoding passes. A body the codec is holding that grows past 16 MiB goes out unmasked, and the next response is masked again. See Kubernetes API for columns: [data] against kube-apiserver’s chunked responses, and the ClickHouse HTTP interface for TSV, JSONEachRow and FORMAT JSON results.

Denials

A denied request returns 403 Forbidden with the rule’s message and Connection: close:

HTTP/1.1 403 Forbidden
Content-Type: text/plain
Connection: close

the admin API is not reachable through this proxy

A request refused for its identity or as a request loop is also answered with a 403. On an h2 connection the 403 ends that stream only.

The Envoy lane

Keep your existing ext_authz filter, and OPA still answers reachability first. The one change is the route’s cluster, which points at the Sidecar instead of at the service:

envoy.yaml

route_config:
  virtual_hosts:
    - name: inspect
      domains: ["*"]
      routes:
        - match: { prefix: "/" }
          route:
            cluster: hoop_inspect_http     # was: the service cluster
            timeout: 60s

Envoy already terminated the client’s TLS on the HTTPS listener, so this lane carries plaintext HTTP/1.1 or h2c to the Sidecar and there is nothing extra to configure. The compose stack’s httpbin lane in deploy/docker-compose/envoy-stack/ runs exactly this shape:

curl -sk https://envoy:8443/anything -H 'x-hoop-user: alice'

To keep h2 on the hop to the lane, give Envoy two clusters to the same lane port: one with http2_protocol_options for ordinary requests, one plain HTTP/1.1 for upgrades. Match Upgrade first, because Envoy turns an upgrade on an h2 cluster into an extended CONNECT, which the lane answers with 501:

envoy.yaml

routes:
  - match:
      prefix: "/"
      headers: [{ name: upgrade, present_match: true }]
    route: { cluster: hoop_inspect_h1, timeout: 0s }    # kubectl exec, attach, port-forward
  - match: { prefix: "/" }
    route: { cluster: hoop_inspect_h2c, timeout: 0s }   # everything else, no downgrade

Kubernetes API

kube-apiserver behind an http lane: header guardrails, masking by JSON key, kubectl exec.

Guardrail Rules

http_resource globs, http_status ranges, http_header and headers_not patterns, and deferring a match to Rego.

Risk Analysis

What the lane’s analyzer sees with and without capture_body, and what it costs.

Getting Started

Sidecar

Features

Control Plane Setup

The normalized resource

The `http` block

Identity

Google identity

h2 and h2c

Via and loop detection

Masking

Denials

The Envoy lane

Next

Kubernetes API

Guardrail Rules

Risk Analysis

​The normalized resource

​The http block

​Identity

​Google identity

​h2 and h2c

​Via and loop detection

​Masking

​Denials

​The Envoy lane

​Next

Kubernetes API

Guardrail Rules

Risk Analysis

The normalized resource

The `http` block

Identity

Google identity

h2 and h2c

Via and loop detection

Masking

Denials

The Envoy lane

Next