From 34274f0f62f95a7d6e00d5666bc7f7505b21c731 Mon Sep 17 00:00:00 2001 From: cabbage Date: Thu, 8 Oct 2026 14:26:52 +0000 Subject: [PATCH] Add reproducible LAN-only RDP access on Helium --- docs/implementation-plan.v1.md | 1 + docs/testing-vm.md | 3 +- docs/testing.md | 8 + test/coverage.toml | 12 ++ test/rdp-access/README.md | 104 +++++++++++ test/rdp-access/compose-lan.yaml | 25 +++ test/rdp-access/lan-access | 203 ++++++++++++++++++++++ test/rdp-access/rdp-access | 21 +++ test/windowsnative/native_fixture_test.go | 76 ++++++++ 9 files changed, 452 insertions(+), 1 deletion(-) create mode 100644 test/rdp-access/compose-lan.yaml create mode 100644 test/rdp-access/lan-access diff --git a/docs/implementation-plan.v1.md b/docs/implementation-plan.v1.md index 2ec941c..55b3cf9 100644 --- a/docs/implementation-plan.v1.md +++ b/docs/implementation-plan.v1.md @@ -849,6 +849,7 @@ mirror; update both documents when the fixture is reprovisioned. | 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 | +| Optional LAN RDP | `test/rdp-access/rdp-access lan-up` starts a small, digest-pinned Docker Compose relay on Helium's detected private LAN IP/subnet; current endpoint `192.168.50.162:3389`, limited to `192.168.50.0/24`. Backend remains loopback-only VRDE, Windows `TermService` and baseline unchanged. `lan-status`/`lan-down`/`lan-clean [--images]` manage only this profile. `up --lan` can enable web and LAN routes together; web cleanup does not implicitly stop LAN access. Disconnect Guacamole before an RDP app uses the single console slot. | | 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-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. | diff --git a/docs/testing-vm.md b/docs/testing-vm.md index b257321..1769a05 100644 --- a/docs/testing-vm.md +++ b/docs/testing-vm.md @@ -75,7 +75,8 @@ 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=RDP`, single connection only, multiconnection and connection reuse 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 through the private SSH/Guacamole path or the explicitly enabled LAN-only Docker relay. | +| Optional LAN RDP relay | `test/rdp-access/rdp-access lan-up` detects Helium's private IPv4/subnet and exposes the existing VRDE endpoint; currently `192.168.50.162:3389`, peers limited to `192.168.50.0/24`. `lan-status`, `lan-down`, and `lan-clean [--images]` manage only the independent relay; no Windows or baseline change. Disconnect Guacamole before using an RDP app. | | 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` | diff --git a/docs/testing.md b/docs/testing.md index 383c612..c9dce73 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -207,6 +207,14 @@ 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 the baseline. +Direct LAN RDP access can be enabled with `test/rdp-access/rdp-access lan-up`: +the small Docker relay runs on Helium, binds its private LAN IP, restricts peers +to that subnet, and preserves the existing private VRDE backend and Windows +session. The independent `lan-status`/`lan-down`/`lan-clean` lifecycle is documented +in [the RDP helper](../test/rdp-access/README.md#direct-rdp-on-heliums-lan). +Disconnect the Guacamole desktop before switching to an RDP app; VRDE still +has one console slot and this does not enable Windows `TermService`. + Interactive browser access is a deliberately temporary recovery path only. See [`test/rdp-access`](../test/rdp-access/README.md) for the Docker-only, self-signed HTTPS Guacamole lifecycle; it must be started only after the native diff --git a/test/coverage.toml b/test/coverage.toml index 1e09e82..39221b2 100644 --- a/test/coverage.toml +++ b/test/coverage.toml @@ -629,6 +629,18 @@ layer = "unit" status = "implemented" tests = ["test/windowsnative/native_fixture_test.go:TestMouseFilterRecoveryAssets_HP_HARNESS_21"] +[[requirements]] +id = "HP-HARNESS-22" +layer = "unit" +status = "implemented" +tests = ["test/windowsnative/native_fixture_test.go:TestLANRelayAssets_HP_HARNESS_22"] + +[[requirements]] +id = "BH-HARNESS-22" +layer = "unit" +status = "implemented" +tests = ["test/windowsnative/native_fixture_test.go:TestLANRelayRejectsUnsafeOptions_BH_HARNESS_22"] + [[requirements]] id = "HP-HARNESS-20" layer = "unit" diff --git a/test/rdp-access/README.md b/test/rdp-access/README.md index bfc4c35..f9e95ea 100644 --- a/test/rdp-access/README.md +++ b/test/rdp-access/README.md @@ -24,6 +24,11 @@ password to the VM. Clipboard, drives, printing, audio, microphone input, GFX, and display-resize extensions are disabled because the fixture's VirtualBox RDP4 server does not handle them reliably. +The optional **LAN-only** RDP relay below is a separate, explicitly requested +path on Helium. It leaves the VM's VRDE socket on loopback, binds only a private +host IPv4 address, and restricts peers to the selected private LAN subnet. +It does not expose the guest NAT address or enable Windows Remote Desktop. + ## Network and graphics quality Use `--graphics minimal|low|normal|high` on `up`, or set `RDP_ACCESS_GRAPHICS`: @@ -66,6 +71,105 @@ less than scrolling images or video. The RDP backend does not provide VNC's `quality-level`/`compress-level` knobs; those must not be added to this RDP mapping as if they controlled its encoding. +## Direct RDP on Helium's LAN + +For an already-running fixture, one command detects the host's primary private +IPv4 address/subnet and starts a small Docker Compose TCP relay **on Helium**: + +```sh +test/rdp-access/rdp-access lan-up +test/rdp-access/rdp-access lan-status +``` + +The current endpoint is **`192.168.50.162:3389`**, restricted to +`192.168.50.0/24` (the helper may print its equivalent host-prefix notation, +`192.168.50.162/24`). Use `rvboxtest` and the same test-only fixture password +as Guacamole, obtained from the host-local password file in +[`docs/testing-vm.md`](../../docs/testing-vm.md). Authentication is passed +through to the existing `VBoxAuthSimple` endpoint; the relay stores no password. + +**Disconnect the Guacamole desktop before connecting an RDP app.** Both routes +use the same single VirtualBox console slot. Changing the access route does +not log off Windows or create another WTS user session. Leave multi-connection +and connection reuse disabled; do not "fix" a rejected second connection by +changing that fixture contract. You can keep the web gateway running for later +use, or stop it with `rdp-access down` while the LAN relay remains available. + +This is the working **VirtualBox VRDE** endpoint, not Windows `TermService`. +Native Windows RDP remains disabled, and its old NAT port `3390` is not this +LAN endpoint. The VRDE backend currently uses legacy `security=rdp`; a client +that requires NLA/TLS or newer RDP extensions may not be compatible. This +relay changes reachability, not VirtualBox's protocol compatibility. Do not +forward this debug endpoint through a WAN router or expose it publicly. + +To start Guacamole and the independent LAN relay together: + +```sh +test/rdp-access/rdp-access up \ + --bind 0.0.0.0 --public-host x1.xcel.me --graphics minimal --lan +``` + +Stop, remove, or recreate only the LAN route: + +```sh +test/rdp-access/rdp-access lan-down # retain small generated config +test/rdp-access/rdp-access lan-clean # remove that profile's config +test/rdp-access/rdp-access lan-clean --images # also try removing its unused image +test/rdp-access/rdp-access lan-up # recover/reproduce after cleanup +``` + +These commands do not stop/reset the VM, change Windows/firewall settings, +stop Guacamole, or affect another LAN profile. Conversely, web `down`/`clean` +do not disable LAN access: use `lan-down`/`lan-clean` explicitly. Before the +usual final VM reset, close both routes if both were enabled. Cleanup checks +profile/VM ownership labels, stops only that Compose project, deletes only +its known generated files, and never force-removes a shared image or runs a +global Docker prune. Unexpected files are retained for inspection. + +All fixture settings have overridable defaults; the most useful overrides are: + +| Variable / option | Default | Purpose | +| --- | --- | --- | +| `RDP_ACCESS_LAN_BIND` / `--lan-bind` | `auto` | Detect primary LAN IP; override for another private host interface | +| `RDP_ACCESS_LAN_PORT` / `--lan-port` | `3389` | Client-facing port; choose a free port on conflicts | +| `RDP_ACCESS_LAN_CIDR` / `--lan-cidr` | `auto` | Allow only the selected interface's subnet; override for a specific private subnet | +| `RDP_ACCESS_PROFILE` / `--profile` | `default` | Independent relay per VM/access profile | +| `RVBOX_TEST_VBOX_HOST` | `helium-remote` | SSH host for Docker/VBoxManage | +| `RDP_ACCESS_VRDE_PORT` | `3389` | Existing VM's loopback-only backend; verified against its actual VRDE port | +| `RDP_ACCESS_LAN_REMOTE_ROOT` | `/home/cabbage/.local/state/rvbox-rdp-access/lan` | Small generated per-profile Compose/state directories on Helium | + +Explicit example for another LAN interface or a port conflict: + +```sh +test/rdp-access/rdp-access lan-up \ + --lan-bind 192.168.50.162 --lan-port 3391 --lan-cidr 192.168.50.0/24 +``` + +`lan-up` rejects wildcard, loopback, public, unassigned, and malformed bind +addresses, excessive subnet masks, unowned port listeners, and a mismatched VM +or backend. It never kills an unrelated listener. Startup is idempotent, and +four bounded SSH attempts handle interruptions. Status/down/clean use saved +remote configuration, so they work even with the VM off; status distinguishes +the LAN listener from the VM's private backend being active/inactive. Rerun `lan-up` to +reconstruct missing generated state once the VM is running. After a host DHCP +address change, rerun `lan-up` and use its newly printed endpoint. Existing +host/network firewalls still apply; the helper does not grant broad firewall +access or configure router forwarding. + +For multiple VMs, export each VM's recorded `RVBOX_TEST_VBOX_VM`, VM UUID, +snapshot name/UUID, and loopback VRDE port, choose a unique profile **and LAN +port**, then repeat that profile/host/VM identity on its lifecycle commands. +Do not reuse `default` to take over another VM's relay. The host-side projects +are `rvbox-rdp-lan-` and state lives under the remote root's +`/` directory, independent of the web gateway's local `.runtime/`. + +The relay uses a digest-pinned [Alpine socat image](https://hub.docker.com/r/alpine/socat) +and Linux [Docker host networking](https://docs.docker.com/engine/network/drivers/host/) +to reach the existing loopback backend without changing its bind address. +It runs non-root, read-only, without Linux capabilities or host mounts, with +32 MiB/32-PID limits, at most 16 children, and bounded logs. No host package, +Windows service, or persistent broker is installed. + ## Current fixture quick start The following is the copy/paste path for the documented `rvbox-win10-test` diff --git a/test/rdp-access/compose-lan.yaml b/test/rdp-access/compose-lan.yaml new file mode 100644 index 0000000..c06e7af --- /dev/null +++ b/test/rdp-access/compose-lan.yaml @@ -0,0 +1,25 @@ +services: + relay: + image: alpine/socat@sha256:82ad20f6f6e29b91ff33b6662d24063522b1378f08fd8569cd3ab412cac13f50 + # On Linux this reaches the host's existing loopback-only VRDE socket. + # Never publish on 0.0.0.0, and never mount the Docker socket or host files. + network_mode: host + user: "65534:65534" + read_only: true + cap_drop: [ALL] + security_opt: [no-new-privileges:true] + restart: unless-stopped + mem_limit: 32m + pids_limit: 32 + command: + - -d + - -d + - TCP4-LISTEN:${LAN_PORT},bind=${LAN_BIND},range=${LAN_CIDR},reuseaddr,fork,max-children=16,keepalive + - TCP4:127.0.0.1:${VRDE_PORT},connect-timeout=5,keepalive + labels: + rvbox.rdp.lan.managed_by: test/rdp-access/rdp-access + rvbox.rdp.lan.profile: ${LAN_PROFILE} + rvbox.rdp.lan.vm_uuid: ${VM_UUID} + logging: + driver: json-file + options: {max-size: 1m, max-file: "2"} diff --git a/test/rdp-access/lan-access b/test/rdp-access/lan-access new file mode 100644 index 0000000..0e2e148 --- /dev/null +++ b/test/rdp-access/lan-access @@ -0,0 +1,203 @@ +#!/bin/sh +# LAN-only, Docker-contained relay on the VirtualBox host. No Windows changes. +set -eu +helper_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +repo_root=$(CDPATH= cd -- "$helper_dir/../.." && pwd) +: "${RVBOX_TEST_VBOX_HOST:=helium-remote}" +: "${RVBOX_TEST_VBOX_VM:=rvbox-win10-test}" +: "${RVBOX_TEST_VBOX_VM_UUID:=6cdc114f-71e5-4167-a394-e922e14e6f5c}" +: "${RDP_ACCESS_PROFILE:=default}" +: "${RDP_ACCESS_LAN_BIND:=auto}" +: "${RDP_ACCESS_LAN_CIDR:=auto}" +: "${RDP_ACCESS_LAN_PORT:=3389}" +: "${RDP_ACCESS_VRDE_PORT:=3389}" +: "${RDP_ACCESS_LAN_REMOTE_ROOT:=/home/cabbage/.local/state/rvbox-rdp-access/lan}" + +usage() { + printf '%s\n' 'usage: test/rdp-access/rdp-access lan-up|lan-status|lan-down|lan-clean [--profile NAME] [--lan-bind PRIVATE-IP] [--lan-port PORT] [--lan-cidr SUBNET] [--images]' + printf '%s\n' 'Defaults: auto-detect the Helium LAN address/subnet, port 3389, profile default.' + printf '%s\n' 'Only lan-up uses bind/port/cidr overrides. Status/down/clean use saved remote state.' +} +fail() { printf 'lan-access: %s\n' "$*" >&2; exit 2; } +safe_word() { case $2 in ''|-*|*[!A-Za-z0-9._:/@=-]*) fail "$1 contains unsupported characters" ;; esac; } +private_ipv4() { + printf '%s\n' "$1" | awk -F. ' + NF != 4 { exit 1 } + { for (i=1;i<=4;i++) if ($i !~ /^[0-9]+$/ || $i+0>255 || (length($i)>1 && substr($i,1,1)=="0")) exit 1 } + { exit !(($1==10) || ($1==172 && $2>=16 && $2<=31) || ($1==192 && $2==168)) }' +} +port() { + case $2 in ''|*[!0-9]*) fail "$1 must be numeric" ;; esac + [ "$2" -ge 1024 ] && [ "$2" -le 65535 ] || fail "$1 must be 1024..65535" +} + +action=${1-} +[ -n "$action" ] || { usage; exit 2; } +shift +case $action in --help|-h) usage; exit 0 ;; up|status|down|clean) ;; *) fail 'unknown action' ;; esac +remove_images=false +while [ "$#" -gt 0 ]; do + case $1 in + --profile) [ "$#" -ge 2 ] || fail '--profile needs a value'; RDP_ACCESS_PROFILE=$2; shift 2 ;; + --lan-bind) [ "$#" -ge 2 ] || fail '--lan-bind needs a value'; RDP_ACCESS_LAN_BIND=$2; shift 2 ;; + --lan-port) [ "$#" -ge 2 ] || fail '--lan-port needs a value'; RDP_ACCESS_LAN_PORT=$2; shift 2 ;; + --lan-cidr) [ "$#" -ge 2 ] || fail '--lan-cidr needs a value'; RDP_ACCESS_LAN_CIDR=$2; shift 2 ;; + --images) remove_images=true; shift ;; + --help|-h) usage; exit 0 ;; + *) fail "unknown option $1" ;; + esac +done +case $RDP_ACCESS_PROFILE in ''|*[!a-z0-9-]*|-*) fail 'profile must start with a lowercase alphanumeric and contain only lowercase alphanumeric/hyphen' ;; esac +for name in RVBOX_TEST_VBOX_HOST RVBOX_TEST_VBOX_VM RVBOX_TEST_VBOX_VM_UUID RDP_ACCESS_LAN_REMOTE_ROOT; do + eval "value=\${$name}" + safe_word "$name" "$value" +done +case $RDP_ACCESS_LAN_REMOTE_ROOT in + /home/*/.local/state/*|/srv/*) ;; + *) fail 'remote root must be a dedicated absolute directory under home/.local/state or /srv' ;; +esac +case $RDP_ACCESS_LAN_REMOTE_ROOT in */../*|*/./*|*/..|*/.|*/) fail 'remote root must be a normalized dedicated directory' ;; esac +port RDP_ACCESS_LAN_PORT "$RDP_ACCESS_LAN_PORT" +port RDP_ACCESS_VRDE_PORT "$RDP_ACCESS_VRDE_PORT" +if [ "$RDP_ACCESS_LAN_BIND" != auto ]; then + private_ipv4 "$RDP_ACCESS_LAN_BIND" || fail 'LAN bind must be an RFC1918 IPv4 address, never wildcard/loopback/public' +fi +if [ "$RDP_ACCESS_LAN_CIDR" != auto ]; then + subnet=${RDP_ACCESS_LAN_CIDR%/*}; bits=${RDP_ACCESS_LAN_CIDR##*/} + private_ipv4 "$subnet" || fail 'LAN subnet must use a private IPv4 address' + case $bits in ''|*[!0-9]*) fail 'LAN subnet needs a numeric prefix length' ;; esac + [ "$bits" -ge 8 ] && [ "$bits" -le 32 ] || fail 'LAN subnet prefix must be 8..32' + # Do not permit a mask broader than the private address block itself. + case $subnet in 172.*) [ "$bits" -ge 12 ] || fail '172 LAN subnet prefix must be at least /12' ;; 192.*) [ "$bits" -ge 16 ] || fail '192 LAN subnet prefix must be at least /16' ;; esac +fi +[ "$remove_images" = false ] || [ "$action" = clean ] || fail '--images is valid only with lan-clean' +if [ "$action" = up ]; then + fixture_status=$("$repo_root/scripts/windows/test-host" status) || fail 'fixture identity check failed' + case $fixture_status in *'state=running') ;; *) fail 'prepare/start the VM first; lan-up never resets or boots it' ;; esac +fi +compose_encoded=$(base64 -w 0 "$helper_dir/compose-lan.yaml") +profile=$RDP_ACCESS_PROFILE +remote_dir=$RDP_ACCESS_LAN_REMOTE_ROOT/$profile +project=rvbox-rdp-lan-$profile + +# One SSH round trip for host-side detection, deployment, readiness and state. +# Values crossing the shell boundary have been constrained above; no credentials +# are copied or passed to the relay. Existing VBoxAuthSimple stays authoritative. +run_remote() { +ssh -o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=10 -o ServerAliveCountMax=2 "$RVBOX_TEST_VBOX_HOST" \ + "sh -s -- '$action' '$remote_dir' '$project' '$profile' '$RVBOX_TEST_VBOX_VM' '$RVBOX_TEST_VBOX_VM_UUID' '$RDP_ACCESS_LAN_BIND' '$RDP_ACCESS_LAN_PORT' '$RDP_ACCESS_LAN_CIDR' '$RDP_ACCESS_VRDE_PORT' '$compose_encoded' '$remove_images'" <<'REMOTE' +set -eu +action=$1; dir=$2; project=$3; profile=$4; vm=$5; vm_uuid=$6 +bind=$7; lan_port=$8; cidr=$9; shift 9 +vrde_port=$1; compose_encoded=$2; remove_images=$3 +image=alpine/socat@sha256:82ad20f6f6e29b91ff33b6662d24063522b1378f08fd8569cd3ab412cac13f50 +fail() { printf 'remote lan-access: %s\n' "$*" >&2; exit 2; } +compose() { docker compose --project-name "$project" --env-file "$dir/.env" -f "$dir/compose.yaml" "$@"; } +listener() { ss -H -ltn4 | awk -v endpoint="$1:$2" '$4==endpoint { found=1 } END { exit !found }'; } +assert_owned() { + # Never adopt/stop an unrelated Compose project merely because its name fits. + for container in $(docker ps -aq --filter "label=com.docker.compose.project=$project"); do + owner=$(docker inspect -f '{{index .Config.Labels "rvbox.rdp.lan.managed_by"}}|{{index .Config.Labels "rvbox.rdp.lan.profile"}}|{{index .Config.Labels "rvbox.rdp.lan.vm_uuid"}}' "$container") + [ "$owner" = "test/rdp-access/rdp-access|$profile|$vm_uuid" ] || fail "unowned/mismatched container in project $project" + done +} +[ ! -L "$dir" ] && [ ! -L "$(dirname "$dir")" ] || fail 'remote state directory is a symlink' +for file in .env .env.new compose.yaml; do [ ! -L "$dir/$file" ] || fail 'remote state file is a symlink'; done +docker info >/dev/null +assert_owned +if [ -f "$dir/.env" ]; then + saved_uuid=$(sed -n 's/^VM_UUID=//p' "$dir/.env") + [ -z "$saved_uuid" ] || [ "$saved_uuid" = "$vm_uuid" ] || fail 'saved VM UUID mismatch; select the correct profile/VM identity' +fi + +case $action in + up) + info=$(VBoxManage showvminfo "$vm" --machinereadable) + printf '%s\n' "$info" | grep -Fqx "UUID=\"$vm_uuid\"" || fail 'VM UUID mismatch' + printf '%s\n' "$info" | grep -qx 'VMState="running"' || fail 'VM is not running' + printf '%s\n' "$info" | grep -qx 'vrde="on"' || fail 'VRDE is disabled' + printf '%s\n' "$info" | grep -qx 'vrdeaddress="127.0.0.1"' || fail 'expected private loopback VRDE backend' + printf '%s\n' "$info" | grep -qx "vrdeport=$vrde_port" || fail 'requested backend port does not belong to this VM' + listener 127.0.0.1 "$vrde_port" || fail 'private VRDE backend is not listening' + if [ "$bind" = auto ]; then + bind=$(ip -4 route get 1.1.1.1 | awk '{ for(i=1;i<=NF;i++) if($i=="src") { print $(i+1); exit } }') + fi + # Revalidate the detected value before it can become a socat argument. + printf '%s\n' "$bind" | awk -F. 'NF!=4 { exit 1 } { for(i=1;i<=4;i++) if($i !~ /^[0-9]+$/ || $i+0>255) exit 1; exit !(($1==10)||($1==172&&$2>=16&&$2<=31)||($1==192&&$2==168)) }' || fail 'detected address is not private IPv4; use --lan-bind' + assigned=$(ip -4 -o addr show scope global | awk -v wanted="$bind" '{ split($4,a,"/"); if(a[1]==wanted) { print $4; exit } }') + [ -n "$assigned" ] || fail 'LAN bind is not assigned on this host' + [ "$cidr" != auto ] || cidr=$assigned + cidr_bits=${cidr##*/} + case ${cidr%/*} in + 10.*) [ "$cidr_bits" -ge 8 ] || fail 'interface subnet extends outside private 10/8; specify --lan-cidr' ;; + 172.*) [ "$cidr_bits" -ge 12 ] || fail 'interface subnet extends outside private 172.16/12; specify --lan-cidr' ;; + 192.*) [ "$cidr_bits" -ge 16 ] || fail 'interface subnet extends outside private 192.168/16; specify --lan-cidr' ;; + esac + # Fail on an occupied unowned listener; never kill it or change firewall. + if listener "$bind" "$lan_port" && [ -z "$(docker ps -q --filter "label=com.docker.compose.project=$project")" ]; then + fail 'LAN port already has an unrelated listener; use --lan-port with a free port' + fi + umask 077 + mkdir -p "$dir" + chmod 700 "$dir" + printf '%s' "$compose_encoded" | base64 -d >"$dir/compose.yaml" + printf 'LAN_BIND=%s\nLAN_PORT=%s\nLAN_CIDR=%s\nVRDE_PORT=%s\nLAN_PROFILE=%s\nVM_UUID=%s\n' \ + "$bind" "$lan_port" "$cidr" "$vrde_port" "$profile" "$vm_uuid" >"$dir/.env.new" + mv "$dir/.env.new" "$dir/.env" + compose config -q + compose up -d --pull missing + attempts=0 + while [ "$attempts" -lt 10 ]; do + relay=$(compose ps -q relay) + if [ -n "$relay" ] && [ "$(docker inspect -f '{{.State.Running}}' "$relay")" = true ] && listener "$bind" "$lan_port"; then break; fi + attempts=$((attempts+1)); sleep 1 + done + [ "$attempts" -lt 10 ] || { compose logs --tail 20 relay; fail 'LAN listener did not become ready'; } + printf 'lan_endpoint=%s:%s\nlan_allowed_subnet=%s\nlan_backend=127.0.0.1:%s\nlan_project=%s\n' "$bind" "$lan_port" "$cidr" "$vrde_port" "$project" + printf 'Disconnect the Guacamole desktop before using a native RDP app: VRDE has one console slot.\n' + ;; + status) + printf 'lan_project=%s remote_state=%s\n' "$project" "$dir" + if [ -f "$dir/.env" ] && [ -f "$dir/compose.yaml" ]; then + sed -n '/^LAN_BIND=/p; /^LAN_PORT=/p; /^LAN_CIDR=/p; /^VRDE_PORT=/p' "$dir/.env" + compose ps -a + saved_bind=$(sed -n 's/^LAN_BIND=//p' "$dir/.env"); saved_port=$(sed -n 's/^LAN_PORT=//p' "$dir/.env") + if listener "$saved_bind" "$saved_port"; then printf 'lan_listener=active\n'; else printf 'lan_listener=inactive\n'; fi + saved_backend=$(sed -n 's/^VRDE_PORT=//p' "$dir/.env") + if listener 127.0.0.1 "$saved_backend"; then printf 'lan_backend=active\n'; else printf 'lan_backend=inactive (VM off or VRDE unavailable)\n'; fi + else + printf 'lan_listener=not_configured\n' + [ -z "$(docker ps -aq --filter "label=com.docker.compose.project=$project")" ] || fail 'owned containers remain without configuration; rerun lan-up to recover' + fi + ;; + down|clean) + if [ -f "$dir/.env" ] && [ -f "$dir/compose.yaml" ]; then + compose down --remove-orphans + else + [ -z "$(docker ps -aq --filter "label=com.docker.compose.project=$project")" ] || fail 'configuration missing while owned containers remain; rerun lan-up, then lan-down' + fi + if [ "$action" = clean ]; then + # Delete only known generated files; unexpected content is retained. + rm -f "$dir/.env" "$dir/.env.new" "$dir/compose.yaml" + if [ -d "$dir" ]; then rmdir "$dir" || fail 'unexpected remote state files retained; inspect this exact profile directory'; fi + if [ "$remove_images" = true ]; then + docker image rm "$image" || printf 'Relay image retained because it is shared/in use; no force or global prune was used.\n' + fi + fi + printf 'LAN relay stopped; VM, Windows settings, Guacamole and other profiles are unchanged.\n' + ;; +esac +REMOTE +} +# All four actions converge on the same owned profile. A lost SSH response can +# safely be retried; unlike VM reset/capture, no VM lifecycle mutation occurs. +attempt=1 +while [ "$attempt" -le 4 ]; do + if run_remote; then exit 0; fi + attempt=$((attempt+1)) + if [ "$attempt" -le 4 ]; then + printf 'LAN relay action interrupted/failed; retry %s/4\n' "$attempt" >&2 + sleep 2 + fi +done +fail 'LAN relay action failed after four attempts; inspect lan-status and the reported host error' diff --git a/test/rdp-access/rdp-access b/test/rdp-access/rdp-access index 24c59aa..e3654e8 100755 --- a/test/rdp-access/rdp-access +++ b/test/rdp-access/rdp-access @@ -4,6 +4,13 @@ set -eu helper_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +# LAN access has independent lifecycle/state on Helium, not in this web stack. +case ${1-} in + lan-up|lan-status|lan-down|lan-clean) + lan_action=${1#lan-}; shift + exec sh "$helper_dir/lan-access" "$lan_action" "$@" + ;; +esac repo_root=$(CDPATH= cd -- "$helper_dir/../.." && pwd) runtime_root=$helper_dir/.runtime compose_file=$helper_dir/compose.yaml @@ -36,6 +43,14 @@ Actions: down stop containers and the private SSH watchdog/tunnel; retain generated state clean run down and delete generated state; pass --images to also remove the exact unused Guacamole/nginx images + lan-up expose the existing VRDE endpoint on Helium's private LAN address + lan-status inspect the independent Docker LAN relay on Helium + lan-down stop only that LAN relay; retain its generated configuration + lan-clean stop/delete that LAN profile; --images removes its unused relay image + +LAN options: --profile NAME, --lan-bind PRIVATE-IP, --lan-port PORT, + --lan-cidr SUBNET (default auto LAN address/subnet, port 3389). +LAN access never changes Windows, the VM's loopback VRDE socket, or Guacamole. up options: --profile NAME isolated VM/gateway profile (default default; use one @@ -51,6 +66,7 @@ up options: or high (1920x1080/24-bit); saved per profile --reset-auth discard the saved password hash and prompt again --web-password-stdin read the password once from stdin instead of prompting + --lan also enable the independent Helium LAN RDP relay Environment equivalents: RDP_ACCESS_PROFILE, RDP_ACCESS_BIND, RDP_ACCESS_HTTP_PORT, RDP_ACCESS_TUNNEL_PORT, RDP_ACCESS_PUBLIC_HOST, RDP_ACCESS_WEB_USER, @@ -443,6 +459,7 @@ case $action in --help|-h) usage; exit 0 ;; esac reset_auth=false password_stdin=false remove_images=false +expose_lan=false while [ "$#" -gt 0 ]; do case $1 in --profile) [ "$#" -ge 2 ] || fail "--profile needs a value"; RDP_ACCESS_PROFILE=$2; shift 2 ;; @@ -455,6 +472,7 @@ while [ "$#" -gt 0 ]; do --reset-auth) reset_auth=true; shift ;; --web-password-stdin) password_stdin=true; shift ;; --images) remove_images=true; shift ;; + --lan) expose_lan=true; shift ;; --help|-h) usage; exit 0 ;; *) break ;; esac @@ -514,6 +532,7 @@ esac [ "$remove_images" = false ] || [ "$action" = clean ] || fail "--images is valid only with clean" [ "$reset_auth" = false ] || [ "$action" = up ] || fail "--reset-auth is valid only with up" [ "$password_stdin" = false ] || [ "$action" = up ] || fail "--web-password-stdin is valid only with up" +[ "$expose_lan" = false ] || [ "$action" = up ] || fail "--lan is valid only with up" case $action in up) @@ -546,6 +565,7 @@ case $action in wait_for_gateway || fail "Guacamole stack is running but its HTTPS endpoint did not become ready; inspect Compose logs" start_ipv6_forward if [ -f "$session_file" ]; then sed -n '1p' "$session_file"; fi + if [ "$expose_lan" = true ]; then sh "$helper_dir/lan-access" up --profile "$profile"; fi exit 0 fi mkdir -p "$runtime_dir" @@ -572,6 +592,7 @@ case $action in start_ipv6_forward printf 'Guacamole is ready at https://%s:%s/guacamole/\n' "$RDP_ACCESS_PUBLIC_HOST" "$RDP_ACCESS_HTTP_PORT" printf 'Accept the self-signed certificate warning, then sign in as %s with the fixture password.\n' "$RDP_ACCESS_WEB_USER" + if [ "$expose_lan" = true ]; then sh "$helper_dir/lan-access" up --profile "$profile"; fi ;; status) [ "$#" -eq 0 ] || { usage >&2; fail "status accepts no options"; } diff --git a/test/windowsnative/native_fixture_test.go b/test/windowsnative/native_fixture_test.go index d23a1a9..8935dd3 100644 --- a/test/windowsnative/native_fixture_test.go +++ b/test/windowsnative/native_fixture_test.go @@ -2,6 +2,7 @@ package windowsnative import ( "os" + "os/exec" "path/filepath" "strings" "testing" @@ -84,6 +85,81 @@ func TestNativeFixtureAssets_HP_HARNESS_20(t *testing.T) { } } +func TestLANRelayAssets_HP_HARNESS_22(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) + } + helper := read("test/rdp-access/lan-access") + for _, required := range []string{"assert_owned", "requested backend port does not belong to this VM", "VM UUID mismatch", "saved VM UUID mismatch", "interface subnet extends outside private", "ip -4 route get", "unrelated listener", "compose down --remove-orphans", "rmdir \"$dir\"", "attempt\" -le 4", "one console slot"} { + if !strings.Contains(helper, required) { + t.Fatalf("LAN helper is missing safety/lifecycle contract %q", required) + } + } + for _, prohibited := range []string{"controlvm", "modifyvm", "docker system prune", "rm -rf", "--privileged", "sudo "} { + if strings.Contains(helper, prohibited) { + t.Fatalf("LAN helper unexpectedly contains %q", prohibited) + } + } + compose := read("test/rdp-access/compose-lan.yaml") + for _, required := range []string{"alpine/socat@sha256:", "network_mode: host", "bind=${LAN_BIND},range=${LAN_CIDR}", "TCP4:127.0.0.1:${VRDE_PORT}", "read_only: true", "cap_drop: [ALL]", "65534:65534", "mem_limit: 32m", "rvbox.rdp.lan.vm_uuid"} { + if !strings.Contains(compose, required) { + t.Fatalf("LAN relay Compose asset is missing %q", required) + } + } + entrypoint := read("test/rdp-access/rdp-access") + if !strings.Contains(entrypoint, "lan-up|lan-status|lan-down|lan-clean") || !strings.Contains(entrypoint, "--lan) expose_lan=true") { + t.Fatal("LAN lifecycle is not exposed through the existing RDP helper") + } +} + +func TestLANRelayRejectsUnsafeOptions_BH_HARNESS_22(t *testing.T) { + t.Parallel() + root := filepath.Clean(filepath.Join("..", "..")) + // Any accidental attempt to reach SSH must fail locally and be detectable. + fakeBin := t.TempDir() + if err := os.WriteFile(filepath.Join(fakeBin, "ssh"), []byte("#!/bin/sh\necho UNEXPECTED_SSH_ATTEMPT >&2\nexit 99\n"), 0700); err != nil { + t.Fatal(err) + } + for _, tc := range []struct { + name string + args []string + }{ + {"wildcard", []string{"--lan-bind", "0.0.0.0"}}, + {"loopback", []string{"--lan-bind", "127.0.0.1"}}, + {"public", []string{"--lan-bind", "8.8.8.8"}}, + {"invalid_octet", []string{"--lan-bind", "192.168.50.999"}}, + {"shell_injection", []string{"--lan-bind", "192.168.50.1;id"}}, + {"high_port", []string{"--lan-port", "65536"}}, + {"privileged_port", []string{"--lan-port", "22"}}, + {"wide_192_subnet", []string{"--lan-cidr", "192.168.50.0/8"}}, + {"wide_172_subnet", []string{"--lan-cidr", "172.20.0.0/8"}}, + {"public_subnet", []string{"--lan-cidr", "0.0.0.0/0"}}, + {"profile_traversal", []string{"--profile", "../other"}}, + {"remote_root_traversal", nil}, + {"images_on_up", []string{"--images"}}, + } { + t.Run(tc.name, func(t *testing.T) { + args := append([]string{filepath.Join(root, "test/rdp-access/rdp-access"), "lan-up"}, tc.args...) + cmd := exec.Command("sh", args...) + cmd.Env = append(os.Environ(), "PATH="+fakeBin+":"+os.Getenv("PATH"), "RDP_ACCESS_PROFILE=default", "RDP_ACCESS_LAN_BIND=auto", "RDP_ACCESS_LAN_CIDR=auto", "RDP_ACCESS_LAN_PORT=3389") + if tc.name == "remote_root_traversal" { + cmd.Env = append(cmd.Env, "RDP_ACCESS_LAN_REMOTE_ROOT=/home/cabbage/.local/state/../other") + } + output, err := cmd.CombinedOutput() + if err == nil || !strings.Contains(string(output), "lan-access:") || strings.Contains(string(output), "UNEXPECTED_SSH_ATTEMPT") { + t.Fatalf("unsafe input was not rejected before SSH: error=%v output=%s", err, output) + } + }) + } +} + // Static safety contracts complement the live Windows device/GUI checks. func TestMouseFilterRecoveryAssets_HP_HARNESS_21(t *testing.T) { t.Parallel()