Range Functional Smoke¶
Automated proof that a participant can actually use a range: an interactive terminal that exchanges real data with a range host, and a Guacamole session driven to a client-level connection. Run it on demand—before an event, or after a change that touches terminal or Guacamole wiring.
Implementation: uat/range-functional-smoke/ (issue
#987).
What it closes¶
The existing automated live-range check (post-deploy range smoke) stops at a TCP connection to ports 22 and 3389. Whether a participant can open a working terminal or a Guacamole session was verified only by hand. The June 2026 failures that reached users—terminal SSH wiring and Guacamole bootstrap—are exactly the class a port probe cannot see.
Unlike the rest of this directory's protocols, this one needs no Browser steps: it drives the real HTTP, WebSocket, and Guacamole paths end to end.
Preconditions¶
- A deployed tenant that is already healthy (this check does not re-prove deployment health or image boot—those are the built-image stack smoke and deploy-health verify).
- A known-up example range: owned by the account you authenticate as, in
ready, with an instance whose authoredparticipant_accessdeclares the channel you are checking. A missing or not-ready range fails the run—it is never a green skip. - A participant session, from either actor source below.
Actor sources¶
Both are real logins. There is no bypass: /dev-login/ is dev-only and disabled
outside ENVIRONMENT=development, and no Admin-SDK custom token, superuser path,
or smoke-only session endpoint is used.
Captured session—log in normally in a browser, copy the sessionid cookie
into a 0600 file, and pass --session-file. The harness refuses a
group- or world-readable file.
Front-door login—for a credential the tenant operator provisioned: password
sign-in, the TOTP second factor, then the product's own
POST /auth/identity/session/ exchange, which independently re-checks
emailVerified and enrolled MFA before creating the session. Secrets are read
from SMOKE_PASSWORD / SMOKE_TOTP_SECRET / SMOKE_API_KEY, never argv.
Identity Platform tenants require enrolled MFA
config.identity_platform refuses to create an app session for an account
with no enrolled factor. A validation account therefore needs a TOTP factor
enrolled before it can be used—for a headless run or by a human.
Running it¶
cd uat/range-functional-smoke
uv sync --group dev
uv run range-functional-smoke \
--origin https://<portal-host> \
--environment <name> \
--target-role attacker \
--protocol rdp \
--session-file ~/.shifter/smoke.session
--protocol defaults to rdp: the terminal check already proves the SSH path,
so driving Guacamole over RDP widens real coverage. Exit code is 0 only on an
overall pass. A production-looking target is refused unless
--allow-production is passed.
Reading the verdict¶
The report lists every check separately—range readiness, target selection, terminal socket, terminal exchange, and the four Guacamole evidence levels—and is a pass only if all of them passed.
Two rows carry the product claim:
terminal_nonce_exchange—input produced matching output from the guest's own shell. A WebSocket upgrade alone is not sufficient.guacamole_session_connected—guacd completed the protocol handshake and opened the session. Bootstrapsucceededand one-time URL delivery are necessary but not sufficient: they prove only that the server minted a credential.
A run that reports guacamole_bootstrap_succeeded: passed alongside
guacamole_session_connected: failed means the portal is minting session
credentials that guacd cannot use—a real user-facing outage, not a harness
problem.
The report carries identifiers and provenance only: no cookie, token, Guacamole URL, SSH key, private address, raw response body, traceback, or terminal output.
Scope¶
This check proves the participant journey. It is not an isolation proof (see
range-escape validation), not a capacity
proof (see uat/event-load-harness), and not scenario-content verification.
It never provisions or destroys a range: the example range belongs to whoever
created it.