Most VPNs announce themselves. WireGuard has a recognizable handshake. Many TLS tunnels still look like long-lived VPN sessions once you inspect the flow.

MASQUE takes another route: proxy arbitrary IP traffic inside HTTP/3, so the outer session looks much closer to normal QUIC/HTTPS.

We published an educational implementation under CloudBridge Research:

github.com/cloudbridge-research/masque-vpn

MIT · ~94★ · Go · CONNECT-IP over QUIC/HTTP3 · REST API · Prometheus · student docs in EN/RU/ZH

Lab / research code. Great for protocol study and teaching — not a hardened appliance with an SLA.

It builds on the original work by iselt/masque-vpn. CloudBridge Research forked and extended it into a fuller educational platform (custom CONNECT-IP path, API, tests, monitoring, labs).

Why CONNECT-IP?

RFC 9484 defines CONNECT-IP: tunnel IP packets through an HTTP connection. Over HTTP/3 that means:

  1. Client opens a QUIC connection to the proxy.
  2. Client sends a MASQUE CONNECT-IP request.
  3. After success, IP packets ride QUIC streams / datagrams instead of a dedicated VPN UDP port with its own fingerprint.

Useful when you want to:

  • learn QUIC / HTTP/3 beyond “JSON API over UDP”
  • research DPI-resistant transports that blend with HTTPS
  • teach how modern proxies move L3 traffic

Inside CloudBridge this sits next to QUIC, WireGuard, WebRTC and AmneziaWG as one mesh transport option — so we needed a readable reference, not only a black box.

MASQUE VPN data-flow architecture

What’s in the repo

Path Role
vpn_server/ CONNECT-IP handler, IP pool, optional TUN, metrics
vpn_client/ QUIC client that tunnels packets
REST API :8080 health, status, clients, stats, config, logs
common/ custom MASQUE CONNECT-IP helpers
admin_webui/ admin UI
monitoring/ + grafana/ observability stack
docs/ architecture, API, student guide
tests/ unit / integration / load
docker-compose.yml containerized bring-up

Also: mutual TLS, automatic client IP allocation, Makefile helpers, and functional protocol smoke tests.

Stack: Go, quic-go, Gin, Zap, Prometheus client.

Local quick start 

git clone https://github.com/cloudbridge-research/masque-vpn.git cd masque-vpn cd vpn_server && go build -o vpn-server . cd ../vpn_client && go build -o vpn-client . cd ../cert && ./generate-test-certs.sh # or generate-certs.ps1 on Windows cd ../vpn_server ./vpn-server -c config.server.local.toml

Local defaults:

  • MASQUE / QUIC → 127.0.0.1:4433
  • REST API → 127.0.0.1:8080 
curl http://127.0.0.1:8080/health curl http://127.0.0.1:8080/api/v1/status curl http://127.0.0.1:8080/api/v1/clients curl http://127.0.0.1:8080/metrics

Point vpn_client at the same address and start it. For a protocol-level check:

go run test_masque_connection.go # or the full local suite ./scripts/test-local.sh

Local server config keeps TUN empty so you can study MASQUE without fighting OS routing on day one:

listen_addr = "127.0.0.1:4433" assign_cidr = "10.0.0.0/24" tun_name = "" log_level = "debug" [api_server] listen_addr = "127.0.0.1:8080"

Architecture notes

Interesting files if you open the tree:

  • common/masque_connectip.go — MASQUE client side
  • common/masque_proxy.go — IP packet proxy helpers
  • vpn_server/internal/server/masque_handler.go — CONNECT-IP handler
  • packet_processor.go — TUN path when enabled
  • api_server.go / metrics.go / tls_config.go — control plane pieces

Design choices we care about for teaching:

  • custom MASQUE layer in-tree (easy to step through)
  • QUIC streams for control / reliable bits
  • QUIC datagrams for packet carriage
  • optional TUN — protocol testing without admin rights
  • REST + Prometheus beside the data plane

Specs in play: RFC 9484 (CONNECT-IP), RFC 9000 (QUIC), RFC 9114 (HTTP/3).

Security as shipped

  • mutual TLS between client and server
  • per-client IP from the configured pool
  • validation of MASQUE headers / parameters
  • self-signed CA scripts for labs — swap to real certs before any serious deploy

If you enable TUN for a fuller tunnel, treat firewalling and certificate distribution as first-class work.

Who this is for

  • students and researchers studying QUIC / HTTP/3 / MASQUE
  • people comparing VPN fingerprints and multi-transport meshes
  • educators who want labs with a real Go codebase

The repo ships a student guide with deployment, performance, protocol deep-dive and impaired-network exercises.

Links

Issues and lab write-ups welcome — especially anything that sharpens the student docs.