You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c6cde38
Browse filesBrowse the repository at this point in the historyBrowse files
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.
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.
174
198
175
199
### Recommended: single-run proof with the test app
176
200
@@ -185,7 +209,8 @@ The test app:
185
209
1. writes `hello.txt` into the granted share (in-policy write → succeeds),
186
210
2. reads it back (in-policy read → succeeds),
187
211
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).
189
214
190
215
It exits `0` only when all three behave correctly (so the sandbox self-reports
191
216
`Ready`); if the out-of-policy write were ever allowed it exits non-zero and the
@@ -228,6 +253,11 @@ Expected:
228
253
229
254
### Negative proof — out-of-policy write is denied
230
255
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
+
231
261
Edit `mxc-gateway.toml` so `agent_command` targets an **out-of-policy** path,
232
262
e.g.:
233
263
@@ -294,7 +324,7 @@ session from the driver's registry. Confirm with `sandbox list`.
294
324
| CLI: `register it first` / `gateway not found`|`openshell gateway add` step skipped, or `OPENSHELL_GATEWAY` env points at the wrong one. |
295
325
| 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. |
296
326
| 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. |
298
328
|`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). |
299
329
300
330
---
@@ -316,10 +346,11 @@ session needed) — these did not need this box:
316
346
**Only this machine can prove (live)** — what the demo audience watches:
317
347
318
348
- 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.
323
354
324
355
Everything else this runbook walks through is mechanical — copy the package,
Copy file name to clipboardExpand all lines: crates/openshell-driver-mxc/examples/mxc-demo-test-instructions.md
+43-12Lines changed: 43 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,34 @@
1
1
# OpenShell + MXC filesystem-policy demo — full test instructions
2
2
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.
6
21
7
22
## Machine requirements (the demo box)
8
23
9
-
- Windows 11 Insider build **>= 26300.8553** (isolation_session gate)
24
+
- Windows 11 Insider build **>= 26300.8553** (the `isolation_session` gate)
10
25
- MXC installed with **`wxc-exec.exe`** (we used `C:\mxc\wxc-exec.exe`) and
11
26
**`IsoSessionApp.dll`** registered
12
27
- 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.
13
32
14
33
## 0. (Optional) verify the box is capable
15
34
@@ -90,17 +109,19 @@ correctly. There are two ways to run the same test.
90
109
91
110
### Option A (recommended) — one command
92
111
93
-
From the package folder:
112
+
From the package folder, driving the default-deny backend:
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:
103
123
124
+
-`-Backend isolation_session|process_container` — which backend to drive. Default is `isolation_session`; pass `process_container` for the default-deny enforcement proof.
104
125
-`-WxcExecPath <path>` — if `wxc-exec` isn't at `C:\mxc\wxc-exec.exe`.
105
126
-`-KeepRunning` — leave the gateway up for inspection.
106
127
-`-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).
110
131
111
132
### Option B — manual steps
112
133
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
+
113
141
**Window 1 — start the gateway:**
114
142
115
143
```powershell
@@ -140,10 +168,13 @@ $env:OPENSHELL_GATEWAY = ""
140
168
141
169
(If `gateway add` says it already exists, skip it and just run `gateway select`.)
142
170
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:
145
172
146
173
```
174
+
# process_container (one-shot): no provision/start phases
0 commit comments