BitBang CLI

BitBang CLI est un multitool d'accès à distance sous forme d'un binaire statique unique : ouvrez un shell interactif, parcourez et transférez des fichiers, et accédez aux applications web du réseau de la machine distante depuis n'importe quel navigateur, sans redirection de port, sans configuration et sans compte.

Sur la machine que vous souhaitez joindre :

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

serve affiche une URL. Ouvrez-la dans n'importe quel navigateur et vous obtenez un terminal, un explorateur de fichiers et un proxy vers le réseau de cette machine — ou connectez-vous depuis un autre terminal avec bitbang connect <url> en utilisant le même binaire. La connexion est chiffrée de bout en bout et pair-à-pair ; le serveur bitba.ng présente les deux extrémités, puis s'efface.

bitbang est un binaire Go statique unique. Il fait partie du projet BitBang ; ce livre blanc couvre la conception en profondeur.

Appairage avec un code à 6 chiffres

Lorsque vous ne pouvez pas coller d'URL ni scanner de QR code, par exemple au téléphone ou à portée de voix, bitbang serve affiche également un code d'appairage court. L'autre partie ouvre bitba.ng/<code> (ou exécute bitbang connect <code>), son écran affiche un second nombre à 6 chiffres, et elle vous le relit. Vous le saisissez pour approuver. Un homme du milieu ne peut pas faire correspondre les deux nombres, et l'appairage enregistre les identifiants de connexion de l'appareil pour la prochaine fois, par ex. bitbang connect nas1. Si vous connaissez Magic Wormhole, la forme est similaire — un code prononcé qui présente deux machines en toute sécurité.

Pourquoi ?

• Rien à rediriger ni à configurer. Fonctionne derrière un NAT, un CGNAT ou un réseau verrouillé — aucune modification de routeur, aucun VPN, aucun démon de tunnel.
• Rien à installer côté connexion. Un navigateur suffit. Une CLI est là quand vous voulez des scripts, des pipes et des copies de fichiers.
• Privé par conception. Le trafic est WebRTC/DTLS, pair-à-pair. Le serveur de signalisation ne le voit jamais ; si un chemin direct n'est pas possible, un relais TURN ne transporte que du texte chiffré.
• Pas de compte, pas de télémétrie.

Pourquoi ne pas simplement utiliser SSH ?

bitbang est façonné comme ssh : serve, connect et cp correspondent à sshd, ssh et scp, avec WebRTC comme transport au lieu de TCP. Pour une machine sur laquelle vous pouvez déjà vous connecter en SSH confortablement, cette différence ne vous apporte pas grand-chose. Mais l'essentiel de bitbang est né de frustrations que je semble rencontrer plus souvent que je ne le devrais :

Portée. L'accès SSH distant nécessite un chemin entrant, et sur la plupart des réseaux, ouvrir un tel chemin ne dépend pas de vous — CGNAT (mobile, Starlink, de nombreux FAI), réseau d'entreprise, universitaire, municipal. En pratique, vous ajoutez donc un second système : Tailscale, un VPN, ngrok — une installation de plus, un compte de plus, un démon de plus à faire tourner. bitbang serve ne nécessite aucun port ouvert et fonctionne de n'importe où.

Configuration. SSH doit être activé et configuré avant de vous laisser entrer. Il est désactivé par défaut sur Raspberry Pi OS, et souvent réservé aux clés, ce qui signifie qu'il faut d'abord placer votre clé publique sur la machine. Et comment faites-vous ? Par e-mail ou clé USB, ce sont généralement les options les moins douloureuses. bitbang établit la connexion par un échange de code à 6 chiffres — quelque chose que vous pouvez faire en toute sécurité par téléphone, ou en criant à travers la pièce. Il s'exécute également en utilisateur ordinaire — pas de root, pas de démon, pas de fichier de configuration.

Proxy. Si vous voulez une application web sur le réseau de cette machine, SSH vous donne un tunnel séparé par application, nommé à l'avance. Le proxy bitbang est générique : indiquez l'URL de l'application web au moment de la connexion.

Client navigateur. SSH nécessite un client SSH et une clé ou un mot de passe côté connexion. bitbang nécessite un navigateur — ce qui signifie un téléphone, un ordinateur portable emprunté, ou quelqu'un qui n'a jamais ouvert de terminal. Donnez-lui l'URL et il obtient l'accès que vous lui avez accordé.

Utiliser bitbang

Chaque connexion a deux extrémités : un écouteur (bitbang serve, exécuté sur la machine à joindre) et un connecteur (un navigateur, ou la CLI bitbang, sur la machine qui se connecte). Une URL d'écouteur dessert les deux types de connecteurs.

L'écouteur : bitbang serve

bitbang serve                    # everything: shell + files + proxy on one URL
bitbang serve shell              # shell only
bitbang serve files ~/share      # files only (add -upload to allow uploads)
bitbang serve proxy              # proxy; pick the target in the browser
bitbang serve proxy localhost:8080   # ...or pin a single target

Chacune affiche un code QR, une URL et un code d'appairage.

Se connecter depuis un navigateur

Ouvrez l'URL. Selon ce qui est servi, vous obtenez :

• Shell -- un terminal complet dans la page (couleurs, redimensionnement, copier/coller).
• Fichiers -- parcourir, prévisualiser, télécharger et envoyer des fichiers.
• Proxy -- saisissez une adresse LAN (nas.local, 192.168.1.10:8080, localhost:3000/admin) et utilisez l'application comme si vous étiez en local. Connexions, cookies, envois de fichiers et streaming fonctionnent tous.

Se connecter depuis la CLI

bitbang connect <url>                                   # interactive shell
bitbang connect <url> -- tail -f /var/log/syslog        # one-shot command
bitbang cp <url>:/var/log/app.log ./app.log             # copy files, scp-style
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin     # stdin/stdout work too

Chaque connexion ou appairage réussi est enregistré dans ~/.bitbang/devices.json ; dès lors, un nom court suffit : bitbang connect nas1.

Installation

La commande en une ligne détecte votre architecture (amd64, arm64, armv7), télécharge le binaire depuis la dernière version GitHub, vérifie son SHA-256 par rapport au checksums.txt de la version, et l'installe dans ~/.local/bin/bitbang.

Épinglez une version, changez l'emplacement ou auditez d'abord le 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

Les versions macOS et Windows arrivent -- des tickets ont été ouverts pour chacune (macOS, Windows, il suffit de réagir ou de poster pour me montrer que vous êtes intéressé(e). Installation manuelle : téléchargez le binaire depuis Releases et placez-le sur votre PATH. Compilation depuis les sources : voir ci-dessous.

Comment fonctionne l'URL d'installation

bitba.ng/install est une redirection, pas un script hébergé. La chaîne :

1. curl appelle https://bitba.ng/install, qui répond par un 302 vers install.sh dans ce dépôt (sur main).
2. Le script s'exécute dans votre shell, détecte OS+arch, et télécharge le binaire depuis https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>.
3. Il récupère checksums.txt depuis la même version et vérifie le SHA-256 du binaire.
4. Il installe dans ~/.local/bin (surchargeable).

Le script d'installation vit dans ce dépôt, à côté du code qu'il installe -- vous pouvez donc l'examiner en même temps que le binaire, et l'hôte canonique bitba.ng ne possède que l'URL courte. Les auto-hébergeurs peuvent pointer /install de leur propre hôte vers n'importe quel script qu'ils fournissent : la variable d'environnement INSTALL_URL du serveur de signalisation contrôle la cible de redirection (vide → 404).

Sécurité

• Identité auto-certifiée. Au premier lancement, bitbang génère une paire de clés RSA dans ~/.bitbang/<program>/ ; l'UID de l'appareil est dérivé de la clé publique, donc usurper un appareil revient à trouver une seconde préimage de son UID.
• Le secret ne touche jamais le serveur. Le code d'accès se trouve dans le fragment d'URL (#…), que les navigateurs n'envoient jamais -- bitba.ng sert d'intermédiaire pour la connexion sans jamais voir l'identifiant qui l'autorise.
• Chiffrement de bout en bout. Tout le trafic passe par le DTLS de WebRTC. Le serveur de signalisation ne voit que la clé publique, l'UID dérivé et les métadonnées de connexion -- jamais vos données. Un relais TURN, si nécessaire, ne voit que du texte chiffré.
• Appairage vérifié. Le nombre lu à voix haute lors de l'appairage par code est une chaîne d'authentification courte (SAS), calculée indépendamment aux deux extrémités à partir des empreintes DTLS négociées et de deux nonces engagés -- un homme du milieu, dont les empreintes diffèrent nécessairement, ne peut pas faire correspondre les deux nombres.
• PIN optionnel (--pin) pour les configurations permanentes ou sans tête, et mode jetable (-ephemeral) pour une identité neuve à chaque exécution.

La manière dont les deux extrémités s'authentifient mutuellement sans faire confiance au serveur de signalisation est détaillée ici : Signalisation sans confiance : authentification sans autorité centrale.

Comparaison

Référence des commandes

Les options acceptent les deux formes (-pin ou --pin). Les options booléennes sont désactivées par défaut sauf mention contraire.

bitbang serve [flags]                  All capabilities: shell + files + proxy on one URL
bitbang serve shell [flags]            Shell only
bitbang serve files [PATH] [flags]     Files only (PATH defaults to cwd)
bitbang serve proxy [TARGET] [flags]   HTTP/WebSocket reverse proxy (TARGET pins one host:port)
bitbang connect <target> [-- cmd …]    Client shell (interactive or one-shot)
bitbang cp <src> <dst>                 Copy files (one side is <URL>:/path, or '-')
bitbang version                        Print version (also --version)
bitbang help                           Usage (also --help, -h)

bitbang serve -- lancer un écouteur

Options partagées (les quatre formes de serve) :

Options du shell (serve et serve shell) :

Options des fichiers :

(Avancé : -video-fd N passe un FD socketpair hérité à un helper vidéo externe ; pour un usage interne/intégré.)

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

<target> peut être l'un des suivants :

• un nom enregistré -- par ex. nas1 ; résolu depuis la table des hôtes connus (voir ci-dessous)
• un code d'appairage à 6 chiffres -- par ex. 482731 ; exécute le flux d'appairage, puis se connecte
• une URL -- https://bitba.ng/<id>#<code>, bitba.ng/<id>#<code>, ou simplement <id>#<code>

Sans -- command, ouvre un shell interactif (un PTY lorsque stdin est un terminal). Avec -- command args…, exécute cette commande unique de manière non interactive et se termine avec son code de sortie (les sorties par signal rapportent 128).

bitbang cp <src> <dst> -- copier des fichiers

Exactement l'un de <src> / <dst> est distant, écrit <URL>:/path (URL sous toute forme acceptée par connect). - signifie stdin/stdout, donc cp <URL>:/f - envoie le flux vers stdout et cp - <URL>:/f téléverse depuis stdin. Un / ou . final côté local conserve le nom de base distant (style scp).

Noms d'appareils et table des hôtes connus

Chaque connexion ou appairage réussi est mémorisé dans ~/.bitbang/devices.json (mode 0600), afin que vous puissiez vous reconnecter par un nom court au lieu d'une URL ou d'un code :

bitbang connect 482731 -name nas1     # pair once, save it as "nas1"
bitbang connect nas1                  # thereafter, just the name

• -name NAME choisit le nom ; il ne s'applique qu'à un nouvel hôte. Sans lui, un nom automatique (device1, device2, …) est attribué et affiché (Saved as "device1".).
• Règles de nommage : un nom doit commencer par une lettre et ne contenir que des lettres, des chiffres, - ou _. Cela garantit qu'il ne peut jamais être confondu avec un code à 6 chiffres ou une URL. Les recherches et l'unicité sont insensibles à la casse.
• Pas de renommage via connect : bitbang connect nas1 -name nas2 est refusé -- -name est réservé aux premiers enregistrements.
• Quand c'est enregistré : un appairage est enregistré dès que le SAS est vérifié (afin qu'une reconnexion instable ne le perde pas) ; une connexion par URL est enregistrée une fois connecté.
• Chaque entrée stocke {name, uid, access_code, server, paired_at}. Se reconnecter à un hôte connu (par nom ou URL) le rafraîchit sur place et conserve le nom.

Compilation depuis les sources

Nécessite Go 1.25+. Go pur, lié statiquement (CGO_ENABLED=0) -- compilation croisée triviale, aucune dépendance d'exécution.

go build ./cmd/bitbang/

# cross-compile:
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/

Diagrammes

Feuille de route

Disponible aujourd'hui : shell, fichiers et proxy, accessibles depuis le navigateur ou la CLI, plus la copie de fichiers façon scp et l'appairage ad-hoc avec une table d'appareils enregistrés. Conçu et en cours de route :

• Pont série -- pilotez un /dev/ttyUSB0 distant depuis un port virtuel local (par ex. exécutez l'IDE Arduino sur Internet). Un ticket a été ouvert ici.
• Redirection de port TCP -- -L 5432:db.internal:5432 pour atteindre des services uniquement accessibles sur le LAN. Un ticket a été ouvert ici.
• Bureau à distance -- écran via une piste vidéo WebRTC, clavier/souris via le canal de données.

Licence

MIT -- voir LICENSE.

Contribution

Les tickets et les PR sont les bienvenus.