kvn-ws

kvn-ws — VPN-туннель через WebSocket/QUIC с маскировкой под обычный веб-трафик. Написан на Go, работает в двух режимах: TUN (VPN) и локальный SOCKS5/HTTP CONNECT прокси. Включает веб-интерфейс (kvn-web) для управления конфигурацией и мониторинга.

• Сервер и клиент в одном Docker-образе (multi-stage build)
• TLS 1.3 + mTLS + WebSocket Binary Frames / QUIC
• TUN (VPN) и Proxy (SOCKS5/HTTP CONNECT) режимы
• Transparent proxy (iptables REDIRECT) + DNS proxy (Linux)
• System proxy — автоустановка/восстановление HTTP_PROXY (Linux, macOS, Windows)
• Обфускация трафика: uTLS (TLS fingerprint), WebSocket padding, QUIC XOR-obfuscation
• SNI rotation — случайный SNI из белого списка при каждом подключении
• Маршрутизация: server/direct, CIDR, DNS-имена, отдельные IP с ordered rules
• DNS-роутинг — маршрутизация DNS-запросов по суффиксу домена
• App-layer шифрование (AES-256-GCM, per-session key derivation)
• Split-tunnel с kill-switch при потере соединения (nftables)
• Dual-stack IPv4/IPv6
• QUIC transport с автоматическим fallback на TCP
• MaxMessageSize защита от OOM в QUIC-транспорте
• Web UI (kvn-web) — конфигурация, логи, импорт/экспорт/QR, статус соединения
• Prometheus-метрики, сессионный менеджмент с BoltDB-персистентностью
• CIDR ACL, rate limiting, per-token bandwidth management
• Netlink API для управления маршрутами (без exec.Command)
• SIGHUP hot-reload конфига
• Graceful shutdown, health endpoints (/livez, /readyz, /health)
• Кроссплатформенный клиент: Linux, macOS, Windows (Web UI)

Quick start (30 sec)

git clone https://github.com/bzdvdn/kvn-ws.git
cd kvn-ws && cp -r examples/* .
bash examples/run.sh

Web UI: http://127.0.0.1:2311

Подробнее: docs/en/quickstart.md · docs/ru/quickstart.md

Documentation

English	Русский
Quickstart	Быстрый старт
Deployment	Развёртывание
Configuration	Конфигурация
Relay Mode	Режим Relay
Architecture	Архитектура

Installation

Server (Linux) — одна команда

Устанавливает бинарник, генерирует конфиг со случайным токеном, настраивает systemd-сервис и nftables.

sudo bash -c "$(curl -sL https://github.com/bzdvdn/kvn-ws/releases/latest/download/install-server.sh)"

С опциями (порт, подсеть, IPv6):

sudo bash -c "$(curl -sL https://github.com/bzdvdn/kvn-ws/releases/latest/download/install-server.sh)" -- --listen :8443 --subnet 10.20.0.0/16 --gateway 10.20.0.1

Client (Linux)

# Install from release
sudo bash -c "$(curl -sL https://github.com/bzdvdn/kvn-ws/releases/latest/download/install-client.sh)" \
  -- -s wss://vpn.example.com/tunnel -t your-token

Client (Windows)

# PowerShell (admin)
iwr -useb https://github.com/bzdvdn/kvn-ws/releases/latest/download/install-client.ps1 -OutFile install-client.ps1
.\install-client.ps1 -Server "wss://vpn.example.com/tunnel" -Token "your-token" -RegisterTask

Web UI (kvn-web) — одна команда

Устанавливает бинарник, регистрирует сервис автозапуска (systemd/launchd/Windows Service) и запускает Web UI на порту 2311.

Linux / macOS:

sudo bash -c "$(curl -sL https://github.com/bzdvdn/kvn-ws/releases/latest/download/install-web.sh)" -- --desktop --start

Windows (PowerShell Admin):

iwr -useb https://github.com/bzdvdn/kvn-ws/releases/latest/download/install-web.ps1 -OutFile install-web.ps1; .\install-web.ps1 -Desktop -Start

Web UI: http://127.0.0.1:2311

Desktop App (kvn-desktop)

Нативное десктопное приложение с WebView-окном для kvn-web.

Linux / macOS: обёртка над уже запущенным systemd/launchd-сервисом, открывает WebView на localhost:2311.

Windows: самозапускаемый — встраивает встроенный webui.Server, запрашивает UAC (embedded manifest), восстанавливает system proxy при закрытии.

Устанавливается вместе с install-web.sh/install-web.ps1 (флаг --desktop / -Desktop).

# Linux/macOS
sudo ./scripts/install-web.sh --desktop --start

# Windows (PowerShell Admin)
.\scripts\install-web.ps1 -Desktop -Start

Сборка:

# Linux (требуется: apt install libgtk-3-dev libwebkit2gtk-4.1-dev)
go build -o bin/kvn-desktop ./src/cmd/desktop

# Windows cross (через Docker)
docker build -f Dockerfile.kvn-desktop -o out .

Configuration

Минимальный client.yaml:

server: wss://vpn.example.com/tunnel
auth:
  token: your-token

Детальная конфигурация — docs/ru/config.md.

Web UI features

• Мультисервер: добавление, переключение, удаление конфигураций серверов
• Редактирование глобальных и per-server настроек через браузер
• Поддержка TUN и Proxy режимов
• Import/Export конфига (JSON, QR-код)
• Мониторинг логов соединения с фильтром по уровню и поиском
• Статус подключения в реальном времени
• Transparent proxy + DNS proxy настройки (Linux)
• System proxy toggle

Obfuscation

Трафик маскируется под обычный HTTPS несколькими уровнями:

• uTLS — подмена TLS fingerprint (Chrome HelloChrome_Auto)
• Padding — дополнение WebSocket-сообщений случайными данными до кратного размера
• QUIC obfuscation — XOR-обфускация QUIC-трафика с nonce через TLS Exporter
• SNI rotation — случайный домен из списка tls.sni

Transport

Два транспорта: TCP (WebSocket) и QUIC (UDP). QUIC используется по умолчанию, при недоступности — автоматический fallback на TCP.

Relay Mode

Режим ретрансляции (relay) — два подрежима:

Bridge — прозрачный pipe: принимает клиентов, проксирует трафик на upstream, не расшифровывает. Terminator — полноценный VPN-endpoint: расшифровывает, маршрутизирует (direct/upstream по CIDR + доменам), перехватывает DNS.

Terminator

Terminator принимает WS/QUIC клиентов, выделяет IP из пула, поднимает TUN и маршрутизирует:

• Direct — CIDR (10.0.0.0/8) и домены (.internal.example) → напрямую через TUN relay
• Upstream — остальной трафик → через upstream VPN-сервер (WS или QUIC)
• DNS interception — для direct-доменов relay форвардит DNS на 1.1.1.1:53 (настраивается)

mode: relay
server: wss://vpn.example.com/tunnel
upstream_token: your-token           # токен для upstream (или env KVN_RELAY_AUTH_TOKEN)
relay:
  mode: terminator
  listen: 0.0.0.0:443
  routing:
    direct_ranges:
      - 10.0.0.0/8
    direct_domains:
      - .internal.example
    dns:
      upstream: "1.1.1.1:53"
  network:
    pool_ipv4:
      subnet: 172.16.0.0/24
      gateway: 172.16.0.1
tls:
  verify_mode: insecure

Bridge relay

Прозрачный pipe — relay не расшифровывает трафик:

mode: relay
server: wss://vpn.example.com/tunnel
relay:
  listen: 0.0.0.0:8443
  ws_paths:
    - /tunnel
  max_connections: 200
  quic:
    keep_alive: 7
    idle_timeout: 60

Клиент через relay (bridge)

mode: tun
server: wss://relay:8443/tunnel
auth:
  token: your-token
tls:
  verify_mode: insecure

Подробнее: docs/en/relay.md · docs/ru/relay.md Пример terminator: examples/relay-terminator/

Examples

Готовые к запуску примеры в examples/:

• docker-compose.yml — сервер + клиент (WS и QUIC)
• server.yaml / client.yaml — конфиги
• relay-terminator/docker-compose.yml — relay-пример terminator (WS + QUIC клиенты)
• run.sh — генерация TLS-сертификата и запуск

Changelog

CHANGELOG.md

License

MIT