feat(driver-mxc): native Windows MXC compute driver + server wiring

[jamieknvidia]

Summary

Adds openshell-driver-mxc, a native-Windows compute driver backed by Microsoft Execution Containers (MXC / wxc-exec), and wires it into openshell-server behind ComputeDriverKind::Mxc. This lets OpenShell run governed agent sandboxes on Windows with filesystem and network policy enforcement, without touching the Linux container drivers. Builds on the Windows build-enablement foundation merged in #2496.

Related Issue

Part of RFC 0013 — Native Windows Support via MXC (merged in #2071). Stacks on the Windows build-enablement work in #2496. This is PR 1 (the driver) of the multi-PR native-Windows effort.

Changes

• New crate openshell-driver-mxc: in-process implementation of the ComputeDriver gRPC contract over MXC / wxc-exec. Backends: process_container (default-deny AppContainer) and isolation_session.
• Embedded policy mapper: translates SandboxPolicy → MXC grants (filesystem, network/egress, binary-scoped, network_middlewares) directly in the driver crate.
• Server wiring: ComputeDriverKind::Mxc dispatch in openshell-server (Windows-gated), mxc_config_from_context config plumbing, and telemetry / CLI / config-validation arms.
• Windows-only dependency: openshell-driver-mxc is pulled in under [target.'cfg(target_os = "windows")'.dependencies], complementary to the conditional Linux-driver exclusion from feat(gateway,cli): windows compilation support #2496.
• Real-host test lane: probe-gated real-wxc-exec tests (no mocks) plus e2e policy fixtures.

Testing

Built x86_64-pc-windows-msvc (release, bundled-z3) and validated on a real Windows 11 host (7F203-MXC-001, build 26300.x):

• Filesystem enforcement — DEMO PASS (process_container): in-policy write + read-back OK; out-of-policy write denied (PermissionDenied).

• Network policy — PASS: disallowed egress → ProvisionFailed: policy (port/protocol/access/binary-scoped grant checks).

• MXC crate unit tests: 75 passed / 0 failed / 9 ignored.

• windows-msvc.ps1 check x86_64-pc-windows-msvc: PASS.

• [] mise run pre-commit passes

• Unit tests added/updated

• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable) — covered by RFC 0013 (docs(rfc): add RFC 0013 native Windows support via MXC #2071)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[pkhodade-NV]

I have read the DCO document and I hereby sign the DCO.

[drew]

gator-agent

PR Review Status

Validation: Project-valid implementation of merged RFC 0013 and the native-Windows foundation in #2496.
Head SHA: 7beadcbaa26e4f08b854b58f2bfef526a02e8609
Base SHA: f24a5aee1390115fbdba7164f158d1491adcda28
Merge base SHA: dd2b4e3bc0688bdd59f90030f7c1d52511d6e354
Patch ID: 86ddd0be6113b95a1aa583c429c0e6360cb7084a
Gator payload: 4
Review mode: initial
Previous reviewed SHA: none
Review budget exhausted: no
Maintainer decision required: no

Blocking findings:

• GATOR-7beadcba-01 (Critical): the implicit MXC backend is documented as unable to enforce default-deny filesystem policy.
• GATOR-7beadcba-02 (Critical): share_dir silently adds a writable host path outside SandboxPolicy.
• GATOR-7beadcba-03 (Critical): governed egress is configured without binding the trimmed policy to an enforcing proxy.
• GATOR-7beadcba-04 (Critical): stop/delete can report success while execution or cleanup remains active, then discard cleanup identity.
• GATOR-7beadcba-05 (Warning): piped child output is never drained and can deadlock sandbox completion.
• GATOR-7beadcba-06 (Warning): joining agent_command loses Windows argv boundaries.
• GATOR-7beadcba-07 (Warning): deterministic policy-mapping failures occur after CreateSandbox has already returned success.

Carried findings:

• None.

Non-blocking suggestions:

• None.

Docs: Missing required Fern documentation for the new user-facing MXC driver setup and [openshell.drivers.mxc] gateway configuration. Please update the relevant page under docs/ and docs/index.yml navigation if needed, or obtain a maintainer-authored explanation that published docs are intentionally unnecessary.

Next state: gator:in-review

[drew]

gator-agent

Critical — GATOR-7beadcba-01

Invariant: A supported compute-driver default must preserve OpenShell's default-deny filesystem policy; selecting the driver without an explicit backend must not choose a backend documented as unable to enforce that policy (CWE-284).

Prerequisite: An operator enables the MXC driver and omits the optional backend setting; sandboxed agent code attempts to access a host path absent from filesystem_policy.

Entry point → sink: The documented [openshell.drivers.mxc] gateway configuration with its default backend, followed by the normal sandbox create path. → WxcExecInvoker::provision starts an isolation_session with grant lists but no deny primitive.

Base → head: At the merge base, MXC was not a supported compute driver, so this non-enforcing default could not be selected. → MxcBackend derives Default with IsolationSession selected even though the adjacent contract states that isolation_session is not default-deny and an out-of-policy write may succeed.

Impact: A malicious or compromised agent can access host filesystem locations excluded by SandboxPolicy while the gateway reports that it is running as an OpenShell sandbox.

Reproducer: Configure drivers=mxc with agent_command but no backend, create a sandbox whose filesystem_policy grants only C:\work\allowed, and run an agent that writes C:\Windows\Temp\outside.txt; on a live isolation_session host, verify that the ungranted write can succeed.

PR ownership: This PR introduces the Windows MXC runtime, explicitly identifies isolation_session's missing deny primitive, and nevertheless makes it the implicit supported default.

Requested change: Default to process_container, or reject isolation_session sandbox creation whenever the requested policy relies on default-deny unless the project defines an explicit, clearly unsafe opt-in contract approved by maintainers.

Sibling sites covered by this finding:

• crates/openshell-driver-mxc/src/driver.rs:37 documents that the selected default is not default-deny.
• crates/openshell-driver-mxc/src/driver.rs:102 installs MxcBackend::default() into default gateway configuration.
• crates/openshell-driver-mxc/src/driver.rs:632 provisions that backend with the translated grants.

[drew]

gator-agent

Critical — GATOR-7beadcba-02

Invariant: MXC filesystem grants must be derived from SandboxPolicy; driver configuration must not silently add a writable host path outside the policy (CWE-732, CWE-863).

Prerequisite: The gateway's share_dir differs from the sandbox policy's read_write entries, and sandboxed agent code accesses share_dir.

Entry point → sink: The documented share_dir gateway setting combined with the standard sandbox create API and filesystem_policy. → EmbeddedPolicyMapper appends share_dir directly to the MXC readwritePaths grant list.

Base → head: The merge base had no MXC driver and no driver-configured path capable of widening a sandbox's filesystem policy. → Every non-empty share_dir is granted read-write even when it is absent from filesystem_policy; correctness depends only on documentation asking operators to keep two independent values identical.

Impact: A configuration mismatch becomes a policy bypass, allowing an agent to modify an arbitrary operator-selected host directory that the sandbox policy explicitly did not grant.

Reproducer: Set share_dir=C:\sensitive, create a process_container sandbox whose filesystem_policy grants only C:\work, and inspect the generated one-shot config or attempt a write to C:\sensitive; readwritePaths contains C:\sensitive and the write is admitted.

PR ownership: The unconditional extra grant is newly implemented by this PR and materially broadens the policy-to-MXC translation.

Requested change: Remove the implicit share_dir grant. If the demo requires it, require the normalized path to already be covered by filesystem_policy.read_write and reject creation with invalid_argument when it is not.

Sibling sites covered by this finding:

• crates/openshell-driver-mxc/src/driver.rs:571 passes the independent gateway share_dir into policy mapping.
• crates/openshell-driver-mxc/src/policy.rs:185 describes the assumption that the two values happen to match.

[drew]

gator-agent

Critical — GATOR-7beadcba-03

Invariant: Enabling governed egress must fail closed unless the configured proxy is actually bound to the sandbox's trimmed policy; retaining policy in an unused registry field is not enforcement (CWE-693, CWE-284).

Prerequisite: An operator enables egress_proxy for process_container and supplies a reachable loopback CONNECT proxy; sandboxed agent code issues an outbound request outside its network policy.

Entry point → sink: The documented egress_proxy and egress_proxy_addr gateway settings with a sandbox network_policies block. → MXC redirects traffic to the configured loopback proxy, while the translated policy is only stored in SandboxEntry and has no consumer.

Base → head: The merge base did not expose MXC governed-egress configuration or claim to delegate MXC network policy to a host proxy. → The mapper accepts otherwise unrepresentable network policy, emits a proxy redirect, and stores trimmed_policy locally; repository references show no code that starts, configures, or updates a CONNECT proxy from that field.

Impact: With no listener, all egress fails despite successful sandbox creation. With a generic listener at the configured address, requests can be forwarded without the declared host, port, binary, middleware, or L7 restrictions, violating the advertised default-deny policy boundary.

Reproducer: Start a permissive CONNECT proxy on 127.0.0.1:18080, enable egress_proxy with that address, create a sandbox policy allowing only api.example.com:443, and request a different destination; inspect that the only policy handoff is the unused registry field and the permissive proxy receives the request without a policy update.

PR ownership: This PR adds the public egress feature and suppresses network mapping losses on the premise that a host proxy enforces the retained policy, while its own README states that host proxy integration is a future consumer.

Requested change: Reject egress_proxy=true until the driver owns or registers a fail-closed proxy instance and atomically installs the per-sandbox trimmed policy before redirecting traffic; alternatively remove the public option from this PR.

Sibling sites covered by this finding:

• crates/openshell-driver-mxc/src/driver.rs:622 emits the effectful MXC network redirect.
• crates/openshell-driver-mxc/src/policy_map/map.rs:114 removes filesystem state and treats network rules as delegated.
• crates/openshell-driver-mxc/src/driver.rs:132 is the only runtime storage for trimmed_policy.

[drew]

gator-agent

Critical — GATOR-7beadcba-04

Invariant: A successful stop or delete must prevent further workload execution and must retain cleanup identity when backend teardown fails (CWE-404, CWE-672).

Prerequisite: An operator stops or deletes a running process_container sandbox, deletes or stops either backend while asynchronous startup is in progress, or encounters an isolation_session deprovision failure.

Entry point → sink: The normal StopSandbox and DeleteSandbox RPCs, including openshell sandbox stop/delete. → The detached lifecycle task continues to provision/start/exec, process_container children are never terminated, and delete removes the registry entry even after deprovision failure.

Base → head: The merge base had no MXC lifecycle and could not report an MXC sandbox deleted while its workload or isolation session remained live. → Stop only invokes the isolation-session stop operation when an ID is already present and otherwise marks the entry stopped. Delete similarly acts only on an already-published isolation ID, does not terminate process_container children, ignores stop/deprovision failures, removes the entry, and has no cancellation handshake with run_lifecycle.

Impact: Agent code can continue running after the API reports it stopped or deleted; an immediate delete can orphan a newly provisioned single-session backend, and a failed deprovision loses the only ID needed to retry cleanup.

Reproducer: Use a blocking mock invoker: call create_sandbox, pause provision or run_oneshot, call delete_sandbox and assert deleted=true, then release the invoker and observe spawn_exec/run_oneshot execute. Separately, run a long process_container command, call stop, and verify the child remains alive; make deprovision return an error and verify the registry still reports deletion.

PR ownership: This PR introduces the detached MXC state machine and its stop/delete implementations without cancellation, child termination, or retryable teardown state.

Requested change: Add a per-entry cancellation/termination mechanism checked across every awaited lifecycle transition; terminate and await the process_container wxc-exec child on stop/delete; serialize teardown with startup; and retain the entry plus return an error when stop or deprovision fails so cleanup can be retried.

Sibling sites covered by this finding:

• crates/openshell-driver-mxc/src/driver.rs:447 skips backend termination when startup has not published iso_sandbox_id.
• crates/openshell-driver-mxc/src/driver.rs:456 reports Stopped without cancelling run_lifecycle or killing a process_container child.
• crates/openshell-driver-mxc/src/driver.rs:489 ignores deprovision failure before forgetting the session.
• crates/openshell-driver-mxc/src/driver.rs:632 and crates/openshell-driver-mxc/src/driver.rs:670 launch work without checking whether stop/delete occurred.

[drew]

gator-agent

Warning — GATOR-7beadcba-05

Invariant: Child stdout and stderr configured as pipes must be drained concurrently; waiting on an undrained child must not allow bounded pipe buffers to deadlock the sandbox (CWE-400).

Prerequisite: The configured agent emits enough stdout or stderr to fill a Windows pipe buffer, which is normal for a logging agent and controllable by sandboxed code.

Entry point → sink: Any MXC sandbox using agent_command on either supported backend. → monitor_exec waits for wxc-exec to exit without reading either piped stream.

Base → head: The merge base had no MXC child process or undrained output pipes. → Both real invocation paths set stdout and stderr to Stdio::piped, return only Child, and later call Child::wait without taking or draining the handles.

Impact: A sufficiently chatty agent or wxc-exec process blocks indefinitely on output, never reaches its intended exit, and leaves the sandbox incorrectly Ready with resources held.

Reproducer: Configure agent_command to write several megabytes to stdout and stderr before exiting, create a sandbox, and observe that monitor_exec never reaches AgentCompleted once the pipe buffer fills.

PR ownership: The PR introduces both piped spawn sites and the wait-only monitor.

Requested change: Either inherit/null the streams according to the intended logging contract or take and drain both streams concurrently before awaiting final completion; add a bounded-output regression test.

Sibling sites covered by this finding:

• crates/openshell-driver-mxc/src/mxc.rs:596 repeats the undrained-pipe configuration for process_container.
• crates/openshell-driver-mxc/src/driver.rs:729 waits without consuming child.stdout or child.stderr.

[drew]

gator-agent

Warning — GATOR-7beadcba-06

Invariant: The documented agent_command array must preserve Windows argv boundaries when converted to MXC's commandLine string.

Prerequisite: An operator configures an executable path or argument containing whitespace, quotes, a trailing backslash, or an empty argument.

Entry point → sink: The documented agent_command array in [openshell.drivers.mxc]. → run_lifecycle concatenates array elements with a single space before wxc-exec/CreateProcess parses the resulting command line.

Base → head: The merge base had no MXC agent_command configuration. → Structured command elements are flattened with Vec::join and no Windows command-line quoting, so the resulting argv differs from the configured array.

Impact: Common Windows paths such as C:\Program Files\Agent\agent.exe and arguments such as "hello world" are split or misparsed, causing the wrong executable or arguments to run and making supported configuration unreliable.

Reproducer: Set agent_command to ["C:\Program Files\Agent\agent.exe", "hello world", ""] and capture the generated process.commandLine; parse it with CommandLineToArgvW-compatible rules and verify it does not round-trip to the input vector.

PR ownership: This PR defines agent_command as Vec and introduces the lossy conversion used for every MXC launch.

Requested change: Encode each element with a tested Windows command-line quoting routine that round-trips under the MXC/CreateProcess parser, or expose a single explicitly documented command_line string instead of promising argv semantics.

[drew]

gator-agent

Warning — GATOR-7beadcba-07

Invariant: Policy translation failures discovered before any MXC side effect must be returned by CreateSandbox rather than converting an invalid request into an asynchronously failed persisted sandbox.

Prerequisite: A user submits a supported sandbox create request containing policy the selected MXC mode cannot enforce, such as network_policies while governed egress is disabled.

Entry point → sink: The gateway CreateSandbox API and openshell sandbox create command. → MxcComputeBackend returns CreateSandbox success after spawning run_lifecycle; the mapper later records ProvisionFailed instead of returning invalid_argument.

Base → head: At the merge base MXC was unsupported, so the gateway could not acknowledge an MXC create request whose policy had already made it invalid. → validate_sandbox_create cannot see the staged policy, create_sandbox starts a detached task and immediately returns Ok, and the deterministic mapper rejection occurs only inside that task after the gateway has persisted the sandbox.

Impact: The API reports successful creation and leaves a failed sandbox object requiring cleanup, contradicting the documented invalid_argument behavior and making automation unable to distinguish request errors from backend failures at create time.

Reproducer: Stage a policy containing one network rule with egress_proxy=false, invoke ComputeDriverService::create_sandbox, and assert that the RPC returns Ok while a later watch event changes the entry to Ready=False/ProvisionFailed.

PR ownership: The PR introduces the out-of-band policy channel and deliberately defers its only semantic validation until after the CreateSandbox response boundary.

Requested change: Consume and map the staged policy synchronously inside create_sandbox before registry insertion or task spawn, return invalid_argument for MapError::Unsupported, and only detach the effectful MXC lifecycle after validation succeeds.

Sibling sites covered by this finding:

• crates/openshell-driver-mxc/src/driver.rs:432 returns success before mapping completes.
• crates/openshell-driver-mxc/src/driver.rs:578 performs the deterministic policy validation asynchronously.
• crates/openshell-server/src/compute/mod.rs:988 stages the policy before the in-process driver call, so synchronous validation is available without changing the protobuf contract.

[drew]

generally we configure these from sandbox commands rather than the gateway. i think we should remove this for now.

[drew]

why does this need to be configurable from the gateway?

[drew]

same question as above. generally this is configured from the sandbox create command

[drew]

whats this example for? shouldn't the driver itself handle this?

[drew]

what is this for?

[drew]

[P1] Propagate policy updates after sandbox creation

This side channel installs the policy only for CreateSandbox. Later sandbox policy updates persist a new revision and notify SandboxWatchBus, but the MXC backend neither consumes that bus nor exposes an update path; its mapped grants and stored trimmed policy therefore remain at the creation-time version. Tightening a running sandbox policy can be reported as successful while the MXC workload continues under the older, broader policy. Please either apply updates to MXC fail-closed or reject policy updates for MXC sandboxes until they can be enforced.

[drew]

[P2] Subscribe before releasing the snapshot lock

The comment says the subscription prevents missed events, but subscribe happens after the registry lock is released. A lifecycle update in that interval is absent from the snapshot and published before this receiver exists, so the gateway can miss the transition permanently. Subscribe while still holding the registry lock, then capture the snapshot, so every update is represented by either the snapshot or the live stream.

[drew]

[P2] Restore a rustfmt-clean import order

cargo fmt --all -- --check fails on this import block, and also reports ordering drift in compute/mod.rs. Please run cargo fmt and commit the resulting import ordering so the required pre-commit formatting check passes.

[drew]

[P2] Include MXC in the local-driver mTLS default

MXC is now reserved as an in-process built-in here, but it is omitted from is_singleplayer_driver below. With the normal local TLS bundle, Docker, Podman, and VM automatically enable mTLS user authentication while MXC does not, so selecting MXC unexpectedly changes the gateway authentication default. Please include ComputeDriverKind::Mxc in is_singleplayer_driver and add the corresponding default-resolution test.

[drew]

/ok to test 7beadcb