
Политика-ориентированная, многоуровневая изоляция и сдерживание
MXC — это система изолированного выполнения кода для запуска недоверенного кода (вывод моделей, плагины, инструменты) на Windows, Linux и macOS. Она предоставляет несколько бэкендов изоляции — от нативных песочниц на уровне ОС до полноценных виртуальных машин — за единой JSON-схемой конфигурации и TypeScript SDK.
[!WARNING] Этот репозиторий содержит раннюю предварительную версию кода, опубликованную для обеспечения ранней интеграции и получения обратной связи от разработчиков по Microsoft Execution Containers. Ожидается, что базовые песочницы в этой ранней предварительной версии будут меняться, поскольку они находятся в процессе активной разработки, однако мы постараемся минимизировать влияние на совместимость по мере развития функциональности. Известны случаи, когда текущие политики, генерируемые MXC SDK в этом репозитории, являются излишне разрешительными, и это будет исправлено до того, как продукт станет более широко доступным. Приветствуется партнёрство с исследователями безопасности по мере развития MXC, однако в настоящее время ни один профиль MXC не следует рассматривать как границу безопасности.
@microsoft/mxc-sdk с одноразовыми и учитывающими состояние APIMXC поставляется с нативной обёрткой контейнера и TypeScript SDK — см. README SDK для полной документации по API.
| Платформа | Бэкенд по умолчанию | Другие бэкенды | Минимальная сборка |
|---|---|---|---|
| Windows 11 24H2+ (проверено на 25H2) | processcontainer | windows_sandbox, wslc, microvm, hyperlight, isolation_session | processcontainer: 26100 (24H2)isolation_session: 26340.9212 (Insider Preview) |
| Linux x64 / ARM64 | bubblewrap | lxc, microvm, hyperlight | — |
macOS ARM64 / x64 (схема 0.7.0-alpha+) | seatbelt | — | — |
Стабильные одноразовые бэкенды (processcontainer, bubblewrap, lxc и seatbelt) не требуют экспериментального режима; для хостов Linux также требуется установка соответствующей среды выполнения: bwrap (Bubblewrap) для бэкенда по умолчанию или набор инструментов lxc для бэкенда lxc. Экспериментальные бэкенды (windows_sandbox, wslc, microvm, isolation_session, hyperlight) требуют { experimental: true } в SandboxSpawnOptions или флаг --experimental в CLI.
Информацию о том, какие аспекты политик файловой системы, сети и ограничений пользовательского интерфейса бэкенд processcontainer для Windows может применять в каждом выпуске Windows 11 (23H2 / 24H2 / 25H2 / 25H2+), см. в Поддержка политик по версиям ОС Windows.
src/rust-toolchain.toml (автоматически выбирается rustup)src/ Рабочее пространство Rust (нативные двоичные файлы + крейты общих библиотек)
sdk/ TypeScript SDK (npm-пакет @microsoft/mxc-sdk)
schemas/ JSON-схемы конфигурации (стабильные + разрабатываемые)
docs/ Документация (справочник по схемам, руководства по бэкендам, проектные документы)
tests/ Тестовые материалы (конфигурации, примеры, скрипты)
scripts/ Скрипты сборки и утилиты
build.bat # Сборка Release для текущей архитектуры
build.bat --debug # Отладочная сборка
build.bat --all # Сборка Release для x64 и ARM64
build.bat --with-microvm # Включить двоичные файлы NanVix micro-VM
./build.sh # Сборка Release
./build.sh --debug # Отладочная сборка
./build.sh --rust-only # Только двоичные файлы Rust, без SDK/CLI
./build-mac.sh # Сборка Release для нативной архитектуры
./build-mac.sh --all # Для Apple Silicon и Intel
./build-mac.sh --debug # Отладочная сборка
./build-mac.sh --rust-only # Только двоичный файл Rust, без SDK
Все скрипты сборки:
Собирают соответствующий платформе двоичный файл Rust
Копируют двоичный файл в sdk/node/bin/<arch>/ (например, x64 или arm64) для включения в SDK
Собирают 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
# Windows Rust (из src/)
cargo clippy --workspace --all-targets -- -D warnings
# Linux Rust (из src/; соответствует набору крейтов, совместимых с платформой, из build.sh)
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 # Отдельный крейт
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
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 см. в README SDK.
Выпущенные, неизменяемые стабильные схемы находятся в schemas/stable/; разрабатываемая dev-схема (экспериментальные бэкенды, жизненный цикл с учётом состояния) находится в schemas/dev/. Текущие стабильная и dev-версии канонически отслеживаются в schemas/schema-version.json.
Для нового кода на любой поддерживаемой платформе выбирайте последнюю стабильную схему. Полный дизайн версионирования см. в docs/versioning.md.
По умолчанию нативные двоичные файлы работают в тихом режиме — stdin/stdout/stderr напрямую связаны с контейнером. Используйте --debug для подробного вывода:
wxc-exec.exe --debug config.json
Полный справочник по диагностике см. в docs/diagnostics.md.
--audit — это обёртка совместимости над processContainer.captureDenials в режиме allow с принудительно включённым удержанием ETL. Он внедряет permissiveLearningMode, поэтому запрещённые операции записываются, но им разрешается выполняться. На хостах с полным набором API PSEC/V2 Learning Mode выбранный исполнитель ProcessContainer использует нативный захват без запуска PLM или запроса повышения привилегий. Более старые или несовместимые с политикой уровни используют резервный вариант guarded-WPR: wxc-exec.exe остаётся без повышения привилегий и запускает сессионного UAC-повышенного хранителя PLM только для привилегированного жизненного цикла WPR, взаимодействуя через аутентифицированный локальный именованный канал. Он отклоняется для Windows Sandbox, WSLC, IsolationSession и всех остальных бэкендов изоляции.
wxc-exec.exe --audit policy.json
Успешные аудиты без режима dry-run требуют метаданных захвата, действующего JSON отказов и сохранённого ETL. CLI перемещает выбранные бэкендом пути в denials.json и trace.etl в каталог аудита для каждого пользователя, затем генерирует снимок исходной конфигурации и Adjusted_*.json из действующего 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 поддерживает необязательную телеметрию ETW TraceLogging для наблюдаемости выполнения. При включении структурированные события (MXC.Execution и MXC.Error) отправляются в локальную подсистему ETW через крейт Rust tracelogging. Каждое событие включает общие поля (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) как пользовательские данные события Part C.
Телеметрия требует:
"telemetry": { "enabled": true } на верхнем уровне JSON-конфигурацииФлаг конфигурации — это дополнительное согласие для каждого запуска; он не может предоставить согласие или обойти административную блокировку. Телеметрия остаётся выключенной, если не открыты все применимые шлюзы. MXC не использует настройку Windows «Диагностика и отзывы» в качестве замены согласия приложения.
На платформах, отличных от Windows, все функции телеметрии являются no-op.
Программное обеспечение может собирать информацию о вас и вашем использовании программного обеспечения и отправлять её в Microsoft. Microsoft может использовать эту информацию для предоставления услуг и улучшения наших продуктов и услуг. Вы можете отключить телеметрию, как описано в репозитории. В программном обеспечении также есть некоторые функции, которые могут позволить вам и Microsoft собирать данные от пользователей ваших приложений. Если вы используете эти функции, вы должны соблюдать применимое законодательство, включая предоставление соответствующих уведомлений пользователям ваших приложений вместе с копией заявления Microsoft о конфиденциальности. Наше заявление о конфиденциальности находится по адресу https://go.microsoft.com/fwlink/?LinkID=824704. Вы можете узнать больше о сборе и использовании данных в справочной документации и нашем заявлении о конфиденциальности. Ваше использование программного обеспечения означает ваше согласие с этими практиками.
Телеметрия по умолчанию выключена. Чтобы она оставалась выключенной, не устанавливайте
"telemetry": { "enabled": true } для запуска.
Если телеметрия включена в конфигурации, сбор всё равно не происходит, если не предоставлено согласие пользователя Windows и административная политика не разрешает сбор.
Официальные/поставляемые сборки Microsoft устанавливают GUID группы поставщиков TraceLogging во время сборки и направляют события MXC.Execution и MXC.Error в Microsoft через конвейер UTC, когда телеметрия включена — та же настройка времени сборки также выбирает правильное ключевое слово Measures и тег конфиденциальности Product-and-Service-Usage для событий, поэтому маршрутизация телеметрии и классификация событий всегда согласованы. Локальные сборки и сборки из открытого исходного кода по умолчанию ничего не отправляют в 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.
| Документ | Описание |
|---|---|
| docs/schema.md | Полный справочник по JSON-схеме конфигурации |
| docs/versioning.md | Версионирование схем и жизненный цикл экспериментальных функций |
| docs/examples.md | Аннотированные примеры конфигураций |
| docs/host-prep.md | Подготовка хоста Windows (wxc-host-prep.exe) |
| docs/diagnostics.md | Диагностическое журналирование и ETW |
| docs/sandbox-policy/0.7.0/policy.md | Спецификация политики песочницы 0.7.0 |
| docs/process-container/guide.md | Руководство по Windows AppContainer / BaseContainer |
| docs/lxc-support/lxc-backend.md | Бэкенд LXC (Linux) |
| docs/bwrap-support/bubblewrap-backend.md | Бэкенд Bubblewrap (Linux) |
| docs/seatbelt/seatbelt-backend.md | Бэкенд Seatbelt (macOS) |
| docs/windows-sandbox/windows-sandbox.md | Бэкенд Windows Sandbox |
| docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md | API жизненного цикла песочницы с учётом состояния |
| docs/telemetry/telemetry.md |
Рекомендации по участию см. в CONTRIBUTING.md.
Подробности см. в LICENSE.md.
| Архитектура телеметрии TraceLogging |
| docs/telemetry/telemetry-consent-design.md | Контракт согласия на телеметрию |
| docs/telemetry/telemetry-administrative-policy.md | Административные элементы управления телеметрией |