Skip to content

Policy action reference

A rule names one action. The action decides which context.input fields the rule can read. The box ships ten actions, and generates one more for each MCP tool it discovers. Each experimental tool grammar adds its own Tool::<name> actions.

Audience: an operator writing a policy.dw who needs the exact action name, its context.input fields, and which part of the box raises it. Policy introduces the rules, and common rules shows each field in use.

A rule that names an action the build does not have refuses to load.

@id("no_env")
forbid (principal, action == Box::Action::"fs:read", resource)
when { context.input.path == "~/project/.env" };

Every request is one principal, one action, one resource, and a context. In the rule above:

  • Principal is Box::Agent::"self", always. Write principal with no condition.
  • Action is one of the names below. action == Box::Action::"fs:read" selects it.
  • Resource is Box::Resource::"unused", always. Write resource with no condition.
  • Context is context.input.<field>, and the fields depend on the action. context.input.path == "~/project/.env" reads the path field of fs:read.

A field marked ? below is optional. Read it behind a guard, as context.input has arg1 && context.input.arg1 == "-rf". A rule that reads an optional field with no guard refuses to load.

Some field names mean different things on different actions. path is a file on fs:read and the path part of a URL on http:request. So a rule that checks context.input covers actions of one family: actions whose names start the same way before the :, such as fs:read and fs:write. Each MCP tool action is a family of its own. A rule that checks context.input for fs:read and http:request together refuses to load, so write one rule for each.

Ten actions in four categories, and one generated action per MCP tool:

  • Filesystem, raised by Strands Shell (the box’s shell) and by Monty (the box’s Python interpreter).
    • fs:read: reading content or metadata, listing a directory, reading a symlink target, changing directory, and testing a file for execution.
    • fs:write: writing content, creating a directory, changing permission bits, and creating a symlink.
    • fs:delete: removing a file or an empty directory.
    • fs:move: renaming or moving a path, once per path.
    • fs:other: reserved. No operation raises it.
  • Network, raised by the egress gateway.
    • net:connect: each connection, before TLS.
    • http:request: each HTTP request inside the connection, after TLS on an HTTPS connection.
  • Shell, raised by Strands Shell.
    • shell:exec: a command line that runs a program the shell implements, such as cat or grep.
    • shell:spawn: a command line that runs a program of the surrounding OS, such as git. The box also raises it at startup, once for each stdio MCP server box.toml declares.
  • MCP, raised by the MCP broker for a local server and by the egress gateway for a remote server whose host matches its configured destinations.
    • mcp:call: each MCP request, except the protocol methods listed in MCP.
    • <server>::Action::"<tool>": a tools/call, after mcp:call permitted it.

The five fs:* actions carry the same two fields:

FieldTypeMeaning
pathStringThe resolved path, spelled ~/… under the operator’s home and absolute elsewhere.
operationBox::Fs<Verb>OperationThe exact verb. The table below gives the spelling and the values for each action.

A rule spells an operation with the action’s own prefix, as Box::FsReadOperation::"read_content":

ActionSpelled in a rule asValues
fs:readBox::FsReadOperation::"<value>"read_content, read_metadata, enumerate, read_link, change_dir, exec
fs:writeBox::FsWriteOperation::"<value>"write_content, create_dir, set_permissions, symlink
fs:deleteBox::FsDeleteOperation::"<value>"remove_file, remove_dir
fs:moveBox::FsMoveOperation::"<value>"rename
fs:otherBox::FsOtherOperation::"<value>"other

A value outside the action’s set refuses to load. A value with another action’s prefix loads, and the rule matches no request. Use the prefix from the action’s row in the table.

What path holds depends on the caller. From Strands Shell, path is the target with every symlink resolved. From Monty, path has . and .. resolved and keeps a symlink as the script spelled it. Monty decides a path that goes through a symlink on that spelling and then refuses it, whatever the verdict.

A rename is three or four decisions: fs:read and fs:move on the source, fs:move on the destination, and fs:delete on the destination when it exists (remove_dir for a directory, remove_file otherwise). All of them must permit. A denial names the path it refused.

fs:other is reserved: the box raises it for no operation. A rule that names fs:other must also name a raised action, as action in [Box::Action::"fs:read", Box::Action::"fs:other"]. A rule that names only fs:other refuses to load.

Each outbound call is two decisions, both of which must permit.

net:connect, once per connection, before TLS:

FieldTypeMeaning
hostStringThe destination host.
portLongThe destination port.
ip4?StringThe IPv4 address the gateway connects to, as a dotted quad, such as "203.0.113.7". Present for an IPv4 destination, and for an IPv6 destination that carries an IPv4 address in a wrapping Box recognises.
ip6?StringThe IPv6 address the gateway connects to, as text, compressed and in lowercase, such as "64:ff9b::cb00:7107". Present for every IPv6 destination, and absent for an IPv4 one.

Both are absent before resolution, on the decision for the host. A destination that arrives wrapped carries both: dialling 64:ff9b::cb00:7107 gives ip4 = "203.0.113.7" and ip6 = "64:ff9b::cb00:7107". A plain IPv4 destination carries ip4 alone, because one IPv4 address has many IPv6 encodings and there is no single IPv6 form to report.

Compare either as a String behind its own guard, as context.input has ip4 && context.input.ip4 == "203.0.113.7". An ipaddr comparison refuses to load with expected ipaddr but saw String.

http:request, once per request inside the connection, after TLS on an HTTPS connection:

FieldTypeMeaning
hostStringThe destination host.
portLongThe destination port.
methodStringGET, POST, and so on.
pathStringThe URL path in canonical form, without the query.
body_bytesLongThe request body length.
interceptedBooltrue when the gateway decrypted a TLS exchange, false for plain HTTP.

A rule on path has caveats for repeated slashes and %2F. Forbid one URL path on a host lists them.

Cloud metadata and link-local protection is two forbid rules on net:connect; what Box always enforces lists them.

A command line is judged once, after the shell parses it, expands it, and resolves its first word to a program. Each nested command, such as the one find -exec or xargs runs, is judged on its own.

shell:exec, for a program the shell implements:

FieldTypeMeaning
commandStringThe submitted text.
programStringThe program the first word resolved to. A shell alias changes command; program is the resolved target.
arg1?StringThe first argument after the program.
arg2?StringThe second argument.
arg_countLongHow many arguments follow the program.
cwdStringThe Shell’s working directory: ~ for the operator’s home, ~/… below it, and an absolute path elsewhere.

shell:spawn, for a program of the surrounding OS, carries the six shell:exec fields and two more:

FieldTypeMeaning
program_pathStringThe resolved binary, spelled ~/… under the operator’s home and absolute elsewhere.
credential_reads?Set of StringThe credential stores that box.toml names for this program under its [tool.<name>] table, such as ~/.aws.

On shell:spawn, cwd names the program’s launch directory. For programs launched through Strands Shell, the selected [tool.<name>] or [agent] table’s workspace takes precedence. Otherwise, Box checks the caller’s resolved directory against the agent’s workspace and the selected table’s read, write, list, and metadata trees. It uses the caller’s directory when one of those trees covers it, or the agent’s workspace otherwise.

The decision, request, and outcome use the same cwd spelling. The program starts in the corresponding absolute directory. If Box cannot select or resolve a directory for a Strands Shell launch, cwd names the Shell’s original directory. A program launched through Strands Shell starts only when its resolved directory matches the directory policy checked.

A program bound to a tool grammar raises its Tool::<name>::Action. For programs launched through Strands Shell, its cwd names the same selected launch directory and stays absolute in decisions and history, including paths below the operator home. Use that absolute path in directory predicates for those grammar actions.

When a tool grammar binds the program, the grammar action decides the spawn, and the spawn enters history as that action and not as shell:spawn. A spawn that the grammar binding refuses before any rule decides it enters history as a shell:spawn request. shell:spawn states when Box refuses one.

A rule that covers both actions names both, as action in [Box::Action::"shell:exec", Box::Action::"shell:spawn"]. A shell:exec permit covers the shell’s own programs, and a shell:spawn permit covers a program of the surrounding OS. A permitted program of the surrounding OS runs in its own sandbox, separate from the agent’s sandbox and wider than it. Its own file operations raise no fs:* decision; Security states that boundary.

mcp:call, once per request through a declared MCP server, except the protocol methods listed below. Remote MCP checks require a matching configured host.

FieldTypeMeaning
serverStringThe server name from box.toml.
methodStringThe JSON-RPC method: tools/call, tools/list, resources/read, and so on.
tool?StringThe tool, on tools/call.
prompt?StringThe prompt, on prompts/get.
uri?StringThe resource URI, on resources/read.

Each stdio server in box.toml starts through a shell:spawn decision on the program its [mcp.<name>] table names, or through the grammar action when a tool grammar binds that program. A policy with no matching permit refuses the server at startup. The program field is the executable’s filename, and program_path identifies its resolved file. The command field starts with that filename. For an enabled MCP wildcard command, command contains the alias name and effective launch arguments, joined by spaces. Its argument fields contain the same values, including the caller’s values in wildcard positions. A permit on mcp:call for a server covers every method and tool on it. Refuse one tool by name with a tool guard, or with the per-tool forbid that MCP policy shows:

forbid (principal, action == Box::Action::"mcp:call", resource)
when { context.input.server == "demo" && context.input has tool && context.input.tool == "echo" };

A generated per-tool action, <server>::Action::"<tool>", carries the tool’s arguments as context.input.<argument>, with the types the server’s tools/list declares. Run the policy generate-schema verb to see the exact names:

Terminal window
./box-core/box policy generate-schema --config my-box/box.toml --output-dir ./schema

It writes actions.cedarschema, with every action and its fields, including the actions of each tool grammar, and events.dwschema, with what a when temporal clause observes. The namespace is the server name with every character other than a letter, a digit, or _ changed to _. A leading digit gets a _ prefix. Server demo-mcp and tool lookup give demo_mcp::Action::"lookup".

A tools/call is two decisions: mcp:call first, then the tool’s generated action when one exists. A per-tool forbid refuses the call. When no per-tool rule matches, the mcp:call verdict stands.

A few protocol methods pass with no decision, and the set depends on the transport:

MethodLocal stdio serverServer over HTTP
initializePassesDecided as mcp:call
Each of server/discover, ping, subscriptions/listenPassesPasses
A notification (a frame with no id)PassesPasses
Every other methodDecided as mcp:callDecided as mcp:call

Over HTTP, each frame is also decided as http:request first. Because tools/list is decided, a rule can refuse it and hide a server’s tools.

Each experimental tool grammar adds the actions Tool::<name>::Action::"<action>", one for each [shell.<action>] table, and Tool::<name>::Action::"unmodeled". Version 2 and later of a grammar use the namespace Tool::<name>::v<version>. Tool::<name>::Action::"*" is the group of every action except unmodeled.

Every action of a grammar carries these fields, and unmodeled carries only these:

FieldTypeMeaning
programStringThe first word after expansion, as on shell:spawn.
program_pathStringThe resolved program file, spelled ~/… under the operator’s home and absolute elsewhere.
cwdStringThe program’s selected launch directory, as an absolute path. See directory selection.
argsSet of StringEvery word after the program.
effectsSet of Tool::<name>::EffectThe effects of this command. A grammar that declares no effect has no effects field.
credential_reads?Set of StringThe credential stores that the program’s [tool.<name>] lists name, as on shell:spawn.

Each other action also carries one field for each of its options and operands, named by its key in options or operands:

The option or operandType
An option with no valueBool
An option with one value, or an operand <name>String, and optional
A repeated option, an option with value = "many", or an operand <name>...Set of String

Box refuses to load a rule that reads context.input over two grammars, or over a grammar action and a Box:: action.

A when temporal { … } clause reads recorded events. The box records three events for each action A:

EventRecorded whenFields
A::requestEvery submitted decision, permitted or deniedrequestId and the action’s input fields
A::responseThe operation ended, or its end is indeterminaterequestId, the input fields, and output when available
A::errorThe operation did not happenrequestId and the input fields

requestId is a nonempty string that identifies one policy request within this box’s history. Its recorded response or error carries the same identifier. Separate requests receive separate identifiers, even when their inputs are identical. Bind the same variable to requestId in two predicates to require events from the same request. Treat the identifier’s spelling as opaque. Older events that lack this field remain in history, but cannot match a predicate that requires it.

For modern stdio MCP, a valid result that asks for more client input before cancellation is not a completed operation and does not record mcp:call::response. Each retry is a new request. Its terminal result or error records a response with that retry’s request ID.

Cancelling an admitted modern stdio tools/call, prompts/get, or resources/read records one indeterminate response immediately. A late reply adds no second event, even if it asks for more input. When the connection ends, Box stops the server and records its remaining admitted item calls as indeterminate outcomes. Each outcome uses the original call’s request ID.

To cap how many times the agent tries an action, count A::request, which also counts denied attempts. Use A::response when a later rule needs a recorded outcome. Partial or indeterminate outcomes also count; an MCP response does not establish tool success.

What each caller records as a response:

ActionResponse recordedoutput
fs:*When the operation ends. A test -e, test -L, or test -r in the Shell, or an os.stat(), Path.exists(), Path.is_file(), Path.is_dir(), or Path.is_symlink() in Python, that got an answer is a response even when the answer is “no”: for example, a missing file in an existing folder. A check of a path inside the reachable paths that can’t be resolved, such as one under a missing folder or under a folder the operating system won’t let Box search, is also a response, although the reachable paths check refuses it. This holds only when the path has no . or .. component, crosses no symbolic link, and isn’t in Box’s own state. Any other check that Box itself refuses is an error: the reach floor refuses it, or a guard refuses it because a path changed during the check.result, spelled Box::FsResponseResult::"<value>": completed, descriptor_issued, or indeterminate
net:connectWhen the connect attempt endsnone
http:requestWhen the upstream response completes, fails, or reaches its deadline, once per exchangestatus: the upstream’s reply status, when received
shell:exec, shell:spawnWhen the command endsstatus: the exit status. When a signal ends the command, status is 128 plus the signal number.
A tool grammar action, Tool::<name>::Action::"<action>"When a program the Shell started endsstatus, as on shell:spawn
mcp:callFor tools/call, prompts/get, and resources/read: when the call completes or ends indeterminately over stdio, or when the upstream response completes, fails, or reaches its deadline over HTTPnone
A per-tool action, <server>::Action::"<tool>"Beside each mcp:call::response for a tools/call that the per-tool action decided and allowed. Its input is the call’s arguments, as its ::request recorded themreply, a string: result, tool_error, or protocol_error for the server’s answer; cancelled; or indeterminate when the connection ended, when the reply only accepted an MCP task or asked for input (resultType other than complete), or when Box couldn’t read an http reply in full (over 16 MiB, compressed, or cut off). structured, when the tool declares an outputSchema and the reply is a result: the reply’s structuredContent, keeping only the fields the outputSchema declares, converted like input. An optional field that doesn’t match its declared type is left out. Box records no structured when a required field doesn’t match

In the Shell, a content write (a redirect, tee, or cp) records descriptor_issued when it opens the file, and nothing when it finishes. A time change from touch records completed.

An MCP outcome is always a response, so Box never records mcp:call::error or a per-tool ::error. The load refuses a when temporal clause that names one, because it could never match. A tools/call to a tool that no per-tool action declares records only mcp:call::response.

Each temporal operator carries a window of at most 24h. A temporal predicate names exactly one action, so a budget that spans fs:read and fs:write is one clause per action.