microsoft/mxcPolítica orientada, isolamento e contenção em camadas
MXC é um sistema de execução de código em sandbox para executar código não confiável (saída de modelos, plugins, ferramentas) no Windows, Linux e macOS. Ele fornece múltiplos backends de contenção — desde sandboxes de processos nativos do SO até VMs completas — por trás de um esquema de configuração JSON unificado e um SDK TypeScript.
[!WARNING] Este repositório contém uma prévia inicial do código publicado para permitir integração antecipada e feedback de desenvolvedores sobre os Microsoft Execution Containers. Espera-se que as sandboxes subjacentes nesta prévia inicial mudem, pois estão em desenvolvimento contínuo; no entanto, buscaremos minimizar o impacto de compatibilidade à medida que a funcionalidade evolui. Há casos conhecidos em que as políticas atuais geradas pelo SDK MXC neste repositório são excessivamente permissivas e serão corrigidos antes que isso seja disponibilizado de forma mais geral. A parceria com pesquisadores de segurança enquanto o MXC amadurece é bem-vinda; no entanto, nenhum perfil MXC deve ser tratado atualmente como limite de segurança.
@microsoft/mxc-sdk com APIs de execução única e cientes de estadoO MXC inclui um wrapper de contêiner nativo além de um SDK TypeScript — consulte o README do SDK para documentação completa da API.
| Plataforma | Backend padrão | Outros backends | Compilação mínima |
|---|---|---|---|
| Windows 11 24H2+ (verificado na 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 (esquema 0.7.0-alpha+) | seatbelt | — | — |
Os backends estáveis de execução única (processcontainer, bubblewrap, lxc e seatbelt) não exigem modo experimental; hosts Linux também precisam do runtime correspondente instalado: bwrap (Bubblewrap) para o backend padrão, ou o conjunto de ferramentas lxc para o backend lxc. Backends experimentais (windows_sandbox, wslc, microvm, isolation_session, hyperlight) exigem { experimental: true } em SandboxSpawnOptions ou o sinalizador de CLI --experimental.
Para saber quais aspectos de política de restrição de sistema de arquivos, rede e interface o backend processcontainer do Windows pode impor em cada versão do Windows 11 (23H2 / 24H2 / 25H2 / 25H2+), consulte Suporte de política por versão do SO Windows.
src/rust-toolchain.toml (selecionada automaticamente pelo rustup)src/ Workspace Rust (binários nativos + crates de bibliotecas compartilhadas)
sdk/ SDK TypeScript (pacote npm @microsoft/mxc-sdk)
schemas/ Esquemas de configuração JSON (estáveis + dev)
docs/ Documentação (referência de esquema, guias de backend, documentos de design)
tests/ Material de teste (configurações, exemplos, scripts)
scripts/ Scripts de compilação e utilitários
build.bat # Compilação Release para a arquitetura atual
build.bat --debug # Compilação Debug
build.bat --all # Compilação Release para x64 e ARM64
build.bat --with-microvm # Incluir binários NanVix micro-VM
./build.sh # Compilação Release
./build.sh --debug # Compilação Debug
./build.sh --rust-only # Apenas binários Rust, ignorar SDK/CLI
./build-mac.sh # Compilação Release para a arquitetura nativa
./build-mac.sh --all # Apple Silicon e Intel
./build-mac.sh --debug # Compilação Debug
./build-mac.sh --rust-only # Apenas binário Rust, ignorar SDK
Todos os scripts de compilação:
sdk/node/bin/<arch>/ (por exemplo, x64 ou arm64) para empacotamento do SDK# Workspace Rust (a partir de 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 (atende LXC e Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin # macOS
# SDK (a partir de sdk/node/)
npm install && npm run build
# Rust Windows (a partir de src/)
cargo clippy --workspace --all-targets -- -D warnings
# Rust Linux (a partir de src/; corresponde ao conjunto de crates compatível com a plataforma do build.sh)
cargo clippy -p lxc -p lxc_common -p wxc_common -p bwrap_common -p unix_test_proxy --all-targets -- -D warnings
# Rust macOS (a partir de src/)
cargo clippy -p mxc_darwin -p seatbelt_common --all-targets -- -D warnings
# Testes unitários Rust (a partir de src/)
cargo test --workspace
cargo test -p wxc_common # Crate único
cargo test -p wxc_common -- config_parser # Filtrar por nome de teste
# SDK (a partir de sdk/node/)
npm test # Testes unitários
npm run test:integration # Testes de integração
# E2E (a partir de src/)
cargo test -p wxc_e2e_tests
O MXC usa uma configuração JSON para definir parâmetros de execução. Consulte a documentação do esquema para referência completa.
# Caminho do arquivo
wxc-exec.exe config.json
# Configuração codificada em Base64
wxc-exec.exe --config-base64 <base64-encoded-json>
# Saída de depuração
wxc-exec.exe --debug config.json
No Linux: ./lxc-exec config.json
No 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));
O SDK também fornece uma API de ciclo de vida ciente de estado para sandboxes de longa duração:
import {
provisionSandbox, startSandbox, execInSandboxAsync,
stopSandbox, deprovisionSandbox,
} from '@microsoft/mxc-sdk';
Consulte o README do SDK para documentação completa da API.
Esquemas estáveis imutáveis lançados ficam em schemas/stable/; o esquema dev em andamento (backends experimentais, ciclo de vida ciente de estado) fica em schemas/dev/. As versões estável e dev atuais são rastreadas canonicamente em schemas/schema-version.json.
Escolha o esquema estável mais recente para novo código em qualquer plataforma suportada. Consulte docs/versioning.md para o design completo de versionamento.
Por padrão, os binários nativos executam em modo silencioso — stdin/stdout/stderr é acoplado diretamente ao contêiner. Use --debug para saída detalhada:
wxc-exec.exe --debug config.json
Consulte docs/diagnostics.md para referência completa de diagnóstico.
--audit é um wrapper de compatibilidade sobre processContainer.captureDenials em modo allow com retenção de ETL forçada. Ele injeta permissiveLearningMode, portanto operações negadas são registradas, mas têm permissão para prosseguir. Em hosts com o conjunto completo de APIs PSEC/V2 Learning Mode, o runner ProcessContainer selecionado usa captura nativa sem iniciar PLM ou solicitar elevação. Camadas mais antigas ou incompatíveis com políticas usam o fallback WPR protegido: wxc-exec.exe permanece sem elevação e inicia um guardião PLM elevado por UAC no escopo da sessão apenas para o ciclo de vida WPR privilegiado, comunicando-se por um pipe nomeado local autenticado. Ele é rejeitado para Windows Sandbox, WSLC, IsolationSession e todos os outros backends de contenção.
wxc-exec.exe --audit policy.json
Auditorias bem-sucedidas sem dry-run exigem metadados de captura, JSON de negações acionáveis e um ETL retido. A CLI realoca os caminhos selecionados pelo backend para denials.json e trace.etl no diretório de auditoria por usuário e, em seguida, gera um instantâneo da configuração de origem e Adjusted_*.json a partir do JSON acionável sem decodificar o ETL novamente. Entrada somente em Base64 mantém JSON e ETL, mas não tem configuração de origem para capturar ou ajustar. Análise truncada mantém JSON, ETL e o instantâneo de origem, mas ignora a geração de configuração ajustada. Use --audit-verbose para imprimir detalhes da política aprendida.
Aviso:
--auditinjetapermissiveLearningMode— as restrições do AppContainer não são aplicadas durante a execução. Use apenas para criação de políticas. Não pode ser combinado comprocessContainer.captureDenials; usecaptureDenials.mode: "allow"para captura permissiva orientada por aplicativo.learningModeLoggingepermissiveLearningModesão nomes de capacidades internas reservados e são rejeitados emprocessContainer.capabilities. Consulte docs/learning-mode/capabilities.md para os três fluxos de modo de aprendizado.
O MXC suporta telemetria ETW TraceLogging opcional para observabilidade de execução. Quando habilitada, eventos estruturados (MXC.Execution e MXC.Error) são emitidos para o subsistema ETW local por meio do crate Rust tracelogging. Cada evento inclui campos comuns (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) como dados de evento personalizado da Parte C.
A telemetria exige:
"telemetry": { "enabled": true } de nível superior na configuração JSONO sinalizador de configuração é um opt-in adicional por execução; ele não pode conceder consentimento ou contornar um bloqueio administrativo. A telemetria permanece desativada a menos que todos os portões aplicáveis estejam abertos. O MXC não usa a configuração Diagnóstico e comentários do Windows como substituto do consentimento do aplicativo.
Em plataformas que não sejam Windows, todas as funções de telemetria são no-ops.
O software pode coletar informações sobre você e seu uso do software e enviá-las à Microsoft. A Microsoft pode usar essas informações para fornecer serviços e melhorar nossos produtos e serviços. Você pode desativar a telemetria conforme descrito no repositório. Há também alguns recursos no software que podem permitir que você e a Microsoft coletem dados de usuários de seus aplicativos. Se você usar esses recursos, deverá cumprir a legislação aplicável, incluindo fornecer avisos apropriados aos usuários de seus aplicativos juntamente com uma cópia da declaração de privacidade da Microsoft. Nossa declaração de privacidade está localizada em https://go.microsoft.com/fwlink/?LinkID=824704. Você pode saber mais sobre coleta e uso de dados na documentação de ajuda e em nossa declaração de privacidade. Seu uso do software opera como seu consentimento para essas práticas.
A telemetria está desativada por padrão. Para mantê-la desativada, não defina "telemetry": { "enabled": true } para a execução.
Se a telemetria estiver habilitada na configuração, a coleta ainda não ocorre a menos que o consentimento do usuário do Windows seja concedido e a política administrativa permita a coleta.
As compilações oficiais/enviadas pela Microsoft definem um GUID de grupo de provedor TraceLogging no momento da compilação e roteiam eventos MXC.Execution e MXC.Error para a Microsoft por meio do pipeline UTC quando a telemetria está habilitada — essa mesma configuração em tempo de compilação também seleciona a palavra-chave Measures correta e a tag de privacidade Product-and-Service-Usage para os eventos, de modo que o roteamento de telemetria e a classificação de eventos sempre concordam. Compilações locais e de código aberto não enviam nada para a Microsoft por padrão — o código-fonte público é distribuído sem um GUID de grupo de provedor, portanto os eventos são emitidos apenas para o subsistema ETW local, usam uma palavra-chave local ao provedor sem significado UTC e não carregam tag de classificação de privacidade, e não são roteados para nenhum pipeline de coleta da Microsoft. Compilações internas que definem a variável de ambiente MXC_TELEMETRY_PROVIDER_GROUP_GUID no momento da compilação habilitam o caminho roteado pela Microsoft.
Nenhum PII é coletado. Os eventos contêm apenas métricas de execução (duração, tipo de backend, código de saída) e uma categoria de erro limitada (error_type). Texto de mensagem de erro de forma livre nunca é emitido, portanto caminhos, nomes de usuário e credenciais não podem vazar pela telemetria. Se você usar o SDK para criar aplicativos, é sua responsabilidade fornecer avisos de telemetria apropriados aos seus próprios usuários.
Informações de privacidade podem ser encontradas em https://privacy.microsoft.com e na declaração de privacidade da Microsoft em https://go.microsoft.com/fwlink/?LinkID=824704.
| Documento | Descrição |
|---|---|
| docs/schema.md | Referência completa do esquema de configuração JSON |
| docs/versioning.md | Versionamento de esquema e ciclo de vida de recursos experimentais |
| docs/examples.md | Exemplos de configuração anotados |
| docs/host-prep.md | Preparação do host Windows (wxc-host-prep.exe) |
| docs/diagnostics.md | Registro de diagnóstico e ETW |
| docs/sandbox-policy/0.7.0/policy.md | Especificação da política de sandbox 0.7.0 |
| docs/process-container/guide.md | Guia do Windows AppContainer / BaseContainer |
| docs/lxc-support/lxc-backend.md | Backend LXC (Linux) |
| docs/bwrap-support/bubblewrap-backend.md | Backend Bubblewrap (Linux) |
| docs/seatbelt/seatbelt-backend.md | Backend Seatbelt (macOS) |
| docs/windows-sandbox/windows-sandbox.md | Backend Windows Sandbox |
| docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md | API de ciclo de vida de sandbox ciente de estado |
| docs/telemetry/telemetry.md |
Consulte CONTRIBUTING.md para diretrizes de contribuição.
Consulte LICENSE.md para detalhes.
| Arquitetura de telemetria TraceLogging |
| docs/telemetry/telemetry-consent-design.md | Contrato de consentimento de telemetria |
| docs/telemetry/telemetry-administrative-policy.md | Controles administrativos de telemetria |