Skip to main content
The analyzer is a per-listener component: an analyzer: block declared beside guardrails, opa and mask, not inside them. It sends a statement to a language model and denies on the risk that comes back. It runs wherever a content builder renders the statement for a model: SQL on a postgres, mysql or mssql listener, request bodies on an http one. It is the only evaluator that leaves the process, costs money per statement and can take a second, so most of its design is about not doing those things. Read the cost controls before you enable it anywhere real.
This runs entirely in the sidecar. There is no gateway call and no control plane: the Sidecar holds the provider credential and reads one YAML file, same as every other feature here.

​
A working config

Two blocks share the work. The top-level analyzer section holds what is genuinely process-wide, the provider, the model and the credential, plus the defaults every lane inherits. Each listener’s own analyzer block holds what is per lane: the trigger, the risk-to-action map, the prompt, and any inherited default it wants to override.
config.yaml
A field the block does not name inherits the top-level value, so the block overrides exactly what it writes down. send, fail_open, timeout_sec, max_input_bytes, max_calls and cache all work this way. Provider, model, endpoint and credential are never per lane: a second provider per lane would double the credential surface, so those stay in the top-level section. That split is also the reload boundary: editing a listener’s block hot-reloads like a rule edit, while the top-level section requires a restart, because the credential lives there.

​
Where it runs in the chain

Evaluators compose in ascending order of cost, and the chain stops at the first denial:
A DELETE that a type: operation guardrail already refuses never reaches a model. That ordering is fixed. The trailing decide-phase call appears only on a lane where a risk level or a guardrail rule defers. The gate phase puts a second decision in front of the analyzer as well.

​
The three cost controls

An ORM issues the same statement shape thousands of times in one session. Without these, that is thousands of API calls.
1

trigger narrows what is classified

Only statements naming these operations, tables or resources are sent. Everything else allows for free.Omit the trigger and every statement on the lane is classified: declaring the analyzer is the opt-in, and the cache and max_calls bound the bill. --validate prints a per-lane note naming that cost, so nobody ships it by accident. A lane running the gate behaves differently: there the policy decides what gets classified, and an omitted trigger leaves it fully in charge — Rego’s silence means skip, and nothing is spent without an explicit request.
2

The cache keys on the statement shape

WHERE id = 1 and WHERE id = 2 are one verdict: literals are stripped from SQL, and HTTP resources are already normalized by the codec, so /users/12345/orders and /users/67890/orders share an entry.This is also more correct than caching on bytes. The shape is what is risky, not the parameter.
3

max_calls is a backstop

A process-lifetime budget for the lane. Past it, statements fall through to the guardrails and OPA, the same outcome as a lane with no analyzer. The budget keys on the listener name, so a hot reload that edits the block continues the running count rather than re-arming it.
Watch the hit rate before you enable a blocking action:
Trigger on operations for anything load-bearing. tables comes from a scanner rather than a full SQL grammar, and a statement whose relations it could not determine does not match a table trigger. operations reads the statement’s most consequential effect, so a data-modifying CTE triggers on the delete it performs. See Guardrail Rules.

​
Actions

A risk level you do not name defaults to allow, so you opt into blocking a tier by writing it down. A blocked statement reaches the user the same way every other denial does:

​
defer hands the verdict to Rego

high: block decides the same way for everyone who touches the lane. high: defer makes the risk level one input among the actor, the hour and the table, and lets the Rego your InfoSec team already owns weigh them:
The analyzer still classifies, annotates and audits. The level travels to the decide-phase call as a finding under the ai_analysis source, with rule carrying the listener’s name, because a component has no rule name:
Guard on status before reading values. An absent risk_level means “found nothing”, “never ran”, “budget spent” and “provider down” all at once, and only the status tells them apart. Guardrail Rules has the full status vocabulary. defer on a lane with no opa.url loads, and denies on a match. Deferring to a decision that does not exist has to fail closed somewhere; --validate prints a note about it, and moving that failure from startup to runtime lets one file serve a deployment with OPA and a deployment without one.
require_review is refused at startup. Holding a statement for human approval needs a review backend this build does not have, and a config that reads as an approval gate while forwarding every statement is worse than one that fails.

​
The gate phase

trigger is a static filter written in YAML. A lane wanting “classify an UPDATE, but only outside business hours, and only against a table the policy calls sensitive” cannot say that in a trigger, and widening the trigger until it can pays for every statement in between. opa.gate: true adds an OPA decision before the analyzer runs, so the policy answers whether the call is worth making:
Both calls hit the same URL and carry input.phase, so a policy ignoring 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 the analyzer where its own trigger would have skipped, false vetoes a run the trigger would have made, and an absent key leaves the trigger 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.
gate: true on a lane with no analyzer block is refused at startup: a round trip per statement that gates nothing.

​
Requests only

The analyzer classifies FromClient statements and ignores responses. By the time a response comes back the write has already run, so a verdict cannot prevent anything. Read-side exposure is masking’s job, which costs less and already runs.

​
Why this one fails open

Every other evaluator in the Sidecar fails closed. This one defaults to fail_open: true, and the difference is what it depends on. OPA is a service you run, usually on the same host. A language model is a third-party API over the public internet. Fail closed there and a vendor outage refuses every UPDATE on the lane: you have turned “we could not score this statement” into “the database is down”, which is a bigger incident than the one you were guarding against. The verdict still carries the error, so it reaches the audit trail and /stats counts it. The guardrails and OPA both ran and both allowed, so a lane whose analyzer is down keeps every control except the paid one.
Set fail_open: false where the classification is a compliance requirement, and accept that a provider outage then stops traffic.

​
What leaves the process

send decides, using the same detector that powers masking: Neither mode needs a pii section: with the section omitted every supported entity is enabled, so a detector is always there to redact with. Set pii.entities to narrow what those modes look for.
A Sidecar whose job is keeping taxpayer IDs out of a database’s own query log must not post them to a model vendor. If you run PII detection, run send: redacted.
HTTP headers never reach the model, even ones a lane allowlists for policy. An allowlist that is safe for a local rule is not safe to hand a third party.

​
Writing your own prompt

Risk depends on what you are protecting, so the guidance is replaceable at two levels.
analyzer.prompt at the top level is process-wide. It reaches every lane, database and HTTP alike. Keep it protocol-neutral; guidance reading “you are classifying SQL against a customer database” follows an HTTP statement to the model and has it reasoning about DROP while it looks at a JSON body.
Protocol- and lane-specific wording belongs on the listener’s own block, which wins:
Precedence is listener block → top-level analyzer.prompt → built-in. Setting neither is fine: the built-in guidance carries separate high-risk examples for SQL and for HTTP.

​
The part you cannot replace

A prompt replaces the guidance. Two instructions are appended after whatever you write and cannot be removed:
The risk level is which tool the model chose, which makes it a three-value enum instead of a parsing problem. Without this instruction the model answers in prose, nothing maps to a level, and every statement fails classification. Under fail_open: true that allows everything.
The verdict is written to an audit record, and audit redaction covers statement text but not verdict metadata. A title repeating the identifier it objected to has published that identifier, through a channel that bypasses your redact_statements setting.
Neither failure raises an error. The classifier keeps answering, worse and leakier, so neither belongs in a config file. Changing a prompt invalidates cached verdicts for the lanes it applies to, so a reworded prompt takes effect on the next statement rather than after the cache TTL.

​
The HTTP lane needs capture_body

The HTTP codec exposes nothing by default: no bodies, no headers. Without a body the analyzer sees POST /orders and nothing else, which tells a model nothing.
An analyzer block on an HTTP lane without capture_body: true is refused at startup, because it could never classify anything. A grpc or spanner lane needs grpc.capture_payload: true for the same reason, and a lane whose protocol has no content builder at all is refused rather than left classifying nothing. A request that carries no body is still skipped at runtime once capture is on, and that stays intentional: paying for a verdict on POST /orders with no payload is the cost this design avoids. The startup check only asserts that the proxy could capture a body.
authorization, cookie and proxy-authorization cannot be allowlisted and are refused at startup. A lane exposing them to policy has put a bearer token into every decision log and audit record.

​
Providers

Vertex authenticates with a GCP OAuth bearer minted from a service account and refreshed before expiry. --validate mints one token, so a bad key, a missing roles/aiplatform.user binding or a skewed clock fails the config check rather than the first risky statement.
Prefer Workload Identity and omit credentials_file. On GKE there is then no credential on disk at all: the pod’s identity is the credential, so you have nothing to leak or rotate.
Set region: global or a multi-region endpoint. A single-region endpoint is an availability risk for something sitting on a database hot path.
One provider serves every lane, so the credential is read once.

​
The credential

The config holds a path, never the key itself. Three ways to supply one, strongest first.
On GKE, GCE or Cloud Run, omit credentials_file. Vertex then resolves Application Default Credentials, and there is no credential on disk at all: the pod’s identity is the credential, so nothing can leak from an image layer, a backup or a kubectl cp.
config.yaml
Bind the Kubernetes service account to a GCP one:
Rotation becomes a GCP concern rather than a redeploy.

​
There is no environment-variable option

The config reads no environment variable and performs no ${VAR} interpolation, deliberately, so this does not work:
/proc/<pid>/environ, docker inspect and a core dump all expose a process’s environment. A 0400 file exposes it to none of them.

​
What protects the key once it is loaded

The third layer is the one that catches you otherwise. A plain string escapes through a struct dump, a debug endpoint, a log line and a panic trace; the credential renders as [REDACTED] through all four, so a field added beside it later cannot leak by someone forgetting a tag. GET /config returns exactly this, with no credential field to omit:
An endpoint URL carrying userinfo or a query string is refused at startup, because that view sits beside a read interface to the audit trail and a credential in a URL would be published there.

​
Reading the verdicts

Every classified statement carries its risk into the audit trail, on allowed statements as well as denied ones:
ai_status is the analyzer’s own vocabulary and keeps the specific word: ok, cached, skipped, error, budget_exhausted, refused. A Rego policy sees a generic status instead, because a policy should not have to learn this package’s reasons: budget_exhausted and refused both arrive as unavailable, with the specific word in the finding’s reason. ai_rule names what produced the level: the listener name for an analyzer block, the rule name for a deprecated ai_analysis rule. That feeds a per-session rollup that keeps the highest risk the session reached:
Only the classification is recorded. The model’s title and explanation reach the user on a denial, but never the audit record.
One block per lane. A lane wanting several analyzers, say different triggers with different prompts, has no block equivalent yet: it keeps its deprecated ai_analysis rules until it can express itself as one block, and --validate counts what is left to migrate on each lane. If more than one evaluator classifies the same statement, the record keeps the highest risk reported, together with the action mapped to it, rather than whichever evaluator ran last.
Roll out with every tier on warn, watch by_risk in /api/stats and the cache hit rate in /stats for a week, then move high to block.

​
What startup refuses

Each of these would otherwise load, evaluate and do nothing: One former refusal moved to runtime: a risk level set to defer on a lane with no opa.url now loads, --validate prints a note, and a deferred verdict denies instead of reporting a finding nobody reads. Check before you deploy:
A lane still carrying deprecated rule-form analyzers reports + ai analyzer (N deprecated ai rule(s)) instead, so the leftover migration work is visible per lane.

​
Migrating from type: ai_analysis rules

The analyzer used to be spelled as a guardrail rule: type: ai_analysis under guardrails.rules. That form is deprecated and still works: it loads, builds the same evaluator through the same code path, and prints a deprecation naming the listener’s analyzer block. --validate --strict turns the warning into a non-zero exit. Both spellings can serve one lane while you migrate, each as its own evaluator. The Sidecar rewrites the file for you:
It folds every deprecated spelling onto its replacement, moves each ai_analysis rule onto its listener’s analyzer block where the move is faithful, and emits a document that passes --validate --strict. Where the move would be lossy — a lane carrying two ai rules, a top-level rule some lane cannot absorb — the rule stays put and the report on stderr says so. Comments and key order from the original are not preserved; review the diff before deploying. hoop start sidecar --migrate is the same command. Or by hand, move the rule’s fields onto the listener’s analyzer block; they keep their names:
Three things change with the move, all visible rather than behavioral traps:
  • metadata.ai_rule and the finding’s rule carry the listener name instead of the rule name, because a component has no rule name. Every field name in findings, audit metadata and /stats stays the same, so dashboards and policies keyed on the fields keep working; anything keyed on the old rule name as a value sees the switch.
  • The call budget keys on the listener name. Two lanes that shared one rule name used to pay from one purse; two analyzer blocks never do.
  • A rule in the top-level guardrails block used to reach every lane; the analyzer block is per listener, so write one on each lane that wants it. What was genuinely process-wide about the analyzer already lives in the top-level analyzer section.

​
Limits worth knowing

  • A verdict is a model’s opinion, sampled once. The same statement can classify differently on two runs, and the cache freezes whichever answer came first for its TTL. Keep the risks you can describe in an operation or table rule, which costs nothing and survives a vendor outage.
  • Requests only. A response verdict cannot prevent a write that already ran.
  • A slow classification can outlive the upstream’s idle budget. The Sidecar dials the upstream when it accepts, then holds the request while it classifies. An upstream with a short keep-alive (gunicorn defaults to 2s) hangs up before a 3s model call returns, and the client reads an empty reply. Raise the upstream’s idle timeout above your analyzer’s p99. The cache hides this after the first call for a given shape, so it shows up as a rare first-request failure.
  • A model can refuse to classify. The reply carries stop_reason: refusal and no verdict, and under fail_open: true the statement is allowed. The Sidecar records model refused to classify this statement. Watch for these in the audit trail while the lane is still on staging: a model that refuses is the wrong model for this job.
  • No human review. require_review is declared in the schema and refused at startup, so a config you write today stays valid when a review backend lands. defer is the closest thing that works now: a decide-phase policy holds the decision, though it still answers in milliseconds rather than waiting for a person.

​
Next

Guardrail Rules

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

Config File

Every other section of the config, and the full list of what startup refuses.

Components and Architecture

How a request flows through the Sidecar and where each verdict is decided.