Whitelist Bypass

Instrada il traffico internet attraverso piattaforme di videochiamata (VK Call, Yandex Telemost, WB Stream) per aggirare la censura basata su whitelist governative.

Configurazione

Guida passo-passo alla configurazione (in russo): docs/SETUP.md

Come funziona

Sono disponibili due modalità di tunnel: DC (DataChannel) e Video (codifica dati VP8). La configurazione consigliata è headless su entrambe le estremità - Go puro (Pion) comunica direttamente con l'SFU della piattaforma, senza browser. L'offuscamento ChaCha20, il pacing VP8 configurabile e il backend LiveKit/WB Stream sono funzionalità esclusive della modalità headless.

Un percorso browser legacy (joiner Android WebView contro un creator desktop Electron con hook JS) funziona ancora per VK DC, ma è più lento, non può offuscare ed è in fase di dismissione. I nuovi deployment dovrebbero usare la modalità headless.

Modalità DC

Pion apre un SCTP DataChannel sul PC publisher e vi incanala TCP/UDP. I frame passano attraverso l'SFU della piattaforma come qualsiasi altro payload DataChannel.

Joiner (censored, Android/iOS/Linux)                Creator (free internet)

All apps
  |
VpnService (captures all traffic)
  |
tun2socks (IP -> TCP)
  |
SOCKS5 proxy (Go, :1080)
  |
Headless joiner (Pion)                    Headless creator (Pion)
  |                                         |
DataChannel  <------- SFU ------->   DataChannel
                                            |
                                        Relay bridge
                                            |
                                        Internet

Modalità Video

Stessa pipeline della modalità DC, ma il tunnel viaggia su una traccia video VP8 pubblicata invece che su un SCTP DataChannel. Utile quando l'SFU applica rate-limiting ai DataChannel ma lascia passare RTP (es. Telemost), e obbligatorio a livello di piattaforma in alcuni casi (la traccia publisher di WB Stream è sempre video). Il framing del tunnel e il layer di multiplexing sovrastante sono gli stessi della modalità DC.

Il traffico passa attraverso l'SFU della piattaforma, che è nella whitelist governativa. Per il DPI sembra una normale videochiamata.

Componenti

• relay/ - Relay Go condiviso da entrambe le estremità: proxy SOCKS5, plumbing tun2socks, tunnel DC/VP8, offuscatore ChaCha20, multiplexer di connessioni, binding gomobile/iOS
• headless/vk/ - Creator VK headless: crea o si unisce a una chiamata tramite l'API HTTP di VK, tunnel Pion DC/VP8, senza browser
• headless/telemost/ - Creator Telemost (Yandex) headless con lo stesso modello
• headless/wbstream/ - Creator WB Stream headless (basato su LiveKit, token guest anonimi)
• headless/dion/ - Creator DION headless con lo stesso modello
• headless/bitrix/ - Creator Bitrix headless (DC/VP8 adattivo, join come guest)
• headless/wbstream-joiner/ - Joiner WB Stream desktop (controparte del creator, usato per test e client Linux)
• headless/telemost-joiner/ - Joiner Telemost desktop (controparte del creator, usato per test e client Linux)
• headless/dion-joiner/ - Joiner DION desktop (controparte del creator, usato per test e client Linux)
• headless/bitrix-joiner/ - Joiner Bitrix desktop (controparte del creator, usato per test e client Linux)

Download

I binari precompilati sono disponibili su GitHub Releases.

Lato creator (internet libero, desktop)

Scarica ed esegui l'app Electron da GitHub Releases. Include automaticamente il relay Go.

1. Apri l'app
2. Seleziona la modalità tunnel (DC o Video)
3. Clicca "VK" o "Telemost"
4. Accedi, crea una nuova chiamata dall'app
5. Copia il link di join, invialo al joiner

Importante: La chiamata deve essere creata dall'interno dell'app Creator. Unirsi a una chiamata esistente dall'app non funzionerà - gli hook JS devono essere presenti dal momento in cui la chiamata inizia.

Lato joiner (censurato, Android/iOS/Linux)

Sono disponibili tre forme; scegli quella più adatta al dispositivo:

• Android - installa whitelist-bypass.apk da Releases. Consenti il prompt VPN al primo avvio. Incolla il link di join e tocca GO; il traffico a livello di sistema fluisce attraverso la chiamata.
• iOS - installa whitelist-bypass-proxy.ipa da Releases (sideload tramite AltStore / Sideloadly / il tuo account sviluppatore). Espone solo un proxy SOCKS5 locale - nessuna VPN di sistema. Per proxare l'intero dispositivo, punta qualsiasi app VPN compatibile con SOCKS5 (Shadowrocket, Streisand, ...) all'endpoint SOCKS5 mostrato dall'app; oppure imposta il proxy per singola app (Telegram ha supporto integrato).
• Linux desktop - esegui un joiner headless; espone un proxy SOCKS5 sulla porta indicata per qualsiasi cosa vi punti. Utile per server e client Linux. I parametri opzionali --socks-user / --socks-pass abilitano l'autenticazione SOCKS5 username/password.
  • WB Stream: headless-wbstream-joiner --room <link> --socks-port 1080 [--socks-user u --socks-pass p]
  • Telemost: headless-telemost-joiner --tm-link <link> --socks-port 1080 [--socks-user u --socks-pass p]
  • DION: headless-dion-joiner --room <link> --socks-port 1080 [--socks-user u --socks-pass p]
  • Bitrix: headless-bitrix-joiner --link <link> --socks-port 1080 [--socks-user u --socks-pass p]

La guida completa passo-passo (in russo) copre ogni piattaforma in dettaglio: vedi docs/SETUP.md.

Compilazione dal sorgente

Requisiti

• Go 1.26+
• gomobile (go install golang.org/x/mobile/cmd/gomobile@latest)
• gobind (go install golang.org/x/mobile/cmd/gobind@latest)
• Android SDK + NDK 29
• Java 11+
• Node.js 18+

Script di build

# Full release build (Android APK + Creator app + Headless creators + Linux joiners + VK bot + iOS IPA on macOS)
./make-release.sh

# Individual builds
./build-go.sh          # Go .aar, relay binary, headless creators
./copy-hooks.sh        # Copy JS hooks to android assets
./build-app.sh         # Android APK
./build-headless.sh    # Headless binaries only (current platform)
./build-cli.sh         # Per-arch zips of headless creators + joiners + vk-bot
./build-creator.sh     # Creator Electron app (all platforms)
./build-ios.sh proxy   # iOS proxy app, xcframework + unsigned IPA
./build-ios.sh vpn     # iOS VPN app, xcframework + unsigned IPA

iOS

Richiede Xcode e macOS. build-ios.sh accetta un argomento, proxy o vpn.

./build-ios.sh proxy   # ios-proxy-app -> prebuilts/whitelist-bypass-proxy.ipa
./build-ios.sh vpn     # ios-vpn-app   -> prebuilts/whitelist-bypass-vpn.ipa

Lo script compila Mobile.xcframework nella directory dell'app, esegue strip-signing.sh dell'app per rimuovere il team di sviluppo dal progetto, compila l'app non firmata e scrive un IPA non firmato in prebuilts/.

Per eseguirla su un dispositivo, apri il .xcodeproj corrispondente in Xcode, imposta il tuo team e identificatori di bundle univoci in Signing & Capabilities, e compila. La variante vpn richiede la capability Network Extension sui suoi identificatori di bundle.

Output in prebuilts/:

Build con Docker

Per compilare il progetto usando Docker, esegui:

docker compose -f docker-build/docker-compose.yml up 

Questo compilerà tutti i componenti (creator-app, headless, app android) nella cartella prebuild (tranne il creator macOS)

Creator headless

Creator in Go puro che creano chiamate tramite API senza browser. Niente Electron, niente hook JS - Go Pion PeerConnection gestisce direttamente il tunnel DataChannel.

./build-headless.sh

Vengono prodotti dieci binari - cinque creator, quattro joiner Linux e il bot VK:

./headless/vk/headless-vk-creator               --cookies cookies-vk.json
./headless/telemost/headless-telemost-creator   --cookies cookies-yandex.json
./headless/wbstream/headless-wbstream-creator   --cookies cookies-wbstream.json
./headless/dion/headless-dion-creator           --cookies cookies-dion.json
./headless/bitrix/headless-bitrix-creator       --cookies cookies-bitrix.json
./headless/wbstream-joiner/headless-wbstream-joiner --room <link> --socks-port 1080
./headless/dion-joiner/headless-dion-joiner         --room <link> --socks-port 1080
./headless/telemost-joiner/headless-telemost-joiner --tm-link <link> --socks-port 1080
./headless/bitrix-joiner/headless-bitrix-joiner     --link <link> --socks-port 1080
./headless/vk-bot/headless-vk-bot               --token <t> --group-id <g> --bins-dir <dir>

Tutti e quattro i creator necessitano dei cookie esportati dall'app creator desktop (pulsante Export Cookies) come JSON [{"name":"..","value":".."},...]. DION accetta anche {"email":"..","password":"..","cookies":[]} e poi effettua il login da solo, vedi docs/SETUP.md.

Flag comuni

Unirsi a una chiamata esistente

Per impostazione predefinita ogni binario crea una nuova chiamata. Per collegarsi a una esistente (riavvii del server senza invalidare il link, sessioni multiple shaped, ...):

Mutuamente esclusivi con i flag di creazione della chiamata (--peer-id per VK; gli altri non hanno flag di creazione).

Modalità risorse

custom ricade sui valori predefiniti di unlimited per qualsiasi flag lasciato non impostato, quindi gli override parziali funzionano:

./headless-vk-creator --cookies cookies-vk.json --vk-link https://vk.com/call/join/<token> \
  --resources custom --read-buf 65536 --max-dc-buf 8388608 --mem-limit 268435456 \
  --write-file /var/run/whitelist-bypass/call.txt

• read-buf - dimensione del buffer di lettura TCP/DC. Più piccolo = controlli di backpressure più frequenti, memoria meno a burst
• max-dc-buf - mette in pausa le letture TCP quando la quantità bufferizzata nel DataChannel supera questo valore; cablato solo in VK (Pion BufferedAmountLowThreshold)
• mem-limit - limite di memoria soft del runtime Go; rende il GC più aggressivo vicino al limite

Licenza

MIT

Donazioni

• 0xd986b7576340d8d7b04f806dfd38a182b19edf50 - USDC (ERC20)
• TTEo4XXTB6CqhEiKpyoncfk3skEvoq3bCP - USDT (TRC20)
• UQCZge2JzLmwNtI56p-ZxLuN2f7ZMCPGqO0XTt3wJ-cy8JaE - USDT (TON)