MXC 沙箱隔离 bitsmug/dsh-sandbox-mxc

dsh-sandbox-mxc

一个 DeepSeek Harness 沙箱服务商，底层由 MXC（Microsoft eXecution Containers）驱动。

它实现 harness 的进程隔离接缝（ctx.sandbox，来自 @deepseek-ai/dsh-sandbox 的 SandboxProvider），做法是把调用方即将启动的原始 argv 包一层：

wxc-exec.exe --config-base64 <policy-json> -- <original argv...>

- 不 import @microsoft/mxc-sdk。 插件从不加载 SDK 的原生绑定——它只需要 wxc-exec 可执行文件，用 require.resolve 定位。所以 SDK 那条限制——「Windows 上的原生 stdio 要求 Node.js 24 系列为 24.21.0 或更新，或 Node.js 26.8.0 或更新」——不适用。它跑在 harness 自带的 Node 上（已在 v24.20.0 验证）。
- 只有一个运行时依赖： @microsoft/mxc-sdk（声明在 dependencies 里；仅用于定位 wxc-exec.exe）。配置校验是手写的，没有 schema 库。
- 不改内核。 它与 @deepseek-ai/dsh-sandbox-local 是兄弟服务商，通过 harness 常规的 bundle-patch 层选择。
- 策略语义不在这里重新实现。 读写根目录来自 @deepseek-ai/dsh-sandbox 导出的 writableRoots(policy) / canonicalPath(path)，所以 read-only / workspace-write 的含义只在一处定义。

环境要求

- Windows。 这个服务商驱动 MXC 的 Windows 后端（wxc-exec.exe、ProcessContainer / AppContainer）。
- DeepSeek Harness，且挂载了 sandbox 服务（@deepseek-ai/dsh-sandbox——声明在 peerDependencies 里；从不打包）。
- Node.js >=22——用 harness 自带的 Node 就行。
- wxc-exec.exe——从已安装的 @microsoft/mxc-sdk（普通依赖）解析，否则取 config.wxcExecPath，再否则取 $DSH_MXC_WXC。
- 一个非打包的 PowerShell，当配置档的 pwsh 工具指向 Store/MSIX 版本时：MXC 容器无法启动打包（MSIX）应用（The target executable '…\WindowsApps\…\pwsh.exe' appears to be a packaged (MSIX) app）。把执行器的 pwshPath 指向非打包版本——比如把官方 ZIP 解压到你选定的固定目录。
- 该 shell 自己的安装目录必须在容器内可读——把它列进 config.readonlyPaths。非打包的 PowerShell 启动时会解析自身路径，否则会失败并报 Failed to resolve full path of the current executable。
- 本机上不存在的路径会被自动丢弃。 交给 MXC 会让它拒绝整个策略（DACL fallback requires write-DACL permission on '/tmp'——/tmp 正是共享 harness 代码在 Windows 上贡献的路径），所以服务商在构建策略前，会对每个路径列表做一次存在性检查。
- 在 MXC 的 appcontainer-dacl 层级上，账户必须能为策略里每个路径写入 DACL。当它做不到时——某个卷属于另一个 SID，或者容器实际读不了的路径——服务商会丢弃该路径并打印原因，而不是让命令失败，同时缓存判定结果。它从不要求逐机器做 ACL 手术。强隔离的 base-container 层级完全不需要处理 DACL。

已验证环境

在开发机上实测；这是一份记录，不是对你机器的断言。

| 项目 | 值 |
| OS | Windows (x64) |
| Harness | DSH 0.2.0-rc.2 |
| Node.js | v24.20.0（harness 自带的） |
| Shell | PowerShell 7.7.0-preview.5，未打包（ZIP 解压） |
| MXC | @microsoft/mxc-sdk 1.0.0；wxc-exec --probe 在 Windows 11 主机上报告 BaseContainer 层级，在 Windows 10 主机上报告 AppContainer + DACL 层级 |

实测行为（完整矩阵见 ## Security posture）：允许写工作区；策略之外的写入和读取均被拒绝；默认阻止出站网络；剪贴板与主机隔离。在信任一台机器之前，有两个与层级相关的事实值得了解：

- base-container 需要 Windows 11；Windows 10 只能用 DACL 层级。 同一个二进制，两台主机：在 Windows 11（build ≥ 26100）上 wxc-exec --probe 报告 tier=base-container / needsDaclAugmentation=false /
baseContainerApiPresent=true；在 Windows 10 上报告 tier=appcontainer-dacl /
needsDaclAugmentation=true / baseContainerApiPresent=false——强隔离层级需要的进程安全环境 API 根本不存在，所以在 Windows 10 上策略里的每条路径都必须可做 DACL 增强（见 ## Requirements，服务商对此的处理方式是丢弃并报告）。wxc-host-prep.exe（提权运行）能清除系统盘和 NUL 设备的警告，但无法凭空造出缺失的 API。

安装

两件事彼此独立：(a) 安装这个插件，(b) 让 wxc-exec 可执行文件能被找到。

(a) 把插件装进配置档

本地检出（开发场景，也是纯 git 插件的常见做法）：

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

从 registry 安装（如果你发布了）：

dsh plugin --profile <profile> add dsh-sandbox-mxc

两种方式都会应用插件自带的 cordis.patch.yml，它会

1. 禁用默认的服务商行（- id: sandbox → @deepseek-ai/dsh-sandbox-local），并
2. 插入本插件——它提供相同的服务名 sandbox，所以所有消费方（pwsh、bash 以及文件系统工具族）都无需改动。

Cordis 补丁方言把为真的 name 视为对已有行的断言，而不是重命名——所以补丁会禁用旧行，再插入新行，而不是直接改 name。

改完补丁后要重启配置档：服务商运行在宿主平面上。

(b) 让 wxc-exec 可达

按优先级顺序：

1. 插件 config.wxcExecPath（wxc-exec.exe 的绝对路径）；
2. 环境变量 DSH_MXC_WXC；
3. 从已安装的 @microsoft/mxc-sdk 推导：<package>/bin/x64/wxc-exec.exe。

以上都解析不出来时，confine() 会失败关闭——抛出 SandboxUnavailableError（错误码
SANDBOX_UNAVAILABLE），而不是放任命令在无沙箱环境下运行。安装 @microsoft/mxc-sdk 是常规运行时依赖（声明在 dependencies 里，从 npm 安装）；它从不被 import——只用来定位 wxc-exec.exe。

配置

| 键 | 默认值 | 含义 |
| wxcExecPath | '' | wxc-exec.exe 的绝对路径。为空 ⇒ 先试 DSH_MXC_WXC，再从 @microsoft/mxc-sdk 推导。 |
| readonlyPaths | [] | 容器可读的额外根目录（工作区之外）。 |
| extraWritablePaths | [] | 容器可写的额外根目录（writableRoots(policy) 之外）。 |
| deniedPaths | [] | 容器永远不能碰的根目录（MXC filesystem.deniedPaths）。 |
| network | 省略 | 省略 ⇒ 用 MXC 默认值，即 block（实测 default_policy=block）。 |
| timeoutMs | 0 | 每次执行的超时毫秒数；0 = 不限。 |
| containerIdPrefix | 'dsh-mxc' | 诊断用容器名的前缀。 |
| sandboxEnv | [] | 容器 process.env 的额外 KEY=VALUE 条目，叠加在后端默认值之上（inheritDefaultEnv: true）。不含 = 的条目会被丢弃并给出警告（MXC 会直接拒绝这类命令）。 |
| injectNodePipeShim | true | 注入 NODE_OPTIONS=--import data:text/javascript,…，让容器内的 Node 通过文件句柄而不是命名管道捕获子进程输出，并在异步 API 上快速失败。设为 false 则不动 process.env / process.inheritDefaultEnv。见下文容器环境。 |

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

容器环境（Node 命名管道垫片）

在 MXC 容器里，进程 token 无法创建命名管道——而 libuv 正是用命名管道实现 stdio: 'pipe' 的。在本机某个容器内实测：

| 容器内调用 | 结果 |
| spawnSync(cmd.exe, ['/c','echo','hi'], { encoding: 'utf8', timeout: 300 }) | 永不返回；timeout / killSignal 都不触发 |
| spawnSync(…, { stdio: ['ignore', fd, fd] })（文件句柄） | 6–10 ms 内返回 |
| stdio: 'inherit' / 'ignore' | 6–10 ms 内返回 |
| .NET NamedPipeServerStream / net.listen | Access to the path is denied / EADDRINUSE |
当 injectNodePipeShim: true（默认值）时，服务商会添加一条 NODE_OPTIONS 条目——一段内联的 data:text/javascript,… 预加载，因此不会写入任何文件——它在容器内部改变命令启动的每个 Node 进程的 child_process：

- spawnSync / execFileSync / execSync —— stdout/stderr 通过临时文件描述符捕获并读回；只有当调用方要求别的东西时，槽位才保持为管道。execFileSync / execSync 是特意重新实现的：Node 自己的实现不会走被覆盖的 spawnSync 导出，所以只覆盖导出无法覆盖它们。execSync 的错误形状（status / stdout / stderr，消息以 Command failed: 开头）和 Node 默认的 encoding: 'buffer' 都保留；maxBuffer 不再生效（输出写入文件）。
- spawn / exec / execFile / fork —— 立即抛出 code: 'MXC_NAMED_PIPE_UNAVAILABLE'，消息中指明是哪个 API，而不是永远挂起。

注意：该 shim 也管辖容器命令启动的任何 Node 进程（NODE_OPTIONS 会被继承——这正是关键所在），真正需要异步子进程的命令必须在容器外部运行。把 injectNodePipeShim: false 设为 false，容器环境就会完全保持此功能引入之前的样子。

shim 通过命令行传递（环境 → 配置 JSON → --config-base64），而 Windows 命令行上限约为 32767 个字符——所以内联源码保持注释精简，补丁脚本会断言编码后的尺寸（目前 NODE_OPTIONS 条目约为 14566 个字符）。

模式映射

| Harness 模式 | MXC filesystem |
| read-only | readwritePaths: []，工作区根目录被加入 readonlyPaths（否则容器连工作区都读不了） |
| workspace-write | readwritePaths: writableRoots(policy)（工作区根目录 + 平台临时区域） |
| danger-full-access | harness 不调用 confine() |

ui 始终固定为 { disable: false, clipboard: 'none', injection: false }，processContainer.ui 固定为 { isolation: 'container', desktopSystemControl: false, systemSettings: 'none', ime: false }。

安全态势（实测，而非假设）

| 属性 | 实测结果 |
| 后端 | BaseContainer（从 --debug 原生日志确认；不需要 --experimental） |
| ACL 增强 | --probe 报告 needsDaclAugmentation: false——它不需要内置 ACL 服务商所要求的写授权步骤 |
| 文件系统 | 允许列表之外连读都被拒绝；readwritePaths 之外的写入被拒绝；只读根目录无法写入 |
| 网络 | 默认阻止（default_policy=block） |
| 剪贴板 | clipboard:'none' 强制执行：宿主机剪贴板标记对容器不可见，容器标记也从未到达宿主机剪贴板。注意：强制执行是静默空操作——不会抛出错误。* |
| ui.disable | 必须为 false，否则容器会阻止 Win32k，node.exe / pwsh 会以 0xC0000142 STATUS_DLL_INIT_FAILED 失败 |
| 容器环境 | 容器不继承宿主机 PATH / 环境——当你的命令需要工具链时，请配置 environment |
| 屏幕 / 桌面 | 未确定。 容器内窗口枚举返回 0（宿主机上为 14），但「独立桌面」和「无枚举权限的合成用户」都能解释这一点，因此不下结论 |

ui.disable: false 的代价：Win32k 从容器内变得可达，也就是说内核攻击面比完全无 UI 的容器更宽——这是运行原生 Windows node.exe/pwsh 无法避免的代价。剪贴板和输入注入仍然关闭，harness 自带的 ACL 服务商也不隔离该攻击面，所以这不算那里的回归。

测试

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

覆盖：策略→配置映射（包括 read-only 下的空可写集）、argv 形状与 -- 分隔符、base64 往返、固定的安全默认值，以及 fail-closed 解析。

许可证

MIT——见 LICENSE。