mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2025-12-18 16:35:48 -07:00
62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
# Borealis Reverse VPN Tunnels (WireGuard) – Operator & Developer Guide
|
||
|
||
This document is the reference for Borealis reverse VPN tunnels built on WireGuard. The legacy WebSocket framing and domain-lane tunnel stack has been retired; the system now uses a single outbound WireGuard tunnel per agent with host-only routing and per-device ACLs.
|
||
|
||
## 1) High-Level Model
|
||
- Outbound-only: agents establish WireGuard tunnels to the Engine; no inbound access on devices.
|
||
- Transport: WireGuard/UDP on port 30000.
|
||
- Sessions: one live VPN tunnel per agent; multiple operators share it.
|
||
- Routing: host-only /32 per agent; AllowedIPs restricted to the agent /32 and engine /32; no client-to-client.
|
||
- Idle timeout: 15 minutes of no operator activity; no grace period.
|
||
- Keys: WireGuard server keys under `Engine/Certificates/VPN_Server`; client keys under `Agent/Borealis/Certificates/VPN_Client`.
|
||
|
||
## 2) Engine Components
|
||
- Orchestrator: `Data/Engine/services/VPN/vpn_tunnel_service.py`
|
||
- Allocates per-agent /32, issues short-lived orchestration tokens, enforces single-session.
|
||
- Starts/stops WireGuard listener, applies firewall rules, idles out on inactivity.
|
||
- Emits Socket.IO events: `vpn_tunnel_start`, `vpn_tunnel_stop`, `vpn_tunnel_activity`.
|
||
- WireGuard manager: `Data/Engine/services/VPN/wireguard_server.py`
|
||
- Generates server keys, renders config, manages `wireguard.exe` tunnel service, applies ACL rules.
|
||
- PowerShell bridge: `Data/Engine/services/WebSocket/vpn_shell.py`
|
||
- Proxies UI shell input/output to the agent’s TCP shell server over WireGuard.
|
||
- Logging: `Engine/Logs/reverse_tunnel.log` plus Device Activity entries.
|
||
|
||
## 3) API Endpoints
|
||
- `POST /api/tunnel/connect` → issues session material (tunnel_id, token, virtual_ip, endpoint, allowed_ports, idle_seconds).
|
||
- `GET /api/tunnel/status` → returns up/down status for an agent.
|
||
- `GET /api/tunnel/connect/status` → alias for status (used by UI before shell open).
|
||
- `DELETE /api/tunnel/disconnect` → immediate teardown (agent + engine cleanup).
|
||
- `GET /api/device/vpn_config/<agent_id>` → read per-agent allowed ports.
|
||
- `PUT /api/device/vpn_config/<agent_id>` → update allowed ports.
|
||
|
||
## 4) Agent Components
|
||
- Tunnel lifecycle: `Data/Agent/Roles/role_WireGuardTunnel.py`
|
||
- Validates orchestration tokens, starts/stops WireGuard client service, enforces idle.
|
||
- Shell server: `Data/Agent/Roles/role_VpnShell.py`
|
||
- TCP PowerShell server bound to `0.0.0.0:47001`, restricted to VPN subnet (10.255.x.x).
|
||
- Logging: `Agent/Logs/reverse_tunnel.log`.
|
||
|
||
## 5) Security & Auth
|
||
- TLS pinned for Engine API/Socket.IO.
|
||
- Orchestration tokens signed via Engine Ed25519 key; agent verifies signatures and stores the signing key.
|
||
- WireGuard AllowedIPs /32; no LAN routes; client-to-client blocked.
|
||
- Engine firewall rules enforce per-device allowed ports.
|
||
|
||
## 6) UI
|
||
- Device details now include an “Advanced Config” tab for per-device allowed ports.
|
||
- PowerShell MVP reuses `Data/Engine/web-interface/src/Devices/ReverseTunnel/Powershell.jsx` with WireGuard APIs + VPN shell events.
|
||
|
||
## 7) Extending to New Protocols
|
||
- Add protocol ports to the device allowlist and UI toggles.
|
||
- Reuse the existing VPN tunnel; no new transport/domain lanes required.
|
||
|
||
## 8) Legacy Removal
|
||
- WebSocket tunnel domains, protocol handlers, and domain limits are removed.
|
||
- No `/tunnel` Socket.IO namespace or framed protocol messages remain.
|
||
|
||
## 9) Change Log (not exhaustive)
|
||
- 2025-11-30: Legacy WebSocket tunnel scaffold introduced (lease manager, framing, tokens).
|
||
- 2025-12-06: Legacy PowerShell handler simplified to pipes-only; UI status tweaks.
|
||
- 2025-12-18: Legacy domain lanes added (`remote-interactive-shell`, `remote-management`, `remote-video`) with limits.
|
||
- 2025-12-20: WireGuard reverse VPN migration complete; legacy WebSocket tunnels retired; VPN shell bridge + new APIs.
|