Fix fixture mouse integration and capture clean USB-tablet baseline

This commit is contained in:
cabbage committed 2026-10-08 09:36:13 +00:00
1 parent 6ccaaae3c7
commit 90d6b05f4d
10 files changed
+424 -43

No files matched your search

+23 -7
View File
@@ -846,13 +846,13 @@ mirror; update both documents when the fixture is reprovisioned.
| Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) | | Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) |
| Resources | 2 vCPU, 4096 MiB RAM, 64 MiB VRAM, `VBoxSVGA`, 3D acceleration disabled, 40 GiB dynamically allocated VDI | | Resources | 2 vCPU, 4096 MiB RAM, 64 MiB VRAM, `VBoxSVGA`, 3D acceleration disabled, 40 GiB dynamically allocated VDI |
| Disk / source media | `/home/cabbage/VMs/rvbox-win10-test.vdi`; source ISO `/media/Data2/Downloaded/Win10_22H2_English_x64.iso` (Windows image index 6) | | Disk / source media | `/home/cabbage/VMs/rvbox-win10-test.vdi`; source ISO `/media/Data2/Downloaded/Win10_22H2_English_x64.iso` (Windows image index 6) |
| Devices | Audio (`none`), playback/capture, USB (OHCI/EHCI/xHCI), clipboard/file transfer, drag-and-drop, and shared folders disabled; Intel 82540EM NIC, cable connected | | Devices | Audio (`none`), playback/capture, clipboard/file transfer, drag-and-drop, and shared folders disabled; OHCI enabled for the standard USB tablet, EHCI/xHCI disabled, no USB passthrough filters, PS/2 keyboard unchanged; Windows mouse-class `UpperFilters = mouclass`, `VBoxMouse` detached/stopped, standard `mouclass`/`mouhid` drivers active; Intel 82540EM NIC, cable connected |
| Network | NAT; last observed guest IPv4 `10.0.2.15` is DHCP state only; NAT rule `rvbox-rdp` maps host `192.168.50.162:3390` to guest `:3389` | | Network | NAT; last observed guest IPv4 `10.0.2.15` is DHCP state only; NAT rule `rvbox-rdp` maps host `192.168.50.162:3390` to guest `:3389` |
| Diagnostic VRDE | Enabled only on Helium loopback at `127.0.0.1:3389`, external/`VBoxAuthSimple` authentication, input/display enabled, audio/USB/clipboard/RDPDR disabled; reach it only through an explicitly temporary, private SSH forward, and treat it as diagnostic-only because client compatibility is unreliable | | Diagnostic VRDE | Enabled only on Helium loopback at `127.0.0.1:3389`, external/`VBoxAuthSimple` authentication, input/display enabled, audio/USB/clipboard/RDPDR disabled; reach it only through an explicitly temporary, private SSH forward, and treat it as diagnostic-only because client compatibility is unreliable |
| Native Windows RDP | Disabled in baseline (`TermService` stopped, `fDenyTSConnections=1`); port 3390 must not be treated as a usable control endpoint | | Native Windows RDP | Disabled in baseline (`TermService` stopped, `fDenyTSConnections=1`); port 3390 must not be treated as a usable control endpoint |
| Test account | Local `rvboxtest`; split-token local administrator; console session 1 observed; Guest Control verified with `whoami`, `whoami /groups`, and `query user` | | Test account | Local `rvboxtest`; split-token local administrator; console session 1 observed; Guest Control verified with `whoami`, `whoami /groups`, and `query user` |
| Baseline | Reset target `baseline-clean-python-ready` (UUID `dfadee95-156f-43ee-bdab-a10a44be4070`): no RVBox service, tray registration, state, logs, or staged binary; built-in `Administrator` is enabled only for the fixture's high-token Guest Control installation path; all-users Python 3.13.16 amd64, pip, venv and launcher installed at `C:\Python313` on machine PATH; pending Windows servicing restart completed before final capture. Retain the initial Python snapshot `baseline-clean-python` (UUID `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89`), pre-Python parent `baseline-clean-administrator` (UUID `ba5ce5f1-77e3-44b0-8d91-534becce27ff`), `baseline-clean` (UUID `5e79176a-3e56-4c5d-bb61-a405a6dcdd59`) and `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`) as diagnostics. | | Baseline | Reset target `baseline-clean-python-usb-ready` (UUID `a4851b6a-24d6-42f8-96c2-ff9f554c9198`): no RVBox service, tray registration, state, logs, or staged binary; built-in `Administrator` is enabled only for the fixture's high-token Guest Control installation path; all-users Python 3.13.16 amd64, pip, venv and launcher installed at `C:\Python313` on machine PATH; pending Windows servicing restart completed; USB tablet and standard Windows mouse drivers, unnecessary `VBoxMouse` filter detached, with a small rollback record preserved. Retain the Python/servicing-ready parent `baseline-clean-python-ready` (UUID `dfadee95-156f-43ee-bdab-a10a44be4070`), initial Python snapshot `baseline-clean-python` (UUID `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89`), pre-Python parent `baseline-clean-administrator` (UUID `ba5ce5f1-77e3-44b0-8d91-534becce27ff`), `baseline-clean` (UUID `5e79176a-3e56-4c5d-bb61-a405a6dcdd59`) and `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`) as diagnostics. |
| Last checked state | Clean powered-off snapshot captured 2026-10-08, then restored/boot-verified and left running for interactive access; current snapshot `baseline-clean-python-ready`; restore that reset target before native runs, and leave it selected/powered off after normal test cleanup | | Last checked state | Clean powered-off snapshot captured 2026-10-08, then restored/boot-verified and left running for interactive access; current snapshot `baseline-clean-python-usb-ready`; restore that reset target before native runs, and leave it selected/powered off after normal test cleanup |
Python is a baseline fixture dependency, not a production RVBox dependency or Python is a baseline fixture dependency, not a production RVBox dependency or
per-run bootstrap. The repeatable `test-host provision-python` and per-run bootstrap. The repeatable `test-host provision-python` and
@@ -865,6 +865,22 @@ verification. Direct Helium download is the default; the metered SOCKS route
requires an explicit `RVBOX_TEST_PYTHON_DOWNLOAD_PROXY`. A new capture's UUID requires an explicit `RVBOX_TEST_PYTHON_DOWNLOAD_PROXY`. A new capture's UUID
must replace the controller defaults and document mirrors before another run. must replace the controller defaults and document mirrors before another run.
The diagnostic input path uses the standard USB tablet and Windows
`mouclass`/`mouhid` drivers, not the unnecessary Guest Additions `VBoxMouse`
class filter. On this fixture the integration path lost button transitions
while still moving the pointer. Backed-up detachment followed by a normal
Windows restart passed ten controlled clicks; fresh baseline restore verifies
the detached/stopped filter, healthy devices, Python on machine PATH and no
RVBox installation. `prepare` must fail if the unwanted filter or unhealthy
input returns. The explicit `mouse-status`, `mouse-verify`, `mouse-bypass` and
`mouse-restore` actions preserve the original ordered `REG_MULTI_SZ` filter list,
keep `mouclass` and unrelated filters, restart only mouse devices, report reboot
requirements without automatically rebooting, and refuse unrelated filter
drift. Baseline capture preserves that rollback record. See
[RDP input recovery](../test/rdp-access/README.md#opt-in-mouse-filter-workaround-and-rollback)
for exact use and the interactive Windows button-state/dialog probe; no RVBox
production code or elevation-hierarchy behavior is changed by this fixture fix.
The isolated disposable fixture deliberately uses one fixed test-only password The isolated disposable fixture deliberately uses one fixed test-only password
for both local test accounts, `rvboxtest` and `Administrator`. Its value is for both local test accounts, `rvboxtest` and `Administrator`. Its value is
provisioned only in the mode-600 Helium host file and is never committed; the provisioned only in the mode-600 Helium host file and is never committed; the
@@ -951,8 +967,8 @@ identity in the run manifest:
```sh ```sh
export RVBOX_TEST_VBOX_HOST=helium-remote export RVBOX_TEST_VBOX_HOST=helium-remote
export RVBOX_TEST_VBOX_VM=rvbox-win10-test export RVBOX_TEST_VBOX_VM=rvbox-win10-test
export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-ready export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-usb-ready
export RVBOX_TEST_VBOX_SNAPSHOT_UUID=dfadee95-156f-43ee-bdab-a10a44be4070 export RVBOX_TEST_VBOX_SNAPSHOT_UUID=a4851b6a-24d6-42f8-96c2-ff9f554c9198
export RVBOX_TEST_GUEST_USER=rvboxtest export RVBOX_TEST_GUEST_USER=rvboxtest
export RVBOX_TEST_GUEST_PASSWORD_FILE=/secure/outside-repo/rvbox-win10-test.password export RVBOX_TEST_GUEST_PASSWORD_FILE=/secure/outside-repo/rvbox-win10-test.password
``` ```
@@ -971,7 +987,7 @@ ssh "$RVBOX_TEST_VBOX_HOST" \
# Restore only while powered off, then boot without a GUI. # Restore only while powered off, then boot without a GUI.
ssh "$RVBOX_TEST_VBOX_HOST" \ ssh "$RVBOX_TEST_VBOX_HOST" \
'VBoxManage snapshot "rvbox-win10-test" restore "baseline-clean-python-ready"' 'VBoxManage snapshot "rvbox-win10-test" restore "baseline-clean-python-usb-ready"'
ssh "$RVBOX_TEST_VBOX_HOST" \ ssh "$RVBOX_TEST_VBOX_HOST" \
'VBoxManage startvm "rvbox-win10-test" --type headless' 'VBoxManage startvm "rvbox-win10-test" --type headless'
@@ -1019,7 +1035,7 @@ Use this shutdown/reset sequence for every native run:
acpipowerbutton` and poll. Use `controlvm ... poweroff` only for a hung, acpipowerbutton` and poll. Use `controlvm ... poweroff` only for a hung,
disposable test; it intentionally loses guest state. disposable test; it intentionally loses guest state.
3. Collect diagnostics while the VM is still available, then restore 3. Collect diagnostics while the VM is still available, then restore
`baseline-clean-python-ready` and verify the snapshot UUID/current marker. `baseline-clean-python-usb-ready` and verify the snapshot UUID/current marker.
4. Leave the VM powered off after cleanup. Never delete any baseline 4. Leave the VM powered off after cleanup. Never delete any baseline
snapshot, unregister the VM, or modify `win10_dev` (that name refers to a snapshot, unregister the VM, or modify `win10_dev` (that name refers to a
stale unregistered configuration with a missing disk on this host). stale unregistered configuration with a missing disk on this host).
+27 -16
View File
@@ -6,7 +6,7 @@ Windows release matrix. Keep the values here in sync with the VM before adding
or changing native test automation. or changing native test automation.
Last configuration check: 2026-10-08 UTC. A powered-off clean Last configuration check: 2026-10-08 UTC. A powered-off clean
`baseline-clean-python-ready` snapshot was captured, restored, and boot-verified. `baseline-clean-python-usb-ready` snapshot was captured, restored, and boot-verified.
The native harness targets that snapshot; The native harness targets that snapshot;
the fixture is ready for native runs. A test run must still perform its own identity, the fixture is ready for native runs. A test run must still perform its own identity,
snapshot, readiness, and exclusive-lease checks rather than relying on that snapshot, readiness, and exclusive-lease checks rather than relying on that
@@ -27,7 +27,7 @@ observation.
| Guest OS | Windows 10 Pro 22H2, build `19045.6456` verified after the baseline's pending Windows servicing restart; en-US, BIOS boot (original install build `19045.2006`) | | Guest OS | Windows 10 Pro 22H2, build `19045.6456` verified after the baseline's pending Windows servicing restart; en-US, BIOS boot (original install build `19045.2006`) |
| Guest account | Local `rvboxtest`; split-token local administrator; console session 1 was observed during provisioning | | Guest account | Local `rvboxtest`; split-token local administrator; console session 1 was observed during provisioning |
| Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) | | Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) |
| Last observed state | `running` for interactive access; current snapshot `baseline-clean-python-ready`, the reset target for native runs; verify live state and lease before mutations | | Last observed state | `running` for interactive access; current snapshot `baseline-clean-python-usb-ready`, the reset target for native runs; verify live state and lease before mutations |
| Baseline Python | Python `3.13.16` amd64 at `C:\Python313`; machine PATH, `py` launcher, bundled pip and venv; no third-party packages | | Baseline Python | Python `3.13.16` amd64 at `C:\Python313`; machine PATH, `py` launcher, bundled pip and venv; no third-party packages |
The two fixture accounts deliberately share one fixed test-only password for The two fixture accounts deliberately share one fixed test-only password for
@@ -56,7 +56,7 @@ remain private and are not part of this test-only credential exception.
| System disk | 40 GiB dynamically allocated VDI; logical base path `/home/cabbage/VMs/rvbox-win10-test.vdi`; active snapshot differencing disks live under the snapshot folder above | | System disk | 40 GiB dynamically allocated VDI; logical base path `/home/cabbage/VMs/rvbox-win10-test.vdi`; active snapshot differencing disks live under the snapshot folder above |
| Install media | `/media/Data2/Downloaded/Win10_22H2_English_x64.iso`, Windows image index 6 | | Install media | `/media/Data2/Downloaded/Win10_22H2_English_x64.iso`, Windows image index 6 |
| Audio | Virtual audio disabled (`audio=none`, playback and capture off) | | Audio | Virtual audio disabled (`audio=none`, playback and capture off) |
| USB | OHCI, EHCI, and xHCI disabled; no USB filters | | USB / input | OHCI enabled; EHCI and xHCI disabled; USB tablet, PS/2 keyboard, no USB passthrough filters; Windows mouse-class `UpperFilters = mouclass`, `VBoxMouse` detached/stopped, standard `mouclass`/`mouhid` drivers active |
| Clipboard / drag and drop | Disabled, including clipboard file transfers | | Clipboard / drag and drop | Disabled, including clipboard file transfers |
| Network adapter | One Intel 82540EM adapter, cable connected, NAT attachment; MAC `080027036E7C` | | Network adapter | One Intel 82540EM adapter, cable connected, NAT attachment; MAC `080027036E7C` |
| Shared folders | None; there is no shared-folder contract for tests | | Shared folders | None; there is no shared-folder contract for tests |
@@ -75,7 +75,7 @@ hard-coded into a harness.
| --- | --- | | --- | --- |
| Host management | SSH to `helium-remote`, then invoke `VBoxManage`; do not assume `VBoxManage` is installed on the Linux controller | | Host management | SSH to `helium-remote`, then invoke `VBoxManage`; do not assume `VBoxManage` is installed on the Linux controller |
| Guest management | VirtualBox Guest Control over the host; use explicit executable/argument vectors and the password file above | | Guest management | VirtualBox Guest Control over the host; use explicit executable/argument vectors and the password file above |
| VRDE (VirtualBox RDP) | Enabled for diagnostics on Helium loopback at `127.0.0.1:3389`; external authentication, `VBoxAuthSimple` user `rvboxtest`, `Security/Method=negotiate`, single connection reuse, multiconnection off. Reach it only through an explicitly temporary, private SSH forward. | | VRDE (VirtualBox RDP) | Enabled for diagnostics on Helium loopback at `127.0.0.1:3389`; external authentication, `VBoxAuthSimple` user `rvboxtest`, `Security/Method=RDP`, single connection only, multiconnection and connection reuse off. Reach it only through an explicitly temporary, private SSH forward. |
| VRDE TLS material | Auto-generated certificate and private key under `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/`; keep both on Helium and do not copy them into the repository or test artifacts | | VRDE TLS material | Auto-generated certificate and private key under `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/`; keep both on Helium and do not copy them into the repository or test artifacts |
| VRDE channels | Input/display enabled; audio, upstream audio, USB, clipboard, and RDP device redirection disabled; no video channel | | VRDE channels | Input/display enabled; audio, upstream audio, USB, clipboard, and RDP device redirection disabled; no video channel |
| Native Windows RDP forward | NAT rule `rvbox-rdp`: host `192.168.50.162:3390` to guest port `3389` | | Native Windows RDP forward | NAT rule `rvbox-rdp`: host `192.168.50.162:3390` to guest port `3389` |
@@ -103,14 +103,16 @@ copy/paste example and explains the native-host lease boundary.
## Snapshots and reset contract ## Snapshots and reset contract
Five snapshots are retained. `baseline-clean-python-ready` Six snapshots are retained. `baseline-clean-python-usb-ready`
is the only reset target: it contains no `RVBoxClient` SCM service, RVBox tray is the only reset target: it contains no `RVBoxClient` SCM service, RVBox tray
Run-key registration, RVBox state, logs, or staged binaries; it also has the Run-key registration, RVBox state, logs, or staged binaries; it also has the
fixture-only built-in `Administrator` account enabled for high-token Guest fixture-only built-in `Administrator` account enabled for high-token Guest
Control installation, plus Python, pip, and venv for repeatable interactive tests. Control installation, plus Python, pip, and venv for repeatable interactive tests.
It is a powered-off descendant of `baseline-clean-administrator`, captured after It is a powered-off descendant of `baseline-clean-python-ready`, with a standard
the first Python snapshot's pending Windows servicing restart completed; the USB tablet and the unnecessary `VBoxMouse` class filter detached. The prior
original parent and both older diagnostic snapshots remain unchanged. baseline had already completed the initial Python capture's Windows servicing
restart. Every older snapshot is retained unchanged. The canonical baseline
contains the small mouse-filter rollback record, not an installed RVBox client.
| Snapshot | UUID | Description | | Snapshot | UUID | Description |
| --- | --- | --- | | --- | --- | --- |
@@ -118,23 +120,29 @@ original parent and both older diagnostic snapshots remain unchanged.
| `baseline-disk-first` | `9430a9a4-754a-4b22-beaa-8dfd90043f5b` | `baseline-windows10-pro-22h2-disk-first`; retained diagnostic snapshot | | `baseline-disk-first` | `9430a9a4-754a-4b22-beaa-8dfd90043f5b` | `baseline-windows10-pro-22h2-disk-first`; retained diagnostic snapshot |
| `baseline-clean-administrator` | `ba5ce5f1-77e3-44b0-8d91-534becce27ff` | `baseline-windows10-pro-22h2-administrator-enabled-full-token`; retained pre-Python parent | | `baseline-clean-administrator` | `ba5ce5f1-77e3-44b0-8d91-534becce27ff` | `baseline-windows10-pro-22h2-administrator-enabled-full-token`; retained pre-Python parent |
| `baseline-clean-python` | `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89` | Retained initial Python capture, before its first-restore Windows servicing restart completed; diagnostic only | | `baseline-clean-python` | `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89` | Retained initial Python capture, before its first-restore Windows servicing restart completed; diagnostic only |
| `baseline-clean-python-ready` | `dfadee95-156f-43ee-bdab-a10a44be4070` | Clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64, pip and venv; no RVBox installation or pending Windows servicing reboot; current reset target | | `baseline-clean-python-ready` | `dfadee95-156f-43ee-bdab-a10a44be4070` | Retained clean Python/servicing-ready parent; still has the original mouse-integration filter; diagnostic only |
| `baseline-clean-python-usb-ready` | `a4851b6a-24d6-42f8-96c2-ff9f554c9198` | Current reset target: clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64 on machine PATH, pip and venv; USB tablet and standard drivers, `VBoxMouse` detached; no RVBox installation or pending Windows servicing reboot |
Restore only while the VM is powered off. Every destructive or potentially Restore only while the VM is powered off. Every destructive or potentially
stateful run must: stateful run must:
1. Acquire the run lease and verify the VM name, UUID, and snapshot UUID. 1. Acquire the run lease and verify the VM name, UUID, and snapshot UUID.
2. Restore `baseline-clean-python-ready` if the current state is not the baseline. 2. Restore `baseline-clean-python-usb-ready` if the current state is not the baseline;
normalize OHCI/USB-tablet and VRDE input settings before boot.
3. Start headless and wait for `VMState=running` plus Guest Additions readiness 3. Start headless and wait for `VMState=running` plus Guest Additions readiness
(bounded 240-second window for cold boots/servicing restarts). (bounded 240-second window for cold boots/servicing restarts).
4. Apply the disposable display/sleep keepalive (`monitor-timeout`, standby, 4. Apply the disposable display/sleep keepalive (`monitor-timeout`, standby,
and hibernate timers set to zero) so VirtualBox VRDE cannot expose a and hibernate timers set to zero) so VirtualBox VRDE cannot expose a
zero-bpp framebuffer after Windows idle timeout. This is recorded as zero-bpp framebuffer after Windows idle timeout. This is recorded as
`prepare-display-keepalive` and is reapplied after every snapshot restore. `prepare-display-keepalive` and is reapplied after every snapshot restore.
Require healthy standard mouse drivers and USB input, with `VBoxMouse`
absent from the class filter and stopped; `prepare-usb-mouse-verified` records
that check. A regression fails preparation instead of silently reviving the
broken path. See the reversible [mouse-filter recovery](../test/rdp-access/README.md#opt-in-mouse-filter-workaround-and-rollback).
5. Run the bounded test, collect redacted artifacts, and close every Guest 5. Run the bounded test, collect redacted artifacts, and close every Guest
Control process that was opened by the run. Control process that was opened by the run.
6. Request a graceful guest shutdown and wait for `VMState=poweroff`. 6. Request a graceful guest shutdown and wait for `VMState=poweroff`.
7. Restore `baseline-clean-python-ready` again and leave the VM powered off. 7. Restore `baseline-clean-python-usb-ready` again and leave the VM powered off.
Use `controlvm ... poweroff` only for a hung, disposable test; it can lose Use `controlvm ... poweroff` only for a hung, disposable test; it can lose
guest state. Never delete any clean snapshot, unregister the VM, or alter guest state. Never delete any clean snapshot, unregister the VM, or alter
@@ -144,7 +152,7 @@ the stale unregistered `win10_dev` configuration (its disk is missing).
### Python-enabled baseline ### Python-enabled baseline
Python is part of `baseline-clean-python-ready`, not a per-run installation. Every Python is part of `baseline-clean-python-usb-ready`, not a per-run installation. Every
normal `test-host prepare`/`reset` restores it together with the clean Windows normal `test-host prepare`/`reset` restores it together with the clean Windows
fixture. No Python installer, bootstrap script, verification venv, or RVBox fixture. No Python installer, bootstrap script, verification venv, or RVBox
installation is retained in that snapshot. Both accounts can run `python`, installation is retained in that snapshot. Both accounts can run `python`,
@@ -194,8 +202,11 @@ and successful venv creation with bundled pip under both Administrator and
`rvboxtest`. Capture additionally refuses an installed RVBox service, normal `rvboxtest`. Capture additionally refuses an installed RVBox service, normal
installation/state directories, or tray Run-key registration; requires no installation/state directories, or tray Run-key registration; requires no
logged-on provisioning Administrator and no Windows servicing reboot pending; logged-on provisioning Administrator and no Windows servicing reboot pending;
deletes only `C:\ProgramData\RVBoxFixture` requires the healthy USB-tablet path with `VBoxMouse` detached/stopped; removes
bootstrap data; requests graceful shutdown; and takes a **powered-off** snapshot. only the owned Python installer staging directory and bootstrap scripts (not
the mouse-filter rollback record); requests graceful shutdown; and takes a
**powered-off** snapshot. Its verification script is staged afresh, so capture
does not require reinstalling Python in an already Python-enabled fixture.
It prints the new snapshot name and UUID and releases the lease. It never It prints the new snapshot name and UUID and releases the lease. It never
forces shutdown just to obtain a baseline and never blindly retries capture. forces shutdown just to obtain a baseline and never blindly retries capture.
@@ -241,8 +252,8 @@ The adapter takes identity and credentials only from its environment:
export RVBOX_TEST_VBOX_HOST=helium-remote export RVBOX_TEST_VBOX_HOST=helium-remote
export RVBOX_TEST_VBOX_VM=rvbox-win10-test export RVBOX_TEST_VBOX_VM=rvbox-win10-test
export RVBOX_TEST_VBOX_VM_UUID=6cdc114f-71e5-4167-a394-e922e14e6f5c export RVBOX_TEST_VBOX_VM_UUID=6cdc114f-71e5-4167-a394-e922e14e6f5c
export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-ready export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-usb-ready
export RVBOX_TEST_VBOX_SNAPSHOT_UUID=dfadee95-156f-43ee-bdab-a10a44be4070 export RVBOX_TEST_VBOX_SNAPSHOT_UUID=a4851b6a-24d6-42f8-96c2-ff9f554c9198
export RVBOX_TEST_GUEST_USER=rvboxtest export RVBOX_TEST_GUEST_USER=rvboxtest
export RVBOX_TEST_GUEST_PASSWORD_FILE=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password export RVBOX_TEST_GUEST_PASSWORD_FILE=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password
# Defaults to Administrator and the same password file; overrides are optional. # Defaults to Administrator and the same password file; overrides are optional.
+4 -2
View File
@@ -198,8 +198,10 @@ The authoritative fixture record is
[testing-vm.md](testing-vm.md): it lists the VM/host UUIDs, Windows build, [testing-vm.md](testing-vm.md): it lists the VM/host UUIDs, Windows build,
hardware and device profile, NAT and VRDE endpoints, snapshot UUIDs, hardware and device profile, NAT and VRDE endpoints, snapshot UUIDs,
credential-file contract, and the required reset sequence. The reset target is credential-file contract, and the required reset sequence. The reset target is
`baseline-clean-python-ready`, which includes all-users Python 3.13.16, pip and venv `baseline-clean-python-usb-ready`, which includes all-users Python 3.13.16 on
but no installed RVBox client. The guest address machine PATH, pip and venv, plus standard USB-tablet input without the problematic
`VBoxMouse` class filter, but no installed RVBox client. Preparation verifies
that mouse path; recovery and rollback are documented with the RDP helper. The guest address
`10.0.2.15` is DHCP state only; use SSH plus VirtualBox Guest Control rather `10.0.2.15` is DHCP state only; use SSH plus VirtualBox Guest Control rather
than treating it as a stable endpoint. VRDE is enabled only on Helium loopback than treating it as a stable endpoint. VRDE is enabled only on Helium loopback
at `127.0.0.1:3389` for diagnostics, while native Windows RDP is disabled in at `127.0.0.1:3389` for diagnostics, while native Windows RDP is disabled in
+81
View File
@@ -0,0 +1,81 @@
# Opt-in VirtualBox fixture workaround, never part of the RVBox client.
# Only the mouse-class VBoxMouse filter is changed; drivers are not uninstalled.
param([ValidateSet('Bypass', 'Restore', 'Status', 'Verify')][string]$Action = 'Status')
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
$key = 'HKLM:\SYSTEM\CurrentControlSet\Control\Class\{4d36e96f-e325-11ce-bfc1-08002be10318}'
$backup = 'C:\ProgramData\RVBoxFixture\mouse-filter-backup.json'
$filters = [string[]](Get-ItemProperty -LiteralPath $key -Name UpperFilters).UpperFilters
$devices = @(Get-PnpDevice -Class Mouse -PresentOnly)
if ($Action -in @('Bypass', 'Restore')) {
$principal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
throw 'Mouse-filter changes require a full-token administrator.'
}
if ($filters -notcontains 'mouclass') { throw 'Refusing to change a mouse class without mouclass.' }
if ((Get-Item -LiteralPath $key).GetValueKind('UpperFilters') -ne [Microsoft.Win32.RegistryValueKind]::MultiString) {
throw 'Expected REG_MULTI_SZ mouse-class UpperFilters.'
}
if ($Action -eq 'Bypass') {
if (-not ($devices | Where-Object { $_.InstanceId -like 'HID\VID_80EE&PID_0021\*' -and $_.Status -eq 'OK' })) {
throw 'Expected healthy VirtualBox USB-tablet mouse is absent.'
}
if (-not (Test-Path -LiteralPath $backup)) {
if ($filters -notcontains 'VBoxMouse') { throw 'No VBoxMouse filter and no original backup.' }
New-Item -ItemType Directory -Path (Split-Path -Parent $backup) -Force | Out-Null
$json = [ordered]@{ key = $key; upperFilters = $filters; savedUtc = [DateTime]::UtcNow.ToString('o') } | ConvertTo-Json
# Never replace the first backup, including on repeated runs.
$file = [IO.File]::Open($backup, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
try {
$bytes = [Text.Encoding]::UTF8.GetBytes($json)
$file.Write($bytes, 0, $bytes.Length)
$file.Flush($true)
} finally { $file.Dispose() }
}
}
$saved = Get-Content -LiteralPath $backup -Raw | ConvertFrom-Json
$original = [string[]]$saved.upperFilters
if ($saved.key -ne $key -or $original -notcontains 'mouclass' -or $original -notcontains 'VBoxMouse') {
throw 'Backup does not match the expected mouse class.'
}
$bypassed = [string[]]@($original | Where-Object { $_ -ine 'VBoxMouse' })
if (($filters -join "`0") -cne ($original -join "`0") -and ($filters -join "`0") -cne ($bypassed -join "`0")) {
throw 'Mouse filters have changed since backup; refusing to overwrite other changes.'
}
$desired = if ($Action -eq 'Bypass') { $bypassed } else { $original }
New-ItemProperty -LiteralPath $key -Name UpperFilters -PropertyType MultiString -Value ([string[]]$desired) -Force | Out-Null
$actual = [string[]](Get-ItemProperty -LiteralPath $key -Name UpperFilters).UpperFilters
if (($actual -join "`0") -cne ($desired -join "`0")) { throw 'Filter update did not persist.' }
$rebootRequired = $false
foreach ($device in $devices) {
Write-Output "Restarting mouse device: $($device.InstanceId)"
& "$env:SystemRoot\System32\pnputil.exe" /restart-device $device.InstanceId
$deviceExit = $LASTEXITCODE
Write-Output "pnputil_exit=$deviceExit"
if ($deviceExit -eq 3010) { $rebootRequired = $true }
elseif ($deviceExit -ne 0) {
throw "Mouse-device restart failed ($deviceExit); backup remains at $backup. Inspect or restore before retrying."
}
}
# Registry success is not proof of a detached driver; no automatic reboot.
Write-Output "reboot_required=$rebootRequired"
}
Write-Output "backup=$backup"
Get-ItemProperty -LiteralPath $key | Select-Object UpperFilters, LowerFilters | Format-List
Get-PnpDevice -Class Mouse -PresentOnly | Select-Object Status, FriendlyName, InstanceId | Format-List
Get-Service VBoxMouse, mouclass, mouhid, VBoxService -ErrorAction SilentlyContinue | Select-Object Name, Status | Format-Table
if ($Action -eq 'Verify') {
if ($filters -contains 'VBoxMouse') { throw 'VBoxMouse remains in the mouse class filter.' }
$driver = Get-Service VBoxMouse -ErrorAction SilentlyContinue
if ($driver -and $driver.Status -ne 'Stopped') { throw 'VBoxMouse is still loaded; restart Windows normally before testing.' }
foreach ($name in @('mouclass', 'mouhid', 'VBoxService')) {
if ((Get-Service $name).Status -ne 'Running') { throw "Required standard driver/service is not running: $name" }
}
if ($filters -notcontains 'mouclass' -or ($devices | Where-Object { $_.Status -ne 'OK' }) -or
-not ($devices | Where-Object { $_.InstanceId -like 'HID\VID_80EE&PID_0021\*' -and $_.Status -eq 'OK' })) {
throw 'Standard mouse class or USB-tablet device is unhealthy.'
}
Write-Output 'mouse_bypass_verified=True'
}
Write-Output 'RVBOX_GUEST_OK'
+66 -9
View File
@@ -27,6 +27,10 @@ Actions:
stop stop RVBox through SCM and request a graceful guest shutdown stop stop RVBox through SCM and request a graceful guest shutdown
reset stop the guest if necessary, restore the declared baseline, and leave it off reset stop the guest if necessary, restore the declared baseline, and leave it off
recover read-only fixture/run-state check for a stopped-resumable run recover read-only fixture/run-state check for a stopped-resumable run
mouse-status inspect Windows mouse filters/devices in the leased running VM
mouse-verify require the USB tablet and standard drivers, with VBoxMouse absent/stopped
mouse-bypass opt-in, backed-up VBoxMouse filter bypass; never reboots automatically
mouse-restore restore the original mouse filters; never reboots automatically
provision-python install/verify pinned Python, pip, and venv in the clean leased VM provision-python install/verify pinned Python, pip, and venv in the clean leased VM
capture-python-baseline verify the clean Python fixture, shut it down, take a capture-python-baseline verify the clean Python fixture, shut it down, take a
new snapshot (--snapshot-name NAME), and release the run lease new snapshot (--snapshot-name NAME), and release the run lease
@@ -94,7 +98,7 @@ while [ "$#" -gt 0 ]; do
esac esac
done done
case $action in status|prepare|stage|install|run|logoff|collect|inspect|logs|stop|reset|recover|provision-python|capture-python-baseline) ;; *) usage >&2; fail "unknown action $action" ;; esac case $action in status|prepare|stage|install|run|logoff|collect|inspect|logs|stop|reset|recover|provision-python|capture-python-baseline|mouse-status|mouse-verify|mouse-bypass|mouse-restore) ;; *) usage >&2; fail "unknown action $action" ;; esac
if [ "$action" = capture-python-baseline ]; then if [ "$action" = capture-python-baseline ]; then
[ -n "$snapshot_name" ] || fail "capture-python-baseline requires --snapshot-name" [ -n "$snapshot_name" ] || fail "capture-python-baseline requires --snapshot-name"
safe_id "$snapshot_name" safe_id "$snapshot_name"
@@ -121,8 +125,8 @@ if [ -n "$fail_contexts" ]; then safe_word fail_contexts "$fail_contexts"; fi
: "${RVBOX_TEST_VBOX_HOST:=helium-remote}" : "${RVBOX_TEST_VBOX_HOST:=helium-remote}"
: "${RVBOX_TEST_VBOX_VM:=rvbox-win10-test}" : "${RVBOX_TEST_VBOX_VM:=rvbox-win10-test}"
: "${RVBOX_TEST_VBOX_VM_UUID:=6cdc114f-71e5-4167-a394-e922e14e6f5c}" : "${RVBOX_TEST_VBOX_VM_UUID:=6cdc114f-71e5-4167-a394-e922e14e6f5c}"
: "${RVBOX_TEST_VBOX_SNAPSHOT:=baseline-clean-python-ready}" : "${RVBOX_TEST_VBOX_SNAPSHOT:=baseline-clean-python-usb-ready}"
: "${RVBOX_TEST_VBOX_SNAPSHOT_UUID:=dfadee95-156f-43ee-bdab-a10a44be4070}" : "${RVBOX_TEST_VBOX_SNAPSHOT_UUID:=a4851b6a-24d6-42f8-96c2-ff9f554c9198}"
: "${RVBOX_TEST_GUEST_USER:=rvboxtest}" : "${RVBOX_TEST_GUEST_USER:=rvboxtest}"
: "${RVBOX_TEST_GUEST_PASSWORD_FILE:=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password}" : "${RVBOX_TEST_GUEST_PASSWORD_FILE:=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password}"
: "${RVBOX_TEST_PROVISIONER_USER:=Administrator}" : "${RVBOX_TEST_PROVISIONER_USER:=Administrator}"
@@ -347,6 +351,17 @@ configure_display_keepalive() {
fail "fixture provisioner could not disable disposable display/sleep timers" fail "fixture provisioner could not disable disposable display/sleep timers"
} }
assert_mouse_bypassed() {
# Read-only guard for the canonical USB-tablet baseline. An additions
# reinstall may re-register VBoxMouse; fail visibly instead of silently
# reviving the path that dropped button transitions. Never reboot here.
mouse_check='$ErrorActionPreference="Stop"; $k="HKLM:\SYSTEM\CurrentControlSet\Control\Class\{4d36e96f-e325-11ce-bfc1-08002be10318}"; $f=(Get-ItemProperty -LiteralPath $k -Name UpperFilters).UpperFilters; if ($f -contains "VBoxMouse" -or $f -notcontains "mouclass") { throw "Unexpected mouse filters" }; $v=Get-Service VBoxMouse -ErrorAction SilentlyContinue; if ($v -and $v.Status -ne "Stopped") { throw "VBoxMouse is still loaded" }; foreach ($n in @("mouclass","mouhid","VBoxService")) { if ((Get-Service $n).Status -ne "Running") { throw "Required mouse driver/service stopped" } }; $d=@(Get-PnpDevice -Class Mouse -PresentOnly); if (($d | Where-Object { $_.Status -ne "OK" }) -or -not ($d | Where-Object { $_.InstanceId -like "HID\VID_80EE&PID_0021\*" })) { throw "USB tablet absent or unhealthy" }; Write-Output RVBOX_GUEST_OK'
mouse_encoded=$(printf '%s' "$mouse_check" | iconv -f UTF-8 -t UTF-16LE | base64 -w 0)
provisioner_run --exe 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' --wait-stdout --wait-stderr --unquoted-args -- \
-NoProfile -NonInteractive -EncodedCommand "$mouse_encoded" >/dev/null || \
fail "USB-tablet baseline guard failed: inspect mouse-status; apply mouse-bypass and restart Windows normally if VBoxMouse returned"
}
wait_service() { wait_service() {
wanted=$1 wanted=$1
attempt=0 attempt=0
@@ -394,8 +409,9 @@ case "$action" in
step prepare-snapshot-restored step prepare-snapshot-restored
assert_identity assert_identity
# Baselines may retain PS/2-only input. On this fixture VRDE mouse # Baselines may retain PS/2-only input. On this fixture VRDE mouse
# movement reached Windows, but PS/2 button clicks did not. Use an # movement reached Windows, but PS/2 button clicks did not. Provide an
# absolute USB tablet before boot; keep the keyboard unchanged. # absolute USB tablet before boot; keep the keyboard unchanged. The
# guest VBoxMouse filter may still need the opt-in mouse-bypass action.
VBoxManage modifyvm "$vm" --usb-ohci on --mouse usbtablet --vrde-property 'Client/DisableInput=' VBoxManage modifyvm "$vm" --usb-ohci on --mouse usbtablet --vrde-property 'Client/DisableInput='
step prepare-virtual-input-configured step prepare-virtual-input-configured
VBoxManage startvm "$vm" --type headless >/dev/null VBoxManage startvm "$vm" --type headless >/dev/null
@@ -405,6 +421,10 @@ case "$action" in
configure_display_keepalive configure_display_keepalive
step prepare-display-keepalive step prepare-display-keepalive
assert_clean_guest assert_clean_guest
# Retained pre-workaround snapshots fail this guard until explicitly
# repaired; never report a prepared fixture with the bad path revived.
assert_mouse_bypassed
step prepare-usb-mouse-verified
step prepare-clean-baseline-verified step prepare-clean-baseline-verified
;; ;;
probe-identity) probe-identity)
@@ -465,11 +485,18 @@ case "$action" in
fail "snapshot name already exists: $snapshot_name" fail "snapshot name already exists: $snapshot_name"
fi fi
assert_clean_guest assert_clean_guest
assert_mouse_bypassed
VBoxManage guestcontrol "$vm" --username "$provisioner_user" --passwordfile "$provisioner_password_file" \
copyto "$host_stage/provision-python.ps1" 'C:/Users/Public/rvbox-provision-python.ps1' </dev/null
guest_run --exe 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' --wait-stdout --wait-stderr --timeout 120000 --unquoted-args -- \ guest_run --exe 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' --wait-stdout --wait-stderr --timeout 120000 --unquoted-args -- \
-NoProfile -NonInteractive -ExecutionPolicy Bypass -File 'C:\ProgramData\RVBoxFixture\provision-python.ps1' -Mode VerifyClean || fail "clean Python baseline verification failed" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File 'C:/Users/Public/rvbox-provision-python.ps1' -Mode VerifyClean || fail "clean Python baseline verification failed"
assert_provisioner_absent assert_provisioner_absent
provisioner_run --exe 'C:\Windows\System32\cmd.exe' --wait-stdout --wait-stderr --unquoted-args -- \ # Preserve the mouse-filter rollback record. Only the owned Python
/d /s /c 'rmdir /s /q C:\ProgramData\RVBoxFixture && echo RVBOX_GUEST_OK' >/dev/null || fail "could not remove Python provisioning files" # installer staging directory and provisioning helpers are disposable.
cleanup_code='$ErrorActionPreference="Stop"; foreach ($p in @("C:\ProgramData\RVBoxFixture\python", "C:\ProgramData\RVBoxFixture\provision-python.ps1", "C:\Users\Public\rvbox-provision-python.ps1")) { if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Recurse -Force }; if (Test-Path -LiteralPath $p) { throw "Python staging cleanup failed" } }; Write-Output RVBOX_GUEST_OK'
cleanup_encoded=$(printf '%s' "$cleanup_code" | iconv -f UTF-8 -t UTF-16LE | base64 -w 0)
provisioner_run --exe 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' --wait-stdout --wait-stderr --unquoted-args -- \
-NoProfile -NonInteractive -EncodedCommand "$cleanup_encoded" || fail "could not remove Python provisioning files"
VBoxManage controlvm "$vm" acpipowerbutton >/dev/null VBoxManage controlvm "$vm" acpipowerbutton >/dev/null
attempt=0 attempt=0
while [ "$attempt" -lt 90 ]; do while [ "$attempt" -lt 90 ]; do
@@ -478,7 +505,7 @@ case "$action" in
sleep 1 sleep 1
done done
[ "$(state)" = poweroff ] || fail "VM did not shut down cleanly; baseline was not captured" [ "$(state)" = poweroff ] || fail "VM did not shut down cleanly; baseline was not captured"
VBoxManage snapshot "$vm" take "$snapshot_name" --description 'Clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64, pip and venv; no RVBox installation' >/dev/null VBoxManage snapshot "$vm" take "$snapshot_name" --description 'Clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64 with machine PATH; USB tablet with standard drivers, VBoxMouse detached; no RVBox installation' >/dev/null
new_snapshot_uuid=$(vm_field CurrentSnapshotUUID) new_snapshot_uuid=$(vm_field CurrentSnapshotUUID)
[ "$(vm_field CurrentSnapshotName)" = "$snapshot_name" ] && [ -n "$new_snapshot_uuid" ] || fail "new snapshot identity could not be verified" [ "$(vm_field CurrentSnapshotName)" = "$snapshot_name" ] && [ -n "$new_snapshot_uuid" ] || fail "new snapshot identity could not be verified"
release_lease release_lease
@@ -593,6 +620,26 @@ case "$action" in
done done
[ "$attempt" -lt 30 ] || fail "fixture user did not log off" [ "$attempt" -lt 30 ] || fail "fixture user did not log off"
;; ;;
mouse-status|mouse-verify|mouse-bypass|mouse-restore)
assert_identity
require_lease
[ "$(state)" = running ] || fail "$action requires a running prepared VM"
case $action in
mouse-status) mouse_action=Status ;;
mouse-verify) mouse_action=Verify ;;
mouse-bypass) mouse_action=Bypass; assert_provisioner_elevated ;;
mouse-restore) mouse_action=Restore; assert_provisioner_elevated ;;
esac
VBoxManage guestcontrol "$vm" --username "$provisioner_user" --passwordfile "$provisioner_password_file" \
copyto "$host_stage/mouse-filter.ps1" 'C:/Users/Public/rvbox-mouse-filter.ps1' </dev/null
provisioner_run --exe 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' --wait-stdout --wait-stderr --unquoted-args -- \
-NoProfile -NonInteractive -ExecutionPolicy Bypass -File 'C:/Users/Public/rvbox-mouse-filter.ps1' -Action "$mouse_action"
if [ "$action" = mouse-bypass ] || [ "$action" = mouse-restore ]; then
VBoxManage guestcontrol "$vm" --username "$provisioner_user" --passwordfile "$provisioner_password_file" \
copyfrom 'C:/ProgramData/RVBoxFixture/mouse-filter-backup.json' "$host_stage/mouse-filter-backup.json" </dev/null
step "$action completed; inspect reboot_required before testing input"
fi
;;
collect) collect)
assert_identity assert_identity
require_lease require_lease
@@ -771,6 +818,16 @@ case $action in
copy_stage_file "$repo_root/scripts/windows/provision-python.ps1" provision-python.ps1 copy_stage_file "$repo_root/scripts/windows/provision-python.ps1" provision-python.ps1
remote provision-python remote provision-python
;; ;;
capture-python-baseline)
remote prepare-stage
copy_stage_file "$repo_root/scripts/windows/provision-python.ps1" provision-python.ps1
remote capture-python-baseline
;;
mouse-status|mouse-verify|mouse-bypass|mouse-restore)
remote prepare-stage
copy_stage_file "$repo_root/scripts/windows/mouse-filter.ps1" mouse-filter.ps1
remote "$action"
;;
stage) stage)
printf 'stage: verify prepared VM and lease\n' printf 'stage: verify prepared VM and lease\n'
remote prepare-stage remote prepare-stage
+1 -1
View File
@@ -7,7 +7,7 @@ param(
[ValidatePattern('^[a-z0-9][a-z0-9-]{0,63}$')] [ValidatePattern('^[a-z0-9][a-z0-9-]{0,63}$')]
[string] $RunId = '', [string] $RunId = '',
[string] $VmName = $(if ($env:RVBOX_WINDOWS_VM) { $env:RVBOX_WINDOWS_VM } elseif ($env:RVBOX_TEST_VBOX_VM) { $env:RVBOX_TEST_VBOX_VM } else { 'rvbox-win10-test' }), [string] $VmName = $(if ($env:RVBOX_WINDOWS_VM) { $env:RVBOX_WINDOWS_VM } elseif ($env:RVBOX_TEST_VBOX_VM) { $env:RVBOX_TEST_VBOX_VM } else { 'rvbox-win10-test' }),
[string] $Snapshot = $(if ($env:RVBOX_WINDOWS_BASELINE_SNAPSHOT) { $env:RVBOX_WINDOWS_BASELINE_SNAPSHOT } elseif ($env:RVBOX_TEST_VBOX_SNAPSHOT) { $env:RVBOX_TEST_VBOX_SNAPSHOT } else { 'baseline-clean' }) [string] $Snapshot = $(if ($env:RVBOX_WINDOWS_BASELINE_SNAPSHOT) { $env:RVBOX_WINDOWS_BASELINE_SNAPSHOT } elseif ($env:RVBOX_TEST_VBOX_SNAPSHOT) { $env:RVBOX_TEST_VBOX_SNAPSHOT } else { 'baseline-clean-python-usb-ready' })
) )
$ErrorActionPreference = 'Stop' $ErrorActionPreference = 'Stop'
+6
View File
@@ -623,6 +623,12 @@ layer = "integration"
status = "planned" status = "planned"
tests = ["test/windowsnative/native_fixture_test.go:TestNativeFixtureAssets_HP_HARNESS_20"] tests = ["test/windowsnative/native_fixture_test.go:TestNativeFixtureAssets_HP_HARNESS_20"]
[[requirements]]
id = "HP-HARNESS-21"
layer = "unit"
status = "implemented"
tests = ["test/windowsnative/native_fixture_test.go:TestMouseFilterRecoveryAssets_HP_HARNESS_21"]
[[requirements]] [[requirements]]
id = "HP-HARNESS-20" id = "HP-HARNESS-20"
layer = "unit" layer = "unit"
+102 -8
View File
@@ -326,16 +326,33 @@ owns the fixture's single VRDE connection slot.
On this Windows 10 / VirtualBox 7.2.16 fixture, the PS/2 pointing device accepted On this Windows 10 / VirtualBox 7.2.16 fixture, the PS/2 pointing device accepted
pointer movement but did not activate buttons through Guacamole. A normal pointer movement but did not activate buttons through Guacamole. A normal
Windows restart did not repair that mouse path. Switching to a USB tablet with Windows restart did not repair that mouse path. Switching to a USB tablet with
an OHCI controller did: the same real Guacamole HTTP-tunnel keyboard shortcut an OHCI controller initially passed a single-click check, but the failure
opened Run, and the mouse Cancel-button click closed it. This identifies a recurred. Do not treat that check as proof of a durable fix. The interactive
failure in the PS/2 input path for this setup, not its exact underlying driver Windows probe then recorded 106 changing pointer samples, no left/right
bug. Guest Control, the updating clock, and `Get-PnpDevice` reporting `OK` had button-down samples, and no accepted OK clicks, despite Guacamole receiving
all remained healthy during the failure. browser mouse-down/up events. Guest Control, the updating clock, and
`Get-PnpDevice` reporting `OK` all remained healthy during the failure.
The guest mouse class had `UpperFilters = VBoxMouse, mouclass`. A USB tablet
alone does not necessarily bypass mouse integration: VirtualBox's
[mouse-routing implementation](https://github.com/VirtualBox/virtualbox/blob/master/src/VBox/Main/src-client/MouseImpl.cpp)
prefers the Guest Additions absolute-pointer path when advertised and can send
buttons separately through the emulated relative mouse. After an explicitly
approved, backed-up removal of **only** `VBoxMouse` from that class filter and
a normal Windows restart, `VBoxMouse` was stopped, the standard drivers remained
running, and input counters moved to the USB-tablet queue. Ten controlled clicks
through the **existing** Guacamole/guacd connection produced ten button-down/up
transitions and ten accepted OK results in Windows. This supports a workaround
for this fixture's mouse-integration path; it does not establish the precise
VirtualBox driver defect or prove every browser/hardware combination.
`scripts/windows/test-host prepare` now configures the USB tablet and enables `scripts/windows/test-host prepare` now configures the USB tablet and enables
VRDE input **after each snapshot restore, before boot**. The retained baseline VRDE input **after each snapshot restore, before boot**. The canonical baseline
snapshots are unchanged. A manual restore followed by `VBoxManage startvm` also records the detached `VBoxMouse` filter; `prepare` verifies it remains
bypasses this normalization and may restore the old PS/2-only configuration. detached, with healthy standard drivers and USB input, before reporting success.
The older snapshots are retained unchanged for rollback. A manual restore of
an older snapshot followed by `VBoxManage startvm` bypasses this normalization
and can restore both the PS/2-only configuration and the problematic filter.
Oracle documents the USB tablet's absolute-coordinate input in its Oracle documents the USB tablet's absolute-coordinate input in its
[pointing-device settings](https://docs.oracle.com/en/virtualization/virtualbox/7.2/user/working-with-vms.html). [pointing-device settings](https://docs.oracle.com/en/virtualization/virtualbox/7.2/user/working-with-vms.html).
@@ -358,6 +375,83 @@ or `prepare` for state-preserving recovery: both restore a baseline and discard
current disk changes. `rdp-access repair` alone never changes the virtual input current disk changes. `rdp-access repair` alone never changes the virtual input
hardware or restarts Windows. hardware or restarts Windows.
#### Opt-in mouse-filter workaround and rollback
The canonical baseline already records this workaround, so normal preparation
does not need an extra driver change or restart. `prepare` fails visibly if the
filter or unhealthy devices return; it does not silently repair a live desktop.
When diagnosing an older baseline or an explicit Guest Additions reinstall,
with the fixture running and the current lease owner known:
```sh
scripts/windows/test-host mouse-status --run-id interactive-rdp
scripts/windows/test-host mouse-bypass --run-id interactive-rdp
scripts/windows/test-host mouse-verify --run-id interactive-rdp
```
The second action requires the fixture's full-token administrator and a healthy
VirtualBox USB-tablet device. It backs up the original ordered filter list to
`C:\ProgramData\RVBoxFixture\mouse-filter-backup.json`, preserving that first
backup on repeated runs, and copies it to the Helium run directory. It removes
only `VBoxMouse`; `mouclass`, other filters, LowerFilters, keyboard devices,
driver files/services, and Guest Additions are retained. It refuses unexpected
filter changes since the backup. The class property is
[REG_MULTI_SZ](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/devpkey-deviceclass-upperfilters),
not a single string.
Only the present mouse devices are reloaded with
[`pnputil /restart-device`](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/pnputil-command-syntax),
which Windows 10 22H2 supports. `pnputil_exit=3010` / `reboot_required=True`
means a normal Windows restart is still required. On the current fixture the
USB mouse reloaded immediately, but the PS/2 device required that restart.
The helper **never** restarts Windows, force-powers off the VM, or restores a
snapshot. Save desktop work before restarting Windows normally, then repeat
`mouse-verify`: it succeeds only when the filters omit `VBoxMouse`,
`VBoxMouse` is stopped, and `mouclass`/`mouhid` and both devices are healthy.
To undo the workaround, keeping the same disk and original backup:
```sh
scripts/windows/test-host mouse-restore --run-id interactive-rdp
```
Restart Windows normally if requested, and inspect `mouse-status` again. Restore
uses the original filter order and also refuses unrelated intervening changes.
Neither bypass nor restore is retried automatically after an interrupted remote
execution: inspect the resulting state first. Restoring the canonical baseline
also restores the known-good detached filter and its rollback record; restoring
an older baseline can discard both. Do not disable/delete `VBoxMouse.sys` while
the class still references it, and do not remove `mouclass`: either can break
normal mouse input. This filter supplies VirtualBox's
[mouse-pointer integration](https://docs.oracle.com/en/virtualization/virtualbox/7.2/user/guestadditions.html),
not an RVBox feature or security restriction. Standard USB-tablet input does not
need it. Guest Control and video support use other Guest Additions components
and remain installed. Avoid untracked Guest Additions updates/reinstalls; they
can register the filter again. After an intentional update, verify/reapply the
workaround, restart normally if needed, and re-run real click checks before
capturing another clean baseline. No workaround guarantees immunity from all
future browser, transport, or unrelated driver failures.
For a Windows-side click check, copy `test/rdp-access/mouse-probe.py` to the
desktop and run it with `C:\Python313\python.exe` **in the interactive desktop
session**. Guest Control runs in Session 0 and cannot measure the desktop's
button state. Ten OK clicks should advance the dialog count and finish the
probe; the adjacent `.log` must contain `left: true` samples and ten
`dialog_result` entries with `result: 1`. Logs include only mouse coordinates,
button state, and diagnostic results, never typed keys. Mouse sampling lasts
ten minutes; `monitor_finished` marks the limit. Relaunch for a fresh capture
(the previous probe log is overwritten, so collect it first).
If Windows+R is intercepted by the browser/host, a verified operator can use
`VBoxManage controlvm <verified-VM> keyboardputscancode e0 5b 13 93 e0 db` on
Helium to open **remote** Run. Inspect a screenshot to verify that Run is open
before typing the exact probe command with `keyboardputstring`; use Ctrl+A to
replace old Run history. Do not blindly send Enter or type into the user's
existing command prompt. Do not inject the command via guessed Unicode
Guacamole keysyms: this fixture did not accept that text reliably. A read-only
observer may join the existing guacd connection for diagnostics, but an
independent RDP connection would compete for its single slot.
The two scripts have a deliberate ownership boundary. `rdp-access` manages only The two scripts have a deliberate ownership boundary. `rdp-access` manages only
the temporary browser gateway, Guacamole/guacd containers, IPv6 forward, and the temporary browser gateway, Guacamole/guacd containers, IPv6 forward, and
Helium SSH tunnel. `scripts/windows/test-host` manages the leased VM and its Helium SSH tunnel. `scripts/windows/test-host` manages the leased VM and its
+77
View File
@@ -0,0 +1,77 @@
"""Interactive Windows mouse diagnostic using only the fixture's Python.
Run on the desktop, not Guest Control's Session 0. Ten accepted OK clicks
finish the test; Cancel/Escape exits early. No settings or keystrokes are read.
The adjacent .log contains changed mouse coordinates/buttons and dialog results.
"""
import ctypes
from ctypes import wintypes
import json
from pathlib import Path
import sys
import threading
import time
if sys.platform != 'win32':
raise SystemExit('Run this probe on the interactive Windows desktop.')
user32 = ctypes.WinDLL('user32', use_last_error=True)
user32.GetCursorPos.argtypes = [ctypes.POINTER(wintypes.POINT)]
user32.GetCursorPos.restype = wintypes.BOOL
user32.GetAsyncKeyState.argtypes = [ctypes.c_int]
user32.GetAsyncKeyState.restype = ctypes.c_short
user32.MessageBoxW.argtypes = [wintypes.HWND, wintypes.LPCWSTR,
wintypes.LPCWSTR, wintypes.UINT]
user32.MessageBoxW.restype = ctypes.c_int
user32.SetProcessDPIAware.argtypes = []
user32.SetProcessDPIAware.restype = wintypes.BOOL
user32.SetProcessDPIAware()
log_path = Path(__file__).with_suffix('.log')
stop = threading.Event()
lock = threading.Lock()
log = log_path.open('w', encoding='utf-8', buffering=1)
def record(kind, **data):
with lock:
entry = json.dumps(dict(time=time.time(), kind=kind, **data))
log.write(entry + '\n')
print(entry, flush=True)
def monitor():
previous = None
deadline = time.monotonic() + 600
point = wintypes.POINT()
while not stop.is_set() and time.monotonic() < deadline:
if user32.GetCursorPos(ctypes.byref(point)):
state = (point.x, point.y,
bool(user32.GetAsyncKeyState(1) & 0x8000),
bool(user32.GetAsyncKeyState(2) & 0x8000))
if state != previous:
record('windows_mouse', x=state[0], y=state[1],
left=state[2], right=state[3])
previous = state
stop.wait(0.01)
record('monitor_finished')
record('started', log=str(log_path))
worker = threading.Thread(target=monitor, daemon=True)
worker.start()
try:
for accepted in range(10):
result = user32.MessageBoxW(
None,
f'Accepted OK clicks: {accepted}\n\n'
'Use the physical mouse to click OK.\n'
'Each accepted click opens the next numbered test.\n'
'The count must advance on each ordinary click.\n\n'
'Cancel or Escape exits. No settings are changed.',
'RVBox Mouse Input Probe', 1)
record('dialog_result', accepted_before=accepted, result=result)
if result != 1:
break
finally:
stop.set()
worker.join(timeout=2)
record('finished')
log.close()
+37
View File
@@ -84,6 +84,43 @@ func TestNativeFixtureAssets_HP_HARNESS_20(t *testing.T) {
} }
} }
// Static safety contracts complement the live Windows device/GUI checks.
func TestMouseFilterRecoveryAssets_HP_HARNESS_21(t *testing.T) {
t.Parallel()
root := filepath.Clean(filepath.Join("..", ".."))
read := func(relative string) string {
t.Helper()
data, err := os.ReadFile(filepath.Join(root, relative))
if err != nil {
t.Fatal(err)
}
return string(data)
}
host := read("scripts/windows/test-host")
for _, required := range []string{"mouse-status|mouse-verify|mouse-bypass|mouse-restore", "mouse_action=Restore; assert_provisioner_elevated", "mouse-filter-backup.json", "step \"$action completed; inspect reboot_required before testing input\"", "prepare-usb-mouse-verified", "assert_mouse_bypassed()", "Never reboot here"} {
if !strings.Contains(host, required) {
t.Fatalf("mouse recovery controller is missing %q", required)
}
}
filter := read("scripts/windows/mouse-filter.ps1")
for _, required := range []string{"$Action = 'Status'", "[IO.FileMode]::CreateNew", "-PropertyType MultiString", "$filters -notcontains 'mouclass'", "VID_80EE&PID_0021", "refusing to overwrite other changes", "/restart-device $device.InstanceId", "$deviceExit -eq 3010", "reboot_required=$rebootRequired", "RVBOX_GUEST_OK"} {
if !strings.Contains(filter, required) {
t.Fatalf("mouse filter helper is missing safety contract %q", required)
}
}
for _, prohibited := range []string{"shutdown.exe", "/delete-driver", "Remove-ItemProperty", "Stop-Service", "/force"} {
if strings.Contains(filter, prohibited) {
t.Fatalf("mouse filter helper contains prohibited automatic/destructive action %q", prohibited)
}
}
probe := read("test/rdp-access/mouse-probe.py")
for _, required := range []string{"Session 0", "range(10)", "GetAsyncKeyState(1)", "'dialog_result'", "time.monotonic() + 600"} {
if !strings.Contains(probe, required) {
t.Fatalf("interactive mouse probe is missing %q", required)
}
}
}
// TestProductionComposeAssets_HP_OPS_01 guards the deployment properties that // TestProductionComposeAssets_HP_OPS_01 guards the deployment properties that
// a syntax-only Compose check cannot prove: private server reachability through // a syntax-only Compose check cannot prove: private server reachability through
// nginx, non-root state initialization, and a repository-local smoke cleanup. // nginx, non-root state initialization, and a repository-local smoke cleanup.