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.

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.

@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 one.
    • mcp:call: each MCP request, on every method.
    • <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 working directory.

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.

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:

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. 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:

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, 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.

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

EventRecorded whenFields
A::requestEvery decision, permitted or deniedThe action’s input fields
A::responseThe operation ended, or its end is indeterminateThe input fields, plus output
A::errorThe operation did not happenThe 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:

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:requestAt reply time, once per exchangestatus: the upstream’s reply status
shell:exec, shell:spawnWhen the command endsstatus: the exit status. When a signal ends the command, status is 128 plus the signal number.
mcp:callWhen a tools/call, prompts/get, or resources/read completesnone

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.