class

Cordon::Policy

Inherits JSON::Serializable < Reference < Object

Describes what a sandboxed process is permitted to access. Platform runners translate this into their native policy format — an SBPL profile on macOS, a bwrap flag list on Linux.

Can be constructed programmatically or deserialised from JSON:

Programmatic

policy = Cordon::Policy.build do |p| p.read_only "/usr/share/myapp" p.read_write "/tmp/workspace" p.tmpfs "/tmp" p.allow_network = false p.working_dir = "/tmp/workspace" p.env["MYAPP_ENV"] = "production" end

From a JSON file

policy = Cordon::Policy.from_json(File.read("policy.json"))

Round-trip to JSON

puts policy.to_json

Constructors

build

Yields a new Policy for configuration, then returns it.

Source
new(pull : JSON::PullParser)
Source
new(*, __pull_for_json_serializable pull : JSON::PullParser)
Source

Instance methods

allow_network=(allow_network : Bool)

Whether outbound network access is permitted. Default: false.

Source
allow_network?

Whether outbound network access is permitted. Default: false.

Source
env

Explicit environment variables to expose inside the sandbox. On bwrap the environment is cleared first; a safe default set (PATH, TERM, LANG, LC_ALL) is passed through before these. On macOS the full parent environment is inherited by sandbox-exec.

Source
env=(env : Hash(String, String))

Explicit environment variables to expose inside the sandbox. On bwrap the environment is cleared first; a safe default set (PATH, TERM, LANG, LC_ALL) is passed through before these. On macOS the full parent environment is inherited by sandbox-exec.

Source
merge(other : Policy) : Policy

Returns a new Policy that is the union of self and other.

Merge rules:

  • Arrays (paths, unset_env): union, duplicates removed, order preserved.
  • allow_network: true if either policy allows it (OR semantics).
  • new_session: true if either policy requires it (OR semantics — safer).
  • working_dir: other wins if set, otherwise self is kept.
  • env: merged; other wins on key collision.
Source
new_session=(new_session : Bool)

Start a new session (setsid). Prevents TTY escape attacks. Default: true.

Source
new_session?

Start a new session (setsid). Prevents TTY escape attacks. Default: true.

Source
read_only(*paths : String) : self

Convenience: add one or more read-only paths (chainable).

Source
read_only_paths

Paths the sandboxed process may read but not write.

Source
read_only_paths=(read_only_paths : Array(String))

Paths the sandboxed process may read but not write.

Source
read_write(*paths : String) : self

Convenience: add one or more read-write paths (chainable).

Source
read_write_paths

Paths the sandboxed process may read and write.

Source
read_write_paths=(read_write_paths : Array(String))

Paths the sandboxed process may read and write.

Source
tmpfs(*paths : String) : self

Convenience: add one or more tmpfs scratch paths (chainable).

Source
tmpfs_paths

Paths to back with in-memory scratch space (tmpfs on Linux). On macOS, sandbox-exec cannot mount tmpfs — these paths receive RW access to the existing filesystem location instead. Pass a pre-created Dir.tempdir value for true scratch isolation.

Source
tmpfs_paths=(tmpfs_paths : Array(String))

Paths to back with in-memory scratch space (tmpfs on Linux). On macOS, sandbox-exec cannot mount tmpfs — these paths receive RW access to the existing filesystem location instead. Pass a pre-created Dir.tempdir value for true scratch isolation.

Source
unset_env

Environment variables to explicitly remove (bwrap only).

Source
unset_env=(unset_env : Array(String))

Environment variables to explicitly remove (bwrap only).

Source
working_dir

Working directory inside the sandbox. Must fall within one of the accessible path lists.

Source
working_dir=(working_dir : String | Nil)

Working directory inside the sandbox. Must fall within one of the accessible path lists.

Source