BitBang CLI

BitBang CLI è un multi-strumento di accesso remoto in un singolo binario statico: apri una shell interattiva, sfoglia e trasferisci file, e accedi alle app web sulla rete della macchina remota da qualsiasi browser, senza port forwarding, senza configurazione e senza account.

Sulla macchina a cui vuoi accedere:

curl -sSfL bitba.ng/install | sh
bitbang serve

serve stampa un URL. Aprilo in qualsiasi browser e ottieni un terminale, un file browser e un proxy verso la rete di quella macchina -- oppure collegati da un altro terminale con bitbang connect <url> usando lo stesso binario. La connessione è crittografata end-to-end e peer-to-peer; il server bitba.ng presenta le due estremità e poi si fa da parte.

bitbang è un singolo binario Go statico. Fa parte del progetto BitBang; questo whitepaper approfondisce il design.

Abbinamento con un codice a 6 cifre

Quando non puoi incollare un URL o scansionare un codice QR, ad esempio se sei al telefono o a pochi metri di distanza, bitbang serve stampa anche un breve codice di abbinamento. L'altra persona apre bitba.ng/<code> (o esegue bitbang connect <code>), il suo schermo mostra un secondo numero a 6 cifre, e loro ti leggono quello ad alta voce. Lo digiti per approvare. Un machine-in-the-middle non può far combaciare i due numeri, e l'abbinamento salva le credenziali di connessione del dispositivo per la volta successiva, ad es. bitbang connect nas1. Se conosci Magic Wormhole, la forma è simile: un codice pronunciato che introduce in modo sicuro due macchine.

Perché?

• Niente da inoltrare o configurare. Funziona dietro NAT, CGNAT o una rete blindata -- nessuna modifica al router, nessuna VPN, nessun demone tunnel.
• Niente da installare sul lato connettente. Un browser è sufficiente. Una CLI c'è quando vuoi script, pipe e copia di file.
• Privato per design. Il traffico è WebRTC/DTLS, peer-to-peer. Il server di segnalazione non lo vede mai; se un percorso diretto non è possibile, un relay TURN trasporta solo testo cifrato.
• Nessun account, nessuna telemetria.

Perché non usare semplicemente SSH?

bitbang ha la forma di ssh: serve, connect e cp corrispondono a sshd, ssh e scp, con WebRTC come trasporto invece di TCP. Per una macchina a cui puoi già accedere comodamente via SSH, questa differenza non ti dà granché. Ma gran parte di bitbang nasce da fastidi che mi sembra di incontrare più spesso di quanto dovrei:

Raggiungibilità. L'accesso SSH remoto richiede un percorso in entrata, e sulla maggior parte delle reti aprire un percorso del genere non dipende da te -- CGNAT (rete mobile, Starlink, molti ISP), rete aziendale, universitaria, municipale. Quindi in pratica ti ritrovi ad aggiungere un secondo sistema: Tailscale, una VPN, ngrok -- un'altra installazione, un altro account, un altro demone da tenere in esecuzione. bitbang serve non richiede porte aperte e funziona da qualsiasi luogo.

Configurazione. SSH deve essere abilitato e configurato prima di farti entrare. È disabilitato di default su Raspberry Pi OS, e spesso solo-chiave, il che significa che devi prima portare la tua chiave pubblica sulla macchina. E come fai? Email o una chiavetta USB sono di solito le opzioni meno dolorose. bitbang imposta la connessione con uno scambio di codice a 6 cifre -- qualcosa che puoi fare in sicurezza al telefono, o gridando attraverso la stanza. Inoltre gira come utente normale -- niente root, niente demone, niente file di configurazione.

Proxy. Se vuoi un'app web sulla rete di quella macchina, SSH ti dà un tunnel separato per ogni app, nominato in anticipo. Il proxy di bitbang è generico: specifica l'URL dell'app web al momento della connessione.

Client browser. SSH richiede un client SSH e una chiave o password sul lato connettente. bitbang richiede un browser -- il che significa un telefono, un laptop preso in prestito, o qualcuno che non ha mai aperto un terminale. Dagli l'URL e ottengono l'accesso che hai concesso loro.

Usare bitbang

Ogni connessione ha due estremità: un listener (bitbang serve, in esecuzione sulla macchina a cui si accede) e un connector (un browser, o la CLI bitbang, sulla macchina che accede). Un singolo URL del listener serve entrambi i tipi di connector.

Il listener: bitbang serve

bitbang serve                    # tutto: shell + file + proxy su un unico URL
bitbang serve shell              # solo shell
bitbang serve files ~/share      # solo file (aggiungi -upload per consentire gli upload)
bitbang serve proxy              # proxy; scegli la destinazione nel browser
bitbang serve proxy localhost:8080   # ...oppure fissa una singola destinazione

Ognuno stampa un codice QR, un URL e un codice di abbinamento.

Connessione da un browser

Apri l'URL. A seconda di cosa viene servito, ottieni:

• Shell -- un terminale completo nella pagina (colori, ridimensionamento, copia/incolla).
• File -- sfoglia, anteprima, scarica e carica.
• Proxy -- digita un indirizzo LAN (nas.local, 192.168.1.10:8080, localhost:3000/admin) e usa l'app come se fossi in locale. Login, cookie, upload e streaming funzionano tutti.

Connessione dalla CLI

bitbang connect <url>                                   # shell interattiva
bitbang connect <url> -- tail -f /var/log/syslog        # comando singolo
bitbang cp <url>:/var/log/app.log ./app.log             # copia file, stile scp
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin     # anche stdin/stdout funzionano

Ogni connessione o abbinamento riuscito viene salvato in ~/.bitbang/devices.json, quindi d'ora in poi basta un nome breve: bitbang connect nas1.

Installazione

La one-liner rileva la tua architettura (amd64, arm64, armv7), scarica il binario dall'ultima release di GitHub, verifica il suo SHA-256 rispetto al checksums.txt della release, e installa in ~/.local/bin/bitbang.

Fissa una versione, cambia la posizione, o controlla prima lo script:

curl -sSfL bitba.ng/install | sh -s -- --version v0.5.0
curl -sSfL bitba.ng/install | sh -s -- --prefix /usr/local/bin

curl -sSfL bitba.ng/install -o install.sh && less install.sh && sh install.sh

Le build per macOS e Windows stanno arrivando -- sono state create delle issue per ciascuna (macOS, windows, basta reagire o commentare per farmi capire che siete interessati. Installazione manuale: scarica il binario dalle Release e mettilo nel tuo PATH. Build dal sorgente: vedi sotto.

Come funziona l'URL di installazione

bitba.ng/install è un redirect, non uno script ospitato. La catena:

1. curl colpisce https://bitba.ng/install, che fa un 302 verso install.sh in questa repo (su main).
2. Lo script viene eseguito nella tua shell, rileva OS+arch, e scarica l'asset binario da https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>.
3. Recupera checksums.txt dalla stessa release e verifica lo SHA-256 del binario.
4. Installa in ~/.local/bin (sovrascrivibile).

Lo script di installazione vive in questa repo, accanto al codice che installa -- così puoi esaminarlo insieme al binario, e l'host canonico bitba.ng possiede solo l'URL breve. Chi si auto-ospita può puntare /install del proprio host a qualsiasi script voglia: la variabile d'ambiente INSTALL_URL del server di segnalazione controlla la destinazione del redirect (vuota → 404).

Sicurezza

• Identità auto-certificante. Al primo avvio, bitbang genera una coppia di chiavi RSA in ~/.bitbang/<program>/; l'UID del dispositivo è derivato dalla chiave pubblica, quindi impersonare un dispositivo significa trovare una seconda preimmagine del suo UID.
• Il segreto non tocca mai il server. Il codice di accesso vive nel frammento dell'URL (#…), che i browser non inviano mai -- bitba.ng fa da intermediario per la connessione senza vedere mai la credenziale che la autorizza.
• Crittografia end-to-end. Tutto il traffico viaggia su DTLS di WebRTC. Il server di segnalazione vede solo la chiave pubblica, l'UID derivato e i metadati di connessione -- mai i tuoi dati. Un relay TURN, se necessario, vede solo testo cifrato.
• Abbinamento verificato. Il numero letto ad alta voce nell'abbinamento con codice è una short authentication string (SAS), calcolata indipendentemente su entrambe le estremità a partire dalle impronte DTLS negoziate e da due nonce impegnati -- un machine-in-the-middle, le cui impronte differiscono necessariamente, non può far combaciare i due numeri.
• PIN opzionale (--pin) per configurazioni permanenti o headless, e modalità usa-e-getta (-ephemeral) per una nuova identità a ogni esecuzione.

Come le due estremità si autenticano a vicenda senza fidarsi del server di segnalazione è trattato in dettaglio qui: Trustless Signaling: Authentication Without a Central Authority.

Come si confronta

Riferimento dei comandi

I flag accettano entrambe le forme (-pin o --pin). I flag booleani sono disattivati di default salvo diversa indicazione.

bitbang serve [flags]                  Tutte le funzionalità: shell + file + proxy su un unico URL
bitbang serve shell [flags]            Solo shell
bitbang serve files [PATH] [flags]     Solo file (PATH predefinito = cwd)
bitbang serve proxy [TARGET] [flags]   Proxy inverso HTTP/WebSocket (TARGET fissa un host:port)
bitbang connect <target> [-- cmd …]    Shell client (interattiva o monouso)
bitbang cp <src> <dst>                 Copia file (un lato è <URL>:/percorso, o '-')
bitbang version                        Stampa la versione (anche --version)
bitbang help                           Utilizzo (anche --help, -h)

bitbang serve -- esegui un listener

Flag condivisi (tutte e quattro le forme di serve):

Flag della shell (serve e serve shell):

Flag dei file:

(Avanzato: -video-fd N passa un FD di socketpair ereditato a un helper video esterno; per uso interno/embedding.)

bitbang connect <target> [-- comando …] -- shell client

<target> può essere uno qualsiasi di:

• un nome salvato -- ad es. nas1; risolto dalla tabella known-hosts (vedi sotto)
• un codice di abbinamento a 6 cifre -- ad es. 482731; esegue il flusso di abbinamento, poi si connette
• un URL -- https://bitba.ng/<id>#<code>, bitba.ng/<id>#<code>, o <id>#<code> nudo

Senza -- comando, apre una shell interattiva (una PTY quando stdin è un terminale). Con -- comando args…, esegue quel singolo comando in modo non interattivo ed esce con il suo stato di uscita (le uscite per segnale riportano 128).

bitbang cp <src> <dst> -- copia file

Esattamente uno tra <src> / <dst> è remoto, scritto <URL>:/percorso (URL in qualsiasi forma accettata da connect). - significa stdin/stdout, quindi cp <URL>:/f - fa streaming su stdout e cp - <URL>:/f carica da stdin. Uno / o . finale sul lato locale mantiene il nome base remoto (stile scp).

Nomi dei dispositivi e tabella known-hosts

Ogni connessione o abbinamento riuscito viene ricordato in ~/.bitbang/devices.json (modalità 0600), così puoi riconnetterti con un nome breve invece di un URL o un codice:

bitbang connect 482731 -name nas1     # abbina una volta, salvalo come "nas1"
bitbang connect nas1                  # da allora in poi, solo il nome

• -name NAME sceglie il nome; si applica solo a un host nuovo. Senza di esso, viene assegnato e stampato un nome automatico (device1, device2, …) (Salvato come "device1".).
• Regole di denominazione: un nome deve iniziare con una lettera e contenere solo lettere, cifre, - o _. Questo garantisce che non possa mai essere confuso con un codice a 6 cifre o un URL. Ricerche e unicità sono case-insensitive.
• Niente rinomina tramite connect: bitbang connect nas1 -name nas2 viene rifiutato -- -name è solo per i salvataggi al primo utilizzo.
• Quando viene salvato: un abbinamento viene registrato appena la SAS è verificata (così una riconnessione instabile non lo perde); una connessione via URL viene registrata una volta connessi.
• Ogni voce memorizza {name, uid, access_code, server, paired_at}. Riconnettere un host noto (per nome o URL) lo aggiorna sul posto e mantiene il nome.

Build dal sorgente

Richiede Go 1.25+. Puro Go, linkato staticamente (CGO_ENABLED=0) -- cross-compilazione banale, nessuna dipendenza a runtime.

go build ./cmd/bitbang/

# cross-compila:
GOOS=linux   GOARCH=arm64        go build -o bitbang-arm64 ./cmd/bitbang/
GOOS=linux   GOARCH=arm GOARM=7  go build -o bitbang-armv7 ./cmd/bitbang/
GOOS=windows GOARCH=amd64        go build -o bitbang.exe   ./cmd/bitbang/
GOOS=darwin  GOARCH=arm64        go build -o bitbang-macos ./cmd/bitbang/

Diagrammi

Roadmap

Disponibile oggi: shell, file e proxy, raggiungibili dal browser o dalla CLI, più copia file stile scp e abbinamento ad-hoc con una tabella di dispositivi salvata. Progettato e in arrivo:

• Bridge seriale -- pilotare una /dev/ttyUSB0 remota da una porta virtuale locale (ad es. eseguire Arduino IDE su internet). È stata aperta una issue qui.
• Port forwarding TCP -- -L 5432:db.internal:5432 per raggiungere servizi solo-LAN. È stata aperta una issue qui.
• Desktop remoto -- schermo su una traccia video WebRTC, tastiera/mouse sul data channel.

Licenza

MIT -- vedi LICENSE.

Contribuire

Issue e PR sono benvenute.