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.
Status. The vocabulary can change before 1.0.0. Pin the Box build you install. 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 one.
mcp:call: each MCP request, on every method.<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 working directory. |
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. |
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 on any method:
| 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. A policy with no matching shell:spawn permit refuses the server at
startup. For an enabled MCP wildcard command, command contains
the effective launch command, 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, 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.
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 decision, permitted or denied | The action’s input fields |
A::response | The operation ended, or its end is indeterminate | The input fields, plus output |
A::error | The operation did not happen | The input fields |
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 evidence that an earlier operation happened.
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 | At reply time, once per exchange | status: the upstream’s reply status |
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. |
mcp:call | When a tools/call, prompts/get, or resources/read completes | none |
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.