Authoring Box Policy

Authoring a Strands Box policy (Dogwood)

Your job: turn a natural-language authorization intent into a Dogwood policy.dw for a Strands Box that loads clean and means what the operator actually intended. This is a formalization task — the hard part is not the syntax (that is documented; see Ground truth) but pinning down ambiguous intent and mapping it onto the right construct over the box's fixed vocabulary.

This is an interactive session, not a one-shot generator. You work with the operator: draw out the intent, ask a sharp question rather than guess when a requirement is underspecified, propose rules, and confirm what stays refused. Do not return a policy you have not loaded.

You author rules, not a schema. A generic Dogwood deployment makes the operator author an action schema and a service schema. Strands Box does not — the box ships a fixed, built-in schema, so the vocabulary of actions, the one principal, and the context shape are already set. You write the permit and forbid rules against that schema — the fixed vocabulary is below.

Follow the loop in order:

1. Disambiguate the intent (resolve every gap that changes the output).
2. Formalize it into policy.dw.
3. Validate by loading it into the box — fail-closed, mandatory (see Step 3). An unloaded policy is not a finished answer.
4. Round-trip the intent and present the result.

The ground truth (read before authoring)

Treat these as authoritative; do not invent syntax, an action, or a field from memory. If a construct is not in these sources, it does not exist.

Box-specific — the vocabulary and the floors:

• The fixed vocabulary below — the one principal, the fixed resource, every action and its context, and the temporal event shape. The source of truth for the box.
• The built-in schema you author against, read but never edit. Generate it in the workspace with box policy generate-schema, which writes .strands-box/actions.cedarschema (actions and their context) and .strands-box/events.dwschema (what a when temporal { … } rule observes). The generated files also carry each declared MCP server's per-tool actions, which a static copy cannot.
• The bundled examples/ — whole agent policies and single-shape refinements to copy from. See examples/README.md.
• The decisions behind the vocabulary, in docs/design/decisions.md: the closed action vocabulary, the filesystem actions, temporal rules, and a credential binding is not an authorization.

Language grammar — bundled in this skill's references/:

• references/dogwood-policy-language.md — core policy syntax: permit/forbid, the (principal, action, resource) scope, when/unless, and the full Cedar expression language (operators, literals, methods, has/like/is, sets/records). See its "Condition expression language" and "What parses but is rejected" sections.
• references/dogwood-temporal-expressions.md — the temporal { … } sublanguage: formerly/previous/since, windows, exists/tp, count/sum, and the acceptance rules. Read "Writing temporal expressions that are accepted" in full before writing any history rule.

The fixed vocabulary

Every request is (principal, action, resource, context). The principal is always Box::Agent::"self" (leave it a bare principal) and the resource is always Box::Resource::"unused", so the action scopes a rule and every readable field rides context.input. There is no context.system, no context.principal, and no now; the only field outside input is output, on a ::response, read only by a temporal rule: output.result on a filesystem response, output.status on an http:request response, and the exit output.status on a shell:exec or shell:spawn response.

The actions are a closed set. A policy names one; it cannot add one. The last column is the exact context.input fields you scope on.

Filesystem operation enums (narrow within an fs: action): FsReadOperation = read_content, read_metadata, enumerate, read_link, change_dir, exec; FsWriteOperation = write_content, create_dir, set_permissions, symlink; FsDeleteOperation = remove_file, remove_dir; FsMoveOperation = rename; FsOtherOperation = other.

Rules that bite:

• No action groups — fs:read does not cover fs:write; cover a family one clause per action.
• One outbound host is two decisions — net:connect (port, before TLS) and http:request (host, after TLS).
• Guard an optional field with has (arg1, arg2, tool, prompt, uri, ip); an unguarded read is a load error.
• path is a filesystem path on fs:* and a URL path on http:request; only fs:* carries operation, so guard a filesystem rule with context.input has operation.
• Write a shell rule on program (what the first word resolved to), not command. Do not read ip in a temporal predicate — it faults.
• tool:invoke, model:invoke, agent:invoke, and cred:inject are removed — naming one is an UnknownAction load error.

Temporal event shape. For action A: a A::request (its input fields), a A::response (its input and output fields, only for an effect that happened), and a A::error. Key a precondition on ::response; a window is mandatory and capped at 24h; there is no ||.

For the rationale behind the vocabulary, read the ## Policy section of docs/design/decisions.md.

The floors you cannot change

A policy only ever adds reachability. Some things hold whatever a rule says:

• Deny-by-default, deny-overrides. No permit means deny, and a forbid always beats a permit. An exception to a broad allow is a forbid that carves a hole, never a narrower permit.
• The reach floor refuses every path inside a .strands-box directory and every write to the box.toml and policy this run loaded, beneath policy, in every box. No rule widens it.
• The SSRF / cloud-metadata floor sits below the engine. A rule can deny more, never re-open it.
• A credential binding is not an authorization (decisions). An [egress.*] entry in box.toml says only what is attached to a request the policy already permitted. It never makes a destination reachable — reachability is this policy's decision alone. The two must name the same host.
• Information providers are not available. A Provider::Name(args) call or a guardrails { … } clause aborts box startup. Do not reach for a computed fact — there is no provider path in the box.

Step 1 — Disambiguate intent (do this first)

A prose intent almost always leaves gaps that change the formal policy. Resolve every gap that affects the output. If you can infer the answer from an obvious convention, state your assumption and proceed; otherwise ask. Prefer a few sharp, batched questions over silently guessing.

Every policy needs egress to an LLM provider. The agent cannot run without reaching a model, so a policy that grants no provider access does not work — confirm which one (Amazon Bedrock, OpenAI, or Anthropic) and write its two egress legs (net:connect and http:request) before anything else. Match the provider to the box's configured endpoint. See the three agent examples in examples/.

1. Effect and default. Granting (permit) or restricting (forbid)? The box is default-deny with deny-overrides. "The agent may X" → a permit. "Never X" / "block X when Y" → a forbid that carves a hole out of the permits.
2. Which action(s)? The principal and resource are fixed, so the action is what scopes a rule. Map the operator's nouns to concrete actions from the table above. Remember: no groups (one clause per fs: verb), and two legs for one outbound host (net:connect and http:request).
3. Where does each fact live? Every fact rides context.input.<field> — confirm the field name and type against the table. There is no principal/resource attribute to read (both are fixed), no context.system, and no provider for a computed fact. A fact about the past goes to the temporal sublanguage (Step 2b).
4. Path and host scope. For a filesystem rule, get the exact path and whether it is one file or a subtree — a subtree needs two clauses (the directory and its contents; see Common shapes). Prefer ~-relative paths so the file is portable. For a host, get the exact hostname and port.
5. Temporal specifics (if history is involved) — the highest-value disambiguations:
   • "happened at least once recently" → formerly within W.
   • "the immediately preceding event" → previous within W.
   • "has held continuously since an anchor" → left since within W right; "has NOT happened since" → a negated since left (there is no dedicated operator).
   • The window W is mandatory (s/m/h/d; no week/month/year) and capped at 24h in the box. If the operator says "recently" without a number, ask — there is no default, and you cannot raise the cap (the event schema is fixed).
   • "the same X" → pin the past predicate's field to the current request: input.path: context.input.path. With one principal, principal-correlation is automatic; correlate anything else (same path, same host) explicitly, or "the same X" silently becomes "any X".
   • Counting/summing → count/sum (no min/max/avg). Confirm the threshold and operator.
   • Key on ::response, never ::request. A ::request event exists even for a denied attempt, so a step-up keyed on ::request is defeated by asking and being refused. A ::response exists only for an effect that happened.
6. Edge cases the prose glosses over. An absent optional field (has guard)? Inclusive boundary (windows are closed)? Surface these and pick a defensible default, stating it.

Tie each question to how it changes the policy — "'recent' — within what window (e.g. 1h)? And the same host the agent reached, or any host?" — not a vague "can you clarify?".

Step 2 — Formalize

2a. Core (single-request) rules

Map the disambiguated intent onto the rule shape (doc comment, @id, @description on a forbid, effect, scope, when/unless, ;). Lead each rule with a // comment in the operator's words and an @id("…"). Keep the scope as the coarse filter (the action) and put fine logic in when/unless.

Give every forbid a @description("…") that the agent can act on. The box prints every @description on a determining forbid into the denial message that the agent sees, so the string is how the policy talks to the agent about why a request was refused. Say what is refused and what the agent should do instead — a sentence the agent can read and take a different action from, not an internal note. A @description on a permit is ignored, so put the author's reason there in a leading // comment instead.

// Refuse setting permissions anywhere, whatever a write permit allows.
@id("no_chmod")
@description("This workload cannot change file permissions. Make the file writable before the box starts, or ask the operator to add a chmod rule.")
forbid ( principal, action == Box::Action::"fs:write", resource )
when { context.input.operation == Box::FsWriteOperation::"set_permissions" };

Use the operator/method vocabulary from references/dogwood-policy-language.md. Watch the type rules it calls out: decimals are equality-only, / and % are unsupported, and there is no let … in.