Skip to content

README.md

Latest commit

 

History

History
285 lines (197 loc) · 13.7 KB

README.md

File metadata and controls

285 lines (197 loc) · 13.7 KB
Raw

Microsoft eXecution Container (MXC)

MXC is a sandboxed code execution system for running untrusted code (model output, plugins, tools) on Windows, Linux, and macOS. It provides multiple containment backends — from OS-native process sandboxes to full VMs — behind a unified JSON configuration schema and TypeScript SDK.

Warning

This repository contains an early preview of code published to enable early integration and feedback from developers on Microsoft Execution Containers. The underlying sandboxes in this early preview are expected to change as they are under ongoing development however we will aim to minimize compatibility impact as functionality evolves. There are known cases where the current policies generated by the MXC SDK in this repository are overly permissive and will be addressed before this is made more generally available. Security researcher partnership while MXC matures is welcome, however no MXC profiles should be treated as security boundaries currently.

Features

  • Cross-platform: Windows, Linux, and macOS support with platform-appropriate containment backends
  • JSON-based Configuration: Define execution parameters and security policies via a versioned JSON schema
  • Multiple Containment Backends: ProcessContainer, Windows Sandbox, LXC, Bubblewrap, Seatbelt (macOS), MicroVM (NanVix), Hyperlight, IsolationSession, and WSLC
  • Policy-driven Sandboxing:
    • Filesystem Policy: Read-only and read-write path lists (denied paths not yet supported on Windows)
    • Network Policy: Proxy support (not supported on macOS); allow/block outbound and host filtering (not yet supported on Windows)
    • UI Policy: Clipboard, display, and GUI access controls
  • State-aware Lifecycle: Multi-step sandbox lifecycle (provision → start → exec → stop → deprovision) for session sandboxes
  • TypeScript SDK: @microsoft/mxc-sdk npm package with one-shot and state-aware APIs
  • Diagnostics: Debug logging and Event Tracing for Windows (ETW) for troubleshooting

Building

MXC ships a native container wrapper plus a TypeScript SDK — see the SDK README for full API documentation.

Platforms

Platform Default backend Other backends Minimum build
Windows 11 24H2+ (verified on 25H2) processcontainer windows_sandbox, wslc, microvm, hyperlight, isolation_session processcontainer: 26100 (24H2)
isolation_session: 26300.8553 (Insider Preview)
Linux x64 / ARM64 bubblewrap lxc, microvm, hyperlight —
macOS ARM64 / x64 (schema 0.7.0-alpha+) seatbelt — —

The stable one-shot backends (processcontainer, bubblewrap, lxc, and seatbelt) do not require experimental mode; Linux hosts also need the matching runtime installed: bwrap (Bubblewrap) for the default backend, or the lxc toolset for the lxc backend. Experimental backends (windows_sandbox, wslc, microvm, isolation_session, hyperlight) require { experimental: true } in SandboxSpawnOptions or the --experimental CLI flag.

For which filesystem, network, and UI-restriction policy aspects the Windows processcontainer backend can enforce on each Windows 11 release (23H2 / 24H2 / 25H2 / 25H2+), see Windows OS-version policy support.

Requirements

  • Rust toolchain — version pinned to 1.93 via src/rust-toolchain.toml (auto-selected by rustup)
  • Node.js ≥ 18
  • npm (for SDK and CLI builds)

Project Structure

src/        Rust workspace (native binaries + shared library crates)
sdk/        TypeScript SDK (@microsoft/mxc-sdk npm package)
schemas/    JSON configuration schemas (stable + dev)
docs/       Documentation (schema reference, backend guides, design docs)
tests/      Test collateral (configs, examples, scripts)
scripts/    Build and utility scripts

Full Build

Windows

build.bat                  # Release build for current architecture
build.bat --debug          # Debug build
build.bat --all            # Release build for both x64 and ARM64
build.bat --with-microvm   # Include NanVix micro-VM binaries

Linux

./build.sh                 # Release build
./build.sh --debug         # Debug build
./build.sh --rust-only     # Only Rust binaries, skip SDK/CLI

macOS

./build-mac.sh             # Release build for native architecture
./build-mac.sh --all       # Both Apple Silicon and Intel
./build-mac.sh --debug     # Debug build
./build-mac.sh --rust-only # Only Rust binary, skip SDK

All build scripts:

  1. Build the platform-appropriate Rust binary

  2. Copy the binary into sdk/bin/<arch>/ (for example, x64 or arm64) for SDK bundling

  3. Build the TypeScript SDK

Building Components Individually

# Rust workspace (from 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 (serves both LXC and Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin  # macOS

# SDK (from sdk/)
npm install && npm run build

Lint and Format

# Windows Rust (from src/)

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

# Linux Rust (from src/; matches build.sh's platform-compatible crate set)

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

# macOS Rust (from src/)

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

Tests

# Rust unit tests (from src/)
cargo test --workspace
cargo test -p wxc_common                      # Single crate
cargo test -p wxc_common -- config_parser     # Filter by test name

# SDK (from sdk/)
npm test                     # Unit tests
npm run test:integration     # Integration tests

# E2E (from src/)
cargo test -p wxc_e2e_tests

Usage

MXC uses a JSON configuration to define execution parameters. See the schema documentation for full reference.

Native Binary

# File path
wxc-exec.exe config.json

# Base64-encoded config
wxc-exec.exe --config-base64 <base64-encoded-json>

# Debug output
wxc-exec.exe --debug config.json

On Linux: ./lxc-exec config.json On 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));

The SDK also provides a state-aware lifecycle API for long-lived sandboxes:

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

See the SDK README for full API documentation.

Schema Versions

Released, immutable stable schemas live in schemas/stable/; the in-progress dev schema (experimental backends, state-aware lifecycle) lives in schemas/dev/. The current stable and dev versions are tracked canonically in schemas/schema-version.json.

Pick the latest stable schema for new code on any supported platform. See docs/versioning.md for the full versioning design.

Debugging

Debug Console Mode

By default, native binaries run in silent mode — stdin/stdout/stderr is coupled directly to the container. Use --debug for verbose output:

wxc-exec.exe --debug config.json

See docs/diagnostics.md for full diagnostics reference.

Audit Mode (Permissive Learning Mode)

--audit runs the policy in permissive mode — denied operations are logged but allowed to proceed — and starts a Permissive Learning Mode (PLM) ETW trace alongside the workload. See src/host/plm/readme.md for the full PLM tool reference, including standalone plm.exe invocation (e.g. re-processing an existing .etl with plm stop --trace-file …).

wxc-exec.exe --audit policy.json

Warning: In release builds, --audit relaxes the rejection of permissiveLearningMode — AppContainer restrictions are not enforced for the duration of the run. Use only for policy authoring.

Telemetry (Experimental)

MXC supports optional TraceLogging ETW telemetry for execution observability. When enabled, structured events (MXC.Execution and MXC.Error) are emitted to the local ETW subsystem via the Rust tracelogging crate. Every event includes common fields (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) as Part C custom event data.

Telemetry is experimental and requires:

  1. The --experimental CLI flag
  2. "experimental": { "telemetry": { "enabled": true } } in the JSON config

On non-Windows platforms, all telemetry functions are no-ops.

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

How to turn telemetry off

Telemetry is off by default. MXC emits telemetry only when both of the following are set, so no action is required to keep it disabled:

  1. The --experimental CLI flag is passed, and
  2. "experimental": { "telemetry": { "enabled": true } } is present in the JSON config.

Omitting either (the default) turns telemetry off entirely. On non-Windows platforms all telemetry functions are no-ops.

What official builds send

Official/shipped Microsoft builds set a TraceLogging provider group GUID at build time and route MXC.Execution and MXC.Error events to Microsoft through the UTC pipeline when telemetry is enabled. Local and open-source builds send nothing to Microsoft by default — the public source ships without a provider group GUID, so events are emitted to the local ETW subsystem only and are not routed to any Microsoft collection pipeline. Internal builds that set the MXC_TELEMETRY_PROVIDER_GROUP_GUID environment variable at build time enable the Microsoft-routed path.

No PII is collected. Events contain only execution metrics (duration, backend type, exit code) and a bounded error category (error_type). Free-form error message text is never emitted, so paths, usernames, and credentials cannot leak through telemetry. If you use the SDK to build applications, you are responsible for providing appropriate telemetry notices to your own users.

Privacy information can be found at https://privacy.microsoft.com and in the Microsoft privacy statement at https://go.microsoft.com/fwlink/?LinkID=824704.

Documentation

Document Description
docs/schema.md Full JSON configuration schema reference
docs/versioning.md Schema versioning and experimental feature lifecycle
docs/examples.md Annotated configuration examples
docs/host-prep.md Windows host preparation (wxc-host-prep.exe)
docs/diagnostics.md Diagnostic logging and ETW
docs/sandbox-policy/v1/policy.md Sandbox policy v1 specification
docs/process-container/guide.md Windows AppContainer / BaseContainer guide
docs/lxc-support/lxc-backend.md LXC backend (Linux)
docs/bwrap-support/bubblewrap-backend.md Bubblewrap backend (Linux)
docs/macos-support/seatbelt-backend.md Seatbelt backend (macOS)
docs/windows-sandbox/windows-sandbox.md Windows Sandbox backend
docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md State-aware sandbox lifecycle API
docs/telemetry/telemetry.md TraceLogging telemetry architecture

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

See LICENSE.md for details.