gRPC

A grpc lane works differently from the relay lanes: the Sidecar terminates HTTP/2 itself (cleartext h2c by default, TLS with downstream_tls), decodes each RPC into statements, evaluates policy per message, and re-encodes responses it masked before forwarding to the upstream. The other protocols arrive as a byte stream a codec reads in flight; gRPC’s multiplexed streams and nested length prefixes rule that shape out, so the lane serves as its own endpoint.

config.yaml

listeners:
  - name: ledger
    protocol: grpc
    listen: 0.0.0.0:18443
    upstream: ledger:9000
    identity_header: x-hoop-user      # trust only behind an authenticating proxy
    grpc:
      descriptors: /etc/hoop-inspect/descriptors/ledger.pb
      capture_payload: true

The `grpc` block

Field	Meaning
`descriptors`	One serialized `FileDescriptorSet` or a list (`protoc --include_imports --descriptor_set_out`, or `buf build -o`). Required for any payload work: schema-less protobuf walking loses values, so no capture, masking or PII scanning happens without it.
`capture_payload`	Renders decoded request and response messages into per-message statements, so payload rules (`pii`, `pattern_match`) and OPA read field values as well as the method path. Requires `descriptors`.
`max_payload_bytes`	Truncates a captured rendering. Masking ignores it: a redactor rewrites decoded fields whatever their size.
`strict`	Refuses what the descriptor set cannot explain; see below.
`metadata`	Request metadata headers exposed to policy, matched case-insensitively. No capture-all, and `authorization`, `cookie` and `proxy-authorization` can never be listed.

Multiple descriptor sets fit the multi-team shape: each service’s CI ships its own artifact and the lane lists them all. Sets merge at startup, byte-identical shared imports dedupe, and two diverged copies of one file refuse to load naming both artifacts.

No descriptor set yet: bootstrap one with `-grpc-discover`

When the upstream serves gRPC server reflection, the Sidecar binary produces the artifact for you. Declare the lane first, without a grpc: block; a descriptor-less lane is valid and enforces method-level policy:

config.yaml

listeners:
  - name: billing
    protocol: grpc
    listen: 127.0.0.1:18443
    upstream: billing:50051
    upstream_tls: {}        # discovery dials with the lane's own TLS facts

Then run discovery against that config:

hoop-inspect -grpc-discover billing -grpc-discover-out billing.pb -config config.yaml

It picks the lane by name, dials the lane’s upstream with the lane’s upstream_tls (h2c when the block is absent), fetches the schema over reflection (v1, with a v1alpha fallback), prints every method with its maskable field paths, and writes the serialized set. Review the report, commit the artifact, add grpc.descriptors pointing at it, restart. Discovery is a bootstrap command, and the lane still loads only the pinned file. A schema fetched live at runtime would let the policed service rename fields out from under your mask rules, so no descriptors: auto exists. Sequencing facts worth knowing:

Discovery runs against a config whose descriptors: path does not exist yet; it never builds the lane. -validate does build the lane, so run it after the file exists.
The artifact is byte-stable against an unchanged server. Re-run discovery and diff the file to see what the service changed.
Discovery sends no credentials and gives one run 30 seconds. An upstream that requires authenticated reflection, or one that serves none (Google’s production APIs, the Spanner emulator), answers with an error naming the offline route: protoc --include_imports --descriptor_set_out, or buf build -o.
spanner lanes bootstrap the same way.

Lenient, strict, and the masking carve-out

	default (lenient)	`strict: true`
Method in a listed set	inspected, masked, forwarded	same
Method in no listed set	forwarded with method-level inspection only; the lane logs the degradation	refused before the upstream is dialed: `FAILED_PRECONDITION`, naming the path
Message that does not decode as its declared type	forwarded uninspected, logged	ends the RPC with `INTERNAL`
Lane with mask rules, either case	refused regardless: a redactor must not forward what it cannot decode	same

strict without descriptors is a startup error: strictness about payloads nothing can decode would refuse every RPC.

Rules on a gRPC lane

A gRPC statement carries its un-normalized RPC path as the resource, so the existing rule types cover it:

http_resource matches method identity: resources: ["/demo.v1.Ledger/ExportAll"].
grpc_status matches the outcome in the grpc-status trailer: statuses: [permission_denied]. It runs response-side, and the body has already reached the client when trailers arrive, so a deny here replaces the final status rather than retracting data. To record outcomes instead, pair action: defer with an opa block.
pii and pattern_match read decoded payloads, so startup refuses them on a lane without capture_payload: they would only ever scan the method path and would fire on nothing.

Denials return PERMISSION_DENIED with the rule’s message, the shape a gRPC client already handles.

Identity

Behind an authenticating proxy, identity_header names the caller, the same proxy-trust contract as on an HTTP lane: safe only when nothing else can reach the listener. Without the header, a lane terminating TLS falls back to the verified client certificate, the SPIFFE URI SAN where one exists and the subject common name otherwise. With neither, sessions record principal=anonymous.

TLS and the two deployment shapes

grpc is one of two protocols that may terminate the client’s TLS at the lane (the other is postgres), because the lane is its own HTTP/2 endpoint and must present the certificate itself:

Shape	Client leg	Config
Behind Envoy	Envoy terminates TLS, forwards h2c	nothing: the lane listens for cleartext HTTP/2
Standalone, in-pod	Cleartext h2c, trusted because the hop never leaves the pod	nothing; clients opt in (`grpcurl -plaintext`, `insecure.NewCredentials()`)
Standalone, exposed	The lane terminates TLS	`downstream_tls: {cert_file: ..., key_file: ...}`

The hop to the upstream is h2c by default; upstream_tls turns it into TLS with the usual ca_file, server_name and client-certificate fields.

The Envoy lane

gRPC is HTTP/2, so Envoy sees more here than on the database lanes: the same http_connection_manager and ext_authz filter run, and OPA answers method-level reachability on :path before the Sidecar sees the RPC. Two settings distinguish the lane from a plain HTTP one:

envoy.yaml

routes:
  - match: { prefix: "/" }
    route:
      cluster: hoop_inspect_grpc
      timeout: 0s               # gRPC convention: the client's grpc-timeout
                                # header sets the deadline, not the router

clusters:
  - name: hoop_inspect_grpc
    type: STRICT_DNS
    connect_timeout: 5s
    typed_extension_protocol_options:
      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
        explicit_http_config:
          http2_protocol_options: {}    # the hop to the lane must be h2
    load_assignment:
      cluster_name: hoop_inspect_grpc
      endpoints:
        - lb_endpoints:
            - endpoint:
                address:
                  socket_address: { address: hoop-inspect, port_value: 18443 }

The gRPC overlay in deploy/docker-compose/envoy-stack/grpc/ runs all of this: the lane through Envoy and without it, two descriptor sets merged, the strict/lenient contrast, and a standalone stack where the lane owns TLS. Its demo drives each beat with grpcurl:

./run.sh
docker compose -f docker-compose.yml -f grpc/docker-compose.grpc.yml up -d --wait
./grpc/demo-grpc.sh

Guardrail Rules

http_resource, grpc_status, PII rules and deferring a match to Rego.

Config File Reference

Every listener field, inheritance between lanes, and what startup refuses.

Getting Started

Core Concepts

Features

Control Plane Setup

Sidecar Reference

The `grpc` block

No descriptor set yet: bootstrap one with `-grpc-discover`

Lenient, strict, and the masking carve-out

Rules on a gRPC lane

Identity

TLS and the two deployment shapes

The Envoy lane

Next

Guardrail Rules

Config File Reference

​The grpc block

​No descriptor set yet: bootstrap one with -grpc-discover

​Lenient, strict, and the masking carve-out

​Rules on a gRPC lane

​Identity

​TLS and the two deployment shapes

​The Envoy lane

​Next

Guardrail Rules

Config File Reference

The `grpc` block

No descriptor set yet: bootstrap one with `-grpc-discover`

Lenient, strict, and the masking carve-out

Rules on a gRPC lane

Identity

TLS and the two deployment shapes

The Envoy lane

Next