> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Command Line > Install and configure the hoop.dev CLI to interact with your applications. ## Prerequisites To get the most out of this guide, you will need to: * Either [create an account in our managed instance](https://use.hoop.dev) or [deploy your own hoop.dev instance](/docs/setup/deployment/overview) ## Installation Through homebrew: ```bash theme={"dark"} brew tap hoophq/brew https://github.com/hoophq/brew.git brew install hoop ``` To upgrade it: ```bash theme={"dark"} brew update && brew upgrade hoop ``` To install or upgrade: ```bash theme={"dark"} curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh ``` Download the latest release of [hoop command line](https://github.com/hoophq/hoop/releases) for your architecture (usually **hoop-windows-amd64**) and save it in the **Downloads** folder Extract the file using **winrar** or **winzip** Move the extracted file `hoop.exe` to the folder `C:\Windows\System32\` Open a terminal session and type `hoop version` if it successfully shows the program’s version it’s installed. ### Prerequisites 1. Install the Windows Terminal [https://aka.ms/terminal](https://aka.ms/terminal) 2. Install Ubuntu WSL [https://ubuntu.com/wsl](https://ubuntu.com/wsl) 3. Open the Windows Terminal App 4. Install and open the Ubuntu typing `ubuntu`. It should prompt to create a user in the first time ```bash theme={"dark"} PS C:\Users\san> ubuntu san@DESKTOP-BBQAAEG:~$ ``` 5. gain root access ```bash theme={"dark"} sudo su - ``` 6. To install or upgrade the hoop.dev command line: ```bash theme={"dark"} curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh ``` Check the latest version for your operating system architecture in the [releases page](https://github.com/hoophq/hoop/releases). Already installed? The CLI ships its own version manager under `hoop versions`. Use `hoop versions sync` to match the connected gateway, `hoop versions upgrade` to track the latest release, or `hoop versions install ` to pin a specific version. See [hoop versions](/docs/clients/cli-versions) for details. *** ## Running the Sidecar The same binary also runs the Sidecar directly — an inspecting proxy that 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. A client can dial it directly: ```mermaid theme={"dark"} flowchart LR C["client
psql · curl"] -->|TCP or socket| H["Sidecar
is this DELETE allowed?"] H --> U["postgres · HTTP API"] ``` Or, if you already run something that owns the network path and identity — Envoy is the common choice in bigger environments — put that in front instead. That's entirely optional, and it's covered at the end of this page in [Optional: Put Envoy in Front](#optional-put-envoy-in-front). This runs with no gateway, no agent, and no control-plane database. One config file is the whole setup — nothing above needs a hoop.dev account. *** ## Before You Start * A backend to protect: PostgreSQL, SQL Server 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 | ```yaml config.yaml theme={"dark"} log_level: info admin: listen: 127.0.0.1:19000 # /healthz, /stats, /config, /api/* audit: file: "-" # JSON lines on stdout listeners: - name: appdb # the name audit rows and rules key on protocol: postgres network: unix # no port is opened at all listen: /run/hoop-inspect/pg.sock # where bytes arrive upstream: appdb:5432 # the real database guardrails: 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: whatever's in front — Envoy is the common choice — and the Sidecar mount the same directory and their uids have to agree. Cheap in a pod spec, awkward across hosts. ```yaml config.yaml theme={"dark"} log_level: info admin: listen: 127.0.0.1:19000 # /healthz, /stats, /config, /api/* audit: file: "-" # JSON lines on stdout listeners: - name: appdb # the name audit rows and rules key on protocol: postgres listen: 127.0.0.1:15432 # network omitted -> tcp upstream: appdb:5432 # the real database guardrails: 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 Sidecar and whatever's in front of it 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. Guardrails, 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](/docs/setup/configuration/hoop-sidecar/config-file#transport) for the full comparison. ### Another protocol is one field `protocol` picks the codec and nothing else in the lane changes with it. A SQL Server lane is the same shape as the Postgres one above: ```yaml config.yaml theme={"dark"} listeners: - name: mssqldb protocol: mssql # postgres | mysql | mssql | mongodb | grpc | http listen: 127.0.0.1:11433 # network: unix works here too upstream: mssql:1433 guardrails: rules: - name: no-destructive-tsql type: operation operations: [drop, delete, truncate] message: destructive statements are not permitted on mssqldb ``` Guardrails, masking and audit behave as they do on a Postgres lane. Two differences belong to the protocol: the client's TLS is TDS 8.0, which Envoy terminates with a plain listener, and the hop to SQL Server stays plaintext because the Linux build accepts no TLS shape the Sidecar can originate. Both are covered in [Kerberos and SQL Server](/docs/setup/configuration/hoop-sidecar/kerberos). What each protocol decodes, refuses and masks has a page of its own under [Protocols](/docs/setup/configuration/hoop-sidecar/protocols/postgres). **A lane always enforces.** There is no observe-only switch: a rule you write denies from the first statement that matches it. Deploy a new rule set against a staging listener, or [validate](#step-2-validate-before-you-deploy) and read `/api/events?kind=violation` there, before it fronts production. `type: operation` matches the statement's most consequential **effect**, so `WITH d AS (DELETE FROM customers RETURNING *) SELECT count(*) FROM d` counts as a `delete` and the rule above catches it. [Guardrail Rules](/docs/setup/configuration/hoop-sidecar/policy-rules) covers every rule type, including deferring a match to a Rego policy instead of denying it. *** ## Step 2: Validate before you deploy Nothing needs to be running. The validator builds every lane and reports every problem in one run: ```bash theme={"dark"} hoop start sidecar --config config.yaml --validate ``` ``` config OK: 1 listener(s) appdb postgres 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`, and one with masking reads `+ masking`. *** ## Step 3: Run it ```bash theme={"dark"} hoop start sidecar --config config.yaml ``` `--config` also reads `HOOP_SIDECAR_CONFIG`, which is the shape a Kubernetes deployment wants: mount the ConfigMap, set the variable, pass no arguments. Check it came up: ```bash theme={"dark"} curl -s localhost:19000/healthz # ok curl -s localhost:19000/config | python3 -m json.tool ``` *** ## Step 4: Watch it work With the lane above in place, a destructive statement never reaches the database: ```bash theme={"dark"} PGSSLMODE=disable psql -h 127.0.0.1 -p 15432 -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. The rule catches more than its three verbs suggest, because `Operation` is the worst effect rather than the leading word. A delete hidden inside a CTE trips it: ```bash theme={"dark"} PGSSLMODE=disable psql -h 127.0.0.1 -p 15432 -U appuser -d appdb \ -c 'WITH d AS (DELETE FROM customers RETURNING *) SELECT count(*) FROM d;' ``` ``` FATAL: destructive statements are not permitted on appdb ``` With Envoy in front (see [Optional: Put Envoy in Front](#optional-put-envoy-in-front)), dial whatever host and port Envoy publishes instead — the Sidecar's behavior is identical either way. `CALL` and `EXECUTE` report `unknown` rather than `call`, because their bodies live in the catalog and no parser can say what they touch. The rule above forwards `CALL purge()`. Add `unknown` where that matters: ```yaml theme={"dark"} operations: [drop, delete, truncate, unknown] ``` A rule written as `operations: [call]` stops matching `CALL` and `EXECUTE` entirely. Write `operations: [call, unknown]`. Read what the Sidecar recorded: ```bash theme={"dark"} curl -s localhost:19000/stats | python3 -m json.tool curl -s 'localhost:19000/api/sessions?limit=1' | python3 -m json.tool ``` ```json theme={"dark"} {"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: ```json theme={"dark"} {"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 Sidecar's own namespace what it listens on: ```bash theme={"dark"} 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 5: Add masking Masking runs on responses. Detection needs no setup — every supported entity is enabled unless a `pii` section narrows the list — so one block says what gets rewritten and how: ```yaml config.yaml theme={"dark"} mask: rules: - {name: emails, entities: [EMAIL_ADDRESS], strategy: redact} - {name: ssn, entities: [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 ``` `entities` is a list, so one rule can cover several types that share a strategy: `{name: ids, entities: [US_SSN, BR_CPF], strategy: hash}`. Only the types a `mask` rule names are rewritten, and `US_SSN` is the one to be careful with: it carries no checksum, so nine digits in a legal range is a valid SSN as far as any detector can tell, and it fires on about a third of random nine-digit business ids. Where a lane carries ids like that, mask the column by name instead, and add a `pii` section naming the types your data really holds: ```yaml config.yaml theme={"dark"} pii: entities: [EMAIL_ADDRESS, CREDIT_CARD, BR_CPF, IBAN_CODE] ``` *** ## 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 Sidecar behind both, a seeded Postgres and an HTTP service behind that. Needs `docker`, `curl`, `openssl` and `python3`. ```bash theme={"dark"} 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. ```bash theme={"dark"} ./run.sh ./demo.sh ``` The Sidecar binds `:15432` and `:18080` on the compose network. Neither is published to the host. ```bash theme={"dark"} 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: ```bash theme={"dark"} 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 Sidecar's two, which were never published to the host. SQL Server runs in two stacks of its own, and what separates them is who terminates the client's TLS. `deploy/docker-compose/envoy-stack/mssql/` (`hoopinspect/scripts/dev/mssql-stack.sh`) runs SQL Server 2022 over TDS 8.0, with Envoy terminating, a Samba AD DC and a client holding a ticket. `deploy/docker-compose/envoy-stack/mssql2019/` (`mssql2019-stack.sh`) runs TDS 7.4 with no Envoy at all, covering the encrypted login; its `MSSQL_TAG` accepts 2017, 2019 and 2022. Microsoft publishes no arm64 image, so first boot on Apple Silicon takes minutes. See [Kerberos and SQL Server](/docs/setup/configuration/hoop-sidecar/kerberos#local-testing). *** ## Troubleshooting | Symptom | Check | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A rule you wrote never fires | `curl -s localhost:19000/config` and read the lane's resolved `rules`. A rule naming `operations: [call]` stopped matching: `CALL` and `EXECUTE` now report `unknown`. | | Masking leaves a value alone | The detector may refuse it. Add a column rule, or check that no `pii.entities` list is narrowing the type out. | | The Sidecar 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`](#terminating-client-tls). The Sidecar 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 Sidecar's umask. On TCP, check the cluster address. | | Everything is allowed | Read the lane's resolved `rules` at `/config`. A rule set that reached no lane, or a `guardrails` block still written as `policy`, allows everything. | | `bind: permission denied` at startup | The Sidecar 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 Sidecar 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. | *** ## Optional: Put Envoy in Front Everything above works with a client dialing the Sidecar directly. If you already run something that owns the network path and identity — Envoy is the common choice in bigger environments — you can put it in front instead. None of the steps above change; this only adds a hop. ```mermaid theme={"dark"} flowchart LR C["client
psql · curl"] -->|TLS| E["envoy
terminates TLS"] E -.->|ext_authz| O["OPA
can alice reach it?"] E -->|socket or port| H["Sidecar
is this DELETE allowed?"] H --> U["postgres · HTTP API"] ``` Envoy answers reachability. The Sidecar answers what the statement does, and what comes back. The Sidecar 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. ```yaml envoy.yaml theme={"dark"} 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 Sidecar unexamined, which is the reason the Sidecar earns its place here. **Two permission traps, and neither produces a useful error.** *Creating the socket.* The Sidecar 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 Sidecar 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 Sidecar with Envoy's gid and `umask 0002`. ```yaml envoy.yaml theme={"dark"} 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 Sidecar's port is reachable by anything that can route to it, so keep it off any interface a client can find. TDS 8.0 is TCP, then TLS, then the protocol, so Envoy terminates it with an ordinary `DownstreamTlsContext` and needs no TDS awareness. ```yaml envoy.yaml theme={"dark"} static_resources: listeners: - name: mssql_ingress address: socket_address: { address: 0.0.0.0, port_value: 1433 } filter_chains: - transport_socket: name: envoy.transport_sockets.tls typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext common_tls_context: tls_certificates: - certificate_chain: { filename: /etc/envoy/certs/server.crt } private_key: { filename: /etc/envoy/certs/server.key } filters: - name: envoy.filters.network.tcp_proxy typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy stat_prefix: ingress_mssql cluster: hoop_inspect_mssql idle_timeout: 3600s # a session idles between keystrokes clusters: - name: hoop_inspect_mssql type: STRICT_DNS connect_timeout: 5s load_assignment: cluster_name: hoop_inspect_mssql endpoints: - lb_endpoints: - endpoint: address: socket_address: { address: hoop-inspect, port_value: 11433 } ``` Clients connect with `Encrypt=strict`. A TDS 7.x client wraps its TLS handshake inside `0x12` packets, which Envoy cannot speak, so that lane skips Envoy and the Sidecar takes the connection directly: `ENCRYPT_OFF` encrypts the login packet alone and leaves every statement readable. See [Kerberos and SQL Server](/docs/setup/configuration/hoop-sidecar/kerberos#tds-7x-encrypts-the-login-and-nothing-else). On HTTP you keep your existing `ext_authz` filter. Only the route's cluster changes: it points at the Sidecar instead of at the service. ```yaml envoy.yaml theme={"dark"} 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 Sidecar and there is nothing extra to configure. ### Setting up the socket directory On a unix-socket lane, the directory needs an owner both Envoy and the Sidecar can work with. In Docker Compose that is a one-shot init container: ```yaml docker-compose.yml theme={"dark"} socket-dir: image: alpine:3.20 command: - sh - -c - | mkdir -p /run/hoop-inspect chown 10001:101 /run/hoop-inspect # relay uid, envoy gid chmod 2775 /run/hoop-inspect # setgid: sockets inherit the group volumes: - inspect-sockets:/run/hoop-inspect hoop-inspect: user: "10001:101" entrypoint: ["sh", "-c", "umask 0002 && exec /usr/local/bin/hoop-inspect -config /etc/hoop-inspect/config.yaml"] volumes: - inspect-sockets:/run/hoop-inspect depends_on: socket-dir: { condition: service_completed_successfully } ``` The setgid bit on the directory and `umask 0002` on the Sidecar are what make the sockets group-writable, which is the permission Envoy needs to connect. On Kubernetes, `fsGroup` on the pod's securityContext does the same job — see [Sharing a socket with Envoy](/docs/install/kubernetes#sharing-a-socket-with-envoy). **Restarting after an unclean exit.** Go unlinks the socket when the listener closes, so SIGTERM leaves nothing behind. A SIGKILL, an OOM kill or `docker kill` skips that and the file outlives the process. The Sidecar reclaims it at startup by dialing the path: a socket nothing answers on gets unlinked with a warning, and one that answers is left alone while the bind fails, naming the conflict. Two relays sharing a socket would split a client's connections between them at random. ### Terminating client TLS The Sidecar reads plaintext. Something in front has to decrypt whatever the client encrypted before the gate sees a statement; the Sidecar 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`. An MSSQL lane is the easy case: TDS 8.0 hands Envoy an ordinary TLS-on-connect handshake, which the tab above terminates. To encrypt the client's Postgres leg, terminate it in Envoy with the `postgres_proxy` filter and a `starttls` transport socket: ```yaml envoy.yaml theme={"dark"} 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 Sidecar 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 Sidecar reads is ever in the clear: | Leg | Encrypted by | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | client → Envoy | Envoy, via `starttls` + `postgres_proxy` (HTTPS listener on the HTTP lane, plain `DownstreamTlsContext` on an MSSQL one) | | Envoy → relay | nothing, and it must stay that way: the gate parses these bytes | | relay → database | the Sidecar, via [`upstream_tls`](/docs/setup/configuration/hoop-sidecar/config-file#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. *** ## Next Every rule type, deferring a match to Rego, and the findings a policy reads. Every section, every rule type, inheritance between lanes, and what startup refuses. How a request flows through the Sidecar, multi-lane and unix-socket deployments, Kubernetes.