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

+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
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
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
provisioner_run --exe 'C:\Windows\System32\cmd.exe' --wait-stdout --wait-stderr --unquoted-args -- \
/d /s /c 'rmdir /s /q C:\ProgramData\RVBoxFixture && echo RVBOX_GUEST_OK' >/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' </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)
assert_identity
require_lease
@@ -771,6 +818,16 @@ case $action in
copy_stage_file "$repo_root/scripts/windows/provision-python.ps1" provision-python.ps1
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)
printf 'stage: verify prepared VM and lease\n'
remote prepare-stage
+1 -1
View File
@@ -7,7 +7,7 @@ param(
[ValidatePattern('^[a-z0-9][a-z0-9-]{0,63}$')]
[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] $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'