Guardrails

Someone runs this against production:

UPDATE users SET email = 'test@example.com';

The WHERE clause is missing. 500,000 rows change. The statement was valid, the credentials were valid, the permissions were valid — nothing in the database’s own model of correctness had an objection. Guardrails are the objection. Every statement is decoded and evaluated before it reaches the resource, and a rule that matches refuses it with a message you wrote.

Free tier: one Data Masking rule and one Guardrail per Sidecar are free, forever. Running more than one rule per feature, or managing rules centrally across Sidecars, requires Enterprise.

How a rule set resolves

Three sentences cover the entire semantics:

A rule matches, and by default it denies.
First match wins among the rules that deny.
A rule set is an ordered deny list. No match means allowed.

config.yaml

guardrails:
  rules:
    - name: no-destructive-sql
      type: operation
      operations: [drop, delete, truncate]
      message: destructive statements are not permitted on this listener

Every rule takes name, message and action in addition to its own fields.

guardrails is Hoop’s own rule engine, evaluated in-process. It was previously spelled policy, which still loads and warns at startup — see Migrating from policy. The separate opa section configures the optional external endpoint a defer hands to.

A rule set that reaches a listener enforces. There is no observe-only switch to forget: a rule you wrote denies from the moment the process starts. Roll out on a staging lane, or hand the call to Rego with action: defer.

Rule types

`type`	Matches on	Protocols
`operation`	the statement’s most consequential effect	SQL, HTTP
`table`	the relation touched, narrowed by read or write	SQL
`deny_words_list`	a case-insensitive substring of the raw text	any
`pattern_match`	an RE2 regex over the statement text	any
`pii`	entity classes a detector finds in the request	any
`http_resource`	the normalized request path	HTTP
`http_status`	the response status	HTTP
`ai_analysis`	risk a language model reports	any

operation — deny by effect

- name: no-destructive-sql
  type: operation
  operations: [drop, delete, truncate]
  message: destructive statements are not permitted on this listener

operation reads the statement’s worst effect, not its leading verb. A delete hidden in a CTE — WITH d AS (DELETE FROM customers RETURNING *) SELECT count(*) FROM d — reports delete and this rule catches it. EXPLAIN DELETE … reports explain; EXPLAIN ANALYZE DELETE … reports delete, because it runs.Vocabulary:

select insert update delete merge create drop alter truncate grant revoke call copy explain show set begin commit rollback

, plus other (parsed but unclassified) and unknown (the scanner could not finish). HTTP verbs are their own values: get post put patch head options connect trace.

table — deny by relation

- name: customers-is-read-only
  type: table
  tables: [customers]
  access: write
  message: customers is read-only through this listener

access is read or write. Add require_table_match: true to also deny when the relations could not be determined — the fail-closed posture for anything genuinely off limits.

deny_words_list — deny by substring

- name: no-admin-functions
  type: deny_words_list
  words: [pg_sleep, pg_terminate_backend]
  message: administrative functions are not available here

Case-insensitive, matched against the raw statement text.

pattern_match — deny by regex

- name: no-unqualified-delete
  type: pattern_match
  pattern_regex: '(?i)^\s*delete\s+from\s+\w+\s*;?\s*$'
  message: a DELETE on this listener needs a WHERE clause

RE2 syntax — no lookaround, no backreferences. A bad regex is rejected at startup, naming the listener and the rule.

pii — deny sensitive values in the request

- name: no-national-id-in-query
  type: pii
  entities: [BR_CPF, US_SSN]
  message: do not put a national ID in a query; it lands in the database's own logs

Every supported entity is detected unless a top-level pii.entities list narrows the set. Once that list exists it is exhaustive, and a rule naming an entity absent from it is refused at startup — otherwise the guardrail would look live while allowing through everything it was written to stop.

http_resource and http_status

- name: no-admin-api
  type: http_resource
  resources: ["/admin/**"]
  methods: [POST, DELETE]
  message: the admin API is not reachable through this proxy

- name: no-upstream-5xx
  type: http_status
  statuses: ["5xx"]
  message: upstream failure suppressed by this listener

http_status is response-side, which is why an authorization filter running before the upstream can never ask it.

ai_analysis — deny by classified risk

- name: risky-writes
  type: ai_analysis
  trigger: {operations: [update, delete]}
  high: block
  medium: warn

This is the Agentic Access path. It takes per-risk-level actions instead of an action field, and setting action on it is refused at startup.

CALL and EXECUTE report unknown rather than call, because their bodies live in the catalog and no parser can say what they touch. A rule written operations: [call] matches neither. Write operations: [call, unknown].

Actions

action on a regular rule is either empty or defer. That is the whole list.

`action`	Effect
(empty)	Deny. First match wins.
`defer`	Record a finding, keep evaluating, and hand the decision to OPA.

- name: cpf
  type: pii
  entities: [BR_CPF]
  action: defer          # OPA rules on it

defer with no opa.url configured is refused at startup — a finding nobody reads forwards every statement while looking like enforcement.

action: warn and require_review are refused at startup. warn exists only as a per-tier action on ai_analysis rules. Human review needs a review backend the current build does not ship — see Agentic Access. For everything else, defer is how a rule stops short of deciding.

Inheritance: guardrail rules concatenate

A listener’s rules are evaluated first, then the top-level defaults:

config.yaml

guardrails:                      # inherited by every listener
  rules:
    - name: no-cpf-in-query
      type: pii
      entities: [BR_CPF]
      message: do not put a taxpayer id in a query

listeners:
  - name: appdb
    protocol: postgres
    listen: 0.0.0.0:15432
    upstream: appdb:5432
    guardrails:
      rules:                     # runs before the inherited rule above
        - name: no-destructive-sql
          type: operation
          operations: [drop, delete, truncate]
          message: destructive statements are not permitted on appdb

Concatenation is safe here precisely because first-match-wins applies to denials: adding rules can never turn a deny into an allow, only change which message the user reads. opa replaces rather than merges, and mask replaces too.

Roll out without breaking anything

Validate the config

Nothing binds and nothing is denied. Startup refusals — a bad regex, a rule naming an entity outside pii.entities, a defer with no opa.url — surface here rather than in front of users.

hoop start sidecar --config config.yaml --validate

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

Run the rule set on a staging lane first

Point a listener carrying the new rules at a staging copy of the upstream and send real query shapes through it. This is what replaces an observe-only flag: the rules are live, but on a lane whose denials cost nothing.

Read what got denied

curl -s 'localhost:19000/api/events?kind=violation' | python3 -m json.tool

Each violation names the rule that fired and the message the client read, so an over-broad rule is visible by name before it reaches production.

Defer anything you are not ready to decide

A rule with action: defer records a finding and hands the call to OPA instead of denying on its own. Rego that returns allow while you watch the findings gives you the same visibility on the production lane.

Move production traffic to the lane

Nothing changes in the rule set. /config reports the resolved rules per listener, which is what to compare against the file when a rule you wrote never fires.

Looking for guardrails on the Hoop Gateway instead? That is a different implementation — Python regex patterns configured in the web app, with Block, Warn and Require Approval actions. See Guardrails.

Guardrail Rules Reference

Every field of every rule type, deferring to Rego, and the full findings vocabulary.

Data Masking

Control what comes back, not just what goes in.

Getting Started

Core Concepts

Features

Control Plane Setup

Sidecar Reference

How a rule set resolves

Rule types

Actions

Inheritance: guardrail rules concatenate

Roll out without breaking anything

Next

Guardrail Rules Reference

Data Masking

​How a rule set resolves

​Rule types

​Actions

​Inheritance: guardrail rules concatenate

​Roll out without breaking anything

​Next

Guardrail Rules Reference

Data Masking

How a rule set resolves

Rule types

Actions

Inheritance: guardrail rules concatenate

Roll out without breaking anything

Next