Skip to content

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 ​

yaml
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.v1guard.policy.v2
Rule effectsallow, denyallow, deny, require_approval, degrade
ExecutorsAny SDKEvery 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 ​

ModeDeny rulesApproval and degrade rulesNo rule matches and default_effect: deny
observe (Observe)Allow with warningAllow with warningAllow with warning
suggest (Suggest)High-risk rules deny; risk: normal rules allow with warningAllow with warningAllow with warning
enforce (Enforce)DenyRequire approval / degradeDeny

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.

SelectorMatches when
action_typeEqual, or * (the default)
resourceGlob match (upload_*), or * (the default)
agent_idEqual
destinationGlob match on the action's destination; an action without one doesn't match
argument_keysThe action has all these argument names
argument_equalsEach named argument equals the value. The value session.subject_id means "equals the trusted subject"
argument_inEach named argument is one of the listed values
argument_regexEach named argument is a string of at most 4,096 characters that the regular expression matches in full
argument_path_underEach named argument is a path that, once resolved, lies under the given folder
data_labelsThe 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 ​

  1. If expires_at has passed, every action is denied (POLICY_EXPIRED).
  2. If any matching rule is a deny rule, it decides (RULE_DENIED). Deny always beats allow, whatever their order.
  3. In format v2, among the other matching rules the most specific one wins: the one that sets the most selectors. On a tie, require_approval beats degrade, which beats allow.
  4. A matching allow rule allows (ALLOWED).
  5. No rule matches: default_effect decides (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:

sh
preworld-guard policy-validate policy.yaml
preworld-guard policy-schema --output guard-policy.schema.json

policy-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: deny and 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: normal if you want Suggest mode to only warn about them.
  • Write message for the person who will read the denial: the model, the user or the reviewer.