Skip to content

Commit c6cde38

Browse files
committed
feat(mxc): add processContainer backend for default-deny enforcement
Add a backend selector to the MXC driver (isolation_session default | process_container). process_container drives a one-shot AppContainer that is genuinely default-deny: a write to any ungranted path is denied by the OS, unlike isolation_session which is grant-only and cannot deny. The lifecycle forks on the flag - isolation_session keeps provision/start/exec, process_container runs a single ephemeral container via run_oneshot. Also: run-demo.ps1 gains -Backend and hardens the CLI register/create calls; docs corrected to state isolation_session does NOT deny out-of-policy writes and that the negative proof requires process_container. Verified end-to-end on a real demo box (gateway -> CLI -> driver -> MXC): in-policy write succeeds, out-of-policy write denied (PermissionDenied), OVERALL: PASS.
1 parent 7d6cd71 commit c6cde38

7 files changed

Lines changed: 405 additions & 83 deletions

File tree

‎crates/openshell-driver-mxc/examples/mxc-demo-runbook.md‎

Lines changed: 48 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,20 @@ You are running this on the **demo Windows 11 host**. Everything in this folder
44
was built off-box; nothing here requires `cargo`/`rustc`/`mise`/Visual Studio
55
on the demo machine.
66

7-
The proof is **filesystem-policy enforcement**: an agent run by the MXC
8-
isolation-session driver writes `hello.txt` into a granted host folder
9-
(positive) and is denied a write to any other path (negative).
7+
The proof is **filesystem-policy enforcement**: an agent run by the MXC driver
8+
writes `hello.txt` into a granted host folder (positive) and is denied a write to
9+
any other path (negative).
10+
11+
> **Backend matters.** The driver has two backends, set by `backend` in
12+
> `mxc-gateway.toml` (or `run-demo.ps1 -Backend`):
13+
>
14+
> - **`process_container`** — one-shot AppContainer, **default-deny**. The
15+
> negative proof (out-of-policy write denied) only holds here. **Use this.**
16+
> - **`isolation_session`** (default) — persistent, but **grant-only / NOT
17+
> default-deny**: an out-of-policy write can still succeed. Good for the
18+
> positive proof and persistent-session demos; it cannot prove denial.
19+
>
20+
> This runbook's enforcement steps assume `backend = "process_container"`.
1021
1122
---
1223

@@ -95,6 +106,16 @@ binaries do not care about cwd.
95106

96107
(Double the backslashes — TOML.)
97108

109+
2a. **Select the backend** — in the same `[openshell.drivers.mxc]` table, for the
110+
default-deny enforcement proof:
111+
112+
```toml
113+
backend = "process_container"
114+
```
115+
116+
(Omit it, or set `isolation_session`, for the persistent grant-only backend.
117+
`run-demo.ps1 -Backend` patches this for you.)
118+
98119
3. **Environment variables for the demo session** (in the same shell you'll
99120
launch the gateway in):
100121

@@ -161,16 +182,19 @@ Once the one-time setup above is done and `wxc_exec_path` is set in
161182
`mxc-gateway.toml`, the whole test is a single command from the package folder:
162183

163184
```powershell
164-
powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1
185+
powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1 -Backend process_container
165186
```
166187

167-
It validates the artifacts, checks the port is free, stages `mxc-demo-agent.exe`
168-
into the share, starts the gateway, registers + selects the CLI gateway, creates
169-
the sandbox (which runs the test app inside), collects the verdict file, prints a
170-
deterministic **DEMO PASS / DEMO FAIL**, and stops the gateway. Exit code `0` ==
171-
PASS. Add `-KeepRunning` to leave the gateway up, or `-Mock` for an off-box
172-
plumbing smoke (the enforcement verdict is not asserted in mock — see the note in
173-
the script header). The manual walkthrough below is the same flow, broken out.
188+
It validates the artifacts, checks the port is free, patches the backend +
189+
`wxc_exec_path` into the toml, stages `mxc-demo-agent.exe` into the share, starts
190+
the gateway, registers + selects the CLI gateway, creates the sandbox (which runs
191+
the test app inside), collects the verdict file, prints a deterministic **DEMO
192+
PASS / DEMO FAIL**, and stops the gateway. Exit code `0` == PASS. Useful flags:
193+
`-Backend isolation_session|process_container` (default `isolation_session`; use
194+
`process_container` for the default-deny proof), `-KeepRunning` to leave the
195+
gateway up, `-Mock` for an off-box plumbing smoke (the enforcement verdict is not
196+
asserted in mock — see the note in the script header). The manual walkthrough
197+
below is the same flow, broken out.
174198

175199
### Recommended: single-run proof with the test app
176200

@@ -185,7 +209,8 @@ The test app:
185209
1. writes `hello.txt` into the granted share (in-policy write → succeeds),
186210
2. reads it back (in-policy read → succeeds),
187211
3. attempts a write to `C:/Windows/Temp/openshell-mxc-out-of-policy.txt`
188-
(out-of-policy → AppContainer denies it).
212+
(out-of-policy → under `process_container` the AppContainer denies it;
213+
under `isolation_session` it would succeed and the verdict would be FAIL).
189214

190215
It exits `0` only when all three behave correctly (so the sandbox self-reports
191216
`Ready`); if the out-of-policy write were ever allowed it exits non-zero and the
@@ -228,6 +253,11 @@ Expected:
228253

229254
### Negative proof — out-of-policy write is denied
230255

256+
> **Requires `backend = "process_container"`.** Under `isolation_session` this
257+
> write **succeeds** (grant-only backend, no deny primitive) and the sandbox
258+
> reaches Ready instead of erroring — that is the expected `isolation_session`
259+
> behavior, not a denial. Set `backend = "process_container"` for this proof.
260+
231261
Edit `mxc-gateway.toml` so `agent_command` targets an **out-of-policy** path,
232262
e.g.:
233263

@@ -294,7 +324,7 @@ session from the driver's registry. Confirm with `sandbox list`.
294324
| CLI: `register it first` / `gateway not found` | `openshell gateway add` step skipped, or `OPENSHELL_GATEWAY` env points at the wrong one. |
295325
| CLI: `Unauthenticated / missing principal` on a non-create RPC | Some CLI subcommands require client auth even when the gateway runs with `--disable-tls`. Use `delete` (works) instead of `get` for verification, or stand the gateway up with mTLS for the full surface. |
296326
| Positive proof: `hello.txt` not on host | `share_dir` / `agent_command` target path / `demo.yaml` `read_write` entry must be identical. Off-by-one slash = no file. |
297-
| Negative proof: the out-of-policy file exists | AppContainer share rules not applied — check the gateway log shows `readwritePaths` correctly mapped from `demo.yaml`; confirm `wxc-exec --features isolation_session` is what's installed. |
327+
| Negative proof: the out-of-policy file exists | Are you on `backend = "process_container"`? Under `isolation_session` the write is **expected** to succeed (grant-only, no default-deny). Switch to `process_container`. If already on it, check the gateway log shows `readwritePaths` mapped from `demo.yaml` and that an AppContainer isolation tier is available. |
298328
| `libz3.dll not found` when running the CLI | Make sure `libz3.dll` is in the same folder as `openshell.exe` (the package script puts it there). |
299329

300330
---
@@ -316,10 +346,11 @@ session needed) — these did not need this box:
316346
**Only this machine can prove (live)** — what the demo audience watches:
317347

318348
- Real `wxc-exec` provisioning a real AppContainer with the policy shares.
319-
- Real AppContainer **OS-enforced** denial of the out-of-policy write (the
320-
off-box harness simulates this; the demo box proves it).
321-
- `hello.txt` appearing on the host shared folder from inside the isolation
322-
session.
349+
- Real AppContainer **OS-enforced** default-deny of the out-of-policy write
350+
**under `process_container`** (the off-box harness simulates this; the demo box
351+
proves it). Note `isolation_session` does **not** deliver this — it is
352+
grant-only and the out-of-policy write succeeds there.
353+
- `hello.txt` appearing on the host shared folder from inside the sandbox.
323354

324355
Everything else this runbook walks through is mechanical — copy the package,
325356
run two binaries, observe the file.

‎crates/openshell-driver-mxc/examples/mxc-demo-test-instructions.md‎

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,34 @@
11
# OpenShell + MXC filesystem-policy demo — full test instructions
22

3-
**What this proves:** an agent run by the OpenShell MXC isolation-session driver can
4-
write to a host folder that policy **grants** (positive), and is **blocked** by the
5-
OS when it tries to write somewhere policy does **not** grant (negative).
3+
**What this proves:** an agent run by the OpenShell MXC driver can write to a host
4+
folder that policy **grants** (positive), and is **blocked** by the OS when it tries
5+
to write somewhere policy does **not** grant (negative).
6+
7+
## Pick a backend first (this matters)
8+
9+
The MXC driver supports two backends, selectable in `mxc-gateway.toml`
10+
(`backend = "..."`) or via `run-demo.ps1 -Backend`:
11+
12+
| Backend | Lifecycle | Filesystem enforcement |
13+
|---|---|---|
14+
| `process_container` | One-shot AppContainer (run agent, tear down) | **Default-deny.** A write to any ungranted path is denied by the OS. **Use this for the enforcement proof.** |
15+
| `isolation_session` (default) | Persistent, attachable session | **Grant-only — NOT default-deny.** Granted paths work, but a write to an *ungranted* path can still succeed. It has no deny primitive. |
16+
17+
> The negative (out-of-policy denied) proof **only holds under
18+
> `process_container`**. Under `isolation_session` the out-of-policy write will
19+
> typically *succeed* — that backend grants access but cannot deny it. Run the
20+
> demo with `-Backend process_container` for the real enforcement story.
621
722
## Machine requirements (the demo box)
823

9-
- Windows 11 Insider build **>= 26300.8553** (isolation_session gate)
24+
- Windows 11 Insider build **>= 26300.8553** (the `isolation_session` gate)
1025
- MXC installed with **`wxc-exec.exe`** (we used `C:\mxc\wxc-exec.exe`) and
1126
**`IsoSessionApp.dll`** registered
1227
- A writable host folder for the share
28+
- For **`process_container`**: one AppContainer isolation tier must be available
29+
(the BaseContainer API, **or** `bfscfg.exe`, **or** `WRITE_DAC` +
30+
`fallback.allowDaclMutation`). If `wxc-exec` exits non-zero with a tier/fallback
31+
error, that's a machine gap, not a driver bug.
1332

1433
## 0. (Optional) verify the box is capable
1534

@@ -90,17 +109,19 @@ correctly. There are two ways to run the same test.
90109

91110
### Option A (recommended) — one command
92111

93-
From the package folder:
112+
From the package folder, driving the default-deny backend:
94113

95114
```powershell
96-
powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1
115+
powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1 -Backend process_container
97116
```
98117

99-
This validates the artifacts, checks the port is free, sets `wxc_exec_path`,
100-
stages the test app, starts the gateway, registers + selects the CLI gateway,
101-
creates the sandbox, collects the verdict, prints **DEMO PASS / DEMO FAIL**
102-
(exit code `0` == PASS), and stops the gateway. Useful flags:
118+
This validates the artifacts, checks the port is free, patches the backend +
119+
`wxc_exec_path` into the toml, stages the test app, starts the gateway, registers
120+
+ selects the CLI gateway, creates the sandbox, collects the verdict, prints
121+
**DEMO PASS / DEMO FAIL** (exit code `0` == PASS), and stops the gateway. Useful
122+
flags:
103123

124+
- `-Backend isolation_session|process_container` — which backend to drive. Default is `isolation_session`; pass `process_container` for the default-deny enforcement proof.
104125
- `-WxcExecPath <path>` — if `wxc-exec` isn't at `C:\mxc\wxc-exec.exe`.
105126
- `-KeepRunning` — leave the gateway up for inspection.
106127
- `-Mock` — off-box plumbing smoke (no real session; the enforcement verdict is **not** asserted).
@@ -110,6 +131,13 @@ deleted the sandbox and stopped the gateway).
110131

111132
### Option B — manual steps
112133

134+
First choose the backend in `mxc-gateway.toml` (under `[openshell.drivers.mxc]`):
135+
136+
```toml
137+
backend = "process_container" # default-deny enforcement (recommended for the proof)
138+
# backend = "isolation_session" # persistent, grant-only (the default if omitted)
139+
```
140+
113141
**Window 1 — start the gateway:**
114142

115143
```powershell
@@ -140,10 +168,13 @@ $env:OPENSHELL_GATEWAY = ""
140168
141169
(If `gateway add` says it already exists, skip it and just run `gateway select`.)
142170

143-
A live MXC session window appears (`RDP desktop ready`, `Session started successfully`).
144-
In Window 1 you should see the lifecycle:
171+
In Window 1 you should see, depending on the backend:
145172

146173
```
174+
# process_container (one-shot): no provision/start phases
175+
MXC agent launched ... backend=ProcessContainer -> phase Ready
176+
177+
# isolation_session (persistent):
147178
MXC provisioned -> MXC started -> MXC agent exec launched -> phase Ready -> MXC agent exec completed successfully
148179
```
149180

‎crates/openshell-driver-mxc/examples/mxc-gateway.toml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,18 @@
2222
# for mock-mode smoke tests (set OPENSHELL_MXC_MOCK_WXC=1 instead).
2323
# wxc_exec_path = "C:\\mxc\\wxc-exec.exe"
2424

25+
# Backend to target:
26+
# "isolation_session" (default) - persistent session; grant-only filesystem
27+
# policy (NO default-deny: a write to an ungranted path may still succeed).
28+
# "process_container" - one-shot AppContainer; genuinely default-deny (a write
29+
# to any ungranted path is denied by the OS). No persistent session.
30+
# backend = "process_container"
31+
32+
# process_container only: request a Less-Privileged AppContainer (stricter).
33+
# pc_least_privilege = false
34+
# process_container only: AppContainer capabilities to grant (e.g. internetClient).
35+
# pc_capabilities = []
36+
2537
# MXC configurationId for isolation session. Never use "small" (known OS bug).
2638
default_configuration_id = "composable"
2739

‎crates/openshell-driver-mxc/examples/run-demo.ps1‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@
1313
#
1414
# powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1
1515
#
16+
# Default backend is isolation_session (persistent, grant-only - NOT default-deny).
17+
# For genuine OS-enforced default-deny (out-of-policy writes blocked even to paths
18+
# with no host ACL lockdown), drive the one-shot AppContainer backend:
19+
#
20+
# powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1 -Backend process_container
21+
#
1622
# Off-box plumbing smoke (no real wxc-exec / isolation session):
1723
#
1824
# powershell -NoProfile -ExecutionPolicy Bypass -File .\run-demo.ps1 -Mock
@@ -31,6 +37,11 @@ param(
3137
[string] $OutOfPolicy = "C:\Windows\Temp\openshell-mxc-out-of-policy.txt",
3238
# Real wxc-exec on the demo box (ignored in -Mock).
3339
[string] $WxcExecPath = "C:\mxc\wxc-exec.exe",
40+
# MXC backend to drive:
41+
# isolation_session - persistent session; grant-only (NOT default-deny).
42+
# process_container - one-shot AppContainer; genuine default-deny.
43+
[ValidateSet("isolation_session", "process_container")]
44+
[string] $Backend = "isolation_session",
3445
# Gateway bind port (matches the gateway default).
3546
[int] $Port = 17670,
3647
# Name the CLI registers the gateway under.
@@ -75,7 +86,23 @@ foreach ($f in @($gateway, $cli, $agent, $policy, $toml)) {
7586

7687
# 2. Mode / pre-flight
7788
$mode = if ($Mock) { "MOCK" } else { "REAL" }
78-
Step "Pre-flight ($mode mode)"
89+
Step "Pre-flight ($mode mode, backend=$Backend)"
90+
91+
# Patch the backend selector into the packaged TOML (this disposable copy only).
92+
# Applies in both modes - the driver branches on backend even under the mock.
93+
$tomlText = Get-Content $toml -Raw
94+
$backendLine = "backend = `"$Backend`""
95+
if ($tomlText -match '(?m)^\s*#?\s*backend\s*=') {
96+
$tomlText = [regex]::Replace($tomlText, '(?m)^\s*#?\s*backend\s*=.*$', $backendLine)
97+
} else {
98+
$tomlText = [regex]::Replace($tomlText, '(?m)^\[openshell\.drivers\.mxc\]\s*$', "[openshell.drivers.mxc]`r`n$backendLine")
99+
}
100+
Set-Content $toml -Value $tomlText -Encoding UTF8
101+
Info "set backend=$Backend in $(Split-Path $toml -Leaf)"
102+
if ($Backend -eq "process_container") {
103+
Info "process_container: one-shot AppContainer per run; out-of-policy writes are denied by default (no host ACLs needed)"
104+
}
105+
79106
if ($Mock) {
80107
$env:OPENSHELL_MXC_MOCK_WXC = "1"
81108
Info "OPENSHELL_MXC_MOCK_WXC=1 - no real wxc-exec / isolation session"
@@ -150,13 +177,18 @@ try {
150177
$env:OPENSHELL_GATEWAY = ""
151178
try { & $cli gateway add "http://127.0.0.1:$Port" --local --name $GatewayName 2>&1 | ForEach-Object { Info $_ } }
152179
catch { Info "gateway add: $($_.Exception.Message) (continuing - likely already registered)" }
153-
& $cli gateway select $GatewayName 2>&1 | ForEach-Object { Info $_ }
180+
# The CLI writes its success checkmark to stderr; don't let that abort the run.
181+
try { & $cli gateway select $GatewayName 2>&1 | ForEach-Object { Info $_ } }
182+
catch { Info "gateway select: $($_.Exception.Message) (continuing)" }
154183
Ok "selected gateway '$GatewayName'"
155184

156185
# 9. Create the sandbox (runs mxc-demo-agent.exe inside)
157186
Step "Create sandbox (runs mxc-demo-agent inside)"
158-
& $cli sandbox create --name demo --policy $policy --no-tty -- exit 2>&1 | ForEach-Object { Info $_ }
159-
Info "(a post-create interactive-attach error e.g. 'supervisor session not connected' / ssh 255 is expected and harmless)"
187+
# The post-create interactive-attach failure (no in-sandbox supervisor on MXC:
188+
# 'supervisor session not connected' / ssh 255) is EXPECTED and harmless - the
189+
# agent already ran in the driver. Swallow it so we always reach verdict collection.
190+
try { & $cli sandbox create --name demo --policy $policy --no-tty -- exit 2>&1 | ForEach-Object { Info $_ } }
191+
catch { Info "sandbox create attach: $($_.Exception.Message) (expected on MXC - agent ran in-driver; continuing)" }
160192

161193
# 10. Collect the verdict
162194
Step "Collect verdict"

0 commit comments

Comments
 (0)