Huanqi Cao
1d56bd5628
A denial this backend cannot explain — the confined child cannot open an object it was granted, or provisioning itself fails with Win32 5 — reached the user as a bare "Access is denied". The README documented both causes but shipped no way to tell them apart. Add the `diagnose-windows-sandbox-acl` skill. Its script reads unless a repair switch is passed, and classifies the failing path and its ancestors before anything changes; its two repair modes are the only supported ACL edits. `-Fix` removes a foreign package-SID allow ACE, and `-GrantFullControl` supplies the WRITE_DAC/WRITE_OWNER pair the mandatory-label write needs without ever changing an owner. Both require `-AllowRoot`, refuse a target outside it, and refuse to run together. `dsh-sandbox-local` registers the skill on Windows through `ctx.inject(['skills'], ...)`, so the skill registry stays optional and the sandbox never depends on it. The assets ship in this package's `files` list, which the workspace-constraints gate now pins alongside the runner and emitted-type entries. Tests cover the script's verdicts (foreign ACE, healthy object, inert capability SID, inert DENY ACE), its surgical removal, the grant's owner invariant, and both refusals; the catalog spec covers registration and disposal.
description, kind
| description | kind |
|---|---|
| The process-sandbox package group: the confinement seam, per-platform backends, the shared policy resolver, and the Windows write-restriction rung. | package-group |
packages/sandbox
English | 中文
Summary
The sandbox/ group confines subprocess execution to a file-effect policy: commands run read-only, write only under the session workspace (workspace-write), or run unrestricted (danger-full-access). Four packages deliver it: the confinement service (sandbox/), the per-platform backends for Linux, macOS, and Windows (sandbox-local/), the shared policy resolver (sandbox-policy/), and the Windows write-restriction backend (sandbox-windows-acl/). A confined call that a policy denies can retry through a user-approved one-time escalation. Confinement is same-world only: it shares the host kernel and filesystem, while containers, microVMs, and remote executors replace whole capabilities instead of registering here.
Table of Contents
Packages
Four packages play the confinement roles; the subsystem reference owns the exhaustive contracts and the per-call policy semantics.
| Package | Role | ctx key |
|---|---|---|
sandbox/ |
Confinement service contract: modes, enforcement, per-call policy, and the escalation vocabulary | ctx.sandbox |
sandbox-local/ |
Per-platform confinement backends: Linux bwrap then Landlock, macOS Seatbelt, Windows restricted token | registers on ctx.sandbox |
sandbox-policy/ |
Shared policy home: deployment defaults and per-session mode overrides for every enforcing family | ctx.sandboxPolicy |
sandbox-windows-acl/ |
Windows write restriction: confined children may write only in the workspace and a private temp directory | — (mounted by sandbox-local as the win32 backend) |
Related documentation
Start with the subsystem reference for the shared vocabulary, then the confinement decision and its cross-family extension.
- Process sandbox subsystem — modes, per-call policy, wrapped-argv dialects, and fail-closed errors.
- The subprocess sandbox decision — the capability boundary, escalation choreography, and deferred phases.
- Cross-family file sandbox decision — the shared policy home and the sandboxed filesystem provider.
- Windows ACL restricted-token sandbox decision — why raw ACL restricted tokens over mxc and AppContainer.
Dev Note
Working context for maintainers — click to expand
None.