diff --git a/docs/implementation-plan.v1.md b/docs/implementation-plan.v1.md index 6e0779e..2ec941c 100644 --- a/docs/implementation-plan.v1.md +++ b/docs/implementation-plan.v1.md @@ -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) | | 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) | -| 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` | | 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 | | 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. | -| 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 | +| 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-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 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 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 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 @@ -951,8 +967,8 @@ identity in the run manifest: ```sh export RVBOX_TEST_VBOX_HOST=helium-remote export RVBOX_TEST_VBOX_VM=rvbox-win10-test -export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-ready -export RVBOX_TEST_VBOX_SNAPSHOT_UUID=dfadee95-156f-43ee-bdab-a10a44be4070 +export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-usb-ready +export RVBOX_TEST_VBOX_SNAPSHOT_UUID=a4851b6a-24d6-42f8-96c2-ff9f554c9198 export RVBOX_TEST_GUEST_USER=rvboxtest 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. 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" \ '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, disposable test; it intentionally loses guest state. 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 snapshot, unregister the VM, or modify `win10_dev` (that name refers to a stale unregistered configuration with a missing disk on this host). diff --git a/docs/testing-vm.md b/docs/testing-vm.md index eb84cc8..b257321 100644 --- a/docs/testing-vm.md +++ b/docs/testing-vm.md @@ -6,7 +6,7 @@ Windows release matrix. Keep the values here in sync with the VM before adding or changing native test automation. 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 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 @@ -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 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) | -| 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 | 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 | | Install media | `/media/Data2/Downloaded/Win10_22H2_English_x64.iso`, Windows image index 6 | | 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 | | Network adapter | One Intel 82540EM adapter, cable connected, NAT attachment; MAC `080027036E7C` | | 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 | | 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 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` | @@ -103,14 +103,16 @@ copy/paste example and explains the native-host lease boundary. ## 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 Run-key registration, RVBox state, logs, or staged binaries; it also has the fixture-only built-in `Administrator` account enabled for high-token Guest Control installation, plus Python, pip, and venv for repeatable interactive tests. -It is a powered-off descendant of `baseline-clean-administrator`, captured after -the first Python snapshot's pending Windows servicing restart completed; the -original parent and both older diagnostic snapshots remain unchanged. +It is a powered-off descendant of `baseline-clean-python-ready`, with a standard +USB tablet and the unnecessary `VBoxMouse` class filter detached. The prior +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 | | --- | --- | --- | @@ -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-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-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 stateful run must: 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 (bounded 240-second window for cold boots/servicing restarts). 4. Apply the disposable display/sleep keepalive (`monitor-timeout`, standby, and hibernate timers set to zero) so VirtualBox VRDE cannot expose a zero-bpp framebuffer after Windows idle timeout. This is recorded as `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 Control process that was opened by the run. 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 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 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 fixture. No Python installer, bootstrap script, verification venv, or RVBox 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 installation/state directories, or tray Run-key registration; requires no logged-on provisioning Administrator and no Windows servicing reboot pending; -deletes only `C:\ProgramData\RVBoxFixture` -bootstrap data; requests graceful shutdown; and takes a **powered-off** snapshot. +requires the healthy USB-tablet path with `VBoxMouse` detached/stopped; removes +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 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_VM=rvbox-win10-test 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_UUID=dfadee95-156f-43ee-bdab-a10a44be4070 +export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-usb-ready +export RVBOX_TEST_VBOX_SNAPSHOT_UUID=a4851b6a-24d6-42f8-96c2-ff9f554c9198 export RVBOX_TEST_GUEST_USER=rvboxtest 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. diff --git a/docs/testing.md b/docs/testing.md index 6a7b796..383c612 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -198,8 +198,10 @@ The authoritative fixture record is [testing-vm.md](testing-vm.md): it lists the VM/host UUIDs, Windows build, hardware and device profile, NAT and VRDE endpoints, snapshot UUIDs, 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 -but no installed RVBox client. The guest address +`baseline-clean-python-usb-ready`, which includes all-users Python 3.13.16 on +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 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 diff --git a/scripts/windows/mouse-filter.ps1 b/scripts/windows/mouse-filter.ps1 new file mode 100644 index 0000000..f172725 --- /dev/null +++ b/scripts/windows/mouse-filter.ps1 @@ -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' diff --git a/scripts/windows/test-host b/scripts/windows/test-host index 46d1666..e398c31 100755 --- a/scripts/windows/test-host +++ b/scripts/windows/test-host @@ -27,6 +27,10 @@ Actions: 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 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 capture-python-baseline verify the clean Python fixture, shut it down, take a new snapshot (--snapshot-name NAME), and release the run lease @@ -94,7 +98,7 @@ while [ "$#" -gt 0 ]; do esac 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 [ -n "$snapshot_name" ] || fail "capture-python-baseline requires --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_VM:=rvbox-win10-test}" : "${RVBOX_TEST_VBOX_VM_UUID:=6cdc114f-71e5-4167-a394-e922e14e6f5c}" -: "${RVBOX_TEST_VBOX_SNAPSHOT:=baseline-clean-python-ready}" -: "${RVBOX_TEST_VBOX_SNAPSHOT_UUID:=dfadee95-156f-43ee-bdab-a10a44be4070}" +: "${RVBOX_TEST_VBOX_SNAPSHOT:=baseline-clean-python-usb-ready}" +: "${RVBOX_TEST_VBOX_SNAPSHOT_UUID:=a4851b6a-24d6-42f8-96c2-ff9f554c9198}" : "${RVBOX_TEST_GUEST_USER:=rvboxtest}" : "${RVBOX_TEST_GUEST_PASSWORD_FILE:=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password}" : "${RVBOX_TEST_PROVISIONER_USER:=Administrator}" @@ -347,6 +351,17 @@ configure_display_keepalive() { 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() { wanted=$1 attempt=0 @@ -394,8 +409,9 @@ case "$action" in step prepare-snapshot-restored assert_identity # Baselines may retain PS/2-only input. On this fixture VRDE mouse - # movement reached Windows, but PS/2 button clicks did not. Use an - # absolute USB tablet before boot; keep the keyboard unchanged. + # movement reached Windows, but PS/2 button clicks did not. Provide an + # 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=' step prepare-virtual-input-configured VBoxManage startvm "$vm" --type headless >/dev/null @@ -405,6 +421,10 @@ case "$action" in configure_display_keepalive step prepare-display-keepalive 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 ;; probe-identity) @@ -465,11 +485,18 @@ case "$action" in fail "snapshot name already exists: $snapshot_name" fi 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 || fail "could not remove Python provisioning files" + # Preserve the mouse-filter rollback record. Only the owned Python + # 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 attempt=0 while [ "$attempt" -lt 90 ]; do @@ -478,7 +505,7 @@ case "$action" in sleep 1 done [ "$(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) [ "$(vm_field CurrentSnapshotName)" = "$snapshot_name" ] && [ -n "$new_snapshot_uuid" ] || fail "new snapshot identity could not be verified" release_lease @@ -593,6 +620,26 @@ case "$action" in done [ "$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' 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 temporary browser gateway, Guacamole/guacd containers, IPv6 forward, and Helium SSH tunnel. `scripts/windows/test-host` manages the leased VM and its diff --git a/test/rdp-access/mouse-probe.py b/test/rdp-access/mouse-probe.py new file mode 100644 index 0000000..3eb4a8b --- /dev/null +++ b/test/rdp-access/mouse-probe.py @@ -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() diff --git a/test/windowsnative/native_fixture_test.go b/test/windowsnative/native_fixture_test.go index 6fe35fc..d23a1a9 100644 --- a/test/windowsnative/native_fixture_test.go +++ b/test/windowsnative/native_fixture_test.go @@ -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 // a syntax-only Compose check cannot prove: private server reachability through // nginx, non-root state initialization, and a repository-local smoke cleanup.