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.
The fixed parts
Section titled “The fixed parts”@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. Writeprincipalwith no condition. - Action is one of the names below.
action == Box::Action::"fs:read"selects it. - Resource is
Box::Resource::"unused", always. Writeresourcewith no condition. - Context is
context.input.<field>, and the fields depend on the action.context.input.path == "~/project/.env"reads thepathfield offs: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.
The ten actions
Section titled “The ten actions”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 ascatorgrep.shell:spawn: a command line that runs a program of the surrounding OS, such asgit. The box also raises it at startup, once for each stdio MCP serverbox.tomldeclares.
- 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>": atools/call, aftermcp:callpermitted it.
Filesystem
Section titled “Filesystem”The five fs:* actions carry the same two fields:
| Field | Type | Meaning |
|---|---|---|
path | String | The resolved path, spelled ~/… under the operator’s home and absolute elsewhere. |
operation | Box::Fs<Verb>Operation | The 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":
| Action | Spelled in a rule as | Values |
|---|---|---|
fs:read | Box::FsReadOperation::"<value>" | read_content, read_metadata, enumerate, read_link, change_dir, exec |
fs:write | Box::FsWriteOperation::"<value>" | write_content, create_dir, set_permissions, symlink |
fs:delete | Box::FsDeleteOperation::"<value>" | remove_file, remove_dir |
fs:move | Box::FsMoveOperation::"<value>" | rename |
fs:other | Box::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.
Network
Section titled “Network”Each outbound call is two decisions, both of which must permit.
net:connect, once per connection, before TLS:
| Field | Type | Meaning |
|---|---|---|
host | String | The destination host. |
port | Long | The destination port. |
ip4? | String | The 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? | String | The 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:
| Field | Type | Meaning |
|---|---|---|
host | String | The destination host. |
port | Long | The destination port. |
method | String | GET, POST, and so on. |
path | String | The URL path in canonical form, without the query. |
body_bytes | Long | The request body length. |
intercepted | Bool | true 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:
| Field | Type | Meaning |
|---|---|---|
command | String | The submitted text. |
program | String | The program the first word resolved to. A shell alias changes command; program is the resolved target. |
arg1? | String | The first argument after the program. |
arg2? | String | The second argument. |
arg_count | Long | How many arguments follow the program. |
cwd | String | The 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:
| Field | Type | Meaning |
|---|---|---|
program_path | String | The resolved binary, spelled ~/… under the operator’s home and absolute elsewhere. |
credential_reads? | Set of String | The 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.
| Field | Type | Meaning |
|---|---|---|
server | String | The server name from box.toml. |
method | String | The JSON-RPC method: tools/call, tools/list, resources/read, and so on. |
tool? | String | The tool, on tools/call. |
prompt? | String | The prompt, on prompts/get. |
uri? | String | The 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:
./box-core/box policy generate-schema --config my-box/box.toml --output-dir ./schemaIt 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:
| Method | Local stdio server | Server over HTTP |
|---|---|---|
initialize | Passes | Decided as mcp:call |
Each of server/discover, ping, subscriptions/listen | Passes | Passes |
A notification (a frame with no id) | Passes | Passes |
| Every other method | Decided as mcp:call | Decided 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.
Tool grammar actions
Section titled “Tool grammar actions”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:
| Field | Type | Meaning |
|---|---|---|
program | String | The first word after expansion, as on shell:spawn. |
program_path | String | The resolved program file, spelled ~/… under the operator’s home and absolute elsewhere. |
cwd | String | The program’s selected launch directory, as an absolute path. See directory selection. |
args | Set of String | Every word after the program. |
effects | Set of Tool::<name>::Effect | The effects of this command. A grammar that declares no effect has no effects field. |
credential_reads? | Set of String | The 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 operand | Type |
|---|---|
An option with no value | Bool |
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.
What a temporal rule observes
Section titled “What a temporal rule observes”A when temporal { … } clause reads recorded events. The box records three events for each action
A:
| Event | Recorded when | Fields |
|---|---|---|
A::request | Every submitted decision, permitted or denied | requestId and the action’s input fields |
A::response | The operation ended, or its end is indeterminate | requestId, the input fields, and output when available |
A::error | The operation did not happen | requestId 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:
| Action | Response recorded | output |
|---|---|---|
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:connect | When the connect attempt ends | none |
http:request | When the upstream response completes, fails, or reaches its deadline, once per exchange | status: the upstream’s reply status, when received |
shell:exec, shell:spawn | When the command ends | status: 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 ends | status, as on shell:spawn |
mcp:call | For 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 HTTP | none |
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 them | reply, 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.
See also
Section titled “See also”- Policy: what a policy is, the common rules, and the refusal for a misspelled action, value, or field.
- Write a policy and read what it decided: the rule shape and the denial text.
- Security: what the operating system enforces with no policy decision.