Microsoft 执行容器 (MXC)

MXC 是一个沙箱化代码执行系统，用于在 Windows、Linux 和 macOS 上运行不受信任的代码（模型输出、插件、工具）。它通过统一的 JSON 配置架构和 TypeScript SDK，提供多种隔离后端——从操作系统原生进程沙箱到完整虚拟机。

[!WARNING] 本仓库包含代码的早期预览版，旨在实现早期集成并收集开发者对 Microsoft 执行容器的反馈。此早期预览中的底层沙箱预计会随着持续开发而发生变化，但我们将在功能演进过程中尽量降低兼容性影响。目前已知本仓库中 MXC SDK 生成的策略存在过度宽松的情况，这些问题将在更广泛发布之前得到解决。欢迎安全研究人员在 MXC 成熟过程中开展合作，但目前不应将任何 MXC 配置文件视为安全边界。

特性

• 跨平台：支持 Windows、Linux 和 macOS，并提供适合各平台的隔离后端
• 基于 JSON 的配置：通过版本化 JSON 架构定义执行参数和安全策略
• 多种隔离后端：ProcessContainer、Windows Sandbox、LXC、Bubblewrap、Seatbelt (macOS)、MicroVM (NanVix)、Hyperlight、IsolationSession 和 WSLC
• 策略驱动的沙箱化：
  • 文件系统策略：只读和读写路径列表（Windows 上尚不支持拒绝路径）
  • 网络策略：代理支持（Linux/macOS 上为协作式）、允许/阻止出站连接，以及依赖后端的宿主机过滤
  • UI 策略：剪贴板、显示和 GUI 访问控制
• 状态感知生命周期：会话沙箱的多步骤沙箱生命周期（预置 → 启动 → 执行 → 停止 → 解除预置）
• TypeScript SDK：@microsoft/mxc-sdk npm 包，提供一次性 API 和状态感知 API
• 诊断：调试日志和 Windows 事件跟踪 (ETW)，用于故障排除

构建

MXC 附带一个原生容器包装器和一个 TypeScript SDK——完整 API 文档请参阅 SDK README。

平台

稳定的单次执行后端（processcontainer、bubblewrap、lxc 和 seatbelt）不需要实验模式；Linux 主机还需要安装匹配的运行时：默认后端需要 bwrap (Bubblewrap)，lxc 后端需要 lxc 工具集。实验性后端（windows_sandbox、wslc、microvm、isolation_session、hyperlight）需要在 SandboxSpawnOptions 中设置 { experimental: true } 或使用 --experimental CLI 标志。

关于 Windows processcontainer 后端在每个 Windows 11 版本（23H2 / 24H2 / 25H2 / 25H2+）上可强制执行的文件系统、网络和 UI 限制策略方面，请参阅 Windows 操作系统版本策略支持。

要求

• Rust 工具链 — 通过 src/rust-toolchain.toml 固定为 1.93 版本（由 rustup 自动选择）
• Node.js ≥ 18
• npm（用于 SDK 和 CLI 构建）

项目结构

src/        Rust 工作区（原生二进制文件 + 共享库 crate）
sdk/        TypeScript SDK（@microsoft/mxc-sdk npm 包）
schemas/    JSON 配置架构（稳定版 + 开发版）
docs/       文档（架构参考、后端指南、设计文档）
tests/      测试辅助文件（配置、示例、脚本）
scripts/    构建和实用脚本

完整构建

Windows

build.bat                  # 当前架构的发布构建
build.bat --debug          # 调试构建
build.bat --all            # x64 和 ARM64 的发布构建
build.bat --with-microvm   # 包含 NanVix 微虚拟机二进制文件

Linux

./build.sh                 # 发布构建
./build.sh --debug         # 调试构建
./build.sh --rust-only     # 仅构建 Rust 二进制文件，跳过 SDK/CLI

macOS

./build-mac.sh             # 本机架构的发布构建
./build-mac.sh --all       # Apple Silicon 和 Intel 均构建
./build-mac.sh --debug     # 调试构建
./build-mac.sh --rust-only # 仅构建 Rust 二进制文件，跳过 SDK

所有构建脚本：

1. 构建适合平台的 Rust 二进制文件
2. 将二进制文件复制到 sdk/node/bin/<arch>/（例如 x64 或 arm64）以用于 SDK 打包
3. 构建 TypeScript SDK

单独构建组件

# Rust 工作区（从 src/ 目录）
cargo build --release --target x86_64-pc-windows-msvc     # Windows x64
cargo build --release --target aarch64-pc-windows-msvc    # Windows ARM64
cargo build --release -p lxc                               # Linux — lxc-exec（同时服务于 LXC 和 Bubblewrap）
cargo build --release -p mxc_darwin --target aarch64-apple-darwin  # macOS

# SDK（从 sdk/node/ 目录）
npm install && npm run build

Lint 和格式化

# Windows Rust（从 src/ 目录）

cargo clippy --workspace --all-targets -- -D warnings

# Linux Rust（从 src/ 目录；与 build.sh 的平台兼容 crate 集匹配）

cargo clippy -p lxc -p lxc_common -p wxc_common -p bwrap_common -p unix_test_proxy --all-targets -- -D warnings

# macOS Rust（从 src/ 目录）

cargo clippy -p mxc_darwin -p seatbelt_common --all-targets -- -D warnings

测试

# Rust 单元测试（从 src/ 目录）
cargo test --workspace
cargo test -p wxc_common                      # 单个 crate
cargo test -p wxc_common -- config_parser     # 按测试名称筛选

# SDK（从 sdk/node/ 目录）
npm test                     # 单元测试
npm run test:integration     # 集成测试

# E2E（从 src/ 目录）
cargo test -p wxc_e2e_tests

使用方法

MXC 使用 JSON 配置来定义执行参数。完整参考请参阅架构文档。

原生二进制文件

# 文件路径
wxc-exec.exe config.json

# Base64 编码的配置
wxc-exec.exe --config-base64 <base64-encoded-json>

# 调试输出
wxc-exec.exe --debug config.json

在 Linux 上：./lxc-exec config.json 在 macOS 上：./mxc-exec-mac --experimental config.json

TypeScript SDK

npm install @microsoft/mxc-sdk

import {
  spawnSandboxFromConfig, createConfigFromPolicy,
  getAvailableToolsPolicy, getTemporaryFilesPolicy,
  getPlatformSupport,
} from '@microsoft/mxc-sdk';

if (!getPlatformSupport().isSupported) {
  throw new Error('MXC not available on this host');
}

const tools = getAvailableToolsPolicy(process.env);
const temp  = getTemporaryFilesPolicy();

const config = createConfigFromPolicy({
  version: '0.6.0-alpha',
  filesystem: {
    readonlyPaths:  tools.readonlyPaths,
    readwritePaths: temp.readwritePaths,
  },
  network: { allowOutbound: false },
  timeoutMs: 30_000,
});
config.process!.commandLine = 'python -c "print(\'hello from sandbox\')"';

const child = spawnSandboxFromConfig(config, { usePty: false });
child.stdout!.on('data', (d) => process.stdout.write(d));
child.on('close', (code) => console.log('exit:', code));

SDK 还为长期运行的沙箱提供了状态感知生命周期 API：

import {
  provisionSandbox, startSandbox, execInSandboxAsync,
  stopSandbox, deprovisionSandbox,
} from '@microsoft/mxc-sdk';

完整 API 文档请参阅 SDK README。

架构版本

已发布、不可变的稳定架构位于 schemas/stable/；正在开发中的开发版架构（实验性后端、状态感知生命周期）位于 schemas/dev/。当前稳定版和开发版版本在 schemas/schema-version.json 中进行规范跟踪。

在任何受支持的平台上编写新代码时，请选择最新的稳定架构。完整的版本控制设计请参阅 docs/versioning.md。

调试

调试控制台模式

默认情况下，原生二进制文件以静默模式运行——stdin/stdout/stderr 直接与容器耦合。使用 --debug 获取详细输出：

wxc-exec.exe --debug config.json

完整的诊断参考请参阅 docs/diagnostics.md。

审计模式（宽松学习模式）

--audit 是 processContainer.captureDenials 在允许模式下并强制启用 ETL 保留的兼容性包装器。它注入 permissiveLearningMode，因此被拒绝的操作会被记录但允许继续执行。在具有完整 PSEC/V2 学习模式 API 集的主机上，所选 ProcessContainer 运行器使用原生捕获，无需启动 PLM 或提示提升权限。较旧或策略不兼容的层级使用受保护的 WPR 回退方案：wxc-exec.exe 保持非提升状态，仅为特权 WPR 生命周期启动一个会话范围的 UAC 提升 PLM 守护进程，并通过经过身份验证的本地命名管道进行通信。该模式对 Windows Sandbox、WSLC、IsolationSession 以及所有其他隔离后端均被拒绝。

wxc-exec.exe --audit policy.json

成功的非试运行审计需要捕获元数据、可操作的拒绝 JSON 和保留的 ETL。CLI 将后端选择的路径重定位到每个用户审计目录中的 denials.json 和 trace.etl，然后从可操作 JSON 生成源配置快照和 Adjusted_*.json，而无需再次解码 ETL。仅 Base64 输入会保留 JSON 和 ETL，但没有可快照或调整的源配置。截断的分析会保留 JSON、ETL 和源快照，但跳过调整配置的生成。使用 --audit-verbose 打印学习到的策略详细信息。

警告： --audit 注入 permissiveLearningMode——在运行期间不强制执行 AppContainer 限制。仅用于策略编写。它不能与 processContainer.captureDenials 组合使用；对于宽松的应用程序驱动捕获，请使用 captureDenials.mode: "allow"。learningModeLogging 和 permissiveLearningMode 是保留的内部能力名称，在 processContainer.capabilities 中被拒绝。三种学习模式流程请参阅 docs/learning-mode/capabilities.md。

遥测

MXC 支持可选的 TraceLogging ETW 遥测，用于执行可观测性。启用后，结构化事件（MXC.Execution 和 MXC.Error）将通过 Rust tracelogging crate 发送到本地 ETW 子系统。每个事件都包含公共字段（Version、Channel、IsDebugging、UTCReplace_AppSessionGuid）作为 Part C 自定义事件数据。

遥测要求：

1. JSON 配置中的顶层 "telemetry": { "enabled": true }
2. Windows 上明确的每用户遥测同意
3. 当配置了管理策略时，允许收集的管理策略

配置标志是额外的每次运行选择加入机制；它不能授予同意或绕过管理阻止。除非每个适用的门控都打开，否则遥测保持关闭。MXC 不使用 Windows 诊断和反馈设置作为应用程序同意的替代。

在非 Windows 平台上，所有遥测功能均为空操作。

数据收集

本软件可能会收集有关您和使用本软件的信息，并将其发送给 Microsoft。Microsoft 可能会使用此信息来提供服务并改进我们的产品和服务。您可以按照本仓库中的说明关闭遥测。本软件中还有一些功能可能使您和 Microsoft 能够从您的应用程序用户那里收集数据。如果您使用这些功能，您必须遵守适用法律，包括向您的应用程序用户提供适当的通知以及 Microsoft 隐私声明的副本。我们的隐私声明位于 https://go.microsoft.com/fwlink/?LinkID=824704。您可以在帮助文档和我们的隐私声明中了解更多关于数据收集和使用的内容。您对本软件的使用即表示您同意这些做法。

如何关闭遥测

遥测默认关闭。要保持关闭状态，请勿在运行中设置 "telemetry": { "enabled": true }。

如果配置中启用了遥测，除非授予 Windows 用户同意且管理策略允许收集，否则仍不会进行收集。

官方构建发送的内容

官方/发布的 Microsoft 构建在构建时设置 TraceLogging 提供程序组 GUID，并在启用遥测时将 MXC.Execution 和 MXC.Error 事件通过 UTC 管道路由到 Microsoft——相同的构建时设置还会为事件选择正确的 Measures 关键字和产品与服务使用隐私标签，因此遥测路由和事件分类始终一致。本地和开源构建默认不会向 Microsoft 发送任何内容——公共源代码不附带提供程序组 GUID，因此事件仅发送到本地 ETW 子系统，使用对 UTC 无意义的提供程序本地关键字，不携带隐私分类标签，也不会路由到任何 Microsoft 收集管道。在构建时设置 MXC_TELEMETRY_PROVIDER_GROUP_GUID 环境变量的内部构建将启用 Microsoft 路由路径。

不收集任何个人身份信息 (PII)。事件仅包含执行指标（持续时间、后端类型、退出代码）和受限的错误类别（error_type）。从不发送自由格式的错误消息文本，因此路径、用户名和凭据不会通过遥测泄露。如果您使用 SDK 构建应用程序，您有责任向您自己的用户提供适当的遥测通知。

隐私信息可在 https://privacy.microsoft.com 和 Microsoft 隐私声明 https://go.microsoft.com/fwlink/?LinkID=824704 中找到。

文档

贡献

贡献指南请参阅 CONTRIBUTING.md。

许可证

详细信息请参阅 LICENSE.md。