Microsoft eXecution Container (MXC)

MXC es un sistema de ejecución de código en sandbox para ejecutar código no confiable (salida de modelos, complementos, herramientas) en Windows, Linux y macOS. Proporciona múltiples backends de contención — desde sandboxes de procesos nativos del sistema operativo hasta VMs completas — detrás de un esquema de configuración JSON unificado y un SDK de TypeScript.

[!WARNING] Este repositorio contiene una vista previa temprana del código publicado para permitir la integración temprana y la retroalimentación de los desarrolladores sobre Microsoft Execution Containers. Se espera que los sandboxes subyacentes en esta vista previa temprana cambien, ya que están en desarrollo continuo; sin embargo, buscaremos minimizar el impacto en la compatibilidad a medida que la funcionalidad evolucione. Hay casos conocidos en los que las políticas actuales generadas por el SDK de MXC en este repositorio son excesivamente permisivas y se abordarán antes de que esto esté disponible de manera más general. Se agradece la colaboración de investigadores de seguridad mientras MXC madura; sin embargo, actualmente ningún perfil de MXC debe tratarse como un límite de seguridad.

Características

• Multiplataforma: Compatibilidad con Windows, Linux y macOS con backends de contención apropiados para cada plataforma
• Configuración basada en JSON: Defina parámetros de ejecución y políticas de seguridad mediante un esquema JSON versionado
• Múltiples backends de contención: ProcessContainer, Windows Sandbox, LXC, Bubblewrap, Seatbelt (macOS), MicroVM (NanVix), Hyperlight, IsolationSession y WSLC
• Sandboxing basado en políticas:
  • Política de sistema de archivos: Listas de rutas de solo lectura y lectura-escritura (las rutas denegadas aún no son compatibles en Windows)
  • Política de red: Compatibilidad con proxy (cooperativo en Linux/macOS), permitir/bloquear salida y filtrado de host según el backend
  • Política de interfaz de usuario: Controles de acceso a portapapeles, pantalla y GUI
• Ciclo de vida consciente del estado: Ciclo de vida de sandbox de múltiples pasos (aprovisionar → iniciar → ejecutar → detener → desaprovisionar) para sandboxes de sesión
• SDK de TypeScript: Paquete npm @microsoft/mxc-sdk con APIs de una sola ejecución y conscientes del estado
• Diagnóstico: Registro de depuración y Seguimiento de eventos para Windows (ETW) para la resolución de problemas

Compilación

MXC incluye un contenedor nativo más un SDK de TypeScript — consulte el README del SDK para obtener la documentación completa de la API.

Plataformas

Los backends estables de una sola ejecución (processcontainer, bubblewrap, lxc y seatbelt) no requieren modo experimental; los hosts Linux también necesitan el runtime correspondiente instalado: bwrap (Bubblewrap) para el backend predeterminado, o el conjunto de herramientas lxc para el backend lxc. Los backends experimentales (windows_sandbox, wslc, microvm, isolation_session, hyperlight) requieren { experimental: true } en SandboxSpawnOptions o el indicador de CLI --experimental.

Para conocer qué aspectos de las políticas de sistema de archivos, red y restricción de interfaz de usuario puede aplicar el backend processcontainer de Windows en cada versión de Windows 11 (23H2 / 24H2 / 25H2 / 25H2+), consulte Compatibilidad de políticas por versión de SO de Windows.

Requisitos

• Cadena de herramientas de Rust — versión fijada en 1.93 mediante src/rust-toolchain.toml (seleccionada automáticamente por rustup)
• Node.js ≥ 18
• npm (para compilaciones de SDK y CLI)

Estructura del proyecto

src/        Espacio de trabajo de Rust (binarios nativos + crates de bibliotecas compartidas)
sdk/        SDK de TypeScript (paquete npm @microsoft/mxc-sdk)
schemas/    Esquemas de configuración JSON (estables + dev)
docs/       Documentación (referencia de esquemas, guías de backends, documentos de diseño)
tests/      Material de pruebas (configuraciones, ejemplos, scripts)
scripts/    Scripts de compilación y utilidades

Compilación completa

Windows

build.bat                  # Compilación de lanzamiento para la arquitectura actual
build.bat --debug          # Compilación de depuración
build.bat --all            # Compilación de lanzamiento para x64 y ARM64
build.bat --with-microvm   # Incluir binarios de micro-VM NanVix

Linux

./build.sh                 # Compilación de lanzamiento
./build.sh --debug         # Compilación de depuración
./build.sh --rust-only     # Solo binarios de Rust, omitir SDK/CLI

macOS

./build-mac.sh             # Compilación de lanzamiento para la arquitectura nativa
./build-mac.sh --all       # Tanto Apple Silicon como Intel
./build-mac.sh --debug     # Compilación de depuración
./build-mac.sh --rust-only # Solo binario de Rust, omitir SDK

Todos los scripts de compilación:

1. Compilan el binario de Rust apropiado para la plataforma

2. Copian el binario en sdk/node/bin/<arch>/ (por ejemplo, x64 o arm64) para el empaquetado del SDK

3. Compilan el SDK de TypeScript

Compilación de componentes individualmente

# Espacio de trabajo de Rust (desde 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 (sirve tanto a LXC como a Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin  # macOS

# SDK (desde sdk/node/)
npm install && npm run build

Lint y formato

# Rust de Windows (desde src/)

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

# Rust de Linux (desde src/; coincide con el conjunto de crates compatible con la plataforma de build.sh)

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

# Rust de macOS (desde src/)

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

Pruebas

# Pruebas unitarias de Rust (desde src/)
cargo test --workspace
cargo test -p wxc_common                      # Crate individual
cargo test -p wxc_common -- config_parser     # Filtrar por nombre de prueba

# SDK (desde sdk/node/)
npm test                     # Pruebas unitarias
npm run test:integration     # Pruebas de integración

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

Uso

MXC utiliza una configuración JSON para definir los parámetros de ejecución. Consulte la documentación del esquema para obtener la referencia completa.

Binario nativo

# Ruta de archivo
wxc-exec.exe config.json

# Configuración codificada en Base64
wxc-exec.exe --config-base64 <base64-encoded-json>

# Salida de depuración
wxc-exec.exe --debug config.json

En Linux: ./lxc-exec config.json En macOS: ./mxc-exec-mac --experimental config.json

SDK de TypeScript

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));

El SDK también proporciona una API de ciclo de vida consciente del estado para sandboxes de larga duración:

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

Consulte el README del SDK para obtener la documentación completa de la API.

Versiones del esquema

Los esquemas estables inmutables publicados se encuentran en schemas/stable/; el esquema dev en progreso (backends experimentales, ciclo de vida consciente del estado) se encuentra en schemas/dev/. Las versiones estables y dev actuales se rastrean canónicamente en schemas/schema-version.json.

Elija el esquema estable más reciente para código nuevo en cualquier plataforma compatible. Consulte docs/versioning.md para conocer el diseño completo de versionado.

Depuración

Modo de consola de depuración

De forma predeterminada, los binarios nativos se ejecutan en modo silencioso — stdin/stdout/stderr se acoplan directamente al contenedor. Use --debug para obtener una salida detallada:

wxc-exec.exe --debug config.json

Consulte docs/diagnostics.md para obtener la referencia completa de diagnóstico.

Modo de auditoría (modo de aprendizaje permisivo)

--audit es un contenedor de compatibilidad sobre processContainer.captureDenials en modo allow con retención de ETL forzada. Inyecta permissiveLearningMode, por lo que las operaciones denegadas se registran pero se permite que continúen. En hosts con el conjunto completo de API de modo de aprendizaje PSEC/V2, el runner de ProcessContainer seleccionado utiliza captura nativa sin iniciar PLM ni solicitar elevación. Los niveles más antiguos o incompatibles con la política utilizan la alternativa WPR protegida: wxc-exec.exe permanece sin elevar e inicia un guardián PLM elevado por UAC limitado a la sesión solo para el ciclo de vida privilegiado de WPR, comunicándose a través de una canalización con nombre local autenticada. Se rechaza para Windows Sandbox, WSLC, IsolationSession y cualquier otro backend de contención.

wxc-exec.exe --audit policy.json

Las auditorías exitosas que no son de prueba en seco requieren metadatos de captura, JSON de denegaciones procesables y un ETL retenido. La CLI reubica las rutas seleccionadas por el backend a denials.json y trace.etl en el directorio de auditoría por usuario, luego genera una instantánea de la configuración fuente y Adjusted_*.json a partir del JSON procesable sin decodificar el ETL nuevamente. La entrada solo en Base64 conserva JSON y ETL pero no tiene configuración fuente para instantánea o ajuste. El análisis truncado conserva JSON, ETL y la instantánea fuente, pero omite la generación de configuración ajustada. Use --audit-verbose para imprimir los detalles de la política aprendida.

Advertencia: --audit inyecta permissiveLearningMode — las restricciones de AppContainer no se aplican durante la duración de la ejecución. Úselo solo para la creación de políticas. No se puede combinar con processContainer.captureDenials; use captureDenials.mode: "allow" para la captura permisiva impulsada por la aplicación. learningModeLogging y permissiveLearningMode son nombres de capacidades internas reservados y se rechazan en processContainer.capabilities. Consulte docs/learning-mode/capabilities.md para conocer los tres flujos de modo de aprendizaje.

Telemetría

MXC admite telemetría ETW opcional de TraceLogging para la observabilidad de la ejecución. Cuando está habilitada, se emiten eventos estructurados (MXC.Execution y MXC.Error) al subsistema ETW local mediante el crate de Rust tracelogging. Cada evento incluye campos comunes (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) como datos de evento personalizados de la Parte C.

La telemetría requiere:

1. "telemetry": { "enabled": true } de nivel superior en la configuración JSON
2. Consentimiento explícito de telemetría por usuario en Windows
3. Una política administrativa que permita la recopilación, cuando se configure una política

El indicador de configuración es una aceptación adicional por ejecución; no puede otorgar consentimiento ni omitir un bloqueo administrativo. La telemetría permanece desactivada a menos que todas las compuertas aplicables estén abiertas. MXC no utiliza la configuración de Diagnóstico y comentarios de Windows como sustituto del consentimiento de la aplicación.

En plataformas que no son Windows, todas las funciones de telemetría son operaciones nulas.

Recopilación de datos

El software puede recopilar información sobre usted y su uso del software y enviarla a Microsoft. Microsoft puede utilizar esta información para proporcionar servicios y mejorar nuestros productos y servicios. Puede desactivar la telemetría como se describe en el repositorio. También hay algunas funciones en el software que pueden permitirle a usted y a Microsoft recopilar datos de los usuarios de sus aplicaciones. Si utiliza estas funciones, debe cumplir con la ley aplicable, incluida la provisión de avisos apropiados a los usuarios de sus aplicaciones junto con una copia de la declaración de privacidad de Microsoft. Nuestra declaración de privacidad se encuentra en https://go.microsoft.com/fwlink/?LinkID=824704. Puede obtener más información sobre la recopilación y el uso de datos en la documentación de ayuda y en nuestra declaración de privacidad. Su uso del software constituye su consentimiento a estas prácticas.

Cómo desactivar la telemetría

La telemetría está desactivada de forma predeterminada. Para mantenerla desactivada, no establezca "telemetry": { "enabled": true } para la ejecución.

Si la telemetría está habilitada en la configuración, la recopilación no se produce a menos que se otorgue el consentimiento del usuario de Windows y la política administrativa permita la recopilación.

Qué envían las compilaciones oficiales

Las compilaciones oficiales/publicadas de Microsoft establecen un GUID de grupo de proveedores de TraceLogging en el momento de la compilación y enrutan los eventos MXC.Execution y MXC.Error a Microsoft a través de la canalización UTC cuando la telemetría está habilitada — esa misma configuración en el momento de la compilación también selecciona la palabra clave de Measures correcta y la etiqueta de privacidad de Uso de producto y servicio para los eventos, por lo que el enrutamiento de telemetría y la clasificación de eventos siempre coinciden. Las compilaciones locales y de código abierto no envían nada a Microsoft de forma predeterminada — el código fuente público se distribuye sin un GUID de grupo de proveedores, por lo que los eventos se emiten solo al subsistema ETW local, usan una palabra clave local del proveedor sin significado UTC y no llevan etiqueta de clasificación de privacidad, y no se enrutan a ninguna canalización de recopilación de Microsoft. Las compilaciones internas que establecen la variable de entorno MXC_TELEMETRY_PROVIDER_GROUP_GUID en el momento de la compilación habilitan la ruta enrutada a Microsoft.

No se recopila información de identificación personal (PII). Los eventos contienen solo métricas de ejecución (duración, tipo de backend, código de salida) y una categoría de error limitada (error_type). El texto libre de mensajes de error nunca se emite, por lo que las rutas, los nombres de usuario y las credenciales no pueden filtrarse a través de la telemetría. Si utiliza el SDK para crear aplicaciones, es responsable de proporcionar avisos de telemetría apropiados a sus propios usuarios.

La información de privacidad se puede encontrar en https://privacy.microsoft.com y en la declaración de privacidad de Microsoft en https://go.microsoft.com/fwlink/?LinkID=824704.

Documentación

Contribuciones

Consulte CONTRIBUTING.md para conocer las pautas de contribución.

Licencia

Consulte LICENSE.md para obtener más detalles.