OpenShell/crates/openshell-driver-mxc/README.md

openshell-driver-mxc

OpenShell compute driver backed by Microsoft MXC (wxc-exec) on Windows.

Design

This driver implements the gateway's ordinary in-process ComputeDriver contract and is linked into openshell-gateway. It sets driver_reports_runtime_readiness, so the gateway accepts driver-reported readiness without a supervisor session. The canonical create-time SandboxPolicy is carried by DriverSandboxSpec.policy. process_container launches a one-shot AppContainer and is the default. The opt-in isolation_session backend uses the state-aware provision → start → exec → stop → deprovision lifecycle. The driver launches and monitors the configured workload itself and self-reports readiness; there is no in-sandbox supervisor or ConnectSupervisor relay.

Capability Matrix

Capability	MXC driver
Filesystem policy	Read-only/read-write grants come only from SandboxPolicy. process_container enforces default-deny; isolation_session is an explicit grant-only compatibility mode.
Network policy	Rejected synchronously during sandbox creation until an enforcing egress path is bound.
Process policy	Unsupported; MXC supplies OS isolation only.
Interactive exec/connect/forward	Unsupported; the configured workload runs in-driver.
Restart durability	Unsupported; the in-memory registry cannot recover live sessions.

The filesystem enforcement proof has two paths:

• A write to a path granted by the sandbox policy succeeds.
• A process_container write outside the sandbox policy fails with Windows access denied, and the driver reports the failed workload.

Configuration ([openshell.drivers.mxc])

Gateway configuration contains only host runtime settings:

[openshell.drivers.mxc]
wxc_exec_path = "C:\\path\\to\\wxc-exec.exe"
# Default: process_container. isolation_session is grant-only and opt-in.
backend = "process_container"
default_configuration_id = "composable"
pc_least_privilege = false
pc_capabilities = []
debug = false
etw_audit = false

Supply workload settings for each sandbox. The public config is keyed by driver name; the gateway forwards only the inner mxc object to the driver:

$config = '{"mxc":{"command":["cmd","/c","echo hello > C:\\\\work\\\\demo\\\\hello.txt"],"cwd":"C:\\\\work\\\\demo"}}'
openshell sandbox create --name mxc-demo --policy demo.yaml `
  --driver-config-json $config --env MODE=demo --no-tty

The command array is required and preserves Windows argument boundaries. cwd is optional. Environment variables come from the standard sandbox and template environment maps; the driver never copies values from the gateway host environment.

Network policy support depends on the selected containment path. Policy replacement and merge updates use the gateway's standard sandbox configuration revision contract.

When etw_audit is enabled, each gateway process owns a distinct real-time ETW session named from the stable OpenShell-MXC-ETW prefix, its process ID, and a per-start discriminator. Starting another gateway never stops an existing gateway's capture. Graceful shutdown stops the session by its owned handle. A force-killed gateway can leave a stale session; the audit example removes only matching sessions whose encoded owner process is no longer running.

The gateway-local OCSF JSONL sink is available only for the Windows/MXC path and is opt-in. Set OPENSHELL_OCSF_JSON=1 to enable it and optionally set OPENSHELL_OCSF_LOG_DIR to override its %PROGRAMDATA%\OpenShell\logs default. Other gateway deployments do not initialize this local file sink.

The ETW callback uses a non-blocking queue capped at 4,096 records and 16 MiB of copied event data. Records that exceed either limit are dropped instead of blocking the ETW pump or growing gateway memory. The gateway emits an immediate warning identifying the audit coverage gap and rate-limits follow-up warnings to once every 30 seconds while overload continues.

Audit attribution bootstraps only when the driver-owned wxc-exec PID and its kernel process start key both match the values attached to the ETW record; command text is never an ownership key. This generation key prevents a recycled PID from inheriting the previous process's attribution regardless of delivery delay. The process monitor retires the live PID at exit. Established identity, activity, and correlation-vector links remain available for five seconds so already in-flight ETW records can arrive, but retired PID evidence cannot resolve them. Records without matching generation evidence remain unattributed.

Prerequisites (live runs)

• Windows 11 Insider build ≥ 26300.8553
• IsoSessionApp.dll present and registered
• wxc-exec.exe built with --features isolation_session

For off-box smoke tests against the in-process mock shim (no wxc-exec, no isolation session needed), set OPENSHELL_MXC_MOCK_WXC=1.

Policy mapping

The production driver maps the typed SandboxPolicy carried by the standard driver request to MXC configuration before it inserts a registry entry or invokes wxc-exec. Mapping failure therefore returns from CreateSandbox without leaving a partial sandbox. There is no in-process policy side channel or MXC-specific gateway composition variant.

EmbeddedPolicyMapper calls the embedded policy_map module directly and normalizes filesystem paths to Windows form. It does not add gateway-configured host paths. The policy supplied for the sandbox is the only source of filesystem grants.

The mapper retains an internal policy-splitting seam for future development, but the runtime exposes no governed-egress switch. Any network rule fails closed until an enforcing proxy is implemented and bound to the sandbox lifecycle.

Parity and matrix tests under tests/ cover the mapper on the Windows MSVC lane. The driver performs this mapping automatically; there is no separate policy-export command or example.

Packaging the demo for the demo box

Use examples/package-demo.ps1 to assemble the gateway EXE, CLI EXE, runtime DLLs (libz3.dll), demo.yaml, the gateway config, and the runbook into one folder, then copy that folder to the demo Windows host and follow mxc-demo-runbook.md inside it. The script prints a SHA256 manifest so the operator can sanity-check what landed before moving it.

Real-MXC test lane

Three tasks drive real wxc-exec.exe hardware; all are skip-safe — any test or scenario that requires an absent binary or backend prints a SKIP reason and exits 0 rather than failing.

Task	What it runs	When to use
windows:test:mxc-real:x64	tests/wxc_exec_real.rs — Tier-2 invoker tests with --ignored --test-threads=1	Pre-merge on any Windows host that has wxc-exec; dry-run tests always pass; enforcement tests probe-gate themselves
windows:e2e:mxc	examples/run-mxc-e2e.ps1 — Tier-3 scenario runner, real binary, probe-gated	Demo box / nightly; needs the gateway + CLI binaries in the script directory
windows:e2e:mxc:mock	Same runner with -Mock — wiring-only, no real wxc-exec needed	Any Windows host (CI, dev machine); validates wiring and the network-reject scenario

Probe script: examples/probe-mxc-host.ps1 is an operator/CI preflight that emits a JSON capability report (OS build, wxc-exec path/version, dry-run exit code, per-backend trial result, and a verdicts object). Run it before the real-MXC lane to understand what will PASS vs SKIP on a given host:

powershell -NoProfile -ExecutionPolicy Bypass `
  -File crates/openshell-driver-mxc/examples/probe-mxc-host.ps1

Skip semantics: tests in wxc_exec_real.rs are marked #[ignore = "requires real wxc-exec"] — the standard windows:test:x64 suite never runs them. OPENSHELL_WXC_EXEC_PATH overrides the default C:\mxc\wxc-exec.exe lookup. See docs4gtb/mxc-box-capabilities.md for the empirical capability snapshot of the development box (build 26200, processcontainer velocity keys not enabled, isolation_session absent).

Deferred work

• Interactive exec/connect/forward → adapt-openshell-gateway-windows
• Governed egress remains fail-closed until an enforcing proxy is implemented and bound to sandbox lifecycle.
• Restart durability (deprovision orphaned sessions on startup) → follow-on
• GPU passthrough → not pursued in host-side-governance design