BitBang CLI

BitBang CLI ist ein Fernzugriffs-Multitool als einzelne statische Binärdatei: Sie öffnen eine interaktive Shell, durchsuchen und übertragen Dateien und greifen aus jedem Browser auf Web-Apps im Netzwerk der entfernten Maschine zu – ohne Portweiterleitung, ohne Konfiguration und ohne Konto.

Auf der Maschine, die Sie erreichen möchten:

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

serve gibt eine URL aus. Öffnen Sie sie in einem beliebigen Browser und Sie erhalten ein Terminal, einen Dateibrowser und einen Proxy zum Netzwerk dieser Maschine – oder verbinden Sie sich mit bitbang connect <url> von einem anderen Terminal aus mit derselben Binärdatei. Die Verbindung ist Ende-zu-Ende-verschlüsselt und Peer-to-Peer; der bitba.ng-Server stellt die beiden Enden einander vor und tritt dann zur Seite.

bitbang ist eine einzelne statische Go-Binärdatei. Es ist Teil des BitBang-Projekts; dieses Whitepaper behandelt das Design ausführlich.

Pairing mit einem 6-stelligen Code

Wenn Sie keine URL einfügen oder einen QR-Code scannen können – etwa wenn Sie telefonieren oder in Rufweite sind –, gibt bitbang serve zusätzlich einen kurzen Pairing-Code aus. Die andere Partei öffnet bitba.ng/<code> (oder führt bitbang connect <code> aus), auf ihrem Bildschirm erscheint eine zweite 6-stellige Zahl, und sie liest Ihnen diese vor. Sie tippen sie zur Bestätigung ein. Ein Man-in-the-Middle kann die beiden Zahlen nicht zur Übereinstimmung bringen, und das Pairing speichert die Verbindungsdaten des Geräts für das nächste Mal, z. B. bitbang connect nas1. Wenn Sie Magic Wormhole kennen: Die Form ist ähnlich – ein gesprochener Code, der zwei Maschinen sicher einander vorstellt.

Warum?

• Nichts weiterzuleiten oder zu konfigurieren. Funktioniert hinter NAT, CGNAT oder einem abgeriegelten Netzwerk – keine Router-Änderungen, kein VPN, kein Tunnel-Daemon.
• Nichts auf der verbindenden Seite zu installieren. Ein Browser genügt. Eine CLI ist da, wenn Sie Skripte, Pipes und Dateikopien möchten.
• Privat konzipiert. Der Datenverkehr läuft über WebRTC/DTLS, Peer-to-Peer. Der Signalisierungsserver sieht ihn nie; wenn kein direkter Pfad möglich ist, transportiert ein TURN-Relay ausschließlich Chiffrat.
• Kein Konto, keine Telemetrie.

Warum nicht einfach SSH?

bitbang ist wie ssh aufgebaut: serve, connect und cp entsprechen sshd, ssh und scp, mit WebRTC als Transport anstelle von TCP. Für eine Maschine, in die Sie bereits bequem per SSH einsteigen, bringt dieser Unterschied nicht viel. Aber der Großteil von bitbang entstand aus Ärgernissen, auf die ich häufiger zu stoßen scheine, als mir lieb ist:

Erreichbarkeit. Fern-SSH-Zugriff benötigt einen eingehenden Pfad, und in den meisten Netzwerken liegt das Öffnen eines solchen nicht in Ihrer Hand – CGNAT (Mobilfunk, Starlink, viele ISPs), Firmen-, Universitäts- oder Kommunalnetze. In der Praxis bauen Sie also ein zweites System an: Tailscale, ein VPN, ngrok – eine weitere Installation, ein weiteres Konto, ein weiterer Daemon, der am Laufen gehalten werden muss. bitbang serve benötigt keinen offenen Port und funktioniert von überall.

Einrichtung. SSH muss erst aktiviert und konfiguriert werden, bevor es Sie hereinlässt. Auf Raspberry Pi OS ist es standardmäßig deaktiviert und oft nur mit Schlüsseln nutzbar, was bedeutet, dass Sie zuerst Ihren öffentlichen Schlüssel auf die Maschine bringen müssen. Und wie machen Sie das? E-Mail oder ein USB-Stick sind meist die schmerzlosesten Optionen. bitbang richtet die Verbindung stattdessen über einen Austausch eines 6-stelligen Codes ein – etwas, das Sie sicher am Telefon tun oder quer durch den Raum rufen können. Es läuft außerdem als normaler Benutzer – kein Root, kein Daemon, keine Konfigurationsdatei.

Proxy-Nutzung. Wenn Sie eine Web-App im Netzwerk dieser Maschine nutzen möchten, erhalten Sie per SSH einen separaten Tunnel pro App, der im Voraus benannt wird. Der bitbang-Proxy ist generisch: Sie geben die URL der Web-App zum Zeitpunkt der Verbindung an.

Browser-Client. SSH benötigt auf der verbindenden Seite einen SSH-Client sowie einen Schlüssel oder ein Passwort. bitbang benötigt einen Browser – also ein Telefon, ein geliehenes Laptop oder jemanden, der noch nie ein Terminal geöffnet hat. Geben Sie ihnen die URL, und sie erhalten den Zugriff, den Sie ihnen gewährt haben.

bitbang verwenden

Jede Verbindung hat zwei Enden: einen Listener (bitbang serve, läuft auf der Maschine, die erreicht werden soll) und einen Connector (einen Browser oder die bitbang-CLI auf der Maschine, die die Verbindung herstellt). Eine Listener-URL bedient beide Arten von Connectors.

Der Listener: 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

Jede Variante gibt einen QR-Code, eine URL und einen Pairing-Code aus.

Verbindung aus einem Browser herstellen

Öffnen Sie die URL. Je nachdem, was bereitgestellt wird, erhalten Sie:

• Shell – ein vollwertiges Terminal in der Seite (Farben, Größenänderung, Kopieren/Einfügen).
• Dateien – durchsuchen, Vorschau anzeigen, herunterladen und hochladen.
• Proxy – geben Sie eine LAN-Adresse ein (nas.local, 192.168.1.10:8080, localhost:3000/admin) und nutzen Sie die App, als wären Sie lokal. Anmeldungen, Cookies, Uploads und Streaming funktionieren alle.

Verbindung über die CLI herstellen

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

Jede erfolgreiche Verbindung und jedes Pairing werden in ~/.bitbang/devices.json gespeichert, sodass ab dann ein kurzer Name genügt: bitbang connect nas1.

Installation

Der Einzeiler erkennt Ihre Architektur (amd64, arm64, armv7), lädt die Binärdatei aus dem neuesten GitHub-Release herunter, prüft ihre SHA-256-Summe gegen die checksums.txt des Releases und installiert sie nach ~/.local/bin/bitbang.

Eine Version festlegen, den Speicherort ändern oder das Skript zuerst prüfen:

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

macOS- und Windows-Builds sind in Arbeit – für jede Plattform wurden Issues erstellt (macOS, windows) – reagieren Sie einfach oder posten Sie, um mir zu zeigen, dass Sie interessiert sind. Manuelle Installation: Laden Sie die Binärdatei aus den Releases herunter und legen Sie sie in Ihren PATH. Aus dem Quellcode bauen: siehe unten.

So funktioniert die Installations-URL

bitba.ng/install ist eine Weiterleitung, kein gehostetes Skript. Die Kette:

1. curl ruft https://bitba.ng/install auf, das per 302 auf install.sh in diesem Repository (auf main) weiterleitet.
2. Das Skript läuft in Ihrer Shell, erkennt OS+Architektur und lädt das Binär-Asset von https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch> herunter.
3. Es ruft checksums.txt aus demselben Release ab und prüft die SHA-256-Summe der Binärdatei.
4. Installiert nach ~/.local/bin (überschreibbar).

Das Installationsskript liegt in diesem Repository direkt neben dem Code, den es installiert – so können Sie es zusammen mit der Binärdatei prüfen, und der kanonische bitba.ng-Host besitzt nur die Kurz-URL. Selbst-Hoster können das /install ihres eigenen Hosts auf jedes von ihnen ausgelieferte Skript zeigen lassen: Die Umgebungsvariable INSTALL_URL des Signalisierungsservers steuert das Weiterleitungsziel (leer → 404).

Sicherheit

• Selbstbeglaubigende Identität. Beim ersten Start erzeugt bitbang ein RSA-Schlüsselpaar unter ~/.bitbang/<program>/; die Geräte-UID wird vom öffentlichen Schlüssel abgeleitet, sodass das Vortäuschen eines Geräts bedeutet, ein zweites Urbild seiner UID zu finden.
• Das Geheimnis berührt den Server nie. Der Zugriffscode befindet sich im URL-Fragment (#…), das Browser niemals senden – bitba.ng vermittelt die Verbindung, ohne jemals die Anmeldeinformationen zu sehen, die sie autorisieren.
• Ende-zu-Ende-Verschlüsselung. Der gesamte Datenverkehr läuft über das DTLS von WebRTC. Der Signalisierungsserver sieht nur den öffentlichen Schlüssel, die abgeleitete UID und Verbindungsmetadaten – niemals Ihre Daten. Ein TURN-Relay, falls eines benötigt wird, sieht nur Chiffrat.
• Verifiziertes Pairing. Die vorzulesende Zahl beim Code-Pairing ist eine kurze Authentifizierungszeichenkette (SAS), die an beiden Enden unabhängig aus den ausgehandelten DTLS-Fingerprints und zwei festgelegten Nonces berechnet wird – ein Man-in-the-Middle, dessen Fingerprints zwangsläufig abweichen, kann die beiden Zahlen nicht zur Übereinstimmung bringen.
• Optionaler PIN (--pin) für dauerhafte oder Headless-Setups und Wegwerf-Modus (-ephemeral) für eine neue Identität bei jedem Lauf.

Wie die beiden Enden einander authentifizieren, ohne dem Signalisierungsserver zu vertrauen, wird hier ausführlich behandelt: Trustless Signaling: Authentication Without a Central Authority.

Vergleich

Befehlsreferenz

Flags akzeptieren beide Formen (-pin oder --pin). Boolesche Flags sind standardmäßig deaktiviert, sofern nicht anders angegeben.

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 – einen Listener ausführen

Gemeinsame Flags (alle vier serve-Formen):

Shell-Flags (serve und serve shell):

Datei-Flags:

(Fortgeschritten: -video-fd N übergibt einen geerbten Socketpair-FD an einen externen Video-Helfer; für interne/Einbettungszwecke.)

bitbang connect <target> [-- command …] – Client-Shell

<target> kann eines der folgenden sein:

• ein gespeicherter Name – z. B. nas1; wird aus der Known-Hosts-Tabelle aufgelöst (siehe unten)
• ein 6-stelliger Pair-Code – z. B. 482731; führt den Pairing-Ablauf aus und verbindet sich dann
• eine URL – https://bitba.ng/<id>#<code>, bitba.ng/<id>#<code> oder nur <id>#<code>

Ohne -- command wird eine interaktive Shell geöffnet (ein PTY, wenn stdin ein Terminal ist). Mit -- command args… wird dieser einzelne Befehl nicht-interaktiv ausgeführt und mit seinem Status beendet (Beenden durch Signale meldet 128).

bitbang cp <src> <dst> – Dateien kopieren

Genau eines von <src> / <dst> ist remote und wird als <URL>:/path geschrieben (URL in jeder Form, die connect akzeptiert). - bedeutet stdin/stdout, sodass cp <URL>:/f - nach stdout streamt und cp - <URL>:/f von stdin hochlädt. Ein abschließendes / oder . auf der lokalen Seite behält den Remote-Basename (scp-Stil).

Gerätenamen und die Known-Hosts-Tabelle

Jede erfolgreiche Verbindung und jedes Pairing werden in ~/.bitbang/devices.json (Modus 0600) gespeichert, sodass Sie sich über einen kurzen Namen statt einer URL oder eines Codes neu verbinden können:

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

• -name NAME wählt den Namen; es gilt nur für einen neuen Host. Ohne diese Option wird ein automatischer Name (device1, device2, …) vergeben und ausgegeben (Saved as "device1".).
• Namensregeln: Ein Name muss mit einem Buchstaben beginnen und darf nur Buchstaben, Ziffern, - oder _ enthalten. Das garantiert, dass er nie mit einem 6-stelligen Code oder einer URL verwechselt werden kann. Nachschlagen und Eindeutigkeit sind unabhängig von Groß-/Kleinschreibung.
• Kein Umbenennen per connect: bitbang connect nas1 -name nas2 wird abgelehnt – -name ist nur für das erste Speichern gedacht.
• Wann gespeichert wird: Ein Pairing wird gespeichert, sobald die SAS verifiziert ist (damit eine unzuverlässige Wiederverbindung es nicht verliert); eine URL-Verbindung wird gespeichert, sobald die Verbindung hergestellt ist.
• Jeder Eintrag speichert {name, uid, access_code, server, paired_at}. Die Wiederverbindung mit einem bekannten Host (per Name oder URL) aktualisiert den Eintrag an Ort und Stelle und behält den Namen.

Aus dem Quellcode bauen

Erfordert Go 1.25+. Reines Go, statisch gelinkt (CGO_ENABLED=0) – triviales Cross-Compiling, keine Laufzeitabhängigkeiten.

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/

Diagramme

Roadmap

Heute im Lieferumfang: Shell, Dateien und Proxy, erreichbar über den Browser oder die CLI, plus scp-artiges Dateikopieren und Ad-hoc-Pairing mit einer gespeicherten Gerätetabelle. Entworfen und in Arbeit:

• Serielle Brücke – eine entfernte /dev/ttyUSB0 über einen lokalen virtuellen Port ansteuern (z. B. Arduino IDE über das Internet ausführen). Ein Issue wurde hier eröffnet.
• TCP-Portweiterleitung – -L 5432:db.internal:5432, um nur im LAN erreichbare Dienste zu erreichen. Ein Issue wurde hier eröffnet.
• Remote-Desktop – Bildschirm über eine WebRTC-Videospur, Tastatur/Maus über den Datenkanal.

Lizenz

MIT – siehe LICENSE.

Mitwirken

Issues und PRs sind willkommen.