QuickZTNA
User Guide

Verify key generation, ChaCha20-Poly1305 encryption, and that private keys never leave the machine.

Verify tunnel establishment, peer visibility, DERP relay selection, and end-to-end ping across the mesh.

Measure baseline latency, throughput via DERP vs direct, reconnect time, and verify no performance regressions.

Controlled penetration tests: port scans, traffic interception, key extraction, and replay attacks.

Test auth-key misuse, configuration hardening, known CVE exposure, and binary integrity verification.

Understand and verify how DERP relay servers provide encrypted fallback paths when direct WireGuard UDP tunnels cannot be established.

Verify that the client selects the nearest DERP region and handles DERP server unavailability gracefully.

Verify that the client uses STUN discovery and UDP hole-punching to establish direct peer connections through NAT devices.

Confirm direct peer-to-peer WireGuard connections are active, measure their performance vs relay, and verify they bypass DERP entirely.

Use ztna netcheck, ztna debug, and ztna bugreport to diagnose connectivity issues, verify STUN reachability, and collect diagnostic bundles for support.

Verify the email/password signup and login flow — including rate limiting, account lockout after failed attempts, and correct token issuance.

Verify the GitHub OAuth login flow — both from the dashboard (browser) and from the CLI — including state parameter validation and token exchange.

Verify the Google OAuth login flow — both from the dashboard and CLI — including token exchange, email verification, and new user auto-creation.

Verify TOTP-based multi-factor authentication — setup, verification, login enforcement, backup codes, and disable flow.

Verify JWT access token expiry, refresh token rotation, logout invalidation, and the CLI auto-refresh mechanism.

Register machines non-interactively using pre-authenticated keys — verify auth key creation, headless registration, re-registration, and key restrictions.

Register machines interactively via browser-based OAuth login — verify the CLI-to-browser flow, client-setup endpoint, and WireGuard config generation.

Verify admin approval of pending machines — approve, enable, disable, quarantine actions and their effect on heartbeat and connectivity.

Verify the heartbeat mechanism — online/offline status transitions, connectivity telemetry, peer list delivery, key expiry enforcement, and update detection.

Verify machine deletion — dashboard and API deletion, cascade cleanup of related records, audit data preservation, and client-side cleanup via ztna logout.

Verify machine rename and tag management — via CLI (ztna set), API (machine-admin), and dashboard edit dialog — including name validation and tag-based ACL integration.

Verify per-machine network flags — shields up, SSH enabled, accept routes, advertise exit node — via CLI (ztna set), API (update_flags), and dashboard toggle.

Verify WireGuard configuration export — download via CLI (ztna wg-config export), verify config structure, validate keys and peer entries, and test with standalone WireGuard.

Verify client version reporting, update availability detection, version comparison logic, and the ztna update command flow.

Verify every section of the machine detail page — settings card, subnets card, machine details card, attributes card, addresses card, connection info card, and all action buttons.

Create allow rules via dashboard and API, verify they permit traffic between specified machines.

Create deny rules and verify they block traffic between specified machines.

Test the ACL evaluation API endpoint — verify allow/deny decisions for specific source/destination/port combinations.

Verify ACL input validation — invalid ports, malformed CIDRs, missing fields, duplicate rules, and protocol validation.

Verify editing existing ACL rules and deleting them — via dashboard and API — and confirm traffic behavior changes immediately.

Create network segmentation groups via dashboard and API — verify group creation, naming, and listing.

Add machines to segmentation groups and verify membership via dashboard and API.

Verify that group membership is reflected in CLI peer listings and machine status.

Create ACL rules that use segmentation groups as source/destination and verify traffic control.

Delete segmentation groups and verify behavior when ACL rules reference the group.

Enable MagicDNS for the organization and verify peer hostname resolution works.

Verify hostname resolution — resolve peer names to tailnet IPs using ztna dns query and system DNS.

Configure custom upstream nameservers for the organization and verify DNS forwarding.

Verify DNS failover — when MagicDNS is unavailable, queries fall back to upstream resolvers.

Verify that DNS resolution works but ACL rules still block actual traffic — DNS and ACLs are independent layers.

Generate auth keys with various configurations — reusable, ephemeral, with expiry dates and IP/tag restrictions.

Register machines using auth keys — verify the headless registration flow and machine status.

Verify auth key usage tracking — used count increments, reusable vs single-use enforcement.

Revoke an auth key and verify that subsequent registration attempts are rejected.

Verify that expired auth keys are rejected during registration and that expiry dates are enforced.

Send organization invitations via email — verify invitation creation, email delivery, and invitation listing.

Accept an organization invitation — verify account creation for new users and org joining for existing users.

Change member roles between member and admin — verify permissions change immediately.

Remove a member from the organization and verify their machines are handled appropriately.

Verify the members list page — user listing, role badges, invite status, and member count accuracy.

Create device posture policies via dashboard and API — define OS version requirements and compliance checks.

Verify that the client sends posture data during registration and heartbeat — disk encryption, antivirus, firewall status.

Verify that a machine failing posture checks is quarantined or flagged as non-compliant.

View posture report history for a machine — verify compliance status tracking over time.

Disable and delete posture policies — verify that machines are no longer evaluated against removed policies.

Issue an X.509 TLS certificate for an internal domain via the QuickZTNA CA -- verify certificate fields and chain.

Issue an SSH certificate for a user or host -- verify certificate type, principals, and validity.

Verify issued certificates using OpenSSL -- check subject, issuer, validity dates, key usage, and chain of trust.

Verify certificate expiry enforcement and revocation -- revoked certificates should be rejected.

Download issued certificates and install them on test machines -- verify TLS connections work with the CA certificate.

Check IP reputation via CLI and API — verify threat score, classification, and data sources.

Check domain reputation — verify malicious domain detection, categorization, and blocking recommendations.

Look up file hashes against threat intelligence feeds — verify known malware detection.

Verify threat feed integration — check feed sources, update frequency, and cached entries.

Verify that high-threat-score IPs/domains are blocked via DNS blocklist delivery in heartbeat.

Create an access review campaign and verify it auto-populates decisions for all active machines and enabled ACL rules.

Submit a JIT access request, approve it as admin, and verify a temporary ACL rule is created. Also test denial and input validation.

Verify JIT grants expire after their duration window, that manual revocation disables the linked ACL rule, and that expired grants cannot be re-approved.

List historical access review campaigns, inspect per-campaign decisions, and verify that revoke decisions are reflected in machine and ACL rule state.

Snapshot a policy before editing it, list version history, and roll back to a previous version. Verify the auto-snapshot-before-rollback behavior.

Load the Audit Log page, confirm Loki-backed entries appear, verify the table columns, and exercise the search bar.

Use the Action Type dropdown to filter audit entries by action category prefix — verify Loki label selector and pipeline filter behaviour.

Apply date range presets and verify Loki start/end timestamps — confirm Today, 7d, 30d, 90d, and All Time behaviour.

Export the audit log as CSV, JSON, and PDF — verify file contents, column headers, and that active filters are respected.

Perform specific control-plane actions and confirm the correct audit entries appear in Loki — covering auth, machine, ACL, auth-key, and API-key events.

Verify that every dashboard metric card — machine count, online count, member count, ACL rule count, threats blocked, active certs, and posture compliance rate — matches the underlying database records returned by the get_dashboard_stats RPC.

Verify the Active Machines list and Team list on the dashboard — correct machines shown, last_seen timestamps formatted correctly, tailnet hostname construction, and member initials rendering.

Verify the health warning cards, the Security Digest (24h) card, and the AI Event Summary card on the dashboard — including anomaly detection logic, plan gating, and the admin-insights daily_digest endpoint.

Verify the OnboardingWizard component — auto-show logic when onlineCount is 0, the 4-step flow (Organization, Install CLI, Connect, Verify), machine approval in-wizard, and the dismiss/skip persistence in localStorage.

Verify that the dashboard updates automatically without page refresh when machines come online or go offline — via the postgres_changes subscription channel, React Query cache invalidation, and the 500ms debounce guard.

Verify the Health page machine list — data source, column rendering, status badges, availability score bar, and heartbeat timestamp display.

Understand and verify the client-side availability score algorithm — three tiers based on status and last_seen freshness — and how the org-wide average is calculated.

Verify that the Health page updates machine status in real-time via WebSocket — channel subscription, UPDATE/DELETE event delivery, fallback polling, and heartbeat timeout eviction.

Verify the DERP relay health check — the on-demand probe button, handleDerpHealth handler, region_health response, active session count, and error states.

Verify all three offline detection paths — graceful shutdown heartbeat, cleanup cron job after 3-minute silence, and ephemeral machine deletion — plus the edge cases around quarantine and admin-disable.

Verify that the Machines page correctly renders all registered machines with their tailnet IPs, statuses, OS types, and network role badges — confirming the complete network inventory view.

Verify that ACL rules represent the permitted and denied traffic paths between machines, and that the ACL evaluator correctly resolves which paths exist in the network topology.

Verify that DERP relay regions are discoverable via the DERP map endpoint, visible in the admin settings UI, and that the CLI correctly identifies and uses the nearest relay node.

Verify that department-level network boundaries are correctly represented in topology data: each department is an isolated org with its own machine inventory, and the parent org can enumerate all departments.

Verify that the Machines page filter and search controls correctly narrow the visible machine inventory, providing a focused view of a subset of the network topology.

Verify that the Billing page loads the correct plan name, usage counters, progress bars, and subscription details from the billing_subscriptions table and feature-check endpoint.

Verify that plan-gated features return FEATURE_GATED (403) on the free plan and are allowed on the appropriate paid plans — tested via the feature-check endpoint and live gated handlers.

Walk through the complete Razorpay subscription creation flow — from clicking Upgrade in the UI to the checkout session being created, the redirect, and the subscription.activated webhook updating the billing_subscriptions table.

Verify that machine registration is blocked when the org reaches its machine_limit quota, and that the limit values in billing_subscriptions match the plan constants enforced by the backend.

Verify the feature comparison table on the Billing page — category collapsing, active plan highlighting, mismatch warnings between the static matrix and live DB features, and accuracy of per-category feature counts.

Create scoped management API keys with configurable expiry, rate limits, and scope restrictions for programmatic access to the QuickZTNA control plane.

Authenticate programmatic API requests using the X-Api-Key header, observe usage tracking, and verify the key context returned by verifyApiKey.

Verify that API key scopes are stored as a JSONB array and that scope metadata is returned correctly; test rate limiting enforcement via Valkey.

Revoke an API key via the revoke_api_key action and verify the key is immediately rejected for all subsequent requests; also test the rotate_api_key action.

Test all five Terraform API resources — machines, acl-rules, dns, users, settings — using the dedicated /api/terraform/* endpoint authenticated with an API key.

Verify that the handleExportData handler at POST /api/export correctly exports machines and audit logs in JSON format, enforces admin-only access, requires valid org_id, and returns the correct response envelope.

Verify that POST /api/export with action 'machines' and format 'csv' returns a well-formed CSV string with the correct header row, one row per machine, CSV-injection-safe values, and the count field matching the row count.

Verify that ACL rule data can be retrieved via the CRUD endpoint and the compliance_report export, cross-check ACL rule counts, and confirm that exported rule structure matches what was configured in the dashboard.

Verify that POST /api/export with action 'audit_logs' returns Loki-backed audit entries in both JSON and CSV formats, that the days parameter controls the lookback window, that admin gating is enforced, and that CSV columns are injection-safe.

Verify that data exported from QuickZTNA via POST /api/export and GET /api/db can be parsed, validated for structural integrity, and — for ACL rules and DNS records — re-imported into the same or a different org via the CRUD insert endpoint.

Verify that the install.sh one-liner correctly detects the OS and architecture, downloads the ztna binary to /usr/local/bin, runs a post-install service setup, and prints the expected success message.

Verify that the PowerShell one-liner installs the ztna binary to %LOCALAPPDATA%\Programs\QuickZTNA, adds it to the user PATH, optionally installs the Windows service, and prints the correct success message.

Verify that passing ZTNA_AUTH_KEY to the install script — or using ztna login --auth-key — registers the machine with the control plane and auto-connects without any browser interaction.

Verify ztna version prints the correct build string, ztna update --check queries the control plane version API, and ztna update downloads and applies a new binary when one is available.

Verify that ztna install registers the system service on Linux (systemd unit quickztna-svc.service) and Windows (service named QuickZTNA), that the service starts on boot, and that ztna uninstall cleanly removes all service artifacts.

Test that the remote shell session creation API correctly issues a one-time token, validates machine status, and enforces the remote_management feature gate.

Test interactive command execution through the WebSocket PTY proxy and script execution via the remote-shell handler, including execution lifecycle and output capture.

Verify that remote shell sessions produce session recording entries in the database and that recording data is stored in Cloudflare R2, including settings, lifecycle, and playback retrieval.

Verify that the remote shell feature gate, admin-only enforcement, and org membership checks correctly restrict shell access — and that non-admin users and wrong-org callers are rejected at every layer.

Test all paths that terminate a remote shell session: user-initiated close, server-side disconnect, agent stream end, session timeout, and recording cleanup after termination.

Verify the full WebRTC signaling handshake: initiate, offer, agent command dispatch, answer polling, and session activation via handleRemoteDesktop.

Verify that screen frames captured via GDI BitBlt on Win-B are chunked, transmitted over WebRTC DataChannel, reassembled in the browser, and rendered at target frame rate.

Verify mouse movement, button clicks, scroll, keyboard keys, and modifier combinations are correctly transmitted over the input DataChannel and injected via Win32 SendInput on the target.

Verify remote desktop session behaviour when WebRTC ICE falls back to TURN/DERP relay, measuring frame rate, latency impact, and session continuity under relay-only conditions.

Verify plan feature gating, admin-vs-peer session type authorization, ACL enforcement for peer sessions, consent workflow, admin terminate, and non-admin disconnect restrictions.

Update the organization name via the API and verify the change propagates — the dashboard Network Name field is read-only in the UI.

Toggle the allow_exit_nodes setting for the org and verify that machines can or cannot advertise as exit nodes based on the setting.

Toggle allow_subnet_routing for the org, advertise a subnet from Linux-C, and verify the control plane accepts or rejects the advertisement based on the setting.

Set the org-level key expiry policy via the Settings UI and API, verify the value stored in org_settings.key_expiry_days, and confirm the enforce-key-expiry cron respects the setting.

Export org data — machines list, audit logs, and compliance report — via POST /api/export in JSON and CSV formats, and verify the response structure and content.