Skip to content

policy-schema.md

Latest commit

 

History

History
258 lines (195 loc) · 9.98 KB

policy-schema.md

File metadata and controls

258 lines (195 loc) · 9.98 KB
title
page nav
Policy Schema Reference
Policy Schema
description Complete field reference for the sandbox policy YAML including static and dynamic sections.
topics
Generative AI
Cybersecurity
tags
Policy
Schema
YAML
Reference
Security
content
type difficulty audience
reference
technical_advanced
engineer

Policy Schema Reference

Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox).

Top-Level Structure

A policy YAML file contains the following top-level fields:

version: 1
filesystem_policy: { ... }
landlock: { ... }
process: { ... }
network_policies: { ... }
Field Type Required Category Description
version integer Yes -- Policy schema version. Must be 1.
filesystem_policy object No Static Controls which directories the agent can read and write.
landlock object No Static Configures Landlock LSM enforcement behavior.
process object No Static Sets the user and group the agent process runs as.
network_policies map No Dynamic Declares which binaries can reach which network endpoints.

Static fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. Dynamic fields can be updated on a running sandbox with openshell policy set and take effect without restarting.

Version

The version field identifies which schema the policy uses:

Field Type Required Description
version integer Yes Schema version number. Currently must be 1.

Filesystem Policy

Category: Static

Controls filesystem access inside the sandbox. Paths not listed in either read_only or read_write are inaccessible.

Field Type Required Description
include_workdir bool No When true, automatically adds the agent's working directory to read_write.
read_only list of strings No Paths the agent can read but not modify. Typically system directories like /usr, /lib, /etc.
read_write list of strings No Paths the agent can read and write. Typically /sandbox (working directory) and /tmp.

Validation constraints:

  • Every path must be absolute (start with /).
  • Paths must not contain .. traversal components. The server normalizes paths before storage, but rejects policies where traversal would escape the intended scope.
  • Read-write paths must not be overly broad (for example, / alone is rejected).
  • Each individual path must not exceed 4096 characters.
  • The combined total of read_only and read_write paths must not exceed 256.

Policies that violate these constraints are rejected with INVALID_ARGUMENT at creation or update time. Disk-loaded YAML policies that fail validation fall back to a restrictive default.

Example:

filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /etc
  read_write:
    - /sandbox
    - /tmp
    - /dev/null

Landlock

Category: Static

Configures Landlock LSM enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow.

Field Type Required Values Description
compatibility string No best_effort, hard_requirement How OpenShell handles Landlock failures. See behavior table below.

Compatibility modes:

Value Kernel ABI unavailable Individual path inaccessible All paths inaccessible
best_effort Warns and continues without Landlock. Skips the path, applies remaining rules. Warns and continues without Landlock (refuses to apply an empty ruleset).
hard_requirement Aborts sandbox startup. Aborts sandbox startup. Aborts sandbox startup.

best_effort (the default) is appropriate for most deployments. It handles missing paths gracefully -- for example, /app may not exist in every container image but is included in the baseline path set for containers that do have it. Individual missing paths are skipped while the remaining filesystem rules are still enforced.

hard_requirement is for environments where any gap in filesystem isolation is unacceptable. If a listed path cannot be opened for any reason (missing, permission denied, symlink loop), sandbox startup fails immediately rather than running with reduced protection.

When a path is skipped under best_effort, the sandbox logs a warning that includes the path, the specific error, and a human-readable reason (for example, "path does not exist" or "permission denied").

Example:

landlock:
  compatibility: best_effort

Process

Category: Static

Sets the OS-level identity for the agent process inside the sandbox.

Field Type Required Description
run_as_user string No The user name or UID the agent process runs as. Default: sandbox.
run_as_group string No The group name or GID the agent process runs as. Default: sandbox.

Validation constraint: Neither run_as_user nor run_as_group may be set to root or 0. Policies that request root process identity are rejected at creation or update time.

Example:

process:
  run_as_user: sandbox
  run_as_group: sandbox

Network Policies

Category: Dynamic

A map of named network policy entries. Each entry declares a set of endpoints and a set of binaries. Only the listed binaries are permitted to connect to the listed endpoints. The map key is a logical identifier. The name field inside the entry is the display name used in logs.

Network Policy Entry

Each entry in the network_policies map has the following fields:

Field Type Required Description
name string No Display name for the policy entry. Used in log output. Defaults to the map key.
endpoints list of endpoint objects Yes Hosts and ports this entry permits.
binaries list of binary objects Yes Executables allowed to connect to these endpoints.

Endpoint Object

Each endpoint defines a reachable destination and optional inspection rules.

Field Type Required Description
host string Yes Hostname or IP address. Supports wildcards: *.example.com matches any subdomain.
port integer Yes TCP port number.
protocol string No Set to rest to enable HTTP request inspection. Omit for TCP passthrough.
tls string No TLS handling mode. The proxy auto-detects TLS by peeking the first bytes of each connection and terminates it when protocol is rest, so this field is optional in most cases. Set to skip to disable auto-detection for edge cases such as client-certificate mTLS or non-standard protocols. The values terminate and passthrough are deprecated and log a warning; they are still accepted for backward compatibility but have no effect on behavior.
enforcement string No enforce actively blocks disallowed requests. audit logs violations but allows traffic through.
access string No HTTP access level. One of read-only, read-write, or full. Mutually exclusive with rules.
rules list of rule objects No Fine-grained per-method, per-path allow rules. Mutually exclusive with access.

Access Levels

The access field accepts one of the following values:

Value Allowed HTTP Methods
full All methods and paths.
read-only GET, HEAD, OPTIONS.
read-write GET, HEAD, OPTIONS, POST, PUT, PATCH.

Rule Object

Used when access is not set. Each rule explicitly allows a method and path combination.

Field Type Required Description
allow.method string Yes HTTP method to allow (for example, GET, POST).
allow.path string Yes URL path pattern. Supports * and ** glob syntax.
allow.query map No Query parameter matchers keyed by decoded param name. Matcher value can be a glob string (tag: "foo-*") or an object with any (tag: { any: ["foo-*", "bar-*"] }).

Path matching behavior:

  • Path rules match only the path component of the request URI (everything before ?).
  • Query strings are not evaluated by path rules. A rule with path: /api/v1/download matches both /api/v1/download and /api/v1/download?slug=my-skill&version=1.0.
  • Glob patterns use / as the segment delimiter. * matches within a single segment, ** matches across segments.

Example with rules:

rules:
  - allow:
      method: GET
      path: /**/info/refs*
      query:
        service: "git-*"
  - allow:
      method: POST
      path: /**/git-upload-pack
      query:
        tag:
          any: ["v1.*", "v2.*"]

Binary Object

Identifies an executable that is permitted to use the associated endpoints.

Field Type Required Description
path string Yes Filesystem path to the executable. Supports glob patterns with * and **. For example, /sandbox/.vscode-server/** matches any executable under that directory tree.

Full Example

The following policy grants read-only GitHub API access and npm registry access:

network_policies:
  github_rest_api:
    name: github-rest-api
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/local/bin/claude
      - path: /usr/bin/node
      - path: /usr/bin/gh
  npm_registry:
    name: npm-registry
    endpoints:
      - host: registry.npmjs.org
        port: 443
    binaries:
      - path: /usr/bin/npm
      - path: /usr/bin/node