Skip to main content
One file is the whole configuration. The Sidecar reads it at startup, resolves every listener, and then tells you what it resolved. YAML and JSON both work, and the file extension picks the parser: .yaml and .yml go through the YAML front end, anything else is read as JSON. Decoding is strict, so a mistyped key fails startup instead of disabling a control without telling you.
New to hoop-inspect? Start with Get Started, which builds a working config one step at a time.

​
Shape of the file

Two concepts that used to share the name policy now have sections of their own. guardrails is Hoop’s own rule engine, running in-process. opa is the optional integration with an OPA Data API endpoint you run yourself. Both are defaults at the top level, as mask is, and each listener inherits them unless it overrides them.
config.yaml
Every lane enforces, and a mask block carrying rules masks. Neither is a second switch you can forget to set.

​
Top-level sections

Keys starting x- are dropped before validation, so a YAML anchor block does not need a matching config field. See sharing rules between lanes.
policy is the previous spelling for both guardrails and opa, and it is deprecated. A file still using it loads and warns at startup. See Migrating from policy for the field-by-field mapping.

​
Listeners

Each listener is one Envoy cluster’s worth of traffic with its own enforcement stack.
identity_header trusts a header, which is safe only when nothing but your proxy can reach the listener. Bind it to loopback or a unix socket. On a listener reachable from anywhere else, a caller can assert any identity.
Leave idle_timeout_sec unset for interactive sessions. psql idles between keystrokes, and a short value disconnects a developer mid-thought.

​
Transport

Each lane binds a TCP port or a unix socket. One field decides it, per listener, and TCP is the default: omit network and you get a port.
network accepts tcp or unix. Anything else fails startup, naming the lane:
Lanes in one process can differ, so you can move one lane to a socket without touching the other. 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.

​
Choosing between them

Both carry the same traffic. They differ in who can reach the lane and what it costs to set up. A socket gives the tighter boundary: no port exists, so reachability is a filesystem question. A port gives the simpler deployment, which is why the compose stack defaults to it and keeps sockets in an overlay. Lanes in one process can differ, so you can take the socket where it is cheap and leave the port where it is not. Keep the admin listener on TCP. It serves /healthz to a container healthcheck and /stats to a scraper, and moving it to a socket means exec-ing into the container to read either.

​
Which transport is running

Three places say it, and they agree because they read the same resolved config. The startup log, one line per lane:
GET /stats, whose addr is whatever the listener bound. A path means unix, a host:port means TCP. This is the post-bind address, so it reflects what happened rather than what you asked for:
The filesystem, where the leading s marks a socket:

​
Two permission traps

Both cost real time, and neither produces a useful error on its own. Creating the socket. The Sidecar needs write permission on the directory. A volume that mounts root-owned against a non-root image gives:
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 a peer needs. Envoy then fails with nothing useful in either log: flags=UF and an upstream_cx_connect_fail counter, while the cluster still reports healthy because the endpoint resolved. Run the Sidecar with the peer’s gid and umask 0002 so its sockets come out group-writable. deploy/docker-compose/envoy-stack/uds/ does exactly this and is worth reading before you write your own.

​
Stale sockets after an unclean exit

Go unlinks the socket when the listener closes, so an orderly shutdown 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 it dials the path, and a socket nothing answers on gets unlinked with a warning:
A socket that does answer is left alone and the bind fails, naming the conflict, because two relays sharing one socket would split a client’s connections between them at random:

​
How a listener inherits

Reading the file will not tell you which rules a lane ended up with, because inheritance happens at startup. Ask the running process:
Every lane inherited no-cpf-in-query. None inherited another lane’s rules. Rule names only: a pattern_regex can encode business logic, and this endpoint already sits beside a read interface to the audit trail.

​
Guardrail rules

Each entry in guardrails.rules is one rule. A rule matches, and by default it denies. First match wins among the rules that deny. A rule set is an ordered deny list. Every rule also takes name, message and action. message is what the user reads on denial, delivered in the protocol’s own error frame. Leave it empty and the rule falls back to a generated string naming only the rule and operation; write one. action takes defer or nothing. Empty denies, the behavior every rule had before findings existed. defer reports the match as a finding and lets a Rego policy rule on it, so the matching stays in the local engine and only the determination moves:
Deferring does not stop the rule set. First match wins applies to denials, so a deferring rule records and evaluation continues, and a hard rule further down still denies. Guardrail Rules covers the producer model, the finding shape and the Rego that reads it. An HTTP rule never matches a SQL statement and vice versa, so one mixed rule set cannot deny the wrong protocol.
ai_analysis is the one type the local rules engine does not evaluate. It is lifted out of the set at startup and runs after the local rules and OPA, so its position in the list has no effect. It also needs an analyzer section, and on an HTTP lane it needs http.capture_body: true. Startup refuses a lane missing either. An ai_analysis rule spells deferring per risk level (high: defer) rather than through action.

​
operation reports the worst effect

Operation is the most consequential effect of the statement, not the verb the user typed. WITH d AS (DELETE FROM customers RETURNING *) SELECT count(*) FROM d reports delete, so a rule naming delete catches it. EXPLAIN ANALYZE DELETE FROM customers reports delete as well, because it runs the statement; plain EXPLAIN reports explain and reads the table. The scanner discards comments and string literals before it classifies, so SELECT 'DROP TABLE customers' is a select. A word list denies that harmless query.
Add unknown to that list on a lane where a statement the scanner could not read must not run. For anything one verb describes too coarsely, input.effects and input.relations carry the full picture to Rego; see Guardrail Rules. SQL operations: select, insert, update, delete, merge, create, drop, alter, truncate, grant, revoke, call, copy, explain, show, set, begin, commit, rollback. Two more carry a meaning of their own: other is a statement that parsed into none of those, and unknown is one the scanner could not finish, with the reason in metadata["sql.incomplete"]. HTTP verbs are distinct values: get, post, put, patch.
Breaking change: CALL and EXECUTE report unknown. Their bodies live in the catalog, so no parser can say what they touch, and reporting call claimed knowledge the Sidecar does not have. A rule written as operations: [call] stops matching them. Write operations: [call, unknown].call survives in the vocabulary and costs nothing to name, though no complete statement reports it as an operation today: CALL, EXECUTE, EXEC and DO all come back incomplete. Rego still sees call in input.effects.unknown covers those four and any other statement the scan could not finish. Naming it is the fail-closed choice, and it stays the right one permanently: no parser reads a body that lives in the catalog, PostgreSQL’s own included.

​
http_resource matches a normalized path

/anything/users/12345/orders/98765 normalizes to /anything/users/*/orders/*, so one rule replaces a regex per endpoint. A trailing /** matches any deeper path.
Short slugs survive normalization intact: merging /users/alice with /users/settings would widen every rule written against either, with no signal that it happened. The normalizer errs toward keeping segments, so a policy comes out too narrow rather than too broad.

​
http_status is the rule ext_authz cannot express

ext_authz decides before Envoy calls the upstream, so no Envoy configuration can read a response status. This one reads it:

​
pii is a guardrail, not masking

Masking rewrites the response. A national ID in a WHERE clause has already landed in the database’s own query log, slow-query log and EXPLAIN output, and no amount of response masking undoes that. Deny it on the way in:
The denial message never quotes the value it found. A message quoting the identifier it denied has published that identifier.

​
table rules split read from write

tables names relations, and access narrows the rule to write or read. Leave access unset and the rule matches either, which is what every rule written before the split meant, so deployed rules behave as they did:
Without access, “nothing writes to customers” has to be spelled “nothing mentions customers”, so INSERT INTO staging SELECT * FROM customers trips a rule it only reads through, and operators widen the rule until it protects nothing. A value other than read or write is refused at startup. Relations come from a scanner rather than a full SQL grammar. A statement it cannot read comes back with no relations and an unknown operation, and empty means “could not determine”:
Set require_table_match: true on rules protecting something critical, and accept the false positives.

​
OPA

opa is its own section, at the top level or on a listener, and it is the only OPA-specific configuration in the file. A lane consults its endpoint after its guardrails pass, so a statement the local set already forbids costs no network round trip.
The Sidecar does not own policy; it owns the input document:
operation is the worst effect and tables the flattened relation names, both unchanged. effects and relations say what those two could not: a data-modifying CTE both deletes and selects, and a flat name list cannot separate the table a statement writes from the one it reads. findings carries what each deferring rule established, keyed by producer source. A lane with no producers sends a byte-identical document to the one it sent before findings existed. context comes from the session: principal, session_id and connection, plus subject, email, groups, peer_addr, upstream and correlation_id where the identity carries them. The document also carries statement (the text verbatim), database, metadata from the codec, and http with the method, path and normalized resource on an HTTP lane. Your Rego may answer {"allow": bool}, {"denied": bool}, or a bare boolean, with an optional message and rule.
OPA fails closed. An unreachable endpoint, a 500, or an undefined decision denies the statement. Set fail_open: true only where availability outranks enforcement. The gate phase below is the one exception, and it is deliberate.

​
Two phases

gate: true adds a decision before the producers run, so a policy answers “is this statement worth a model call” before anyone pays for one. Both calls hit the same URL and carry input.phase, so a policy that ignores the field answers both identically and turning the gate on costs one round trip. The gate answers with its allow/deny plus a request map keyed by producer source:
true runs a producer its own configuration would have skipped, false vetoes one it would have run, and an absent key leaves the config in charge.
An undefined gate decision allows and requests nothing, even under fail_open: false. A gate is an optimization over a policy someone already wrote, so reading its absence as a denial would block every statement on the lane until the Rego author writes a second rule nobody asked for. The decide phase keeps the fail-closed reading of undefined.
A single-call lane sends no phase field, so Rego testing input.phase == "decide" is undefined there and fail_open: false denies everything. Write phase := object.get(input, "phase", "decide") and the same policy serves both arrangements.
See Guardrail Rules for the finding shape, the status vocabulary and worked Rego.

​
Masking

Masking runs on responses only. Requests are never rewritten: changing the statement the upstream executes is a correctness change wearing a privacy label. A mask block carrying rules is on; there is no separate switch.
One rule may name several entity types, and they share its strategy. Types needing different strategies need one rule each:

​
Entity rules versus column rules

An entity rule masks by detection and applies anywhere, including inside an opaque HTTP body. A column rule masks by position: it works only where the protocol names its values, and there it beats detection outright, because the column does not care what the value looks like. The difference is observable. The seeded value 123-45-6789 is one the detector refuses, rejecting sequential digit runs as obvious test fixtures:
A validating detector cuts false positives on ordinary numeric ids and declines the placeholders. A column rule covers the gap wherever the protocol gives you a name to key on.

​
Naming your entities

Omit pii and every supported entity is enabled. Nothing has to be declared before a mask rule or a pii guardrail can name a type, which is the whole point of the default: a config that names US_SSN in one place should not also have to name it in another. Set the section to narrow the engine, or to tune it:
Naming entities makes the list exhaustive: a rule naming a type outside it is refused at startup, so narrowing the engine cannot silently disarm a rule that reads as live.
The permissive default costs recall nothing and precision something. Some recognizers carry a real checksum — card (Luhn), CPF (mod-11), IBAN (ISO 7064) — and leave lookalike ids alone. US_SSN carries none, so nine digits in a legal range is a valid SSN as far as any detector can tell:
That only reaches a client through a rule you wrote: masking rewrites the types a mask rule names, and nothing else. Where a lane carries numeric ids that look like an identifier, prefer a columns rule to an entity rule, and set pii.entities to what the data actually holds.
Masking needs a codec that can carry it. HTTP declares its body length in a header the Sidecar corrects; Postgres rebuilds its length-prefixed row frames around the new values, and MSSQL reassembles the TDS token stream and lays fresh packets over the rewritten rows. A protocol offering neither gets its mask section refused at startup. Accepting a mask config that can never fire is the failure that ends with an unmasked SSN in a screenshot.

​
Licensing

Unlicensed, the Sidecar enforces one guardrail rule and one data masking rule. The cap is per process, not per lane: one rule in the top-level guardrails block counts once however many listeners inherit it, and mask.rules on a lane counts against the same budget as the default block it replaces. ai_analysis rules are counted apart and never capped, because their controls are the trigger and analyzer.max_calls rather than a number of rules. A license Hoop signed lifts the caps for the features it names.

​
Three places carry a license

HOOP_LICENSE is not HOOP_SIDECAR_LICENSE: the same document Hoop issues verifies on the gateway too, and a deployment that spells it two ways sets one of them wrong. Installing it on the gateway is a separate step, covered in License Management.

​
A path or the document itself

All three sources take the same two shapes. A value whose first non-blank character is { is read as the license document; anything else is read as a filename. One field serves a mounted secret and an inline value, so moving a license between the two is not also a rename.
The same holds for the flag and the environment variable, which is what makes a Kubernetes secret work without a volume:
First wins, not first valid. A HOOP_LICENSE pointing at a file that does not exist is an error, not a reason to fall back to the license key. A process that quietly ignored your environment variable would surprise you on the restart after somebody edits the config file.

​
What a license lifts

Each feature named in the license lifts its own cap. The Sidecar reads two of them, guardrails and data-masking. A license naming neither covers both; one naming only data-masking leaves the guardrail cap where it was. An oss license verifies and grants nothing, matching what the control plane does with the same document.

​
What the process concluded

One line, first in the startup log and first in --validate:
GET /config on the admin listener serves the same verdict under license and the caps under limits, where null means the license lifted one. It never returns the signature:
Missing and expired are states, not failures: the process starts and the caps stay in force. A license that cannot be read stops startup instead — a path to nothing, malformed JSON, or a signature that does not verify — and the error names the source it came from. Dropping to the free tier over a typo in a path would be a silent downgrade.

​
When a term ends under a running process

The verdict is a function of the clock rather than a flag set at startup, so a relay that has been up for months flips /config and its caps to the free tier the second its term lapses. Nothing reloads.
  • A config inside the free tier keeps serving. Expiry took nothing from it, and stopping the relay would be an outage with no revenue behind it.
  • A config over the free tier stops. The relay logs the expiry, drains open connections, flushes the audit trail and exits non-zero. Startup then refuses the config by name until somebody renews or removes rules.
The log counts the term down once a day through its last fortnight, so the stop is not the first warning you get:
Re-applying the caps to a running relay would mean deleting rules, and that is worse than the stop. Lanes are built once and hold their rules for the life of the process; dropping a guardrail lets through statements it was refusing, and dropping a mask rule leaks the values it was hiding. A billing event must never widen what a proxy allows.

​
Control Plane

A Sidecar that knows nothing about a Control Plane reads its config file from disk and runs standalone. Pointing it at one is two independent settings: where the Control Plane is, and the token that identifies this Sidecar to it. The environment variable outranks the config file for the URL, the same as every other source pair in this file. There is no config file key for the token. A token is a bearer credential for this Sidecar’s identity, and a config file is the thing most likely to end up committed, backed up, or pasted into a support ticket — so the only two sources are the flag and the environment variable, never something written to disk in the file this Sidecar’s own diagnostics might echo back.
config.yaml
See Connect a Sidecar for the handshake itself and how to issue a token.

​
Audit

Six event kinds reach the sink: session_start, statement, violation, masked, error, session_end. A denial writes violation instead of statement, so a security team can select denials without scanning every statement anyone ever ran.
fail_closed: false is the default and it is the uncomfortable one. A dropped audit write lets the statement proceed and logs the error. Set it to true where proving who did what matters more than staying up.
The Sidecar records what was masked, never the values:
The admin listener serves a read interface to every statement every user ran, with no authentication and no CORS of its own. Bind it to loopback or put it behind whatever already gates audit access, and never expose it on a data port.

​
Upstream TLS

The hop from the Sidecar to the backend can be encrypted, and it costs you no inspection.
The Sidecar is the TLS client on that hop, so it decrypts on read and the gate inspects plaintext the same way it does without TLS. Verify it from a client session:
Three behaviors on a Postgres lane surprise people:
  • Postgres negotiates in-band. The server expects an 8-byte SSLRequest and a one-byte reply before any handshake. The Sidecar speaks that exchange, so upstream_tls works the way the field name implies.
  • A refusal is an error, never a downgrade. If the server declines TLS, the connection fails with a message naming the likely cause. Sending credentials in the clear because the server said no is the outcome you were preventing.
  • Channel binding is dropped from the server’s offer. With TLS terminating at the Sidecar, SCRAM-SHA-256-PLUS cannot work. The Sidecar removes that one mechanism, leaving plain SCRAM-SHA-256, which authenticates the same password against the same verifier.
On an MSSQL lane upstream_tls performs a plain TLS-on-connect handshake, which is TDS 8.0 and the only TLS shape the Sidecar originates. SQL Server on Linux cannot accept it: strict encryption is a Windows feature, and the Linux build offers network.forceencryption, whose TLS is the TDS 7.x kind negotiated inside 0x12 PRELOGIN packets. Leave upstream_tls off that lane and keep the hop on loopback or a private network.

​
The client leg is a different hop

upstream_tls covers the Sidecar-to-backend hop only. The Sidecar terminates no downstream TLS: if the client negotiates TLS all the way through, there is no plaintext at the gate and inspection is impossible. Terminating that leg belongs to Envoy. Keep the middle leg on loopback or a unix socket. It carries decrypted traffic, and a socket is the tighter boundary because no port exists to reach. See Terminating client TLS for the Envoy config.

​
Sharing a rule block between lanes

This is the reason to prefer YAML. Anchors let several listeners reference one block:

​
Validate before you deploy

Nothing needs to be running:
Validation builds every lane, so it catches what a syntax check cannot, and it reports every problem in one run rather than one per restart.

​
What startup refuses

A key typo, in YAML or JSON:
A bad regex, naming the lane and the rule:
A pii rule naming an entity absent from an explicit pii.entities:
That last check matters more than it looks. Without it the rule loads, evaluates, and matches nothing, so a guardrail looks live while allowing through everything it was written to stop. It only fires where pii.entities is set: with the section omitted, every supported entity is enabled and no rule can name one that is missing. An ai_analysis rule that would classify nothing:
Every analyzer refusal follows the same argument, applied to a control that also costs money per statement: a rule with no trigger, a tier with no action, a provider the binary does not link, or send: redacted with no pii section all produce a lane that looks classified and is not. The full list is in Risk Analysis. A rule that defers to nothing:
A gate over nothing:
A config over the free-tier caps, naming every block that authored rules so the message reads as a map of what to merge:
This one is checked after the license resolves rather than while the file parses, so a config a license makes legal is never refused before anyone read the license. See Licensing. Four more refusals arrived with findings, each one a config that would load and then mean something other than what it says: A mask block on a protocol whose codec can carry neither masking mechanism, naming the lane, plus a mask.rules entry with neither entities nor columns, empty rule lists, duplicate listen addresses, missing upstreams and an opa block with no URL.

​
Migrating from policy

The old policy section split into guardrails and opa, and four fields went away. Deprecated spellings still load and log a warning at startup, so an existing file keeps working; they are not part of the specification above and will be removed. Do not write both spellings of one concept into the same file. Three of those changes alter behavior rather than spelling:
  • Enforcement is unconditional. A lane that used to run with enforce: false starts denying the moment the field is dropped. Read /api/events?kind=violation on the observe-only deployment first, and move rules you are still evaluating to a staging listener or to action: defer behind a policy that allows them.
  • A mask block is live on sight. A block left in place with enabled: false used to be inert. Delete the rules to keep it off.
  • PII detection is on by default. A config that omitted pii detected nothing; the same file now enables every supported entity. Detection alone changes no traffic, since masking rewrites only what a mask rule names, but analyzer.send: redacted now has a detector to work with and pii guardrail rules can name any supported type.
/config no longer reports an enforcing flag per lane, and --validate no longer prints observe-only.

​
Next

Guardrail Rules

Every rule type in depth, deferring to Rego, and the findings a policy reads.

Get Started

Configure Envoy, run the Sidecar, and watch a denial land in psql.

Components and Architecture

How a request flows through the Sidecar, and where each config knob takes effect.