# Your first deny

One role's agents cannot run a recursive force-delete, and each denial tells the agent why.

- Who: Admin
- Where: Console or strazactl, and the agent's machine

In short: A policy set is one YAML document that says what a role's sessions may do. Each rule matches an event, such as a shell command, and allows or denies it, and a deny wins over every allow. Here one rule denies `rm -rf` for a role, with a reason the agent reads back to its user.


A policy set is one YAML document that says what the sessions of a role may do. Each rule matches a canonical event, such as a shell command, a file write or an MCP tool call, and produces allow or deny. An explicit deny wins over every allow, and the enterprise profile denies a local tool that no rule allows. A deny carries a reason that the agent reads back and relays to its user instead of retrying. [PolicySet grammar](https://docs.straza.ai/reference/policyset-grammar/index.md) lists every key a set can hold.

## Before you start

You need an administrator's console sign-in, or an admin API token for `strazactl` in `STRAZA_API_TOKEN` minted in the console as [Mint an admin API token](https://docs.straza.ai/guides/console/settings/index.md#mint-an-admin-api-token) shows, an application role, a user who holds it, and a machine enrolled as that user, as [Enroll a machine](https://docs.straza.ai/guides/govern-an-agent/enroll-a-machine/index.md) shows. This page uses the role `local-tools` and the user `dana`. The role reaches no MCP server and is there for policy rules only. The console makes such a role only together with a policy, through **A new role** in the New policy wizard, so this page makes it with the CLI:

Terminal, administration:

```sh
strazactl roles create local-tools --kind application
strazactl assign local-tools --user dana
```

Under the enterprise profile, a session from a machine whose install is not managed is refused at check-in, because `governance.minAttestation` defaults to `managed`. The outputs on this page come from a server at `http://localhost:8420` where it is set to `none`, as on the [demo stack](https://docs.straza.ai/evaluate/try-it-on-the-demo-stack/index.md), which is why the one-line `systemMessage` for the person says `attestation advisory`.

## Write the document

Save this as `local-tools-guardrails.yaml`. `match.roles` names an application role, the kind that carries the access rows, so every path to the role's tools is governed. The first rule opens the shell and file tools, because the enterprise profile denies a local tool that no rule allows. The second rule denies any command that matches the glob `rm -rf *`. Patterns are anchored and run against the raw command string, the argv joined again with single spaces, and against every single argv token, so quoting tricks do not slip past. The deny always carries its reason, and the session banner tells the agent to tell the user that reason and not to retry the call or work around it.

```yaml
apiVersion: straza.dev/v1beta1
kind: PolicySet
metadata:
  name: local-tools-guardrails
  description: Open the local tools for the local-tools role and deny recursive force-deletes with a reason
spec:
  match:
    roles: [local-tools]
  rules:
    - id: local-tools
      # The enterprise profile denies a local tool that no rule allows, so
      # this rule opens the local tools the role uses.
      events: [tool.pre]
      tools: [shell.exec, file.read, file.write, file.edit]
      effect: allow
    - id: no-rm-rf
      events: [tool.pre]
      tools: [shell.exec]
      command:
        denyPatterns: ["rm -rf *"]
      effect: deny
      reason: "Straza: recursive force-delete is denied for this role. Delete the files one by one, or ask an admin to change the local-tools-guardrails policy"
```

On a standalone host, leave `match` out so the set applies to every identity, and drop the `local-tools` rule, because the standalone default allows a local tool that no rule matches. The seeded `standalone-starter` set already denies `rm -rf` there, so this deny is a second copy of the same protection until you edit or delete the starter.

With the CLI:

Validate the file before it leaves your machine. The check is offline and needs no login.

Terminal, administration:

```sh
strazactl policy validate -f local-tools-guardrails.yaml
```

```text
local-tools-guardrails.yaml: PolicySet "local-tools-guardrails" OK (2 rules, priority 0)
note: validate refuses only the roles the product reserves, whose names start with straza- or mcp-admin-, in match.roles, and any of them but straza-admin in approve.roles. The server judges every other role a set names, in match.roles and approve.roles, and strazactl drafts check -f local-tools-guardrails.yaml runs those checks against live state.
```

## Store and publish it

In the console:

Click path in the console: "Policies" › "New policy" › "Write YAML instead" › "Save draft" › "Publish…" › "Publish"

![New policy written as YAML, with the policy text and Save draft](https://docs.straza.ai/shots/policy-yaml-dark.png)

The sheet that **Write YAML instead** opens, shown here with another policy set in it, and **Save draft** at its foot.

Paste the document into the sheet before **Save draft**. The console stores it as your draft, `Add policy set local-tools-guardrails`, and opens the draft's page with the server's checks. **Publish…** there opens the dialog that publishes it. The New policy wizard writes one outcome per run and a shell rule there needs a pattern, so a set like this one, an allow with no pattern beside a deny, goes in through the YAML door.

With the CLI:

`apply` uploads the document and stores it off, and nothing governs until you activate it, which compiles the policy snapshot again and distributes it.

Terminal, administration:

```sh
strazactl policy apply -f local-tools-guardrails.yaml
strazactl policy activate local-tools-guardrails
```

```text
applied local-tools-guardrails (Off, 01a0e994-2698-78f5-9137-e3ea3efd8edf)
published local-tools-guardrails, it is live now; new snapshot 186e5ced1e330243a67e88c285015689d8b50a0a416fa2f4a8f0bb5a8b1eaa35
```

Terminal, administration:

```sh
strazactl policy list
```

```table
NAME                          PRIORITY  STATUS  ID
agent-guardrails              150       Live    01a0e97b-ddea-7a79-b6bd-398e34fe1a13
local-tools-guardrails        0         Live    01a0e994-2698-78f5-9137-e3ea3efd8edf
```

The listing is trimmed to the two sets that matter here.

A session that is already running picks up the new snapshot as soon as the server announces it on the session's push stream, because `straza service` then renews the session at once. When that stream is down, a session that keeps working picks it up within about one call plus 30 seconds, because after a decision the service asks the server for a newer snapshot at most every 30 seconds, or every `snapshotLagSeconds` of the managed config. An idle session picks it up at its first call back when that call renews the session, which it does once 120 seconds or less of its token remain, and otherwise from the call after it. To see the change at once, start a new session.

## Prove the deny through the hook

CLI only: The hook runs on dana's enrolled machine, where the decision is made.

Run the hook by hand with the same JSON Claude Code sends. The session start checks the machine in and prints a governance banner that names the identity and tells the agent how to treat a deny.

dana's machine, client:

```sh
printf %s '{"hook_event_name":"SessionStart","session_id":"7d1c2f7e-4b1a-4c3e-9e6b-0b2a5d8f1c01","cwd":"/home/dana/work","source":"startup"}' | straza hook --harness claude-code
```

```text
{"hookSpecificOutput":{"additionalContext":"Straza governs this session as \"dana\". Every tool call is checked against policy and recorded in the audit log. When a call is denied, tell the user what the reason says, then do what it says next: wait for a person's approval, change the call, or try once more later. A denial that says none of these is a policy decision, and the same call will be denied again. Do not try to reach the denied result another way.","hookEventName":"SessionStart"}}
```

The output is trimmed to the context document, and the same run also prints a one-line `systemMessage` for the person that names the roles and the snapshot in force.

A matching command comes back as a deny with your reason, on stdout as the harness reads it and on stderr for you, and the process exits with code 2.

dana's machine, client:

```sh
printf %s '{"hook_event_name":"PreToolUse","session_id":"7d1c2f7e-4b1a-4c3e-9e6b-0b2a5d8f1c01","cwd":"/home/dana/work","tool_name":"Bash","tool_input":{"command":"rm -rf /home/dana/work/build"}}' | straza hook --harness claude-code; echo "exit $?"
```

```text
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Straza: recursive force-delete is denied for this role. Delete the files one by one, or ask an admin to change the local-tools-guardrails policy"}}
Straza: recursive force-delete is denied for this role. Delete the files one by one, or ask an admin to change the local-tools-guardrails policy
exit 2
```

A command the first rule allows passes with exit code 0 and an allow the harness understands.

dana's machine, client:

```sh
printf %s '{"hook_event_name":"PreToolUse","session_id":"7d1c2f7e-4b1a-4c3e-9e6b-0b2a5d8f1c01","cwd":"/home/dana/work","tool_name":"Bash","tool_input":{"command":"git status"}}' | straza hook --harness claude-code; echo "exit $?"
```

```text
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}
exit 0
```

## Read the audit record

`straza service` spools the record of each decision and starts an upload at once, so both decisions land in the audit log as soon as that upload completes.

In the console:

Click path in the console: "Users" › "dana" › "open"

The link **open** follows `Audit trail:` at the foot of dana's sheet, and it opens Audit filtered to dana. A row opens the record with its rule, its reason and the chain check.

![The audit record of alice's denied rm -rf, with the rule, the reason and what ran](https://docs.straza.ai/shots/audit-deny-dark.png)

A deny record, here alice's on a standalone server: the rule, its reason and what ran.

With the CLI:

Terminal, administration:

```sh
strazactl audit tail --user dana --limit 2
```

```text
#213 [dana] {"data":{"app":"","command":"rm -rf /home/dana/work/build","effect":"deny","event":"tool.pre","harness":"claude-code","reason":"Straza: recursive force-delete is denied for this role. Delete the files one by one, or ask an admin to change the local-tools-guardrails policy","ruleId":"no-rm-rf","session":"01a0e995-9374-76d0-8b10-5ac35c8c3902","setName":"local-tools-guardrails","snapshot":"186e5ced1e330243a67e88c285015689d8b50a0a416fa2f4a8f0bb5a8b1eaa35","tool":"shell.exec","user":"01a0e993-ecd5-7958-bb56-b30a3f7a5ca7","workspace":"/home/dana/work"},"id":"4a949ec4-cb5c-4ea2-bcdb-7b9ed5bcf6f7","source":"straza","specversion":"1.0","time":"2026-09-28T19:54:58.351075018Z","type":"straza.audit.tool"}
#214 [dana] {"data":{"app":"","command":"git status","effect":"allow","event":"tool.pre","harness":"claude-code","reason":"","ruleId":"local-tools","session":"01a0e995-9374-76d0-8b10-5ac35c8c3902","setName":"local-tools-guardrails","snapshot":"186e5ced1e330243a67e88c285015689d8b50a0a416fa2f4a8f0bb5a8b1eaa35","tool":"shell.exec","user":"01a0e993-ecd5-7958-bb56-b30a3f7a5ca7","workspace":"/home/dana/work"},"id":"ff9771fb-9811-406a-8259-5c9a2f048890","source":"straza","specversion":"1.0","time":"2026-09-28T19:54:58.381186984Z","type":"straza.audit.tool"}
```

Both decisions are `straza.audit.tool` records. Each names the command, the effect, the rule in `ruleId`, the set in `setName`, and the session and the snapshot that decided, and the deny also carries your reason.

## Undo

Turning the set off compiles the snapshot again without it. The document stays stored, so you can edit and turn it on again later.

In the console:

Click path in the console: "Policies" › "local-tools-guardrails" › "More" › "Turn off" › "Turn off"

With the CLI:

Terminal, administration:

```sh
strazactl policy deactivate local-tools-guardrails
```

```text
turned local-tools-guardrails off; new snapshot 18fb94f4ae40f36d31d05a1d39ed427f4a51de152c862d9544bdd34843a4368c
```

Two things trip new authors. A deny in any live set overrides an allow in every other set, so a broad allow elsewhere never rescues a command you deny here. A glob such as `rm -rf *` matches whole tokens and whole strings, so `rm -r -f build` passes it. When the variants matter, add a second pattern or a `re:` regular expression.

## Deny a tool of an MCP server

A tool of an MCP server is the event `mcp.call`. Rules name the server in `apps` and the tool in `toolNames`. Access to a server's tool comes from a role's access row, so an MCP rule never needs an allow. A deny rule matters when the row reaches more than the role should run, such as a row stored as every tool, including tools added later. This set keeps `get-env` of the `scout-tools` server from [Add a server](https://docs.straza.ai/guides/serve-mcp-apps/add-a-server/index.md) away from `scout-tools-readers`, because that tool prints the server's environment:

```yaml
apiVersion: straza.dev/v1beta1
kind: PolicySet
metadata:
  name: scout-tools-no-env
  description: Keep get-env of scout-tools away from scout-tools-readers
spec:
  match:
    roles: [scout-tools-readers]
  rules:
    - id: block-get-env
      events: [tool.pre]
      tools: [mcp.call]
      apps: [scout-tools]
      toolNames:
        deny: ["get-env"]
      effect: deny
      reason: "Straza: get-env prints the server's environment, which holds its secret. Ask an admin for the value you need"
```

In the console:

The New policy wizard writes this rule whole:

Click path in the console: "Policies" › "New policy" › "Denied" › "Next" › "A role" › "scout-tools-readers" › "Next" › "MCP tool"

Pick `scout-tools` under Server and tick `get-env`. On the next step, type the reason under `Reason the agent reads`, then name the set on Review and press **Save and publish**, then **Publish**.

With the CLI:

Terminal, administration:

```sh
strazactl policy validate -f scout-tools-no-env.yaml
strazactl policy apply -f scout-tools-no-env.yaml
strazactl policy activate scout-tools-no-env
```

The validate step prints `scout-tools-no-env.yaml: PolicySet "scout-tools-no-env" OK (1 rules, priority 0)` and the same note as above.

The gateway hides a tool that policy denies from the session's tools list, so the agent never sees `get-env`, and a call to it answers `unknown tool`, the same answer a misspelled name gets. With `apps.catalog.policyFilter` set to false in the strazad config, the tool stays listed and its call is denied with your reason. `strazactl catalog preview --role scout-tools-readers` shows the tool as `hidden_policy` with the reason, as [Access per role](https://docs.straza.ai/guides/serve-mcp-apps/catalogs-per-role/index.md) explains.

## Next

[Hold a call for a person](https://docs.straza.ai/guides/write-policy/hold-for-a-human/index.md) lets a person say yes before a call runs.


Walked on v1.1.0 on 2026-09-28. Linux, against the enterprise demo stack under the enterprise profile with the minimum attestation lowered to none, with strazactl logged in as an administrator and the hook events fed to straza hook by hand in a Linux container enrolled as dana. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

