Microsoft eXecution Container (MXC)

MXC는 Windows, Linux, macOS에서 신뢰할 수 없는 코드(모델 출력, 플러그인, 도구)를 실행하기 위한 샌드박스 코드 실행 시스템입니다. 통합된 JSON 구성 스키마와 TypeScript SDK 뒤에서 OS 네이티브 프로세스 샌드박스부터 전체 VM까지 다양한 격리 백엔드를 제공합니다.

[!WARNING] 이 리포지토리는 개발자들이 Microsoft Execution Containers를 조기에 통합하고 피드백을 제공할 수 있도록 게시된 코드의 초기 미리보기를 포함합니다. 이 초기 미리보기의 기본 샌드박스는 지속적인 개발 중에 변경될 것으로 예상되지만, 기능이 발전함에 따라 호환성 영향을 최소화하기 위해 노력할 것입니다. 이 리포지토리의 MXC SDK가 생성하는 현재 정책이 과도하게 허용적인 것으로 알려진 사례가 있으며, 이는 더 널리 제공되기 전에 해결될 것입니다. MXC가 성숙하는 동안 보안 연구원 파트너십을 환영하지만, 현재 MXC 프로필은 보안 경계로 취급되어서는 안 됩니다.

기능

• 크로스 플랫폼: 플랫폼에 적합한 격리 백엔드를 갖춘 Windows, Linux, macOS 지원
• JSON 기반 구성: 버전이 지정된 JSON 스키마를 통해 실행 매개변수와 보안 정책 정의
• 다중 격리 백엔드: ProcessContainer, Windows Sandbox, LXC, Bubblewrap, Seatbelt(macOS), MicroVM(NanVix), Hyperlight, IsolationSession 및 WSLC
• 정책 기반 샌드박싱:
  • 파일시스템 정책: 읽기 전용 및 읽기-쓰기 경로 목록(Windows에서는 거부 경로가 아직 지원되지 않음)
  • 네트워크 정책: 프록시 지원(Linux/macOS에서 협력적), 아웃바운드 허용/차단, 백엔드 종속 호스트 필터링
  • UI 정책: 클립보드, 디스플레이 및 GUI 액세스 제어
• 상태 인식 수명주기: 세션 샌드박스를 위한 다단계 샌드박스 수명주기(프로비저닝 → 시작 → 실행 → 중지 → 프로비저닝 해제)
• TypeScript SDK: 일회성 및 상태 인식 API를 제공하는 @microsoft/mxc-sdk npm 패키지
• 진단: 문제 해결을 위한 디버그 로깅 및 Windows용 이벤트 추적(ETW)

빌드

MXC는 네이티브 컨테이너 래퍼와 TypeScript SDK를 제공합니다 — 전체 API 문서는 SDK README를 참조하세요.

플랫폼

안정적인 일회성 백엔드(processcontainer, bubblewrap, lxc, seatbelt)는 실험 모드가 필요하지 않습니다. Linux 호스트는 일치하는 런타임도 설치해야 합니다: 기본 백엔드용 bwrap(Bubblewrap) 또는 lxc 백엔드용 lxc 도구 모음. 실험적 백엔드(windows_sandbox, wslc, microvm, isolation_session, hyperlight)는 SandboxSpawnOptions에서 { experimental: true } 또는 --experimental CLI 플래그가 필요합니다.

Windows processcontainer 백엔드가 각 Windows 11 릴리스(23H2 / 24H2 / 25H2 / 25H2+)에서 적용할 수 있는 파일시스템, 네트워크 및 UI 제한 정책 측면에 대해서는 Windows OS 버전 정책 지원을 참조하세요.

요구 사항

• Rust 툴체인 — src/rust-toolchain.toml을 통해 1.93 버전으로 고정(rustup이 자동 선택)
• Node.js ≥ 18
• npm(SDK 및 CLI 빌드용)

프로젝트 구조

src/        Rust 워크스페이스(네이티브 바이너리 + 공유 라이브러리 크레이트)
sdk/        TypeScript SDK(@microsoft/mxc-sdk npm 패키지)
schemas/    JSON 구성 스키마(안정 + 개발)
docs/       문서(스키마 참조, 백엔드 가이드, 설계 문서)
tests/      테스트 자료(구성, 예제, 스크립트)
scripts/    빌드 및 유틸리티 스크립트

전체 빌드

Windows

build.bat                  # 현재 아키텍처용 릴리스 빌드
build.bat --debug          # 디버그 빌드
build.bat --all            # x64 및 ARM64용 릴리스 빌드
build.bat --with-microvm   # NanVix 마이크로-VM 바이너리 포함

Linux

./build.sh                 # 릴리스 빌드
./build.sh --debug         # 디버그 빌드
./build.sh --rust-only     # Rust 바이너리만, SDK/CLI 건너뜀

macOS

./build-mac.sh             # 네이티브 아키텍처용 릴리스 빌드
./build-mac.sh --all       # Apple Silicon 및 Intel 모두
./build-mac.sh --debug     # 디버그 빌드
./build-mac.sh --rust-only # Rust 바이너리만, SDK 건너뜀

모든 빌드 스크립트:

1. 플랫폼에 적합한 Rust 바이너리 빌드
2. SDK 번들링을 위해 바이너리를 sdk/node/bin/<arch>/(예: x64 또는 arm64)에 복사
3. TypeScript SDK 빌드

개별 구성 요소 빌드

# Rust 워크스페이스(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(LXC 및 Bubblewrap 모두 제공)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin  # macOS

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

린트 및 포맷

# Windows Rust(src/에서)

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

# Linux Rust(src/에서; 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(src/에서)

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

테스트

# Rust 단위 테스트(src/에서)
cargo test --workspace
cargo test -p wxc_common                      # 단일 크레이트
cargo test -p wxc_common -- config_parser     # 테스트 이름으로 필터링

# SDK(sdk/node/에서)
npm test                     # 단위 테스트
npm run test:integration     # 통합 테스트

# E2E(src/에서)
cargo test -p wxc_e2e_tests

사용법

MXC는 JSON 구성을 사용하여 실행 매개변수를 정의합니다. 전체 참조는 스키마 문서를 참조하세요.

네이티브 바이너리

# 파일 경로
wxc-exec.exe config.json

# Base64 인코딩 구성
wxc-exec.exe --config-base64 <base64-encoded-json>

# 디버그 출력
wxc-exec.exe --debug config.json

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

TypeScript SDK

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

SDK는 또한 장기 실행 샌드박스를 위한 상태 인식 수명주기 API를 제공합니다:

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

전체 API 문서는 SDK README를 참조하세요.

스키마 버전

릴리스된 불변의 안정 스키마는 schemas/stable/에 있으며, 진행 중인 개발 스키마(실험적 백엔드, 상태 인식 수명주기)는 schemas/dev/에 있습니다. 현재 안정 및 개발 버전은 schemas/schema-version.json에 표준으로 추적됩니다.

지원되는 모든 플랫폼의 새 코드에는 최신 안정 스키마를 선택하세요. 전체 버전 관리 설계는 docs/versioning.md를 참조하세요.

디버깅

디버그 콘솔 모드

기본적으로 네이티브 바이너리는 자동 모드로 실행됩니다 — stdin/stdout/stderr가 컨테이너에 직접 연결됩니다. 자세한 출력에는 --debug를 사용하세요:

wxc-exec.exe --debug config.json

전체 진단 참조는 docs/diagnostics.md를 참조하세요.

감사 모드(허용 학습 모드)

--audit는 ETL 보존을 강제로 적용한 허용 모드에서 processContainer.captureDenials에 대한 호환성 래퍼입니다. permissiveLearningMode를 주입하므로 거부된 작업이 기록되지만 계속 진행됩니다. 완전한 PSEC/V2 학습 모드 API 세트가 있는 호스트에서는 선택된 ProcessContainer 러너가 PLM을 시작하거나 승격을 요청하지 않고 네이티브 캡처를 사용합니다. 이전 또는 정책 비호환 계층은 보호된 WPR 대체를 사용합니다: wxc-exec.exe는 비승격 상태를 유지하고 인증된 로컬 명명된 파이프를 통해 통신하면서 권한 있는 WPR 수명주기에 대해서만 세션 범위의 UAC 승격 PLM 가디언을 시작합니다. Windows Sandbox, WSLC, IsolationSession 및 기타 모든 격리 백엔드에서는 거부됩니다.

wxc-exec.exe --audit policy.json

성공적인 비-드라이런 감사에는 캡처 메타데이터, 실행 가능한 거부 JSON 및 보존된 ETL이 필요합니다. CLI는 백엔드가 선택한 경로를 사용자별 감사 디렉토리의 denials.json 및 trace.etl로 이동시킨 다음, ETL을 다시 디코딩하지 않고 실행 가능한 JSON에서 소스 구성 스냅샷과 Adjusted_*.json을 생성합니다. Base64 전용 입력은 JSON과 ETL을 유지하지만 스냅샷하거나 조정할 소스 구성이 없습니다. 잘린 분석은 JSON, ETL 및 소스 스냅샷을 유지하지만 조정된 구성 생성을 건너뜁니다. 학습된 정책 세부 정보를 출력하려면 --audit-verbose를 사용하세요.

경고: --audit는 permissiveLearningMode를 주입합니다 — 실행 기간 동안 AppContainer 제한이 적용되지 않습니다. 정책 작성에만 사용하세요. processContainer.captureDenials와 결합할 수 없습니다. 허용적인 애플리케이션 기반 캡처에는 captureDenials.mode: "allow"를 사용하세요. learningModeLogging 및 permissiveLearningMode는 예약된 내부 기능 이름이며 processContainer.capabilities에서 거부됩니다. 세 가지 학습 모드 흐름은 docs/learning-mode/capabilities.md를 참조하세요.

원격 분석

MXC는 실행 관찰 가능성을 위한 선택적 TraceLogging ETW 원격 분석을 지원합니다. 활성화되면 구조화된 이벤트(MXC.Execution 및 MXC.Error)가 Rust tracelogging 크레이트를 통해 로컬 ETW 하위 시스템으로 전송됩니다. 모든 이벤트에는 Part C 사용자 지정 이벤트 데이터로 공통 필드(Version, Channel, IsDebugging, UTCReplace_AppSessionGuid)가 포함됩니다.

원격 분석에는 다음이 필요합니다:

1. JSON 구성의 최상위 "telemetry": { "enabled": true }
2. Windows에서 사용자별 명시적 원격 분석 동의
3. 정책이 구성된 경우 수집을 허용하는 관리 정책

구성 플래그는 실행별 추가 옵트인입니다. 동의를 부여하거나 관리 차단을 우회할 수 없습니다. 적용 가능한 모든 게이트가 열리지 않으면 원격 분석은 꺼진 상태로 유지됩니다. MXC는 Windows 진단 및 피드백 설정을 애플리케이션 동의의 대체 수단으로 사용하지 않습니다.

Windows가 아닌 플랫폼에서는 모든 원격 분석 함수가 no-op입니다.

데이터 수집

이 소프트웨어는 귀하와 귀하의 소프트웨어 사용에 관한 정보를 수집하여 Microsoft에 보낼 수 있습니다. Microsoft는 이 정보를 사용하여 서비스를 제공하고 제품과 서비스를 개선할 수 있습니다. 리포지토리에 설명된 대로 원격 분석을 끌 수 있습니다. 또한 이 소프트웨어에는 귀하와 Microsoft가 귀하의 애플리케이션 사용자로부터 데이터를 수집할 수 있게 하는 일부 기능이 있습니다. 이러한 기능을 사용하는 경우 Microsoft 개인정보 보호정책 사본과 함께 애플리케이션 사용자에게 적절한 고지를 제공하는 것을 포함하여 적용 가능한 법률을 준수해야 합니다. 개인정보 보호정책은 https://go.microsoft.com/fwlink/?LinkID=824704에 있습니다. 도움말 문서와 개인정보 보호정책에서 데이터 수집 및 사용에 대해 자세히 알아볼 수 있습니다. 소프트웨어 사용은 이러한 관행에 대한 동의로 간주됩니다.

원격 분석을 끄는 방법

원격 분석은 기본적으로 꺼져 있습니다. 꺼진 상태를 유지하려면 실행에 대해 "telemetry": { "enabled": true }를 설정하지 마세요.

구성에서 원격 분석이 활성화된 경우에도 Windows 사용자 동의가 부여되고 관리 정책이 수집을 허용하지 않으면 수집이 발생하지 않습니다.

공식 빌드가 보내는 내용

공식/배포된 Microsoft 빌드는 빌드 시 TraceLogging 공급자 그룹 GUID를 설정하고 원격 분석이 활성화되면 UTC 파이프라인을 통해 MXC.Execution 및 MXC.Error 이벤트를 Microsoft로 라우팅합니다 — 동일한 빌드 시 설정이 이벤트에 대한 올바른 Measures 키워드와 Product-and-Service-Usage 개인정보 태그도 선택하므로 원격 분석 라우팅과 이벤트 분류가 항상 일치합니다. 로컬 및 오픈 소스 빌드는 기본적으로 Microsoft에 아무것도 보내지 않습니다 — 공개 소스는 공급자 그룹 GUID 없이 제공되므로 이벤트는 로컬 ETW 하위 시스템에만 전송되고, UTC 의미가 없는 공급자 로컬 키워드를 사용하며, 개인정보 분류 태그를 포함하지 않으며, Microsoft 수집 파이프라인으로 라우팅되지 않습니다. 빌드 시 MXC_TELEMETRY_PROVIDER_GROUP_GUID 환경 변수를 설정하는 내부 빌드는 Microsoft 라우팅 경로를 활성화합니다.

PII는 수집되지 않습니다. 이벤트에는 실행 메트릭(기간, 백엔드 유형, 종료 코드)과 제한된 오류 범주(error_type)만 포함됩니다. 자유 형식 오류 메시지 텍스트는 절대 전송되지 않으므로 경로, 사용자 이름 및 자격 증명이 원격 분석을 통해 유출될 수 없습니다. SDK를 사용하여 애플리케이션을 빌드하는 경우 자체 사용자에게 적절한 원격 분석 고지를 제공할 책임이 있습니다.

개인정보 정보는 https://privacy.microsoft.com 및 https://go.microsoft.com/fwlink/?LinkID=824704의 Microsoft 개인정보 보호정책에서 확인할 수 있습니다.

문서

기여

기여 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

자세한 내용은 LICENSE.md를 참조하세요.