PolicySet grammar

Every key of a PolicySet document, with its type, its default and a one-line example.

On this page

A PolicySet is one YAML document that selects sessions and holds the rules for their tool calls. The grammar is version straza.dev/v1beta1, and the parser refuses a key it does not know, so a typo fails at once instead of matching nothing. strazactl policy validate -f checks a file on your machine with no server, and strazactl drafts check -f adds the server’s checks of the roles the set names. Policies explains how rules combine. Every example on this page passes the offline check.

apiVersion: straza.dev/v1beta1
kind: PolicySet
metadata:
  name: dev-rules
  description: Rules for sessions that hold the dev role
spec:
  priority: 10
  match:
    roles: [dev]
  rules:
    - id: no-force-push
      tools: [shell.exec]
      command:
        denyPatterns: ["git push --force*"]
      reason: "Straza: force-push is denied for dev"
    - id: hold-deploy
      tools: [mcp.call]
      apps: [deploy-tools]
      toolNames:
        allow: ["deploy_*"]
      mode: approve
      approve:
        roles: [release-approvers]
      reason: "Straza: a deploy needs a release approver"

Document

Priority only picks which firing rule a decision reports, and it never turns a deny into an allow.

Match

Values inside one list combine with OR, and the lists combine with AND. An empty match selects every session.

match.roles takes application roles, the roles that carry tool access. A session holds every role its roles compose, so naming the application role covers every way a person holds it. The server’s check refuses a business role, an approver role and a Straza role in match.roles, and each refusal names the fix, such as “Name the application roles it composes instead”. A name that is not a role yet stays legal and matches nobody until the role exists.

match.identity needs at least one of its three lists. Your identity manager sets the user type, agency mode and swarm ID of each identity, as AI agents as identities shows. An identity that carries none of them matches no identity selector, so a set scoped to userType: [agent] does not reach it. A deny that must also catch such identities belongs in a set with no identity selector, and it then applies to people as well, because a deny overrides every allow.

match.groups was retired, and the parser refuses it with a sentence that tells you to select on roles instead.

Rule

A rule applies to a call when the call’s event kind is in events, its tool is in tools when the rule lists any, and, for a rule with apps, the call is an MCP call to one of those servers. A rule with apps never applies to a local tool, and toolNames is read only for an MCP call.

Once a rule applies, it checks require first. A session below the required attestation, or on a harness the list does not name, gets a deny from this rule with its reason. Harness names include claude-code, codex and gemini. require.deviceCert cannot be met today, because no device certificate is issued yet, so a rule that sets it denies wherever it gates an allow, and the server’s check warns that “require.deviceCert is not implemented yet”.

The pattern lists come next, deny side first. A match on a deny side is a deny, a match on an allow side is an allow, and a rule whose lists match nothing does not fire. A rule with no lists uses its effect. An interpreter list is read only when the shell command runs a known interpreter, such as bash, python3 or node.

The parser refuses a rule that can never fire with “rule needs an effect, a matcher block, or require (it can never fire)”. It also refuses effect: allow beside deny-side lists only, and the reverse.

obligations was retired. A set that carries it is refused, and the sentence names the two replacements, capture.mode: redact on the set and approve.notify on the rule.

Modes

A mode acts only when the rule’s allow wins, because a deny is final. Every mode fails closed.

A confirm rule shares the approve block, but the requester is the only one who decides. The parser therefore refuses roles, deciders and selfApproval under it, with “mode confirm may not set approve.roles (the requester is the decider)” and the same sentence for the other two keys. A local tool call that a confirm rule holds is denied with a reason that starts “Straza: this call needs the requester’s confirmation, on” and names where the requester confirms and the request’s reference.

Approve

The approve block is legal only beside mode: approve or mode: confirm, and the parser refuses it elsewhere with “approve block requires mode: approve or mode: confirm”.

An approve rule with no roles, no deciders and no selfApproval routes each request to the person behind the agent, which is the agent’s sponsor, or the person themself when they run their own agent. An agent with no usable sponsor is denied at once, and the server’s check warns about such a rule with “no approver named”. The server’s check also refuses an approve.roles entry that is not an approver role or straza-admin, with a sentence that says “only approver roles or straza-admin may decide”. For an autonomous session the engine turns selfApproval off, whatever the rule says.

A hold waits for the decision. The held MCP call keeps its connection open, and a local tool call is denied at once with the request’s reference, so the agent sends it again after the approval. One approval runs one call, either the held call or one identical retry by the same person in the same session within retryTTLSeconds of the decision. The parser refuses timeoutSeconds and retryTTLSeconds under class: ticket.

A ticket never waits. ticketTTLSeconds is the window in which a person decides. grantTTLSeconds is the time after the approval in which one later call that matches the approved one runs on the grant, from any session of the requester.

binding sets what an approval covers for an MCP call. call covers the tool and its exact arguments, and tool covers the tool with any arguments, for a tool whose arguments change on every call. bind: predicate is reserved and works exactly like fingerprint, and the server’s check says so. notify narrows which channels announce a request, and every surface where a person decides keeps working whatever it lists. Lifetimes and timeouts says what happens when each window runs out.

Patterns

• A pattern is a glob, or a Go regular expression when it starts with re:. Either one must match the whole value.
• In a glob, ? matches one character. In a command or a tool name, * matches any run of characters, spaces included.
• In a path, * stops at / and ** crosses it. ${workspace} stands for the session’s workspace, and a relative path in a call is read against it.
• A command pattern runs against the command as written, against its words joined with single spaces, and against each word alone, so quoting and extra spaces do not slip past a deny.
• A call that touches several paths is denied when any path matches a deny, and allowed only when every path matches an allow.
• Matching is case-sensitive, except the drive letter of a Windows path.

Events

A rule with no events fires on tool.pre, which every harness sends. The MCP gateway checks a call once, as tool.pre, so a rule for MCP calls whose events leave out tool.pre never fires there. The console’s rule editor and the server’s check both warn when a kind you pick never fires on a harness, and name the harnesses whose sessions then pass the rule. GET /v1/admin/policies/event-support serves the same table. An event kind Straza does not know is denied before any rule is read.

Tools

An MCP call that no rule matches runs when one of the caller’s roles has access to the tool, and is denied when none has. Every other tool that no rule matches takes the profile default, as Standalone and enterprise compared shows.

Capture

Recording is off unless a set that matches the session turns it on. When matched sets disagree on the mode, redact wins. The parser refuses mode without conversations: true, and the server’s check warns about a verbatim set with an empty match, because it records every session in full. Record a conversation shows a recording set.

Escape

The module runs after the rules and can only add denies. Straza reads its deny rules and nothing else, and refuses a module that declares an allow rule. The input is the call as input.event, the identity behind the session as input.subject and the rules’ decision as input.decision. A deny message reaches the agent with Straza: in front of it.

escape:
  rego: |
    package straza.ext

    deny contains msg if {
      input.event.tool == "shell.exec"
      contains(input.event.command, "sudo")
      msg := "sudo is not allowed"
    }

The modules that apply to one decision share a deadline of 100 ms, and a decision whose modules run past it is a deny. A module may not reach the network, the file system or the process environment, and may not call a built-in whose single call can run far past the deadline. The refused built-ins are http.send, net.lookup_ip_addr, json.match_schema, json.verify_schema, opa.runtime, strings.render_template, rego.parse_module, graph.reachable_paths, bits.lsh, net.cidr_contains_matches, glob.match and the six graphql built-ins. The refusal names the set, the built-in, its line and the reason:

policy: set rego-glob: its Rego module calls glob.match on line 4, and Straza refuses that built-in because a single call of it can run far past the 100 ms decision deadline or crash the process, and Straza checks that deadline only between calls. Remove the call from the module