Skip to content

Instantly share code, notes, and snippets.

@pimlock
Last active September 19, 2026 00:24
Show Gist options
  • Select an option

  • Save pimlock/835476b662c06051da5dac9ee7c0da77 to your computer and use it in GitHub Desktop.

Select an option

Save pimlock/835476b662c06051da5dac9ee7c0da77 to your computer and use it in GitHub Desktop.
OpenShell policy YAML compared with the current SandboxPolicy protobuf shape
# Current authored policy YAML from the model introduced by PR #3334.
version: 1
filesystem_policy:
include_workdir: true
read_only:
- /usr
- /lib
- /etc
read_write:
- /sandbox
- /tmp
landlock:
compatibility: best_effort
process:
run_as_user: sandbox
run_as_group: sandbox
network_policies:
github:
name: github-read
endpoints:
- host: api.github.com
port: 443
protocol: rest
enforcement: enforce
rules:
- allow:
method: GET
path: /repos/**
query:
state: open
deny_rules:
- method: POST
path: "**"
binaries:
- path: /usr/bin/curl
mcp_tools:
name: approved-mcp-tools
endpoints:
- host: mcp.example.com
port: 443
protocol: mcp
enforcement: enforce
mcp:
versions:
- "2025-11-25"
max_body_bytes: 131072
strict_tool_names: true
allow_all_known_mcp_methods: true
rules:
- allow:
method: tools/call
tool: repo_*
binaries:
- path: /usr/local/bin/agent
# The same policy in today's SandboxPolicy protobuf shape.
# Canonical ProtoJSON field names are used, but the document is written as YAML.
version: 1
filesystem:
includeWorkdir: true
readOnly:
- /usr
- /lib
- /etc
readWrite:
- /sandbox
- /tmp
landlock:
compatibility: best_effort
process:
runAsUser: sandbox
runAsGroup: sandbox
networkPolicies:
github:
name: github-read
endpoints:
- host: api.github.com
port: 443
ports:
- 443
protocol: rest
enforcement: enforce
rules:
- allow:
method: GET
path: /repos/**
query:
state:
glob: open
denyRules:
- method: POST
path: "**"
binaries:
- path: /usr/bin/curl
mcp_tools:
name: approved-mcp-tools
endpoints:
- host: mcp.example.com
port: 443
ports:
- 443
protocol: mcp
enforcement: enforce
jsonRpcMaxBodyBytes: 131072
mcp:
strictToolNames: true
allowAllKnownMcpMethods: true
versions:
- "2025-11-25"
rules:
- allow:
method: tools/call
params:
name:
glob: repo_*
binaries:
- path: /usr/local/bin/agent

Policy YAML compared with the current policy protobuf

Historical comparison. The current proposal uses a separate public authored proto, keeps binaries as [{path: ...}], treats omitted and empty binaries as matching no process, uses ports only, and adopts the full proto matcher shapes. See the links under "Current design" below.

This gist shows one policy twice:

  • 01-authored-policy-v1.yaml uses the YAML shape owned by the handwritten policy model in PR #3334.
  • 02-current-runtime-proto.yaml shows the same policy in the shape of today's SandboxPolicy protobuf. It uses canonical ProtoJSON field names, but the data is written as YAML so the two files are easy to compare.

The second file is not a proposed v2 format. It shows what would happen if OpenShell reused the current runtime protobuf as the authored schema without redesigning it.

What changes

Current policy YAML Current runtime protobuf Why
filesystem_policy filesystem The handwritten model and runtime message use different field names.
include_workdir, network_policies includeWorkdir, networkPolicies ProtoJSON prints field names in lower camel case by default. Parsers must also accept the original protobuf field name, so snake case can still work as input.
port: 443 port: 443 and ports: [443] The current conversion fills both runtime fields for backward compatibility. A new authored schema should choose one representation.
mcp.max_body_bytes endpoint-level jsonRpcMaxBodyBytes The authored model groups MCP settings. The runtime message stores the shared JSON-RPC body limit on the endpoint.
tool: repo_* params.name.glob: repo_* tool is authoring shorthand. The runtime matcher uses the generic JSON-RPC parameter map.
query.state: open query.state.glob: open The authored model accepts a scalar matcher. The protobuf matcher is always a message.

The runtime message also contains advisorProposed and providerCredentialed. They do not appear in the example because both are false, but their presence in an authorable message would be a security mistake.

Standard ProtoJSON accepts null for most fields and treats it as unset. Today's authored parser rejects explicit null where presence matters. A Proto-backed YAML loader needs a check before ProtoJSON decoding if we want to keep that behavior.

Design takeaway

We should not make policy authors use the second file as-is. Most of its churn comes from using a runtime message for an authoring job.

A v2 authored protobuf keeps filesystem_policy, nested mcp options, and binary objects with path. It removes runtime-owned fields, uses the full protobuf matcher objects instead of scalar shorthands, and emits canonical snake-case names. Basic portable validation is declared with Protovalidate, while the gateway retains context-dependent checks.

This comparison supports OpenShell issue #3388.

Current design

Sources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment