From 5d1bfbf92135f4ee899f80999ccdf09152b77964 Mon Sep 17 00:00:00 2001 From: Shailendra Singh Date: Tue, 27 Oct 2026 17:38:48 -0700 Subject: [PATCH] docs(windows): align MXC documentation with the implementation (#4646) Complete the MXC documentation corrections after #4757. Update the Windows test reference, policy and runtime limitations, RFC runtime binary names and socket-owner lookup, and CLI guidance for live network policy updates. Closes #4645. Signed-off-by: Shailendra Singh --- .../build-openshell-mxc-windows/reference.md | 38 +++++++++++++------ docs/about/support-matrix.mdx | 5 ++- docs/how-it-works/policies/overview.mdx | 3 ++ docs/how-it-works/sandboxes/runtimes.mdx | 4 +- rfc/0013-native-windows-mxc/README.md | 33 +++++++++------- skills/openshell-cli/SKILL.md | 10 ++++- 6 files changed, 64 insertions(+), 29 deletions(-) diff --git a/.agents/skills/build-openshell-mxc-windows/reference.md b/.agents/skills/build-openshell-mxc-windows/reference.md index c47a69913..f157d8795 100644 --- a/.agents/skills/build-openshell-mxc-windows/reference.md +++ b/.agents/skills/build-openshell-mxc-windows/reference.md @@ -73,9 +73,11 @@ The wrapper adds missing rustup targets and preserves an inherited the setting. It does not install Visual Studio, Rust, Docker, Kubernetes, Podman, WSL, Hyper-V, or VM tooling. -On Windows, `mise run pre-commit` routes `rust:check`, `rust:lint`, and -`test:rust` through this wrapper for the host-native target. The shared task -definitions retain their existing Unix commands. Only tests for Linux glibc +On Windows, `mise run pre-commit` routes its `rust:lint` dependency through +this wrapper for the host-native target. The separate `rust:check` and +`test:rust` tasks also use the wrapper; `pre-commit` itself runs formatting +and lint checks. The shared task definitions retain their existing Unix +commands. Only tests for Linux glibc installer behavior, Linux build-environment shell helpers, and Linux service/RPM packaging assets skip on Windows. The Windows Clippy command excludes unsupported runtime packages as top-level targets and allows only @@ -91,8 +93,10 @@ For ARM64, verify the Visual Studio instance contains the ARM64 MSVC tools, ARM64 Spectre-mitigated libraries, Clang tools, CMake tools, and a Windows SDK. Clang supplies host-native `libclang.dll` for `bindgen` and `clang-cl.exe` for ARM64 crypto dependencies such as `aws-lc-sys`. Native and -x64-to-ARM64 builds use the official prebuilt Z3 5.1.0 static library for the -target architecture. An x64-to-ARM64 check/build discovers and adds host-native +x64-to-ARM64 builds use the official prebuilt Z3 5.1.0 import library and +`libz3.dll` for the target architecture. Release build tasks stage that DLL +beside the four executables; copy it with them to the runtime host. +An x64-to-ARM64 check/build discovers and adds host-native Ninja to `PATH`, while the crypto crates select `clang-cl`. Use a short `CARGO_TARGET_DIR` if Windows path-length limits are reached. @@ -117,9 +121,12 @@ Current focused unsupported-contract tests: ```text windows_builtin_compute_drivers_report_unsupported +default_registry_contains_exactly_the_enabled_compute_drivers ``` Run them with the architecture-specific focused task on the native host. +That task also tests gateway library builds with no compute driver, MXC only, +the Docker stub only, and MXC plus the Docker stub. ## Cargo Excludes @@ -146,7 +153,7 @@ package-level tests are excluded as top-level targets. The supervisor and supervisor-process packages now participate as top-level native check/test targets. Their portable session, attachment, and TCP readiness -coverage does not enable a Windows isolation runtime. +coverage does not qualify MXC isolation enforcement. ## Common Errors @@ -204,20 +211,29 @@ blocked dependency. ### Focused tests report many filtered-out tests -This is expected for `windows:test:unsupported:x64`. Cargo runs one named test -and filters the other `openshell-gateway` tests. Report these as filtered, not -ignored. +This is expected for `windows:test:unsupported:x64`. Each focused Cargo +invocation runs one named contract and filters the other `openshell-gateway` +tests. The task also runs four selective-feature library suites. Report +filtered tests separately from ignored tests. ## Reporting Counts +`windows:test:x64`, `windows:test:arm64`, and the workspace test step in +`windows:ci` use `cargo nextest run --profile ci --workspace` with +`openshell-server/test-support` and the selected Z3 features. The CI profile +disables fail-fast. Nextest does not run doc tests. Install the pinned +Nextest tool with `mise install --locked github:nextest-rs/nextest` before +running these tasks with `--skip-tools`. + Use the log summaries from: | Log | Count source | |---|---| -| `test-x86_64-pc-windows-msvc.log` | Full x64 workspace test pass. | -| `test-aarch64-pc-windows-msvc.log` | Full native ARM64 workspace test pass. | +| `test-x86_64-pc-windows-msvc-precommit.log` | Native x64 workspace Nextest run with server test support. | +| `test-aarch64-pc-windows-msvc-precommit.log` | Native ARM64 workspace Nextest run with server test support. | | `test-x86_64-pc-windows-msvc-unsupported-*.log` | Focused unsupported-contract re-runs and filtered counts. | | `test-aarch64-pc-windows-msvc-unsupported-*.log` | Focused native ARM64 re-runs and filtered counts. | +| `test--selective-*.log` | Gateway library tests for each selective compute-driver feature set. | Separate: diff --git a/docs/about/support-matrix.mdx b/docs/about/support-matrix.mdx index 2ec8b717e..28686d865 100644 --- a/docs/about/support-matrix.mdx +++ b/docs/about/support-matrix.mdx @@ -150,11 +150,14 @@ Install the software for the compute driver you use: ## Workload Images -OpenShell accepts standard Linux OCI images. The built-in default workload is +Docker, Podman, Kubernetes, and MicroVM accept standard Linux OCI images. The built-in default workload is `nvcr.io/nvidia/base/ubuntu:24.04` for `linux/amd64` and `linux/arm64`. It is a minimal Ubuntu Noble userspace and does not bundle agent CLIs. Operators can change the default, and users can select an explicit image with `--from`. +Native Windows MXC runs host commands rather than OCI images. See the +[Windows guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md). + ## Container Images | Image | Reference | Pulled When | diff --git a/docs/how-it-works/policies/overview.mdx b/docs/how-it-works/policies/overview.mdx index 964ed190c..5a54d92f6 100644 --- a/docs/how-it-works/policies/overview.mdx +++ b/docs/how-it-works/policies/overview.mdx @@ -33,6 +33,9 @@ specific time: | `network_policies` | Destinations each binary can reach, and the requests it can send. | Sandbox network proxy. | While the sandbox runs. | | `network_middlewares` | Additional inspection, transformation, or blocking of traffic that network rules allow. | Sandbox network proxy. | While the sandbox runs. | +For native Windows filesystem enforcement and proxy limitations, see +[Windows policy controls](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md#runtime-and-current-limits). + Filesystem, Landlock, process, and UI settings are fixed once the sandbox starts. Network rules and middleware can change while it runs, as described in [How Changes Take diff --git a/docs/how-it-works/sandboxes/runtimes.mdx b/docs/how-it-works/sandboxes/runtimes.mdx index bf786157c..03dea1c69 100644 --- a/docs/how-it-works/sandboxes/runtimes.mdx +++ b/docs/how-it-works/sandboxes/runtimes.mdx @@ -3,7 +3,7 @@ # SPDX-License-Identifier: Apache-2.0 title: "Sandbox Runtimes" sidebar-title: "Runtimes" -description: "Configure the Docker, Podman, MicroVM, or Kubernetes runtime that runs OpenShell sandboxes." +description: "Configure the Docker, Podman, MicroVM, Kubernetes, or experimental Windows MXC runtime that runs OpenShell sandboxes." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Docker, Podman, MicroVM, Kubernetes, MXC, Reference" position: 4 --- @@ -37,7 +37,7 @@ compute_driver = "docker" Every gateway TOML file must start with the `[openshell]` table and `version = 2`, or `openshell-gateway config preflight` rejects it with `missing_version`. The remaining examples on this page show only the tables they change. -When `compute_driver` is unset, the gateway auto-detects Kubernetes, then Podman, then Docker. The VM driver is never auto-detected. +When `compute_driver` is unset, the gateway auto-detects Kubernetes, then Podman, then Docker. The VM and MXC drivers are never auto-detected. Configure driver-specific values, such as images, endpoints, and sizing, under `[openshell.drivers.]`. See the [Gateway Configuration File](/how-it-works/gateways/configuration) reference for every option. diff --git a/rfc/0013-native-windows-mxc/README.md b/rfc/0013-native-windows-mxc/README.md index c4706cfd5..50e46dba5 100644 --- a/rfc/0013-native-windows-mxc/README.md +++ b/rfc/0013-native-windows-mxc/README.md @@ -15,7 +15,7 @@ links: OpenShell runs natively on Windows 11 by using Microsoft Execution Containers (MXC, through `wxc-exec.exe`) as an RFC 0012 isolation backend. The gateway's in-process MXC compute driver provisions a host -`openshell-supervisor --role=isolation-backend` and an `openshell-sandbox` +`openshell-supervisor --role=isolation-backend` and an `openshell-windows-sandbox` boundary inside each ProcessContainer. The authenticated Sandbox Protocol is the only runtime control and forwarding @@ -62,7 +62,7 @@ authenticated paths instead of MXC-only side channels. flowchart TD Gateway[Gateway / in-process MXC driver] Supervisor[openshell-supervisor
role=isolation-backend] - Sandbox[openshell-sandbox
inside MXC ProcessContainer] + Sandbox[openshell-windows-sandbox
inside MXC ProcessContainer] Workload[Workload process tree] Gateway -->|policy + launch authentication| Supervisor @@ -96,6 +96,12 @@ The boundary terminates owned workload processes if no authenticated supervisor recovers within the bounded reconnect deadline. Host auth bundles and runtime descriptors are stored beneath an owner-only Windows DACL. +The current Windows development implementation temporarily asserts the +required no-unmanaged-egress and revocation guarantees for compatibility +testing. These assertions are not verified enforcement evidence. Broad host +loopback remains outside exclusive proxy mediation, and passing runtime tests +does not establish production qualification. + ### Networking and credentials MXC denies direct Internet egress and permits the loopback route used by the @@ -109,12 +115,13 @@ children. The supervisor retains private CA keys and provider secrets, applies network policy, and refreshes provider state through the ordinary session. The listener rejects missing, duplicate, malformed, and cross-generation proxy -authorization before policy evaluation. The initial implementation assigns -requests to the admitted main workload binary because Windows socket-owner -identity is not yet carried by the explicit-proxy transport. Policies that rely -on different network rights for descendant executables are therefore outside -the initial enforcement contract. The loopback exception also does not isolate -unrelated services bound to `127.0.0.1`; the gateway host remains trusted. +authorization before policy evaluation. The Windows backend resolves the +socket-owning PID with `GetExtendedTcpTable`, obtains its executable path with +`QueryFullProcessImageNameW`, hashes the executable, and rechecks ownership. +The proxy denies missing, ambiguous, or changed ownership. Network rules must +authorize the child executable opening the connection, not only its launcher. +The loopback exception still does not isolate unrelated services bound to +`127.0.0.1`; the gateway host remains trusted. ### Process lifecycle and forwarding @@ -129,9 +136,11 @@ resize is deferred; non-terminal exec and byte-stream I/O are supported first. ### Configuration and packaging -The Windows release contains `openshell-gateway.exe`, `openshell.exe`, -`openshell-supervisor.exe`, and `openshell-sandbox.exe`. The runtime binaries -default to siblings of the gateway and may be overridden for development. +The Windows source build produces `openshell-gateway.exe`, `openshell.exe`, +`openshell-supervisor.exe`, and `openshell-windows-sandbox.exe`, and stages the +matching `libz3.dll` beside them. The Windows workflow does not publish these +artifacts. The runtime binaries default to siblings of the gateway and may be +overridden for development. Gateway TLS uses the gateway-owned guest certificate bundle. The MXC driver configuration contains only host/runtime settings. Workload @@ -208,8 +217,6 @@ diverge by platform. ## Open questions -- Which Windows API should provide race-resistant socket-owner executable - identity for per-descendant binary network policy? - Should MXC restart recovery persist enough generation metadata to reconnect, or should startup always terminate and recreate orphaned ProcessContainers? - What ConPTY surface is required before Windows interactive exec is considered diff --git a/skills/openshell-cli/SKILL.md b/skills/openshell-cli/SKILL.md index fef712590..c4ce90767 100644 --- a/skills/openshell-cli/SKILL.md +++ b/skills/openshell-cli/SKILL.md @@ -26,7 +26,7 @@ This is your primary fallback. Use it freely -- the CLI's help output is authori ## Prerequisites - `openshell` is on the PATH. Follow the published [installation guide](https://docs.nvidia.com/openshell/latest/about/installation.md) when it is not installed. -- A reachable OpenShell gateway backed by Docker, Podman, Kubernetes, or the experimental VM driver +- A reachable OpenShell gateway backed by Docker, Podman, Kubernetes, VM, or the experimental native Windows MXC driver - Docker is running only when using BYOC local builds or a Docker-backed gateway - For Kubernetes deployments: `kubectl` and Helm access to the target cluster @@ -94,6 +94,12 @@ attachment and delete its sandbox after the service exits. When supplying `--name`, use a portable DNS-1123 label: at most 63 lowercase alphanumeric or `-` characters, beginning and ending with an alphanumeric character. The Kubernetes driver rejects uppercase letters, underscores, dots, and other names that cannot become Kubernetes resource labels. +For native Windows MXC, supply the Windows command and absolute working +directory through `--driver-config-json` and use `--detach`. The gateway +administrator must enable caller driver configuration. Foreground attachment +is rejected before provisioning; `--no-tty` alone does not request detachment. +See [MXC configuration and limitations](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/configuration#mxc). + Provider attachment is explicit. Name each provider with `--provider`; the trailing command does not select or attach one. If the named provider does not exist but a profile with that ID is available, the CLI can create it from local @@ -635,7 +641,7 @@ Edit `current-policy.yaml` to allow the blocked actions. **For policy content au - Binary matching patterns - Ordered `network_middlewares`, host selection, HTTP request/response and WebSocket bindings, and `fail_open` or `fail_closed` behavior -`network_policies` and `network_middlewares` can be modified at runtime when the selected compute driver supports live policy updates. Use `--wait` to verify that the active runtime loaded the revision; do not infer enforcement from the gateway accepting the update. MXC rejects live policy replacement and merge updates; delete and recreate an MXC sandbox instead. If `filesystem_policy`, `landlock`, or `process` need changes, the sandbox must be recreated. Built-in middleware such as `openshell/regex` needs no gateway registration. An operator-run middleware must already be registered under `[[openshell.supervisor.middleware]]`; changing that static registration requires a gateway restart. +`network_policies` and `network_middlewares` can be modified at runtime through the shared supervisor. Use `--wait` to verify that the active runtime loaded the revision; do not infer enforcement from the gateway accepting the update. On MXC, network rules govern explicit-proxy traffic; direct host-loopback access and native live-revocation qualification remain documented limitations. If `filesystem_policy`, `landlock`, `process`, or `ui` need changes, the sandbox must be recreated. Built-in middleware such as `openshell/regex` needs no gateway registration. An operator-run middleware must already be registered under `[[openshell.supervisor.middleware]]`; changing that static registration requires a gateway restart. Middleware can inspect HTTP requests, HTTP responses, or client WebSocket text messages when the implementation advertises the matching binding. The built-in