TailVNC - GitLite

KO | EN

gitlite — search

#command-line #css #developer-tools #terminal #reactjs #http #vue #api #mcp #json

TailVNC

(★ 309)

Tailscale-based Windows VNC persistence tool with Session 0 isolation bypass, embedding a full WireGuard peer and RFB server into a single drop-in binary.

File Explorer

ZIP Download

- image-20260412003923140.png
- image-20260412004037568.png
- - main.go
- obfuscate_key_hex.go
- - deobfuscate_key_hex.go
- - utils.go
- - agent.go
  - clipboard.go
  - input.go
  - ipc.go
  - rfb.go
  - screen.go
  - server.go
go.mod
go.sum
Makefile
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`Tailscale`

View Details ▼

A private WireGuard network service.
Some subcommands such as `up` have their own usage documentation.

sudo tailscale set --operator $USER

Allow the current user to operate on the Tailscale daemon:

tailscale {{up|down|status}}

Handle connection to Tailscale (connect, disconnect, check status):

tailscale set --advertise-exit-node

Offer the current machine to be an exit node for internet traffic:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A Windows remote desktop persistence tool built on top of Tailscale's WireGuard-encrypted mesh network. TailVNC embeds a fully self-contained VNC server and Tailscale node into a single binary, enabling secure remote desktop access over Tailscale/Headscale without exposing any ports to the public internet. Designed for both legitimate infrastructure administration and red team persistence operations.

Inspired by [SockTail](https://github.com/Yeeb1/SockTail).

## Features

- **Tailscale/Headscale Integration** - Leverages `tsnet` to embed a WireGuard peer directly into the binary; supports both official Tailscale coordination and self-hosted Headscale control planes
- **Windows Session 0 Isolation Bypass** - When running as SYSTEM, automatically spawns an agent process in the active user session via `CreateProcessAsUser` and proxies VNC traffic through IPC, circumventing Vista+ session isolation
- **Dynamic Desktop Tracking** - Follows the user across desktop transitions including the default desktop, Winlogon (login screen), UAC secure desktop, and lock screen via `OpenInputDesktop`/`SetThreadDesktop`
- **Ctrl+Alt+Del Injection** - Sends the Secure Attention Sequence from Session 0 via `sas.dll!SendSAS`
- **Bidirectional Clipboard Sync** - Latin-1 clipboard synchronization between VNC client and target host
- **Build-Time Configuration Embedding** - Auth key, VNC password, listen port, and control URL are injected at compile time via LDFLAGS; the resulting binary requires no configuration files at runtime
- **Auth Key Obfuscation** - Tailscale auth key is XOR-obfuscated at build time to prevent plaintext credential exposure in the binary

## Architecture

```
┌──────────────────────────────────────────────┐
│          TailVNC Service (Session 0)         │
│                                              │
│  tsnet.Server ───► Tailscale/Headscale Net   │
│       │                                      │
│  VNC Listener :5900 (Tailscale interface)    │
│       │                                      │
│  ┌────▼───────────────────────────────────┐  │
│  │ Session Manager                        │  │
│  │  - Polls active console session (2s)   │  │
│  │  - Spawns agent via CreateProcessAsUser│  │
│  │  - Auto-restarts on session change     │  │
│  │    or agent crash                      │  │
│  └────┬───────────────────────────────────┘  │
│       │ TCP Proxy (bidirectional)            │
└───────┼──────────────────────────────────────┘
        ▼
┌────────────────────────────────────────┐
│   VNC Agent (User Session, Desktop)    │
│   127.0.0.1:15900                      │
│   - GDI+ screen capture (~30fps)       │
│   - SendInput keyboard/mouse injection │
│   - Clipboard monitoring               │
└────────────────────────────────────────┘
```

## Tech Stack

| Component | Technology |
|-----------|------------|
| Language | Go 1.25+ |
| Network Transport | [Tailscale tsnet](https://pkg.go.dev/tailscale.com/tsnet) — embedded WireGuard peer |
| VNC Protocol | RFB 3.008 (custom implementation, Raw encoding) |
| Screen Capture | Windows GDI+ (`CreateDIBSection`, `BitBlt`) |
| Input Injection | Windows `SendInput` API |
| Session Management | `WTSQueryUserToken` + `CreateProcessAsUser` |
| Desktop Switching | `OpenInputDesktop` + `SetThreadDesktop` |
| SAS Injection | `sas.dll!SendSAS` |
| Authentication | VNC DES challenge-response (per RFB spec) |
| Key Obfuscation | XOR + hex encoding |
| System Calls | `golang.org/x/sys` (Windows syscall wrappers) |
| Binary Compression | UPX (optional) |
| Build System | GNU Make + Go LDFLAGS injection |

## Building

### Prerequisites

- **Go** >= 1.25.3
- **GNU Make**
- **UPX** (optional, for binary size reduction)
- **Tailscale Auth Key** — generate from the Tailscale admin console; reusable + ephemeral keys are recommended for operational use

### Build Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `AUTH_KEY` | Yes | — | Tailscale auth key; automatically XOR-obfuscated and embedded at compile time |
| `LISTEN_PORT` | No | `5900` | VNC listen port on the Tailscale interface |
| `AUTH_PASS` | No | Empty (no auth) | VNC connection password (DES challenge-response) |
| `CONTROL_URL` | No | Empty (official Tailscale) | Headscale control plane URL |
| `CONFIG_DIR` | No | `C:\Windows\Temp\.cache` | Persistent tsnet state directory (WireGuard keys, node identity) |

### Compilation

```bash
# Minimal build — only auth key required
make build-vnc AUTH_KEY=tskey-auth-kBEXAMPLEKEY

# Full build with all parameters
# [CONTROL_URL] — optional, only required when using a self-hosted Headscale control plane
# [CONFIG_DIR]  — optional, overrides the default tsnet state directory (C:\Windows\Temp\.cache)
make build-vnc \
  AUTH_KEY=tskey-auth-kBEXAMPLEKEY \
  LISTEN_PORT=5900 \
  AUTH_PASS=VNCPassword \
  [CONTROL_URL=https://headscale.example.com] \
  [CONFIG_DIR='C:\Windows\Temp\.cache']
```

Build artifacts are written to `dist/`:

```
dist/TailVNC-windows-amd64.exe
```

The build pipeline performs the following steps:

1. Cleans previous build artifacts
2. Downloads and tidies Go module dependencies
3. Runs `obfuscator/` to XOR-obfuscate the auth key
4. Injects all configuration into the binary via LDFLAGS (`-X`)
5. Strips the symbol table and DWARF debug info (`-s -w`)
6. Compresses the binary with UPX (`--best --lzma`) if available

### Additional Make Targets

```bash
make clean    # Remove build artifacts
make deps     # Download and tidy Go modules
make help     # Print usage and parameter reference
```

## Usage

**TailVNC must run with SYSTEM privileges.** When executing in Session 0 (as a Windows service or under SYSTEM context), the tool automatically detects the active console session, spawns an agent process within it for screen capture and input injection, and proxies all VNC traffic. If launched directly within an interactive user session, it operates in local mode without the agent proxy layer.

Upon execution, the target host joins the configured Tailscale network as a new node. Connect using any standard VNC client:

```
<Tailscale IP>:5900
```

![image-20260412003923140](https://raw.githubusercontent.com/wh0amitz/TailVNC/master/assets/image-20260412003923140.png)

![image-20260412004037568](https://raw.githubusercontent.com/wh0amitz/TailVNC/master/assets/image-20260412004037568.png)