microsoft/mxcPiloté par des politiques, isolation et confinement en couches
MXC est un système d'exécution de code sandboxé permettant d'exécuter du code non fiable (sortie de modèle, plugins, outils) sur Windows, Linux et macOS. Il fournit plusieurs backends de confinement — des sandbox de processus natifs au système d'exploitation jusqu'aux machines virtuelles complètes — derrière un schéma de configuration JSON unifié et un SDK TypeScript.
[!WARNING] Ce dépôt contient un aperçu précoce de code publié pour permettre une intégration anticipée et des retours des développeurs sur Microsoft Execution Containers. Les sandbox sous-jacentes de cet aperçu précoce devraient évoluer car elles sont en cours de développement continu, mais nous viserons à minimiser l'impact sur la compatibilité à mesure que les fonctionnalités évoluent. Il existe des cas connus où les politiques actuelles générées par le SDK MXC de ce dépôt sont trop permissives et seront corrigées avant une disponibilité plus générale. Un partenariat avec les chercheurs en sécurité pendant la maturation de MXC est bienvenu, mais aucun profil MXC ne doit actuellement être traité comme une frontière de sécurité.
@microsoft/mxc-sdk avec API à exécution unique et API avec étatMXC fournit un wrapper de conteneur natif ainsi qu'un SDK TypeScript — consultez le README du SDK pour la documentation complète de l'API.
| Plateforme | Backend par défaut | Autres backends | Build minimum |
|---|---|---|---|
| Windows 11 24H2+ (vérifié sur 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 (schéma 0.7.0-alpha+) | seatbelt | — | — |
Les backends stables à exécution unique (processcontainer, bubblewrap, lxc et seatbelt) ne nécessitent pas de mode expérimental ; les hôtes Linux doivent également disposer du runtime correspondant installé : bwrap (Bubblewrap) pour le backend par défaut, ou la suite d'outils lxc pour le backend lxc. Les backends expérimentaux (windows_sandbox, wslc, microvm, isolation_session, hyperlight) nécessitent { experimental: true } dans SandboxSpawnOptions ou l'indicateur CLI --experimental.
Pour savoir quels aspects de politique de restriction du système de fichiers, du réseau et de l'interface utilisateur le backend processcontainer Windows peut appliquer sur chaque version de Windows 11 (23H2 / 24H2 / 25H2 / 25H2+), consultez Prise en charge des politiques selon la version du système d'exploitation Windows.
src/rust-toolchain.toml (sélectionnée automatiquement par rustup)src/ Espace de travail Rust (binaires natifs + crates de bibliothèques partagées)
sdk/ SDK TypeScript (package npm @microsoft/mxc-sdk)
schemas/ Schémas de configuration JSON (stables + dev)
docs/ Documentation (référence des schémas, guides des backends, documents de conception)
tests/ Supports de test (configs, exemples, scripts)
scripts/ Scripts de build et utilitaires
build.bat # Build Release pour l'architecture actuelle
build.bat --debug # Build Debug
build.bat --all # Build Release pour x64 et ARM64
build.bat --with-microvm # Inclure les binaires NanVix micro-VM
./build.sh # Build Release
./build.sh --debug # Build Debug
./build.sh --rust-only # Uniquement les binaires Rust, sans SDK/CLI
./build-mac.sh # Build Release pour l'architecture native
./build-mac.sh --all # Apple Silicon et Intel
./build-mac.sh --debug # Build Debug
./build-mac.sh --rust-only # Uniquement le binaire Rust, sans SDK
Tous les scripts de build :
Compilent le binaire Rust adapté à la plateforme
Copient le binaire dans sdk/node/bin/<arch>/ (par exemple, x64 ou arm64) pour le regroupement du SDK
Compilent le SDK TypeScript
# Espace de travail Rust (depuis 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 (sert à la fois LXC et Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin # macOS
# SDK (depuis sdk/node/)
npm install && npm run build
# Rust Windows (depuis src/)
cargo clippy --workspace --all-targets -- -D warnings
# Rust Linux (depuis src/ ; correspond à l'ensemble de crates compatible plateforme 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 macOS (depuis src/)
cargo clippy -p mxc_darwin -p seatbelt_common --all-targets -- -D warnings
# Tests unitaires Rust (depuis src/)
cargo test --workspace
cargo test -p wxc_common # Crate unique
cargo test -p wxc_common -- config_parser # Filtrer par nom de test
# SDK (depuis sdk/node/)
npm test # Tests unitaires
npm run test:integration # Tests d'intégration
# E2E (depuis src/)
cargo test -p wxc_e2e_tests
MXC utilise une configuration JSON pour définir les paramètres d'exécution. Consultez la documentation du schéma pour la référence complète.
# Chemin de fichier
wxc-exec.exe config.json
# Configuration encodée en Base64
wxc-exec.exe --config-base64 <json-encodé-en-base64>
# Sortie de débogage
wxc-exec.exe --debug config.json
Sur Linux : ./lxc-exec config.json
Sur 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));
Le SDK fournit également une API de cycle de vie avec état pour les sandbox de longue durée :
import {
provisionSandbox, startSandbox, execInSandboxAsync,
stopSandbox, deprovisionSandbox,
} from '@microsoft/mxc-sdk';
Consultez le README du SDK pour la documentation complète de l'API.
Les schémas stables publiés et immuables se trouvent dans schemas/stable/ ; le schéma dev en cours (backends expérimentaux, cycle de vie avec état) se trouve dans schemas/dev/. Les versions stables et dev actuelles sont suivies de manière canonique dans schemas/schema-version.json.
Choisissez le dernier schéma stable pour tout nouveau code sur n'importe quelle plateforme prise en charge. Consultez docs/versioning.md pour la conception complète du versionnage.
Par défaut, les binaires natifs s'exécutent en mode silencieux — stdin/stdout/stderr est couplé directement au conteneur. Utilisez --debug pour une sortie détaillée :
wxc-exec.exe --debug config.json
Consultez docs/diagnostics.md pour la référence complète des diagnostics.
--audit est un wrapper de compatibilité sur processContainer.captureDenials en mode allow avec rétention ETL forcée. Il injecte permissiveLearningMode, de sorte que les opérations refusées sont enregistrées mais autorisées à se poursuivre. Sur les hôtes disposant de l'ensemble complet d'API PSEC/V2 Learning Mode, le runner ProcessContainer sélectionné utilise la capture native sans lancer PLM ni demander d'élévation. Les niveaux plus anciens ou incompatibles avec la politique utilisent le repli WPR protégé : wxc-exec.exe reste non élevé et démarre un gardien PLM élevé par UAC limité à la session uniquement pour le cycle de vie WPR privilégié, communiquant via un canal nommé local authentifié. Il est rejeté pour Windows Sandbox, WSLC, IsolationSession et tous les autres backends de confinement.
wxc-exec.exe --audit policy.json
Les audits réussis non simulés nécessitent des métadonnées de capture, un JSON de refus actionnable et un ETL conservé. La CLI déplace les chemins sélectionnés par le backend vers denials.json et trace.etl dans le répertoire d'audit par utilisateur, puis génère un instantané de la configuration source et Adjusted_*.json à partir du JSON actionnable sans décoder à nouveau l'ETL. Une entrée uniquement en Base64 conserve le JSON et l'ETL mais n'a pas de configuration source à instancier ou ajuster. Une analyse tronquée conserve le JSON, l'ETL et l'instantané source mais ignore la génération de la configuration ajustée. Utilisez --audit-verbose pour afficher les détails de la politique apprise.
Avertissement :
--auditinjectepermissiveLearningMode— les restrictions AppContainer ne sont pas appliquées pendant la durée de l'exécution. À utiliser uniquement pour la rédaction de politiques. Il ne peut pas être combiné avecprocessContainer.captureDenials; utilisezcaptureDenials.mode: "allow"pour une capture permissive pilotée par l'application.learningModeLoggingetpermissiveLearningModesont des noms de capacités internes réservés et sont rejetés dansprocessContainer.capabilities. Consultez docs/learning-mode/capabilities.md pour les trois flux de mode d'apprentissage.
MXC prend en charge la télémétrie ETW TraceLogging facultative pour l'observabilité de l'exécution. Lorsqu'elle est activée, des événements structurés (MXC.Execution et MXC.Error) sont émis vers le sous-système ETW local via la crate Rust tracelogging. Chaque événement inclut des champs communs (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) comme données d'événement personnalisées Part C.
La télémétrie nécessite :
"telemetry": { "enabled": true } au niveau supérieur dans la configuration JSONL'indicateur de configuration est une adhésion supplémentaire par exécution ; il ne peut pas accorder le consentement ni contourner un blocage administratif. La télémétrie reste désactivée à moins que chaque passerelle applicable soit ouverte. MXC n'utilise pas le paramètre Diagnostics et commentaires de Windows comme substitut au consentement de l'application.
Sur les plateformes non Windows, toutes les fonctions de télémétrie sont des no-ops.
Le logiciel peut collecter des informations vous concernant et concernant votre utilisation du logiciel et les envoyer à Microsoft. Microsoft peut utiliser ces informations pour fournir des services et améliorer nos produits et services. Vous pouvez désactiver la télémétrie comme décrit dans le dépôt. Certaines fonctionnalités du logiciel peuvent également vous permettre, ainsi qu'à Microsoft, de collecter des données auprès des utilisateurs de vos applications. Si vous utilisez ces fonctionnalités, vous devez vous conformer à la loi applicable, notamment en fournissant des avis appropriés aux utilisateurs de vos applications ainsi qu'une copie de la déclaration de confidentialité de Microsoft. Notre déclaration de confidentialité se trouve à l'adresse https://go.microsoft.com/fwlink/?LinkID=824704. Vous pouvez en apprendre davantage sur la collecte et l'utilisation des données dans la documentation d'aide et notre déclaration de confidentialité. Votre utilisation du logiciel vaut consentement à ces pratiques.
La télémétrie est désactivée par défaut. Pour la maintenir désactivée, ne définissez pas
"telemetry": { "enabled": true } pour l'exécution.
Si la télémétrie est activée dans la configuration, la collecte n'a toujours pas lieu à moins que le consentement de l'utilisateur Windows soit accordé et que la politique administrative autorise la collecte.
Les builds officiels/expédiés de Microsoft définissent un GUID de groupe de fournisseurs TraceLogging au moment de la compilation et acheminent les événements MXC.Execution et MXC.Error vers Microsoft via le pipeline UTC lorsque la télémétrie est activée — ce même paramètre de compilation sélectionne également le mot-clé Measures correct et la balise de confidentialité Product-and-Service-Usage pour les événements, de sorte que le routage de la télémétrie et la classification des événements concordent toujours. Les builds locaux et open source n'envoient rien à Microsoft par défaut — le code source public est fourni sans GUID de groupe de fournisseurs, de sorte que les événements sont émis uniquement vers le sous-système ETW local, utilisent un mot-clé local au fournisseur sans signification UTC, ne portent aucune balise de classification de confidentialité et ne sont acheminés vers aucun pipeline de collecte Microsoft. Les builds internes qui définissent la variable d'environnement MXC_TELEMETRY_PROVIDER_GROUP_GUID au moment de la compilation activent le chemin routé vers Microsoft.
Aucune donnée personnelle n'est collectée. Les événements contiennent uniquement des métriques d'exécution (durée, type de backend, code de sortie) et une catégorie d'erreur bornée (error_type). Le texte libre des messages d'erreur n'est jamais émis, de sorte que les chemins, noms d'utilisateur et identifiants ne peuvent pas fuir via la télémétrie. Si vous utilisez le SDK pour créer des applications, vous êtes responsable de fournir des avis de télémétrie appropriés à vos propres utilisateurs.
Les informations de confidentialité sont disponibles à l'adresse https://privacy.microsoft.com et dans la déclaration de confidentialité de Microsoft à l'adresse https://go.microsoft.com/fwlink/?LinkID=824704.
| Document | Description |
|---|---|
| docs/schema.md | Référence complète du schéma de configuration JSON |
| docs/versioning.md | Versionnage des schémas et cycle de vie des fonctionnalités expérimentales |
| docs/examples.md | Exemples de configuration annotés |
| docs/host-prep.md | Préparation de l'hôte Windows (wxc-host-prep.exe) |
| docs/diagnostics.md | Journalisation de diagnostic et ETW |
| docs/sandbox-policy/0.7.0/policy.md | Spécification de la politique de sandbox 0.7.0 |
| docs/process-container/guide.md | Guide 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 cycle de vie de sandbox avec état |
| docs/telemetry/telemetry.md |
Consultez CONTRIBUTING.md pour les directives de contribution.
Consultez LICENSE.md pour plus de détails.
| Architecture de télémétrie TraceLogging |
| docs/telemetry/telemetry-consent-design.md | Contrat de consentement de télémétrie |
| docs/telemetry/telemetry-administrative-policy.md | Contrôles administratifs de la télémétrie |