microsoft/mxcPolicy-driven, isolamento e contenimento a strati
MXC è un sistema di esecuzione codice in sandbox per eseguire codice non attendibile (output di modelli, plugin, strumenti) su Windows, Linux e macOS. Fornisce molteplici backend di contenimento — dalle sandbox di processo native del sistema operativo a VM complete — dietro uno schema di configurazione JSON unificato e un SDK TypeScript.
[!WARNING] Questo repository contiene un'anteprima iniziale del codice pubblicato per consentire l'integrazione anticipata e il feedback degli sviluppatori su Microsoft Execution Containers. Le sandbox sottostanti in questa anteprima iniziale dovrebbero cambiare poiché sono in continuo sviluppo, tuttavia mireremo a ridurre al minimo l'impatto sulla compatibilità man mano che la funzionalità evolve. Ci sono casi noti in cui le policy attuali generate dall'SDK MXC in questo repository sono eccessivamente permissive e verranno affrontate prima che questo venga reso più ampiamente disponibile. La collaborazione con i ricercatori di sicurezza mentre MXC matura è benvenuta, tuttavia nessun profilo MXC dovrebbe essere attualmente trattato come confine di sicurezza.
MXC include un wrapper nativo del contenitore più un SDK TypeScript — consulta il README dell'SDK per la documentazione completa dell'API.
| Piattaforma | Backend predefinito | Altri backend | Build minima |
|---|---|---|---|
| Windows 11 24H2+ (verificato su 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 (schema 0.7.0-alpha+) | seatbelt | — | — |
I backend one-shot stabili (processcontainer, bubblewrap, lxc e seatbelt) non richiedono la modalità sperimentale; gli host Linux necessitano anche del runtime corrispondente installato: bwrap (Bubblewrap) per il backend predefinito, o il toolset lxc per il backend lxc. I backend sperimentali (windows_sandbox, wslc, microvm, isolation_session, hyperlight) richiedono { experimental: true } in SandboxSpawnOptions o il flag CLI --experimental.
Per sapere quali aspetti delle policy di restrizione del filesystem, della rete e dell'interfaccia utente il backend processcontainer di Windows può applicare su ciascuna versione di Windows 11 (23H2 / 24H2 / 25H2 / 25H2+), consulta Supporto policy per versione del sistema operativo Windows.
src/rust-toolchain.toml (selezionata automaticamente da rustup)src/ Workspace Rust (binari nativi + crate di librerie condivise)
sdk/ SDK TypeScript (pacchetto npm @microsoft/mxc-sdk)
schemas/ Schemi di configurazione JSON (stabili + dev)
docs/ Documentazione (riferimento schema, guide backend, documenti di progettazione)
tests/ Materiale di test (configurazioni, esempi, script)
scripts/ Script di build e utilità
build.bat # Build Release per l'architettura corrente
build.bat --debug # Build Debug
build.bat --all # Build Release sia per x64 che ARM64
build.bat --with-microvm # Includi i binari NanVix micro-VM
./build.sh # Build Release
./build.sh --debug # Build Debug
./build.sh --rust-only # Solo binari Rust, salta SDK/CLI
./build-mac.sh # Build Release per l'architettura nativa
./build-mac.sh --all # Sia Apple Silicon che Intel
./build-mac.sh --debug # Build Debug
./build-mac.sh --rust-only # Solo binario Rust, salta SDK
Tutti gli script di build:
Compilano il binario Rust appropriato per la piattaforma
Copiano il binario in sdk/node/bin/<arch>/ (ad esempio, x64 o arm64) per il bundling dell'SDK
Compilano l'SDK TypeScript
# Workspace Rust (da 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 (serve sia LXC che Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin # macOS
# SDK (da sdk/node/)
npm install && npm run build
# Rust Windows (da src/)
cargo clippy --workspace --all-targets -- -D warnings
# Rust Linux (da src/; corrisponde al set di crate compatibili con la piattaforma di 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 (da src/)
cargo clippy -p mxc_darwin -p seatbelt_common --all-targets -- -D warnings
# Test unitari Rust (da src/)
cargo test --workspace
cargo test -p wxc_common # Crate singolo
cargo test -p wxc_common -- config_parser # Filtra per nome del test
# SDK (da sdk/node/)
npm test # Test unitari
npm run test:integration # Test di integrazione
# E2E (da src/)
cargo test -p wxc_e2e_tests
MXC utilizza una configurazione JSON per definire i parametri di esecuzione. Consulta la documentazione dello schema per il riferimento completo.
# Percorso del file
wxc-exec.exe config.json
# Config codificata in Base64
wxc-exec.exe --config-base64 <base64-encoded-json>
# Output di debug
wxc-exec.exe --debug config.json
Su Linux: ./lxc-exec config.json
Su 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));
L'SDK fornisce anche un'API state-aware del ciclo di vita per sandbox di lunga durata:
import {
provisionSandbox, startSandbox, execInSandboxAsync,
stopSandbox, deprovisionSandbox,
} from '@microsoft/mxc-sdk';
Consulta il README dell'SDK per la documentazione completa dell'API.
Gli schemi stabili rilasciati e immutabili si trovano in schemas/stable/; lo schema dev in corso di sviluppo (backend sperimentali, ciclo di vita state-aware) si trova in schemas/dev/. Le versioni stabili e dev correnti sono tracciate canonicamente in schemas/schema-version.json.
Scegli lo schema stabile più recente per il nuovo codice su qualsiasi piattaforma supportata. Consulta docs/versioning.md per la progettazione completa del versioning.
Per impostazione predefinita, i binari nativi vengono eseguiti in modalità silenziosa — stdin/stdout/stderr è collegato direttamente al contenitore. Usa --debug per un output dettagliato:
wxc-exec.exe --debug config.json
Consulta docs/diagnostics.md per il riferimento completo alla diagnostica.
--audit è un wrapper di compatibilità su processContainer.captureDenials in modalità allow con conservazione ETL forzata. Inietta permissiveLearningMode, quindi le operazioni negate vengono registrate ma consentite di procedere. Sugli host con il set completo di API PSEC/V2 Learning Mode, il runner ProcessContainer selezionato utilizza la cattura nativa senza avviare PLM o richiedere l'elevazione. I livelli più vecchi o incompatibili con le policy utilizzano il fallback WPR protetto: wxc-exec.exe rimane non elevato e avvia un guardian PLM elevato UAC limitato alla sessione solo per il ciclo di vita WPR privilegiato, comunicando tramite una named pipe locale autenticata. Viene rifiutato per Windows Sandbox, WSLC, IsolationSession e ogni altro backend di contenimento.
wxc-exec.exe --audit policy.json
Gli audit non dry-run riusciti richiedono metadati di cattura, JSON delle negazioni utilizzabili e un ETL conservato. La CLI sposta i percorsi selezionati dal backend in denials.json e trace.etl nella directory di audit per utente, quindi genera un'istantanea della configurazione sorgente e Adjusted_*.json dal JSON utilizzabile senza decodificare nuovamente l'ETL. L'input solo Base64 mantiene JSON ed ETL ma non ha configurazione sorgente da istantanare o regolare. L'analisi troncata mantiene JSON, ETL e l'istantanea sorgente ma salta la generazione della configurazione regolata. Usa --audit-verbose per stampare i dettagli della policy appresa.
Avvertenza:
--auditiniettapermissiveLearningMode— le restrizioni AppContainer non vengono applicate per la durata dell'esecuzione. Usa solo per la creazione di policy. Non può essere combinato conprocessContainer.captureDenials; usacaptureDenials.mode: "allow"per la cattura permissiva guidata dall'applicazione.learningModeLoggingepermissiveLearningModesono nomi di capacità interni riservati e vengono rifiutati inprocessContainer.capabilities. Consulta docs/learning-mode/capabilities.md per i tre flussi di modalità di apprendimento.
MXC supporta la telemetria ETW TraceLogging opzionale per l'osservabilità dell'esecuzione. Quando abilitata, gli eventi strutturati (MXC.Execution e MXC.Error) vengono emessi al sottosistema ETW locale tramite il crate Rust tracelogging. Ogni evento include campi comuni (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) come dati di evento personalizzati di Parte C.
La telemetria richiede:
"telemetry": { "enabled": true } di primo livello nella configurazione JSONIl flag di configurazione è un opt-in aggiuntivo per esecuzione; non può concedere il consenso o aggirare un blocco amministrativo. La telemetria rimane disattivata a meno che ogni gate applicabile sia aperto. MXC non utilizza l'impostazione Diagnostica e feedback di Windows come sostituto del consenso dell'applicazione.
Su piattaforme non Windows, tutte le funzioni di telemetria sono no-op.
Il software può raccogliere informazioni su di te e sul tuo utilizzo del software e inviarle a Microsoft. Microsoft può utilizzare queste informazioni per fornire servizi e migliorare i nostri prodotti e servizi. Puoi disattivare la telemetria come descritto nel repository. Ci sono anche alcune funzionalità nel software che possono consentire a te e a Microsoft di raccogliere dati dagli utenti delle tue applicazioni. Se utilizzi queste funzionalità, devi rispettare la legge applicabile, inclusa la fornitura di notifiche appropriate agli utenti delle tue applicazioni insieme a una copia dell'informativa sulla privacy di Microsoft. La nostra informativa sulla privacy si trova su https://go.microsoft.com/fwlink/?LinkID=824704. Puoi saperne di più sulla raccolta e l'uso dei dati nella documentazione di aiuto e nella nostra informativa sulla privacy. L'uso del software costituisce il tuo consenso a queste pratiche.
La telemetria è disattivata per impostazione predefinita. Per mantenerla disattivata, non impostare
"telemetry": { "enabled": true } per l'esecuzione.
Se la telemetria è abilitata nella configurazione, la raccolta non avviene comunque a meno che il consenso dell'utente Windows non sia concesso e la policy amministrativa consenta la raccolta.
Le build ufficiali/distribuite di Microsoft impostano un GUID del gruppo provider TraceLogging al momento della build e instradano gli eventi MXC.Execution e MXC.Error a Microsoft tramite la pipeline UTC quando la telemetria è abilitata — quella stessa impostazione al momento della build seleziona anche la parola chiave Measures corretta e il tag di privacy Product-and-Service-Usage per gli eventi, quindi l'instradamento della telemetria e la classificazione degli eventi concordano sempre. Le build locali e open-source non inviano nulla a Microsoft per impostazione predefinita — il codice sorgente pubblico viene distribuito senza un GUID del gruppo provider, quindi gli eventi vengono emessi solo al sottosistema ETW locale, utilizzano una parola chiave locale al provider senza significato UTC e non portano alcun tag di classificazione della privacy, e non vengono instradati a nessuna pipeline di raccolta Microsoft. Le build interne che impostano la variabile d'ambiente MXC_TELEMETRY_PROVIDER_GROUP_GUID al momento della build abilitano il percorso instradato a Microsoft.
Non vengono raccolti PII. Gli eventi contengono solo metriche di esecuzione (durata, tipo di backend, codice di uscita) e una categoria di errore limitata (error_type). Il testo libero dei messaggi di errore non viene mai emesso, quindi percorsi, nomi utente e credenziali non possono fuoriuscire tramite la telemetria. Se utilizzi l'SDK per creare applicazioni, sei responsabile di fornire notifiche di telemetria appropriate ai tuoi utenti.
Le informazioni sulla privacy si trovano su https://privacy.microsoft.com e nell'informativa sulla privacy di Microsoft su https://go.microsoft.com/fwlink/?LinkID=824704.
| Documento | Descrizione |
|---|---|
| docs/schema.md | Riferimento completo dello schema di configurazione JSON |
| docs/versioning.md | Versioning dello schema e ciclo di vita delle funzionalità sperimentali |
| docs/examples.md | Esempi di configurazione annotati |
| docs/host-prep.md | Preparazione dell'host Windows (wxc-host-prep.exe) |
| docs/diagnostics.md | Registrazione diagnostica ed ETW |
| docs/sandbox-policy/0.7.0/policy.md | Specifica della policy sandbox 0.7.0 |
| docs/process-container/guide.md | Guida a 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 del ciclo di vita sandbox state-aware |
| docs/telemetry/telemetry.md |
Consulta CONTRIBUTING.md per le linee guida sui contributi.
Consulta LICENSE.md per i dettagli.
| Architettura della telemetria TraceLogging |
| docs/telemetry/telemetry-consent-design.md | Contratto di consenso alla telemetria |
| docs/telemetry/telemetry-administrative-policy.md | Controlli amministrativi della telemetria |