microsoft/mxcPolicygesteuerte, mehrschichtige Isolierung und Eindämmung
MXC ist ein in einer Sandbox ausgeführtes Code-Ausführungssystem zum Ausführen von nicht vertrauenswürdigem Code (Modellausgabe, Plugins, Tools) unter Windows, Linux und macOS. Es bietet mehrere Containment-Backends – von betriebssystemeigenen Prozess-Sandboxes bis hin zu vollständigen VMs – hinter einem einheitlichen JSON-Konfigurationsschema und TypeScript-SDK.
[!WARNING] Dieses Repository enthält eine frühe Vorschau von Code, der veröffentlicht wurde, um eine frühe Integration und Feedback von Entwicklern zu Microsoft Execution Containers zu ermöglichen. Es wird erwartet, dass sich die zugrunde liegenden Sandboxes in dieser frühen Vorschau ändern, da sie sich in laufender Entwicklung befinden. Wir werden jedoch versuchen, die Auswirkungen auf die Kompatibilität zu minimieren, wenn sich die Funktionalität weiterentwickelt. Es gibt bekannte Fälle, in denen die aktuellen Richtlinien, die vom MXC-SDK in diesem Repository generiert werden, übermäßig permissiv sind; dies wird behoben, bevor dies allgemeiner verfügbar gemacht wird. Eine Partnerschaft mit Sicherheitsforschern während der Reifung von MXC ist willkommen, jedoch sollten derzeit keine MXC-Profile als Sicherheitsgrenzen behandelt werden.
@microsoft/mxc-sdk npm-Paket mit One-Shot- und zustandsbewussten APIsMXC wird mit einem nativen Container-Wrapper sowie einem TypeScript-SDK ausgeliefert – siehe SDK-README für die vollständige API-Dokumentation.
| Plattform | Standard-Backend | Andere Backends | Mindest-Build |
|---|---|---|---|
| Windows 11 24H2+ (verifiziert auf 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 | — | — |
Die stabilen One-Shot-Backends (processcontainer, bubblewrap, lxc und seatbelt) erfordern keinen experimentellen Modus; Linux-Hosts benötigen zusätzlich die passende Laufzeit: bwrap (Bubblewrap) für das Standard-Backend oder das lxc-Toolset für das lxc-Backend. Experimentelle Backends (windows_sandbox, wslc, microvm, isolation_session, hyperlight) erfordern { experimental: true } in SandboxSpawnOptions oder das CLI-Flag --experimental.
Informationen dazu, welche Aspekte der Dateisystem-, Netzwerk- und UI-Beschränkungsrichtlinien das Windows-processcontainer-Backend auf jeder Windows-11-Version (23H2 / 24H2 / 25H2 / 25H2+) durchsetzen kann, finden Sie unter Windows-Betriebssystemversions-Richtlinienunterstützung.
src/rust-toolchain.toml (automatisch von rustup ausgewählt)src/ Rust-Workspace (native Binärdateien + Shared-Library-Crates)
sdk/ TypeScript-SDK (@microsoft/mxc-sdk npm-Paket)
schemas/ JSON-Konfigurationsschemata (stabil + dev)
docs/ Dokumentation (Schema-Referenz, Backend-Anleitungen, Design-Dokumente)
tests/ Testmaterial (Konfigurationen, Beispiele, Skripte)
scripts/ Build- und Hilfsskripte
build.bat # Release-Build für aktuelle Architektur
build.bat --debug # Debug-Build
build.bat --all # Release-Build für x64 und ARM64
build.bat --with-microvm # NanVix-Micro-VM-Binärdateien einschließen
./build.sh # Release-Build
./build.sh --debug # Debug-Build
./build.sh --rust-only # Nur Rust-Binärdateien, SDK/CLI überspringen
./build-mac.sh # Release-Build für native Architektur
./build-mac.sh --all # Sowohl Apple Silicon als auch Intel
./build-mac.sh --debug # Debug-Build
./build-mac.sh --rust-only # Nur Rust-Binärdatei, SDK überspringen
Alle Build-Skripte:
Erstellen die plattformgerechte Rust-Binärdatei
Kopieren die Binärdatei in sdk/node/bin/<arch>/ (z. B. x64 oder arm64) für die SDK-Bündelung
Erstellen das TypeScript-SDK
# Rust-Workspace (aus 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 (bedient sowohl LXC als auch Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin # macOS
# SDK (aus sdk/node/)
npm install && npm run build
# Windows-Rust (aus src/)
cargo clippy --workspace --all-targets -- -D warnings
# Linux-Rust (aus src/; entspricht dem plattformkompatiblen Crate-Satz von build.sh)
cargo clippy -p lxc -p lxc_common -p wxc_common -p bwrap_common -p unix_test_proxy --all-targets -- -D warnings
# macOS-Rust (aus src/)
cargo clippy -p mxc_darwin -p seatbelt_common --all-targets -- -D warnings
# Rust-Unit-Tests (aus src/)
cargo test --workspace
cargo test -p wxc_common # Einzelnes Crate
cargo test -p wxc_common -- config_parser # Nach Testnamen filtern
# SDK (aus sdk/node/)
npm test # Unit-Tests
npm run test:integration # Integrationstests
# E2E (aus src/)
cargo test -p wxc_e2e_tests
MXC verwendet eine JSON-Konfiguration zur Definition von Ausführungsparametern. Siehe die Schema-Dokumentation für die vollständige Referenz.
# Dateipfad
wxc-exec.exe config.json
# Base64-kodierte Konfiguration
wxc-exec.exe --config-base64 <base64-kodiertes-json>
# Debug-Ausgabe
wxc-exec.exe --debug config.json
Unter Linux: ./lxc-exec config.json
Unter 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));
Das SDK bietet außerdem eine zustandsbewusste Lebenszyklus-API für langlebige Sandboxes:
import {
provisionSandbox, startSandbox, execInSandboxAsync,
stopSandbox, deprovisionSandbox,
} from '@microsoft/mxc-sdk';
Siehe SDK-README für die vollständige API-Dokumentation.
Veröffentlichte, unveränderliche stabile Schemata befinden sich in schemas/stable/; das in Arbeit befindliche Dev-Schema (experimentelle Backends, zustandsbewusster Lebenszyklus) befindet sich in schemas/dev/. Die aktuellen stabilen und Dev-Versionen werden kanonisch in schemas/schema-version.json nachverfolgt.
Wählen Sie das neueste stabile Schema für neuen Code auf jeder unterstützten Plattform. Siehe docs/versioning.md für das vollständige Versionierungsdesign.
Standardmäßig laufen native Binärdateien im stillen Modus – stdin/stdout/stderr ist direkt mit dem Container verbunden. Verwenden Sie --debug für ausführliche Ausgabe:
wxc-exec.exe --debug config.json
Siehe docs/diagnostics.md für die vollständige Diagnose-Referenz.
--audit ist ein Kompatibilitäts-Wrapper über processContainer.captureDenials im Allow-Modus mit erzwungener ETL-Aufbewahrung. Es injiziert permissiveLearningMode, sodass verweigerte Vorgänge aufgezeichnet, aber ausgeführt werden dürfen. Auf Hosts mit dem vollständigen PSEC/V2-Lernmodus-API-Satz verwendet der ausgewählte ProcessContainer-Runner die native Erfassung, ohne PLM zu starten oder eine Erhöhung anzufordern. Ältere oder richtlinieninkompatible Stufen verwenden den abgesicherten WPR-Fallback: wxc-exec.exe bleibt nicht erhöht und startet einen sitzungsbezogenen, UAC-erhöhten PLM-Guardian nur für den privilegierten WPR-Lebenszyklus, der über eine authentifizierte lokale Named Pipe kommuniziert. Es wird für Windows Sandbox, WSLC, IsolationSession und jedes andere Containment-Backend abgelehnt.
wxc-exec.exe --audit policy.json
Erfolgreiche Nicht-Trockenlauf-Audits erfordern Erfassungsmetadaten, umsetzbare Denials-JSON und ein aufbewahrtes ETL. Die CLI verschiebt die vom Backend ausgewählten Pfade in denials.json und trace.etl im benutzerspezifischen Audit-Verzeichnis und generiert dann einen Quellkonfigurations-Snapshot und Adjusted_*.json aus der umsetzbaren JSON, ohne das ETL erneut zu dekodieren. Nur-Base64-Eingabe behält JSON und ETL bei, hat aber keine Quellkonfiguration zum Snapshot oder Anpassen. Abgeschnittene Analyse behält JSON, ETL und den Quell-Snapshot bei, überspringt jedoch die Generierung der angepassten Konfiguration. Verwenden Sie --audit-verbose, um Details der gelernten Richtlinie auszugeben.
Warnung:
--auditinjiziertpermissiveLearningMode– AppContainer-Einschränkungen werden für die Dauer der Ausführung nicht durchgesetzt. Nur für die Richtlinienerstellung verwenden. Es kann nicht mitprocessContainer.captureDenialskombiniert werden; verwenden SiecaptureDenials.mode: "allow"für permissive anwendungsgesteuerte Erfassung.learningModeLoggingundpermissiveLearningModesind reservierte interne Capability-Namen und werden inprocessContainer.capabilitiesabgelehnt. Siehe docs/learning-mode/capabilities.md für die drei Lernmodus-Abläufe.
MXC unterstützt optionale TraceLogging-ETW-Telemetrie für Ausführungsbeobachtbarkeit. Wenn aktiviert, werden strukturierte Ereignisse (MXC.Execution und MXC.Error) über die Rust-tracelogging-Crate an das lokale ETW-Subsystem ausgegeben. Jedes Ereignis enthält gemeinsame Felder (Version, Channel, IsDebugging, UTCReplace_AppSessionGuid) als benutzerdefinierte Part-C-Ereignisdaten.
Telemetrie erfordert:
"telemetry": { "enabled": true } in der JSON-KonfigurationDas Konfigurationsflag ist ein zusätzliches Opt-in pro Ausführung; es kann keine Einwilligung erteilen oder einen administrativen Block umgehen. Telemetrie bleibt aus, es sei denn, jedes zutreffende Gate ist geöffnet. MXC verwendet die Windows-Einstellung „Diagnose & Feedback“ nicht als Ersatz für die Anwendungseinwilligung.
Auf Nicht-Windows-Plattformen sind alle Telemetriefunktionen No-Ops.
Die Software kann Informationen über Sie und Ihre Nutzung der Software erfassen und an Microsoft senden. Microsoft kann diese Informationen verwenden, um Dienste bereitzustellen und unsere Produkte und Dienste zu verbessern. Sie können die Telemetrie wie im Repository beschrieben deaktivieren. Es gibt auch einige Funktionen in der Software, die es Ihnen und Microsoft ermöglichen, Daten von Benutzern Ihrer Anwendungen zu erfassen. Wenn Sie diese Funktionen verwenden, müssen Sie geltendes Recht einhalten, einschließlich der Bereitstellung angemessener Hinweise an Benutzer Ihrer Anwendungen zusammen mit einer Kopie der Datenschutzerklärung von Microsoft. Unsere Datenschutzerklärung finden Sie unter https://go.microsoft.com/fwlink/?LinkID=824704. Weitere Informationen zur Datenerfassung und -verwendung finden Sie in der Hilfedokumentation und unserer Datenschutzerklärung. Ihre Nutzung der Software gilt als Ihre Zustimmung zu diesen Praktiken.
Telemetrie ist standardmäßig deaktiviert. Um sie deaktiviert zu lassen, setzen Sie "telemetry": { "enabled": true } nicht für die Ausführung.
Wenn Telemetrie in der Konfiguration aktiviert ist, erfolgt die Erfassung dennoch nicht, es sei denn, die Windows-Benutzereinwilligung wurde erteilt und die administrative Richtlinie erlaubt die Erfassung.
Offizielle/ausgelieferte Microsoft-Builds legen zur Build-Zeit eine TraceLogging-Provider-Gruppen-GUID fest und leiten MXC.Execution- und MXC.Error-Ereignisse über die UTC-Pipeline an Microsoft weiter, wenn Telemetrie aktiviert ist – dieselbe Build-Zeit-Einstellung wählt auch das korrekte Measures-Keyword und das Product-and-Service-Usage-Datenschutz-Tag für die Ereignisse aus, sodass Telemetrie-Routing und Ereignisklassifizierung immer übereinstimmen. Lokale und Open-Source-Builds senden standardmäßig nichts an Microsoft – der öffentliche Quellcode wird ohne Provider-Gruppen-GUID ausgeliefert, sodass Ereignisse nur an das lokale ETW-Subsystem ausgegeben werden, ein providerlokales Keyword ohne UTC-Bedeutung verwenden und kein Datenschutzklassifizierungs-Tag tragen und nicht an eine Microsoft-Erfassungspipeline weitergeleitet werden. Interne Builds, die die Umgebungsvariable MXC_TELEMETRY_PROVIDER_GROUP_GUID zur Build-Zeit setzen, aktivieren den Microsoft-gerouteten Pfad.
Es werden keine personenbezogenen Daten erfasst. Ereignisse enthalten nur Ausführungsmetriken (Dauer, Backend-Typ, Exit-Code) und eine begrenzte Fehlerkategorie (error_type). Freiform-Fehlermeldungstext wird nie ausgegeben, sodass Pfade, Benutzernamen und Anmeldeinformationen nicht über Telemetrie durchsickern können. Wenn Sie das SDK zum Erstellen von Anwendungen verwenden, sind Sie dafür verantwortlich, Ihren eigenen Benutzern angemessene Telemetrie-Hinweise bereitzustellen.
Datenschutzinformationen finden Sie unter https://privacy.microsoft.com und in der Microsoft-Datenschutzerklärung unter https://go.microsoft.com/fwlink/?LinkID=824704.
| Dokument | Beschreibung |
|---|---|
| docs/schema.md | Vollständige JSON-Konfigurationsschema-Referenz |
| docs/versioning.md | Schema-Versionierung und Lebenszyklus experimenteller Funktionen |
| docs/examples.md | Kommentierte Konfigurationsbeispiele |
| docs/host-prep.md | Windows-Host-Vorbereitung (wxc-host-prep.exe) |
| docs/diagnostics.md | Diagnoseprotokollierung und ETW |
| docs/sandbox-policy/0.7.0/policy.md | Sandbox-Richtlinien-Spezifikation 0.7.0 |
| docs/process-container/guide.md | Windows-AppContainer-/BaseContainer-Anleitung |
| docs/lxc-support/lxc-backend.md | LXC-Backend (Linux) |
| docs/bwrap-support/bubblewrap-backend.md | Bubblewrap-Backend (Linux) |
| docs/seatbelt/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 | Zustandsbewusste Sandbox-Lebenszyklus-API |
| docs/telemetry/telemetry.md |
Siehe CONTRIBUTING.md für Richtlinien zur Mitarbeit.
Siehe LICENSE.md für Details.
| TraceLogging-Telemetriearchitektur |
| docs/telemetry/telemetry-consent-design.md | Telemetrie-Einwilligungsvertrag |
| docs/telemetry/telemetry-administrative-policy.md | Administrative Telemetriesteuerungen |