[PR #6170] [client, management] Add embedded VNC server #27663

Open
opened 2026-08-05 07:09:04 -04:00 by saavagebueno · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/netbirdio/netbird/pull/6170
Author: @lixmal
Created: 5/16/2026
Status: 🔄 Open

Base: mainHead: embedded-vnc


📝 Commits (10+)

  • 9f0aa1c Add embedded VNC server with JWT auth and per-peer toggle
  • 62cf9e8 Track active VNC sessions in status and address CodeRabbit findings
  • 7123e6d Fix Windows lint errcheck/unused and Linux nilerr in console VNC fallback
  • 9b5541d Extract session-address anonymization helper to lower status complexity
  • 738c585 Guard VNC session negotiated encoding state with RWMutex
  • 94068d3 Drop -ac from Xvfb/Xorg invocations to keep xhost localuser grant authoritative
  • a8541a1 Apply posture and validated-peers filtering on ResourceTypePeer policy resolution
  • 8bf13b0 Merge SSH wildcard authorized users across matching rules
  • fa90283 Extract wildcard user merge helper to satisfy case-clause length
  • d6d3fa9 Drop unused getPeerFromResource helper

📊 Changes

183 files changed (+25089 additions, -2312 deletions)

View changed files

📝 client/cmd/up.go (+59 -43)
client/cmd/vnc_agent.go (+100 -0)
client/cmd/vnc_agent_darwin.go (+18 -0)
client/cmd/vnc_agent_dropprivs_darwin.go (+77 -0)
client/cmd/vnc_agent_dropprivs_darwin_test.go (+55 -0)
client/cmd/vnc_agent_dropprivs_testhelpers_darwin.go (+11 -0)
client/cmd/vnc_agent_dropprivs_windows.go (+14 -0)
client/cmd/vnc_agent_windows.go (+15 -0)
client/cmd/vnc_flags.go (+16 -0)
📝 client/configs/configs.go (+16 -5)
client/internal/approval/broker.go (+219 -0)
client/internal/approval/broker_test.go (+434 -0)
client/internal/approval/fingerprint_test.go (+62 -0)
📝 client/internal/auth/auth.go (+1 -0)
📝 client/internal/connect.go (+3 -0)
📝 client/internal/debug/debug.go (+6 -0)
📝 client/internal/debug/debug_test.go (+2 -0)
📝 client/internal/engine.go (+35 -1)
📝 client/internal/engine_ssh.go (+6 -10)
client/internal/engine_vnc.go (+329 -0)

...and 80 more files

📄 Description

Describe your changes

Adds an opt-in embedded VNC server to the client so peers can be remoted into without installing or running external VNC software. Access is gated per-peer with a "VNC enabled" toggle and per-policy ACLs, with browser-side connections going over the existing WireGuard tunnel.

Highlights:

  • Cross-platform capture and input: X11, Wayland via Xvfb session, macOS (CoreGraphics + CGEvent), Windows (DXGI desktop duplication + SendInput), FreeBSD framebuffer.
  • Per-session user agents on Windows and macOS: the daemon runs as a system service and brokers connections, but capture and input need a per-user context. Windows spawns a vnc-agent into the active WTS session via CreateProcessAsUser; macOS spawns one via launchctl asuser into the console user's launchd domain. The agents are recycled on session change (logout, fast user switch).
  • Windows secure desktop: a SAS listener brokers Ctrl+Alt+Del so login screens, UAC prompts, and the lock screen are reachable.
  • Per-peer policy: VNC access is gated by policy and a per-peer "VNC enabled" setting, surfaced through the dashboard API and the gRPC peer capability.
  • Noise_IK session auth: the dashboard generates an X25519 keypair inside the WASM client per connection and registers the public key with management as part of an ephemeral access grant. The daemon accepts the connection only after a Noise_IK handshake against that allowlisted key; the private key never leaves WASM.
  • vnc-agent subcommand powering both the Windows and macOS user-session workers.

#6135

Stack

Checklist

  • Is it a bug fix
  • Is a typo/documentation fix
  • Is a feature enhancement
  • It is a refactor
  • Created tests that fail without the change (if possible)

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Documentation

Select exactly one:

  • I added/updated documentation for this change
  • Documentation is not needed for this change (explain why)

Docs will follow in a separate PR.

Docs PR URL (required if "docs added" is checked)

Paste the PR link from https://github.com/netbirdio/docs here:

https://github.com/netbirdio/docs/pull/__

Summary by CodeRabbit

  • New Features

    • Added embedded VNC server controls, inbound approval workflows, view-only access, and session status reporting.
    • Added clipboard synchronization, text input, cursor support, optimized screen updates, and temporary-access authorization.
    • Added browser-based VNC proxy support with cross-platform screen capture and input handling.
  • Bug Fixes

    • Improved VNC authorization, configuration synchronization, session lifecycle, and status reporting.
  • Documentation

    • Added VNC management policies and localized UI text.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbirdio/netbird/pull/6170 **Author:** [@lixmal](https://github.com/lixmal) **Created:** 5/16/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `embedded-vnc` --- ### 📝 Commits (10+) - [`9f0aa1c`](https://github.com/netbirdio/netbird/commit/9f0aa1ce26c09883a507cda469f605df3d562674) Add embedded VNC server with JWT auth and per-peer toggle - [`62cf9e8`](https://github.com/netbirdio/netbird/commit/62cf9e873b0f86b56d0b7dd166403f1dbf6e3c9f) Track active VNC sessions in status and address CodeRabbit findings - [`7123e6d`](https://github.com/netbirdio/netbird/commit/7123e6d1f4e3b505c59e626eeaed1212413e8bea) Fix Windows lint errcheck/unused and Linux nilerr in console VNC fallback - [`9b5541d`](https://github.com/netbirdio/netbird/commit/9b5541d17d8e712fc36243fdcd58fcf2290a9e53) Extract session-address anonymization helper to lower status complexity - [`738c585`](https://github.com/netbirdio/netbird/commit/738c585ee74eda93f5280d731eb00485ae3d47a7) Guard VNC session negotiated encoding state with RWMutex - [`94068d3`](https://github.com/netbirdio/netbird/commit/94068d3ebc486ad47cd6c04e57a51279e7c5f6ab) Drop -ac from Xvfb/Xorg invocations to keep xhost localuser grant authoritative - [`a8541a1`](https://github.com/netbirdio/netbird/commit/a8541a152993afc516f22aa4d7ee635220553ce4) Apply posture and validated-peers filtering on ResourceTypePeer policy resolution - [`8bf13b0`](https://github.com/netbirdio/netbird/commit/8bf13b0d0ced050a059a4c9b43f795a492230df0) Merge SSH wildcard authorized users across matching rules - [`fa90283`](https://github.com/netbirdio/netbird/commit/fa90283781bc2f53b8f01592d65f1c7221632998) Extract wildcard user merge helper to satisfy case-clause length - [`d6d3fa9`](https://github.com/netbirdio/netbird/commit/d6d3fa95c7fbef0b3114c36d11da27fcb7ae9d54) Drop unused getPeerFromResource helper ### 📊 Changes **183 files changed** (+25089 additions, -2312 deletions) <details> <summary>View changed files</summary> 📝 `client/cmd/up.go` (+59 -43) ➕ `client/cmd/vnc_agent.go` (+100 -0) ➕ `client/cmd/vnc_agent_darwin.go` (+18 -0) ➕ `client/cmd/vnc_agent_dropprivs_darwin.go` (+77 -0) ➕ `client/cmd/vnc_agent_dropprivs_darwin_test.go` (+55 -0) ➕ `client/cmd/vnc_agent_dropprivs_testhelpers_darwin.go` (+11 -0) ➕ `client/cmd/vnc_agent_dropprivs_windows.go` (+14 -0) ➕ `client/cmd/vnc_agent_windows.go` (+15 -0) ➕ `client/cmd/vnc_flags.go` (+16 -0) 📝 `client/configs/configs.go` (+16 -5) ➕ `client/internal/approval/broker.go` (+219 -0) ➕ `client/internal/approval/broker_test.go` (+434 -0) ➕ `client/internal/approval/fingerprint_test.go` (+62 -0) 📝 `client/internal/auth/auth.go` (+1 -0) 📝 `client/internal/connect.go` (+3 -0) 📝 `client/internal/debug/debug.go` (+6 -0) 📝 `client/internal/debug/debug_test.go` (+2 -0) 📝 `client/internal/engine.go` (+35 -1) 📝 `client/internal/engine_ssh.go` (+6 -10) ➕ `client/internal/engine_vnc.go` (+329 -0) _...and 80 more files_ </details> ### 📄 Description ## Describe your changes Adds an opt-in embedded VNC server to the client so peers can be remoted into without installing or running external VNC software. Access is gated per-peer with a "VNC enabled" toggle and per-policy ACLs, with browser-side connections going over the existing WireGuard tunnel. Highlights: - **Cross-platform capture and input**: X11, Wayland via Xvfb session, macOS (CoreGraphics + CGEvent), Windows (DXGI desktop duplication + SendInput), FreeBSD framebuffer. - **Per-session user agents on Windows and macOS**: the daemon runs as a system service and brokers connections, but capture and input need a per-user context. Windows spawns a `vnc-agent` into the active WTS session via `CreateProcessAsUser`; macOS spawns one via `launchctl asuser` into the console user's launchd domain. The agents are recycled on session change (logout, fast user switch). - **Windows secure desktop**: a SAS listener brokers Ctrl+Alt+Del so login screens, UAC prompts, and the lock screen are reachable. - **Per-peer policy**: VNC access is gated by policy and a per-peer "VNC enabled" setting, surfaced through the dashboard API and the gRPC peer capability. - **Noise_IK session auth**: the dashboard generates an X25519 keypair inside the WASM client per connection and registers the public key with management as part of an ephemeral access grant. The daemon accepts the connection only after a Noise_IK handshake against that allowlisted key; the private key never leaves WASM. - **`vnc-agent` subcommand** powering both the Windows and macOS user-session workers. ## Issue ticket number and link #6135 ## Stack <!-- branch-stack --> ### Checklist - [ ] Is it a bug fix - [ ] Is a typo/documentation fix - [x] Is a feature enhancement - [ ] It is a refactor - [ ] Created tests that fail without the change (if possible) > By submitting this pull request, you confirm that you have read and agree to the terms of the [Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md). ## Documentation Select exactly one: - [ ] I added/updated documentation for this change - [x] Documentation is **not needed** for this change (explain why) Docs will follow in a separate PR. ### Docs PR URL (required if "docs added" is checked) Paste the PR link from https://github.com/netbirdio/docs here: https://github.com/netbirdio/docs/pull/__ <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added embedded VNC server controls, inbound approval workflows, view-only access, and session status reporting. * Added clipboard synchronization, text input, cursor support, optimized screen updates, and temporary-access authorization. * Added browser-based VNC proxy support with cross-platform screen capture and input handling. * **Bug Fixes** * Improved VNC authorization, configuration synchronization, session lifecycle, and status reporting. * **Documentation** * Added VNC management policies and localized UI text. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
saavagebueno added the pull-request label 2026-08-05 07:09:04 -04:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#27663