diff --git a/crates/openshell-driver-mxc/README.md b/crates/openshell-driver-mxc/README.md index c4f1bfefdd..674892ceae 100644 --- a/crates/openshell-driver-mxc/README.md +++ b/crates/openshell-driver-mxc/README.md @@ -168,6 +168,38 @@ The MXC credential handoff is also fixed at sandbox creation. The gateway reject `openshell.exe`. Diagnose executable blocks with event 3077 in the `Microsoft-Windows-CodeIntegrity/Operational` log. +Place `wxc-exec.exe` in a regular directory outside any installed MSIX or +`WindowsApps` package directory. A package directory's ACLs can prevent the +gateway from starting the executable outside its package context, even when +the same binary runs after it is copied elsewhere. If sandbox creation fails +with `wxc-exec spawn failed: Access is denied. (os error 5)`, verify that +`wxc_exec_path` points to the standalone copy. + +Before the first live `process_container` run, check the selected isolation +tier and host-preparation warnings in PowerShell: + +```powershell +& "C:\path\to\wxc-exec.exe" --probe +``` + +If the probe selects AppContainer + DACL (`appcontainer-dacl`) and recommends +`prepare-system-drive`, obtain `wxc-host-prep.exe` from the MXC binaries +distribution and run this command once in an elevated PowerShell session. +BaseContainer and AppContainer + BFS do not require this preparation. + +```powershell +& "C:\path\to\wxc-host-prep.exe" prepare-system-drive +``` + +This persistent, host-wide change adds non-inheriting ACL entries that give +the AppContainer well-known SIDs metadata access to the system-drive root. It +does not grant directory listing or write access, or change descendant ACLs. +If `wxc-exec.exe` starts but the agent exits with +`wxc-exec stderr: Access is denied.` or exit code 1, check the probe warnings +before changing host ACLs; these errors alone do not identify missing host +preparation. See Microsoft's [MXC host-preparation guide](https://github.com/microsoft/mxc/blob/main/docs/host-prep.md) +for verification, other host prerequisites, and rollback instructions. + For off-box smoke tests against the in-process mock shim (no `wxc-exec`, no isolation session needed), set `OPENSHELL_MXC_MOCK_WXC=1`. diff --git a/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt b/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt index 51bedd26a7..c81a047aed 100644 --- a/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt +++ b/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt @@ -21,7 +21,26 @@ WHAT THIS PROVES / PRODUCES [2004] Detection Finding - MXC setup activity errors (informational) PREREQUISITES (on this test box) - - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe) + - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe). + Use a standalone copy in a regular directory, not a copy inside an + installed MSIX or WindowsApps package directory. If CreateSandbox reports + "wxc-exec spawn failed: Access is denied. (os error 5)", check this path. + - Before the first process_container run, check the selected isolation tier + and host-preparation warnings in PowerShell: + & "C:\path\to\wxc-exec.exe" --probe + Only if the probe selects AppContainer + DACL (appcontainer-dacl) and + recommends prepare-system-drive, obtain wxc-host-prep.exe from the MXC + binaries distribution and run this once in elevated PowerShell: + & "C:\path\to\wxc-host-prep.exe" prepare-system-drive + BaseContainer and AppContainer + BFS do not require this preparation. + The persistent, host-wide ACL change grants the AppContainer well-known + SIDs metadata access to the system-drive root only; it does not grant + directory listing or write access, or change descendant ACLs. + If wxc-exec starts but the agent exits with "wxc-exec stderr: Access is + denied." or exit code 1, check the probe warnings before changing host + ACLs; these errors alone do not identify missing host preparation. + For verification, other host prerequisites, and rollback, see: + https://github.com/microsoft/mxc/blob/main/docs/host-prep.md - process_container backend live (it was for our earlier runs) - Run ELEVATED (Run as administrator) OR from an account in the 'Performance Log Users' group. Opening the real-time ETW session needs this; diff --git a/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt b/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt index c3aa149896..810cd2a9b8 100644 --- a/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt +++ b/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt @@ -40,7 +40,26 @@ PREREQUISITES (on this test box) ownership. Non-elevated fails both with ERROR_ACCESS_DENIED (0x5), the second as "Network proxy error: Failed to set loopback exemption: 0x00000005". -Backend isolation_session does not hit either path. - - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe) + - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe). + Use a standalone copy in a regular directory, not a copy inside an + installed MSIX or WindowsApps package directory. If CreateSandbox reports + "wxc-exec spawn failed: Access is denied. (os error 5)", check this path. + - Before the first process_container run, check the selected isolation tier + and host-preparation warnings in PowerShell: + & "C:\path\to\wxc-exec.exe" --probe + Only if the probe selects AppContainer + DACL (appcontainer-dacl) and + recommends prepare-system-drive, obtain wxc-host-prep.exe from the MXC + binaries distribution and run this once in elevated PowerShell: + & "C:\path\to\wxc-host-prep.exe" prepare-system-drive + BaseContainer and AppContainer + BFS do not require this preparation. + The persistent, host-wide ACL change grants the AppContainer well-known + SIDs metadata access to the system-drive root only; it does not grant + directory listing or write access, or change descendant ACLs. + If wxc-exec starts but the agent exits with "wxc-exec stderr: Access is + denied." or exit code 1, check the probe warnings before changing host + ACLs; these errors alone do not identify missing host preparation. + For verification, other host prerequisites, and rollback, see: + https://github.com/microsoft/mxc/blob/main/docs/host-prep.md - process_container or isolation_session backend live (whichever -Backend you pass) - Your own OpenClaw install: a node.exe binary + the openclaw npm package diff --git a/crates/openshell-driver-mxc/examples/README.txt b/crates/openshell-driver-mxc/examples/README.txt index 659124f9e5..6e010dbd00 100644 --- a/crates/openshell-driver-mxc/examples/README.txt +++ b/crates/openshell-driver-mxc/examples/README.txt @@ -17,7 +17,26 @@ Prerequisites - openshell-gateway.exe and openshell.exe beside these files, or explicit -GatewayPath and -CliPath arguments. - wxc-exec.exe beside these files, on PATH, named by - OPENSHELL_WXC_EXEC_PATH, or passed with -WxcExecPath. + OPENSHELL_WXC_EXEC_PATH, or passed with -WxcExecPath. Use a standalone + copy in a regular directory. Do not use a copy from an installed MSIX or + WindowsApps package directory; its package ACLs can make CreateSandbox + fail with "wxc-exec spawn failed: Access is denied. (os error 5)". + - Before the first process_container run, check the selected isolation tier + and host-preparation warnings in PowerShell: + & "C:\path\to\wxc-exec.exe" --probe + Only if the probe selects AppContainer + DACL (appcontainer-dacl) and + recommends prepare-system-drive, obtain wxc-host-prep.exe from the MXC + binaries distribution and run this once in elevated PowerShell: + & "C:\path\to\wxc-host-prep.exe" prepare-system-drive + BaseContainer and AppContainer + BFS do not require this preparation. + The persistent, host-wide ACL change grants the AppContainer well-known + SIDs metadata access to the system-drive root only; it does not grant + directory listing or write access, or change descendant ACLs. + If wxc-exec starts but the agent exits with "wxc-exec stderr: Access is + denied." or exit code 1, check the probe warnings before changing host + ACLs; these errors alone do not identify missing host preparation. + For verification, other host prerequisites, and rollback, see: + https://github.com/microsoft/mxc/blob/main/docs/host-prep.md - Local demo: an Ollama-compatible service on 127.0.0.1:11434 by default. Override -OllamaHost, -OllamaPort, and -Model when needed. - Cloud demo: NV_API_KEY and outbound HTTPS to integrate.api.nvidia.com. diff --git a/docs/reference/gateway-config.mdx b/docs/reference/gateway-config.mdx index dce1b313a5..ab1702a896 100644 --- a/docs/reference/gateway-config.mdx +++ b/docs/reference/gateway-config.mdx @@ -933,6 +933,39 @@ mount setup to bypass that profile. The MXC driver is Windows-only and opt-in. It links into the gateway, invokes Microsoft MXC through `wxc-exec.exe`, and runs each sandbox's configured command in-driver instead of using the Linux sandbox supervisor. +#### Prepare the Windows host + +Copy `wxc-exec.exe` to a regular directory outside any installed MSIX or +`WindowsApps` package directory. A package directory's ACLs can prevent the +gateway from starting the executable outside its package context. If sandbox +creation fails with `wxc-exec spawn failed: Access is denied. (os error 5)`, +verify that `wxc_exec_path` points to the standalone copy. + +Before the first live `process_container` run, check the selected isolation +tier and host-preparation warnings in PowerShell: + +```shell +& "C:\path\to\wxc-exec.exe" --probe +``` + +If the probe selects AppContainer + DACL (`appcontainer-dacl`) and recommends +`prepare-system-drive`, obtain `wxc-host-prep.exe` from the MXC binaries +distribution and run this command once in an elevated PowerShell session. +BaseContainer and AppContainer + BFS do not require this preparation. + +```shell +& "C:\path\to\wxc-host-prep.exe" prepare-system-drive +``` + +This persistent, host-wide change adds non-inheriting ACL entries that give +the AppContainer well-known SIDs metadata access to the system-drive root. It +does not grant directory listing or write access, or change descendant ACLs. +If `wxc-exec.exe` starts but the agent exits with +`wxc-exec stderr: Access is denied.` or exit code 1, check the probe warnings +before changing host ACLs; these errors alone do not identify missing host +preparation. See Microsoft's [MXC host-preparation guide](https://github.com/microsoft/mxc/blob/main/docs/host-prep.md) +for verification, other host prerequisites, and rollback instructions. + ```toml [openshell] version = 1