Security model

Sandbox Policy protects the integrity and meaning of a resolved sandbox decision. It validates source, produces one canonical representation, matches required semantics to declared backend capabilities and refuses ambiguity. It does not by itself authenticate the policy author or enforce kernel boundaries.

Trust model

Trusted inputs:

• the JSON manifest, C builder calls or upstream policy engine that grants rights;
• host bindings for workspace, temp and minimal-runtime roots;
• the mediator identifier selected for mediated networking;
• backend capability declarations consumed during plan compilation.

Potentially hostile inputs:

• binary MIR received across a process or storage boundary;
• repositories, packages and workload arguments;
• paths that may disappear or change between policy creation and execution;
• a process attempting to escape through descendants or ambient networking.

Guarantees provided by this library

• strict JSON source with duplicate and unknown-key rejection;
• bounded input sizes, strings, rules, destinations and nesting;
• canonical path and hostname normalization;
• deterministic ordering, deduplication and conflict precedence;
• canonical binary validation by decode and byte-identical re-encode;
• decision digest covering every canonical byte;
• explicit capability matching before SandboxPlan creation;
• immutable MIR and SandboxPlan objects after sealing;
• no returned partial object after failure.

What belongs to Warden and the backend

Sandbox Policy does not prove that the kernel, a backend executable or the host configuration is uncompromised. Warden must:

• bind symbolic roots to trusted paths;
• preserve path identity between preparation and spawn;
• select exactly the backend whose capabilities were checked;
• lower the SandboxPlan without granting additional access;
• confine the complete process lifecycle;
• stop and reap work within bounded time;
• emit evidence describing the actual backend and terminal outcome.

Network mediation

A mediated MIR contains destination hostnames and ports, not proxy credentials or endpoints. The trusted host selects a mediator. Netd then owns authentication, DNS resolution and pinning, destination checks, connection relay and network receipts.

If a compatible mediator is not configured, plan creation or execution must fail. Falling back to ambient networking is forbidden.

Path handling

Relative paths reject parent traversal. Absolute paths are accepted only as explicit host-root decisions. During resolution, missing: skip applies solely to ENOENT and ENOTDIR; permission failures and symlink loops remain fatal.

This distinction is security-critical for deny rules: treating every lookup error as “missing” could silently remove the restriction.

Decision identity and provenance

maelys_mir_digest_hex identifies the normalized policy decision. maelys_mir_artifact_digest_hex identifies arbitrary source or package bytes. They are separate because two differently formatted JSON files can compile to the same decision.

Signed release tags and build attestations establish software provenance. They do not authorize an individual policy manifest.

Failure behavior

The expected reaction to malformed input, unsupported semantics, missing capabilities, inconsistent canonical bytes or resolution failure is refusal. There is no permissive parser mode and no “best effort” plan.

Report a vulnerability

Use GitHub private vulnerability reporting under Security → Advisories → Report a vulnerability in the source repository. Do not publish a suspected vulnerability in a public issue before coordination.