Get Started

hoop-inspect is an inspecting relay. It decodes the wire protocol between a client and a database or an API, evaluates every statement against policy, records an audit trail, and masks sensitive values in the response. It routes nothing and terminates no client TLS. You run it behind something that already owns the network path and identity, which in most enterprises means Envoy. Envoy reaches it over a unix socket or a TCP port, your choice per lane. Envoy answers reachability. hoop-inspect answers what the statement does, and what comes back.

This runs with no gateway, no agent, and no control-plane database. One config file is the whole setup.

Prerequisites

The hoop CLI installed. See CLI installation.
An Envoy you can add a cluster to, or any proxy that can forward plaintext to a local port.
A backend to protect: PostgreSQL or an HTTP service.

Step 1: Write a config file

One listener is one upstream. Start with a single Postgres lane and nothing else. Pick a transport first. One field decides it, and the rest of the file is identical either way:

	Unix socket	TCP port
Config	`network: unix` + a path	omit `network`, `listen` takes `host:port`
Reachable by	whoever can open the file	anything that can route to the host
Needs	both processes sharing a directory, and agreeing uids	nothing
Fits	a sidecar beside one workload, one pod	separate hosts, or a laptop

Unix socket
TCP port

config.yaml

log_level: info

admin:
  listen: 127.0.0.1:19000     # /healthz, /stats, /config, /api/*

audit:
  file: "-"                   # JSON lines on stdout

policy:
  enforce: true               # false is observe-only: inspect and audit, deny nothing

listeners:
  - name: appdb
    protocol: postgres
    network: unix                          # no port is opened at all
    listen: /run/hoop-inspect/pg.sock      # where Envoy sends bytes
    upstream: appdb:5432                   # the real database
    connection: appdb                      # the name audit rows and policy key on
    policy:
      rules:
        - name: no-destructive-sql
          type: operation
          operations: [drop, delete, truncate]
          message: destructive statements are not permitted on appdb

A socket opens no port, so reachability becomes a filesystem question rather than a network one. The cost is coordination: Envoy and the relay mount the same directory and their uids have to agree. Cheap in a pod spec, awkward across hosts.

config.yaml

log_level: info

admin:
  listen: 127.0.0.1:19000     # /healthz, /stats, /config, /api/*

audit:
  file: "-"                   # JSON lines on stdout

policy:
  enforce: true               # false is observe-only: inspect and audit, deny nothing

listeners:
  - name: appdb
    protocol: postgres
    listen: 127.0.0.1:15432   # network omitted -> tcp
    upstream: appdb:5432      # the real database
    connection: appdb         # the name audit rows and policy key on
    policy:
      rules:
        - name: no-destructive-sql
          type: operation
          operations: [drop, delete, truncate]
          message: destructive statements are not permitted on appdb

Nothing to mount and nothing to chown, which is why the compose stack defaults to this. Bind loopback where the relay and Envoy share a network namespace: a 0.0.0.0 bind is reachable by anything that can route to the host, and a NetworkPolicy narrows that without removing it.

Nothing above the transport changes. Policy, masking, audit and upstream_tls behave the same way, because the gate reads a net.Conn and never asks what kind it is. See Transport for the full comparison.

policy.enforce defaults to false. Without it every lane inspects and audits but denies nothing, so a misconfigured rule cannot take production down on first deploy. Set it to true when you want the rules to bite.

Step 2: Validate before you deploy

Nothing needs to be running. The validator builds every lane and reports every problem in one run:

hoop start inspect --config config.yaml --validate

config OK: 1 listener(s)
  appdb            postgres  enforcing 1 rule(s)

Each line is the resolved lane, so the rule count includes anything it inherited. A lane with an opa block reads + opa, one with masking reads + masking, and one with enforce: false reads observe-only.

Step 3: Run it

hoop start inspect --config config.yaml

--config also reads HOOP_INSPECT_CONFIG, which is the shape a Kubernetes deployment wants: mount the ConfigMap, set the variable, pass no arguments. Check it came up:

curl -s localhost:19000/healthz     # ok
curl -s localhost:19000/config | python3 -m json.tool

Step 4: Point Envoy at it

hoop-inspect is an ordinary upstream. There is no ext_proc, no WASM, no custom Envoy filter to install. You change the cluster your listener already routes to. The cluster shape follows the transport you picked in Step 1:

Transport	Cluster `type`	Endpoint address
Unix socket	`STATIC`	`pipe: { path: … }`
TCP port	`STRICT_DNS`	`socket_address: { address, port_value }`

A path resolves to nothing, so STRICT_DNS on a pipe: endpoint fails at load.

Unix socket
TCP port
HTTP lane

envoy.yaml

static_resources:
  listeners:
    - name: postgres_ingress
      address:
        socket_address: { address: 0.0.0.0, port_value: 5432 }
      filter_chains:
        - filters:
            - name: envoy.filters.network.tcp_proxy
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
                stat_prefix: ingress_pg
                cluster: hoop_inspect_pg

  clusters:
    - name: hoop_inspect_pg
      type: STATIC
      connect_timeout: 5s
      load_assignment:
        cluster_name: hoop_inspect_pg
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    pipe: { path: /run/hoop-inspect/pg.sock }

Envoy has no pgwire parser, so this lane is plain tcp_proxy. Every byte reaches the relay unexamined, which is the reason the relay earns its place here.

Two permission traps, and neither produces a useful error.Creating the socket. The relay needs write permission on the directory. A volume that mounts root-owned against a non-root image fails with bind: permission denied. Chown the directory before the relay starts, or set fsGroup on a Kubernetes pod.Connecting to it. connect() on a unix socket requires write permission on the socket file, not read. Go creates a listening socket at 0777 &^ umask, and the usual 022 clears exactly the group-write bit Envoy needs. Envoy then reports flags=UF and upstream_cx_connect_fail while the cluster still shows healthy, because the endpoint resolved. Run the relay with Envoy’s gid and umask 0002.

envoy.yaml

static_resources:
  listeners:
    - name: postgres_ingress
      address:
        socket_address: { address: 0.0.0.0, port_value: 5432 }
      filter_chains:
        - filters:
            - name: envoy.filters.network.tcp_proxy
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
                stat_prefix: ingress_pg
                cluster: hoop_inspect_pg

  clusters:
    - name: hoop_inspect_pg
      type: STRICT_DNS
      connect_timeout: 5s
      load_assignment:
        cluster_name: hoop_inspect_pg
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address: { address: hoop-inspect, port_value: 15432 }

Nothing to mount. The relay’s port is reachable by anything that can route to it, so keep it off any interface a client can find.

On HTTP you keep your existing ext_authz filter. Only the route’s cluster changes: it points at the relay instead of at the service.

envoy.yaml

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

http_filters:
  # Unchanged. OPA still answers reachability before anything is forwarded.
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      transport_api_version: V3
      failure_mode_allow: false
      grpc_service:
        envoy_grpc: { cluster_name: opa }
        timeout: 2s

  - name: envoy.filters.http.router
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

clusters:
  - name: hoop_inspect_http
    type: STATIC                          # STRICT_DNS for a TCP lane
    connect_timeout: 5s
    load_assignment:
      cluster_name: hoop_inspect_http
      endpoints:
        - lb_endpoints:
            - endpoint:
                address:
                  pipe: { path: /run/hoop-inspect/http.sock }

Envoy already terminated the client’s TLS on the HTTPS listener, so this lane carries plaintext to the relay and there is nothing extra to configure.

Terminating client TLS

The relay reads plaintext. Whatever the client encrypts, something has to decrypt before the gate sees a statement, and the relay is not that something: it terminates no downstream TLS. On the HTTP lane Envoy already does it, because an HTTPS listener terminates TLS by definition. On the Postgres lane the stock tcp_proxy does not, which is why the client connects with PGSSLMODE=disable. To encrypt the client’s Postgres leg, terminate it in Envoy with the postgres_proxy filter and a starttls transport socket:

envoy.yaml

filter_chains:
  - transport_socket:
      name: envoy.transport_sockets.starttls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.starttls.v3.StartTlsConfig
        tls_socket_config:
          common_tls_context:
            tls_certificates:
              - certificate_chain: { filename: /etc/envoy/certs/pg.crt }
                private_key: { filename: /etc/envoy/certs/pg.key }
    filters:
      - name: envoy.filters.network.postgres_proxy
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.postgres_proxy.v3alpha.PostgresProxy
          stat_prefix: pg
          terminate_ssl: true
      - name: envoy.filters.network.tcp_proxy
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
          stat_prefix: tcp
          cluster: hoop_inspect_pg

Postgres negotiates TLS in-band: the client sends an SSLRequest packet and waits for a one-byte reply, which is why this needs the starttls socket rather than a plain DownstreamTlsContext. The client then connects with PGSSLMODE=require, Envoy decrypts, and the relay receives the plaintext it needs.

postgres_proxy ships only in the contrib image (envoyproxy/envoy-contrib), and Envoy marks it experimental and not hardened. The stock envoyproxy/envoy image rejects the config with could not find @type … PostgresProxy. On Envoy 1.33 the field is terminate_ssl: true; newer versions deprecate it in favor of downstream_ssl: REQUIRE, so check which your image accepts.

With all three legs covered, only the hop the relay reads is ever in the clear:

Leg	Encrypted by
client → Envoy	Envoy, via `starttls` + `postgres_proxy` (HTTPS listener on the HTTP lane)
Envoy → relay	nothing, and it must stay that way: the gate parses these bytes
relay → database	the relay, via `upstream_tls`

Keep the middle leg on loopback or a unix socket. It carries decrypted traffic by design, and a socket is the tighter boundary because no port exists to reach.

Step 5: Watch it work

With the lane above in place, a destructive statement never reaches the database:

PGSSLMODE=disable psql -h envoy -p 5432 -U appuser -d appdb \
  -c 'DELETE FROM customers WHERE id = 1;'

FATAL:  destructive statements are not permitted on appdb

That is a real pgwire ErrorResponse carrying the message you wrote in config.yaml, so the developer reads it in psql instead of watching a socket drop. Envoy forwarded the same bytes as opaque TCP and consulted nobody. Read what the relay recorded:

curl -s localhost:19000/stats                  | python3 -m json.tool
curl -s 'localhost:19000/api/sessions?limit=1' | python3 -m json.tool

{"sessions": [
  {"id": "98203ccc…", "principal": "anonymous", "protocol": "postgres",
   "connection": "appdb", "duration_ms": 11,
   "statement_count": 2, "denied_count": 1, "masked_count": 0, "verdict": "denied"}
]}

Confirm which transport bound

/stats reports the address each lane bound, not the string you configured, so it tells you what happened. A path means a socket, a host:port means TCP:

{"listeners": [
  {"name": "appdb",   "addr": "/run/hoop-inspect/pg.sock",   "active": 0, "total": 4},
  {"name": "httpbin", "addr": "/run/hoop-inspect/http.sock", "active": 0, "total": 5}
]}

On a socket deployment, ask the relay’s own namespace what it listens on:

netstat -ltn        # or: ss -ltn

tcp  0  0  127.0.0.11:41515  0.0.0.0:*  LISTEN     docker's internal resolver
tcp  0  0  :::19000          :::*       LISTEN     the admin API

The admin port is the only entry left. A TCP deployment lists :::15432 and :::18080 beside it. From a peer, nc -z -w2 hoop-inspect 15432 reports closed or open to match.

Check with nc, not (echo > /dev/tcp/host/port). The latter is a bash builtin, and under BusyBox or dash it fails with no such device and calls every port closed, including open ones. It looks like a passing check and proves nothing.

Step 6: Add masking

Masking runs on responses. Turn on detection by naming the entity types your data holds, then say how each is rewritten:

config.yaml

pii:
  entities: [EMAIL_ADDRESS, US_SSN, CREDIT_CARD, BR_CPF, IBAN_CODE]

mask:
  enabled: true
  rules:
    - {name: emails, entity: EMAIL_ADDRESS, strategy: redact}
    - {name: ssn,    entity: US_SSN, strategy: partial, keep_last: 4}

The same query now comes back rewritten:

     name     |          email           |     ssn     |          iban
--------------+--------------------------+-------------+------------------------
 Ada Lovelace | [REDACTED:EMAIL_ADDRESS] | ***-**-6789 | ******************5432
 Grace Hopper | [REDACTED:EMAIL_ADDRESS] | ***-**-4321 | ******************3000

pii.entities is required and there is no all-entities default. Turning on all 45 recognizers rewrites ordinary numeric columns: nine digits in a legal range is a valid US_SSN as far as any detector can tell, and it fires on about a third of random nine-digit business ids. Name the types your data contains.

Run the whole thing on your laptop

The repository ships a compose stack that runs all of this end to end: Envoy terminating TLS, OPA answering reachability, the relay behind both, a seeded Postgres and an HTTP service behind that. Needs docker, curl, openssl and python3.

git clone https://github.com/hoophq/hoop
cd hoop/deploy/docker-compose/envoy-stack

./run.sh       # cert, sidecar image, compose up. First run takes a minute.
./demo.sh      # walks every lane and prints the audit trail
./run.sh down  # tear down, including volumes

The stack ships both transports. TCP is the default because it needs no shared volume; the overlay swaps in sockets once the certs exist and the image is built.

TCP (default)
Unix socket (overlay)

./run.sh
./demo.sh

The relay binds :15432 and :18080 on the compose network. Neither is published to the host.

export COMPOSE_FILE=docker-compose.yml:uds/docker-compose.uds.yml
docker compose up -d --wait

./demo.sh                     # same lanes, same policy, now over sockets
docker compose down -v        # tear down

COMPOSE_FILE applies to every docker compose in that shell, demo.sh included, so the overlay stays selected without repeating the flags. Prefer it to a CF="-f a -f b" variable: that idiom relies on unquoted word splitting, which bash does and zsh does not, so on zsh the whole string arrives as one argument.Confirm it took effect:

docker compose exec -T envoy ls -l /run/hoop-inspect/
#  srwxrwxr-x 1 10001 envoy 0 http.sock
#  srwxrwxr-x 1 10001 envoy 0 pg.sock

docker compose exec -T client sh -c 'nc -z -w2 hoop-inspect 15432 && echo OPEN || echo closed'
#  closed

Port	Serves
8443	Envoy HTTPS, to the HTTP lane
5433	Envoy TCP, to the Postgres lane
19000	relay admin: `/healthz`, `/stats`, `/config`, `/events`, `/api/*`
9901	Envoy admin

Inside the compose network that Postgres listener is envoy:5432. The host publishes it on 5433, because a laptop tends to have something on 5432 already. Those are Envoy’s ports and the overlay leaves them alone: it removes the relay’s two, which were never published to the host.

Troubleshooting

Symptom	Check
A rule you wrote never fires	`curl -s localhost:19000/config` and read the lane’s resolved `rules`
Masking leaves a value alone	The detector may refuse it. Add a column rule, or widen `pii.entities`.
The relay refuses to start	It prints every config problem at once, each naming its lane
psql says SSL is required	Set `PGSSLMODE=disable`, or terminate the client’s TLS in Envoy with `postgres_proxy`. The relay reads plaintext either way.
Envoy returns 503 with `flags=UF`	On a socket lane, Envoy lacks write permission on the socket file. Check `ls -l` on the directory and the relay’s umask. On TCP, check the cluster address.
Everything is allowed	`policy.enforce` defaults to false. `/config` reports `enforcing` per lane.
`bind: permission denied` at startup	The relay cannot write to the socket directory. Chown it, or set `fsGroup` on the pod.
`is a live socket; another relay is already listening on it`	A second relay tried to bind a path in use. Stop the first one.
Envoy rejects the cluster config	A `pipe:` endpoint needs `type: STATIC`; `STRICT_DNS` tries to resolve a filesystem path. A `socket_address` endpoint needs `STRICT_DNS` or `STATIC` with an IP.

Config File Reference

Every section, every rule type, inheritance between lanes, and what startup refuses.

Components and Architecture

How a request flows through the relay, multi-lane and unix-socket deployments, Kubernetes.

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Prerequisites

Step 1: Write a config file

Step 2: Validate before you deploy

Step 3: Run it

Step 4: Point Envoy at it

Terminating client TLS

Step 5: Watch it work

Confirm which transport bound

Step 6: Add masking

Run the whole thing on your laptop

Troubleshooting

Next

Config File Reference

Components and Architecture

​Prerequisites

​Step 1: Write a config file

​Step 2: Validate before you deploy

​Step 3: Run it

​Step 4: Point Envoy at it

​Terminating client TLS

​Step 5: Watch it work

​Confirm which transport bound

​Step 6: Add masking

​Run the whole thing on your laptop

​Troubleshooting

​Next

Config File Reference

Components and Architecture

Prerequisites

Step 1: Write a config file

Step 2: Validate before you deploy

Step 3: Run it

Step 4: Point Envoy at it

Terminating client TLS

Step 5: Watch it work

Confirm which transport bound

Step 6: Add masking

Run the whole thing on your laptop

Troubleshooting

Next