Skip to main content
A policy file describes one policy. Files live in policies/ in your repository, at any depth, with a .yaml or .yml extension.

A complete example

policies/hipaa-phi-egress.yaml

Top level

metadata

metadata.id is the identity of the policy. Renaming it in place means the old policy is removed and a new one created — which apply will refuse without --allow-remove.
Each id must be unique across your whole file set. Two files claiming the same id are rejected, because which one owned the resulting rows would otherwise depend on directory ordering.

spec

spec.appliesTo

environments and models are enforced at different moments, and the difference matters:
  • environments is checked once, when you apply. apply refuses to write a policy into an environment the policy does not list. It never fans one apply out into several.
  • models is checked on every request. A policy scoped to ["gpt-4*"] does not fire for a request reporting claude-opus-4, and a request that reports no model at all is out of scope rather than blocked — the same convention model_governance uses.

spec.rules[]

Rule order is significant and is preserved exactly as written. Valid type values: pii, toxicity, topic_boundary, format, cost_ceiling, custom_llm, regex, agent_rate_limit, tool_misuse, loop_detection, agent_misuse, scope_enforcement, delegation_control, model_governance, secret_egress, schema_contract, require_confirmation.

loop_detection

Flags or blocks a tool call that repeats too often within the recent calls of a reply. A call that carries none of the keyFields is keyed on all its arguments, so it is never merged into a wrong key. With keyFields, only the current call’s own key is counted: earlier repeats of another key (another claim) never block it. A rule without keyFields still stops when any key reached the limit. Once per key. Zespan drafts a rule like this for a tool that moves money, deletes or is destructive, from the repeated calls in the finding itself: maxRepeatCalls: 2, windowSize: 10, the tool in toolFilter, and the argument names whose value was the same in every repeat (at most 3, for example amount_inr and claim_id) as keyFields. A name that is different on every normal call is kept first under the cap of 3, then id-like names, then the rest; request ids, idempotency keys, nonces, uuids, timestamps and trace or span ids are never used. The draft reads “Blocks a second call with the same within 10 calls”, and a retry that changes only a request id or a timestamp still counts as the same call, while a retry that changes one of the key fields is a different call and is not blocked. Arguments longer than 2,000 characters are cut when recorded, so such a call is keyed on all its arguments. If the key is unclear, too coarse, or the tool is not one you confirmed, Zespan drafts the plain repeat guard instead.

require_confirmation

Flags a call to a tool unless your app recorded a confirmation for that call. It runs on the tool-call check, before the tool runs. It is written in a policy document (it cannot be created from the guardrails page), and it is observe-only: it never goes above warn, and a policy that contains it cannot be set to deny, even with Apply without a test. A confirmation unlocks one call. Only a confirmation your own code records through the SDK counts: text in the conversation, in a tool result or in an argument never does. If your SDK does not send confirmation data, the rule reports no confirmation data and blocks nothing, at any enforcement level. Zespan checks that your app recorded a confirmation for the call. It does not verify that the end user agreed, who they are, or what they saw, and an app that records a confirmation from a model’s output defeats the rule. Each check writes one reason to the guardrail log: confirmed, no_confirmation, confirmation_rejected, confirmation_args_mismatch, confirmation_expired, sdk_no_ledger or hash_not_comparable (the SDK’s argument hash could not be compared with this call, for example with tool capture off and bindFields set; nothing is blocked). Your app records confirmations with confirmToolCall / confirm_tool_call — see Confirmations. When the rule type is not enabled for your deployment, an apply that contains it is refused with 422 and RULE_TYPE_DISABLED.

model_governance

Globs use * only; everything else is literal. A caller that reports no model at all is out of scope for this rule rather than blocked by it.

secret_egress

The curated set covers AWS access keys, GitHub tokens (including fine-grained PATs), Slack, Stripe, OpenAI, Anthropic, Google, SendGrid, Twilio, npm tokens, PEM private keys, JWTs and bearer credentials. With action: redact the matched material is replaced with [REDACTED] rather than the response being blocked.

schema_contract

Output that is not valid JSON is reported as such rather than as a schema mismatch. A rule with no schema passes rather than failing every response — the misconfiguration is caught by zespan policy validate.

spec.exemptions[]

An exemption suppresses the policy’s rules for the scope it names. A suppressed rule produces no guardrail event at all — not one recorded as allowed, which would read on the dashboard as “the control ran and found nothing”.
expiresAt is required, and a policy whose exemption has already expired fails validation — naming the exemption’s reason so you know which one to renew. An exemption with no expiry is a permanent hole in a control that nobody ever revisits.
The expiry is checked on every request, not when you apply. The day named in expiresAt is itself still exempt (compared as a UTC date, so the result does not depend on your server’s timezone); from the day after, the control enforces again on its own — you do not have to re-run apply for it to take effect. Renewing an exemption, or changing appliesTo.models, is a real change to the policy, so zespan policy plan reports it as an update.

The supported YAML subset

Policy files are parsed as YAML 1.2 core. Almost everything you would normally write works, including block scalars, flow collections, comments, and any consistent indentation. A small set of features is rejected — each with the line number and a message saying what to write instead. These are all things that make a security policy harder to read or review, not parser limitations:
Because parsing follows YAML 1.2 core rather than 1.1, on, off, yes and no stay strings rather than becoming booleans. This is the well-known “Norway problem” (no → false), and avoiding it matters here because on is a plausible value in a policy file.

Validation

Runs offline. Every problem in every file is reported at once:

Next steps

Policy as code

The authoring loop and the ownership model.

zespan policy

Every verb and flag.