dsh-sandbox-mxc

A DeepSeek Harness sandbox provider backed by
MXC (Microsoft eXecution Containers).

It implements the harness's process-confinement seam (ctx.sandbox, a
SandboxProvider from @deepseek-ai/dsh-sandbox) by wrapping the exact argv the caller is about to
spawn:

wxc-exec.exe --config-base64  --

• No @microsoft/mxc-sdk import. The plugin never loads the SDK's native bindings — it only needs
  the wxc-exec executable, located with require.resolve. So the SDK's
  “native stdio on Windows requires Node.js 24.21.0 or newer within Node.js 24, or Node.js 26.8.0
  or newer” restriction does not apply. It runs on the Node inside the harness (verified on
  v24.20.0).
• One runtime dependency: @microsoft/mxc-sdk (declared in dependencies; used only to locate
  wxc-exec.exe). Config validation is hand-written; no schema library.
• No kernel patch. It is a sibling provider to @deepseek-ai/dsh-sandbox-local, selected through
  the harness's normal bundle-patch layer.
• Policy semantics are not re-implemented here. Read/write roots come from
  writableRoots(policy) / canonicalPath(path) exported by @deepseek-ai/dsh-sandbox, so the
  meaning of read-only / workspace-write stays in one place.

Requirements

• Windows. This provider drives MXC's Windows backends (wxc-exec.exe, ProcessContainer / AppContainer).
• DeepSeek Harness that mounts the sandbox service (@deepseek-ai/dsh-sandbox — declared in peerDependencies; never bundled).
• Node.js >=22 — the harness's own Node is fine.
• wxc-exec.exe — resolved in this order: config.wxcExecPath → $DSH_MXC_WXC → the installed
  @microsoft/mxc-sdk's bin//wxc-exec.exe (arm64 / x64), then its bin/wxc-exec.exe.
• MXC >= 1.0.1 for the allowHostLoopback knob: the ProcessContainer host-loopback fix on PSEC 1.0
  (microsoft/mxc#1490) ships in 1.0.1.
• An unpackaged PowerShell, when the profile's pwsh tool points at a Store/MSIX build: MXC containers cannot launch packaged (MSIX) apps
  (The target executable '…\WindowsApps\…\pwsh.exe' appears to be a packaged (MSIX) app). Point the executor's pwshPath at an unpackaged
  build — e.g. the official ZIP extracted to a stable directory of your choosing.
• That shell's own install directory must be readable inside the container — list it in config.readonlyPaths. An unpackaged PowerShell
  resolves its own path at startup and otherwise fails with Failed to resolve full path of the current executable.
• Paths that do not exist on this machine are dropped automatically. Handing one to MXC makes it reject the whole policy
  (DACL fallback requires write-DACL permission on '/tmp' — /tmp is what the shared harness code contributes on Windows), so the
  provider filters every path list through an existence check before building the policy.
• On MXC's appcontainer-dacl tier, the account must be able to write a DACL for every path in the policy. When it cannot — a volume
  owned by another SID, or a path the container turns out not to be able to read — the provider drops that path and prints why, instead
  of failing the command, and caches the verdict. It never asks for per-machine ACL surgery. The strong base-container tier needs no
  DACL work at all. Which case applies is read from the probe's needsDaclAugmentation flag rather than from the tier name, so a tier
  this plugin has never heard of does not accidentally trigger DACL surgery.

Verified environment

Measured on the development machine; it is a record, not a claim about yours.

Measured behaviour (the full matrix is under ## Security posture): workspace writes allowed; writes outside the policy denied;
outbound network blocked by default; clipboard isolated from the host. Reads are not an absolute boundary — see the
security-posture notes below before trusting a machine. Three tier-dependent facts are worth knowing:

• base-container needs Windows 11; Windows 10 can only use the DACL tier. Same binary, two hosts:
  on Windows 11 (build ≥ 26100) wxc-exec --probe reports tier=base-container / needsDaclAugmentation=false / baseContainerApiPresent=true; on Windows 10 it reports tier=appcontainer-dacl / needsDaclAugmentation=true / baseContainerApiPresent=false — the process-security-environment API the strong tier needs is
  simply not there, so on Windows 10 every path in the policy must be DACL-augmentable (see ## Requirements, where the provider
  handles that by dropping and reporting). wxc-host-prep.exe (elevated) clears the system-drive and NUL-device warnings but
  cannot create the missing API.

Install

Two things are independent: (a) installing this plugin, and (b) making a wxc-exec
executable reachable.

(a) Install the plugin into a profile

Local checkout (development, and the usual way for a git-only plugin):

# 1. put the repo somewhere stable, then link it into the profile
#    /package.json :  "dsh-sandbox-mxc": "link:"
# 2. add it to the profile's bundle list:
#    "dsh": { "profile": { "bundles": [ "...", "dsh-sandbox-mxc" ] } }
# 3. create the node_modules junction:
#    /node_modules/dsh-sandbox-mxc  ->

From a registry (if you publish it):

dsh plugin --profile  add dsh-sandbox-mxc

Either way the plugin's own cordis.patch.yml is applied, which

1. disables the default provider row (- id: sandbox → @deepseek-ai/dsh-sandbox-local), and
2. inserts this plugin — it provides the same service name sandbox, so every consumer
   (pwsh, bash, and filesystem tool families) is unchanged.

> The Cordis patch dialect treats a truthy name as an assertion on an existing row, not a
> rename — which is why the patch disables the old row and inserts a new one instead of editing
> name in place.
>
> Restart the profile after changing the patch: the provider lives on the host plane.

(b) Make wxc-exec reachable

In order of precedence:

1. plugin config.wxcExecPath (absolute path to wxc-exec.exe);
2. environment variable DSH_MXC_WXC;
3. derivation from an installed @microsoft/mxc-sdk: /bin//wxc-exec.exe (the SDK's own
   layout — arm64 on Arm64 hosts, x64 elsewhere), then /bin/wxc-exec.exe (older layout).

If none resolves, the plugin throws while the profile loads (see Host readiness — the same executor
must also pass --probe), and confine() fails closed with SandboxUnavailableError (code
SANDBOX_UNAVAILABLE) rather than letting a command run unconfined. Installing
@microsoft/mxc-sdk is a normal runtime dependency (declared in dependencies, installed from npm);
it is never imported — it is used only to locate wxc-exec.exe.

Configuration

Unknown keys fail the profile load with an actionable error naming the key and the valid set (the
plugin is the config boundary: a misspelled or stale key silently dropping your safety intent is worse
than a loud failure). The valid keys are exactly the table below.

Both timeout keys must be a finite number >= 1: Node treats timeout: 0 as no timeout, the
opposite of what these fields promise.

- insert:
- id: sandbox-mxc
name: dsh-sandbox-mxc
config:
wxcExecPath: !!js process.env.DSH_MXC_WXC ?? ''
readonlyPaths: []

Host readiness

While the profile loads (Windows only, readinessCheck: true by default) the plugin resolves
wxc-exec and runs that same executable's own host probe, wxc-exec --probe:

• No executor resolvable, or --probe failing to start (ENOENT, timeout, non-zero exit without JSON),
  or the probe selecting no isolation tier ⇒ the plugin throws with an actionable error and the
  profile does not load. A provider that cannot confine would fail every command anyway; a loud failure
  at load is the honest one. Run "" --probe yourself to see the facts.
• Tier-degradation warnings from the probe are reported but never block (MXC explains why it
  degraded), and allowHostLoopback is reported when the probe says the host cannot do
  ingressHostLoopbackAllow.
• The system drive is checked for AppContainer directory access (icacls \ must list
  S-1-15-2-1 / APPLICATION PACKAGES); when missing, the plugin warns with the exact fix —
  an elevated wxc-host-prep prepare-system-drive (the command ships in @microsoft/mxc-sdk/bin//).
  Without it, directory listing (e.g. dir) inside the container fails with Access is denied, while
  reads and writes still work. Non-fatal.

Set readinessCheck: false to skip the gate; confine() then fails closed on the first command
instead of the profile load.

What the container can see of your invocation

The command, its environment, and the whole policy travel to the executor as a base64 request
envelope on argv (--config-base64). A host user with process-inspection rights can read that
while the process runs, so do not put secrets in command arguments or sandboxEnv values until MXC
provides a non-argv transport (microsoft/mxc#626).
An inline NODE_OPTIONS shim also widens the command line: see Container environment below for the
measured size budget.

Container environment (the Node named-pipe shim)

Inside an MXC container the process token cannot create named pipes — which is exactly how libuv
implements stdio: 'pipe'. Measured in one container on this machine:

So with injectNodePipeShim: true (the default) the provider adds one NODE_OPTIONS entry — an inline
data:text/javascript,… preload, so no file is written — which, inside the container, changes
child_process for every Node process the command starts:

• spawnSync / execFileSync / execSync — stdout/stderr are captured through temporary file
  descriptors and read back; a slot stays a pipe only if the caller asked for something else.
  execFileSync / execSync are re-implemented on purpose: Node’s own implementations do not go
  through the overridden spawnSync export, so overriding the export alone would not cover them. The
  exec*Sync error shape (status / stdout / stderr, message starting with Command failed:) and
  Node's default encoding: 'buffer' are preserved; maxBuffer no longer applies (output goes to a file).
• spawn / exec / execFile / fork — throw immediately with
  code: 'MXC_NAMED_PIPE_UNAVAILABLE' and a message naming the API, instead of hanging forever.

Notes: the shim also governs any Node process the container’s command starts (NODE_OPTIONS is
inherited — that is the point), and a command that genuinely needs asynchronous child processes has to
run outside the container. Set injectNodePipeShim: false to leave the container environment exactly
as it was before this feature.

The shim travels in the command line (environment → config JSON → --config-base64), and Windows
caps a command line at ≈32767 characters — so the inlined source is kept comment-lean, and the test
suite asserts the encoded size (measured: ≈14579 characters for the NODE_OPTIONS entry and ≈20148 for
the whole policy envelope).

Mode mapping

ui is always pinned to { disable: false, clipboard: 'none', injection: false } and
processContainer.ui to { isolation: 'container', desktopSystemControl: false, systemSettings: 'none', ime: false }.

Security posture (measured, not assumed)

Cost of ui.disable: false: Win32k becomes reachable from the container, i.e. the kernel attack
surface is wider than a fully UI-less container — the unavoidable price of running a native Windows
node.exe/pwsh. Clipboard and input injection stay closed, and the harness's bundled ACL provider
does not isolate that surface either, so this is not a regression there.

Denial and runner-failure evidence

confine() returns two pieces of evidence the harness uses to tell "confinement worked and blocked it"
apart from "the runner never ran the command":

• denialSignatures — the denial dialect this backend actually produces, matched case-insensitively:
  Access is denied, Access to the path, Permission denied, Operation not permitted, and 拒绝访问.
  Measured: the harness's normal executor (pwsh/.NET) prints Access to the path '' is denied.; Node's
  EACCES/EPERM show up as their messages (permission denied / operation not permitted) — the
  bare errno names never appear in stderr and are deliberately not listed. cmd.exe on a Chinese
  system prints 「拒绝访问。」 as GBK bytes (BE DC BE F8 B7 C3 CE CA), so the listed Chinese form does
  not survive a UTF-8 read: a cmd-driven denial is reported per the English/errno forms only.
• runnerFailureRules — five fatal stderr signatures that mean the command never ran:
  BaseContainer is unavailable, DACL fallback requires write-DACL permission on,
  appears to be a packaged (MSIX) app, STATUS_DLL_INIT_FAILED, 0xC0000142. Deliberately no
  allowedExitCodes gate: wxc-exec exits 1 for its own errors while a confined command may also exit 1,
  so an exit gate would conflate the two (the harness's dsh-sandbox-local bwrap/seatbelt rungs match by
  signature only, for the same reason).

The test suite asserts both with the harness's own predicates (matchesSignature, classifyRunnerFailure):
a denial must not classify as a runner failure, and vice versa.

Tests

node --test "tests/**/*.test.mjs"

Covers: policy→config mapping (including the empty writable set under read-only), the argv shape
and the -- separator, base64 round-trip, the pinned security defaults, fail-closed resolution,
executor candidate order (bin/ before bin), --probe facts parsing, the load-time readiness
gate (success / probe failure / no tier / readinessCheck: false / non-Windows), the DACL-tier
adaptation judgement, allowHostLoopback policy composition, strict config validation, the denial /
runner-failure contract via the harness's own predicates, and the command-line size budget.

License

MIT — see LICENSE.