Policies
A policy is one YAML (or JSON) document per project. It lists rules, says what happens when no rule matches, and sets the mode. The DSL only describes selectors: there are no expressions or code in it, so the same document gives the same decision in the Python SDK, the TypeScript SDK and the control plane's preview.
An example
schema_version: guard.policy.v1
policy_id: support-agent
version: 1
name: Support agent, least privilege
mode: suggest
default_effect: deny
source: manual
rules:
- rule_id: allow-customer-search
effect: allow
risk: normal
match:
action_type: tool.call
resource: search_customer
agent_id: support-agent
argument_keys: [customer_id]
message: Customer lookups are allowed.
- rule_id: deny-external-upload
effect: deny
risk: high
match:
action_type: tool.call
resource: "upload_*"
destination: "*.external.example"
message: Uploads to unapproved external services are not allowed.Every field is listed in Policy schema.
Format v1 and v2
guard.policy.v1 | guard.policy.v2 | |
|---|---|---|
| Rule effects | allow, deny | allow, deny, require_approval, degrade |
| Executors | Any SDK | Every active executor in the project must support format v2 |
Before a format v2 policy can be published, the project needs at least one connected executor, and every active executor must report format v2 support. The SDKs the wizard installs all do. Retire executors you no longer use on "Executors". SDKs older than format v2 refuse to load a v2 policy rather than misread it.
Modes
| Mode | Deny rules | Approval and degrade rules | No rule matches and default_effect: deny |
|---|---|---|---|
observe (Observe) | Allow with warning | Allow with warning | Allow with warning |
suggest (Suggest) | High-risk rules deny; risk: normal rules allow with warning | Allow with warning | Allow with warning |
enforce (Enforce) | Deny | Require approval / degrade | Deny |
A rule is high risk unless it says risk: normal, so in Suggest mode most deny rules already deny. An expired policy denies everything in every mode. A new project starts in Observe mode.
What a rule matches
A rule matches an action when every selector it sets matches. Selectors it leaves out match anything.
| Selector | Matches when |
|---|---|
action_type | Equal, or * (the default) |
resource | Glob match (upload_*), or * (the default) |
agent_id | Equal |
destination | Glob match on the action's destination; an action without one doesn't match |
argument_keys | The action has all these argument names |
argument_equals | Each named argument equals the value. The value session.subject_id means "equals the trusted subject" |
argument_in | Each named argument is one of the listed values |
argument_regex | Each named argument is a string of at most 4,096 characters that the regular expression matches in full |
argument_path_under | Each named argument is a path that, once resolved, lies under the given folder |
data_labels | The action carries all these labels |
Comparing with the trusted subject
argument_equals: {customer_id: session.subject_id} lets an agent act only on the signed-in user's own records. When the action has no trusted subject but carries customer_id, the rule can't be checked. Guard then treats it like a deny of that rule under the current mode, with reason SUBJECT_REQUIRED, so a missing subject never makes a deny rule silently fall away.
Regular expressions
A single expression can be at most 1,024 characters, and all the expressions in one policy at most 4,096. If any TypeScript executor is active, the editor warns about expressions outside the subset both SDKs evaluate the same way: no \d, \w, \s, \b, lookarounds, inline flags or backreferences, ^ only at the start and $ only at the end. See TypeScript SDK.
Which rule decides
- If
expires_athas passed, every action is denied (POLICY_EXPIRED). - If any matching rule is a deny rule, it decides (
RULE_DENIED). Deny always beats allow, whatever their order. - In format v2, among the other matching rules the most specific one wins: the one that sets the most selectors. On a tie,
require_approvalbeatsdegrade, which beatsallow. - A matching allow rule allows (
ALLOWED). - No rule matches:
default_effectdecides (DEFAULT_DENY, or allowed).
Then the mode adjusts the result (see Modes). Rule order in the file doesn't matter.
Checking a policy before you publish
On your own machine:
preworld-guard policy-validate policy.yaml
preworld-guard policy-schema --output guard-policy.schema.jsonpolicy-validate compiles the file and prints the result with its hash. policy-schema writes the JSON Schema for editors and CI.
The console's editor also refuses YAML anchors, aliases, tags, merge keys, duplicate keys and multiple documents, and documents over 64 KiB, deeper than 16 levels or with more than 5,000 nodes. Its preview warns when:
- The mode is Enforce, the default is deny, and there is no allow rule.
- The policy has an expiry time.
- There is an approval rule (approvals need a trusted subject on every call).
- A degrade rule's fallback tool isn't allowed by the policy itself.
- A managed gateway is connected and the mode isn't Enforce.
Tips
- Start in Observe mode, then generate a candidate from what the agent really did. See Publishing a policy.
- In Enforce mode, use
default_effect: denyand allow what you know. A missing allow rule then shows up as a denial you can see, not as a quiet gap. - Mark low-stakes deny rules
risk: normalif you want Suggest mode to only warn about them. - Write
messagefor the person who will read the denial: the model, the user or the reviewer.