BitBang CLI

BitBang CLI는 단일 정적 바이너리 원격 접근 멀티툴입니다: 대화형 셸을 열고, 파일을 탐색·전송하며, 원격 머신의 네트워크에 있는 웹 앱에 어떤 브라우저에서든 접근할 수 있습니다. 포트 포워딩도, 설정도, 계정도 필요 없습니다.

접근하려는 머신에서:

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

serve는 URL을 출력합니다. 아무 브라우저에서나 그 URL을 열면 터미널, 파일 브라우저, 그 머신의 네트워크 프록시를 얻을 수 있습니다. 또는 같은 바이너리로 bitbang connect <url>을 사용해 다른 터미널에서 연결할 수도 있습니다. 연결은 종단 간 암호화되며 P2P입니다. bitba.ng 서버는 양쪽을 중개한 뒤 물러납니다.

bitbang은 단일 정적 Go 바이너리입니다. BitBang 프로젝트의 일부이며, 이 백서에서 설계를 자세히 다룹니다.

6자리 코드로 페어링

URL을 붙여넣거나 QR 코드를 스캔할 수 없는 경우(예: 통화 중이거나 소리로 전달해야 하는 거리에 있을 때), bitbang serve는 짧은 페어링 코드도 함께 출력합니다. 상대방은 bitba.ng/<code>를 열거나 bitbang connect <code>를 실행하면 화면에 두 번째 6자리 숫자가 표시되고, 그 숫자를 다시 당신에게 읽어줍니다. 당신이 그 숫자를 입력하면 승인됩니다. 중간자 공격은 두 숫자를 일치시킬 수 없으며, 페어링은 다음에 사용할 기기 연결 자격 증명을 저장합니다(예: bitbang connect nas1). Magic Wormhole을 알고 있다면 형태가 비슷합니다. 두 머신을 안전하게 소개하는 구두 코드입니다.

왜?

• 포워딩하거나 설정할 것이 없습니다. NAT, CGNAT 또는 잠긴 네트워크 뒤에서도 동작합니다. 라우터 변경, VPN, 터널 데몬이 필요 없습니다.
• 연결하는 쪽에 설치할 것이 없습니다. 브라우저만으로 충분합니다. 스크립팅, 파이프, 파일 복사가 필요할 때는 CLI를 사용할 수 있습니다.
• 설계상 프라이빗합니다. 트래픽은 WebRTC/DTLS, P2P입니다. 시그널링 서버는 트래픽을 볼 수 없습니다. 직접 경로가 불가능하면 TURN 릴레이가 암호문만 전달합니다.
• 계정 없음, 텔레메트리 없음.

SSH를 쓰면 안 되나요?

bitbang은 ssh와 같은 형태입니다: serve, connect, cp는 sshd, ssh, scp에 대응하며, 전송 계층으로 TCP 대신 WebRTC를 사용합니다. 이미 SSH로 편하게 접속할 수 있는 머신이라면 그 차이는 별로 체감되지 않습니다. 하지만 bitbang의 대부분은 예상보다 자주 마주치는 불편함에서 나왔습니다:

도달성. 원격 SSH 접근에는 인바운드 경로가 필요한데, 대부분의 네트워크에서 그것을 여는 것은 당신의 결정이 아닙니다. CGNAT(셀룰러, Starlink, 많은 ISP), 기업, 대학, 시립 네트워크 등이 그렇습니다. 그래서 실제로는 Tailscale, VPN, ngrok 같은 두 번째 시스템을 추가로 설치하게 됩니다. 또 다른 설치, 또 다른 계정, 계속 실행해야 하는 또 다른 데몬이 생깁니다. bitbang serve는 열린 포트가 필요 없으며 어디서든 동작합니다.

설정. SSH는 접속을 허용하려면 먼저 활성화하고 구성해야 합니다. Raspberry Pi OS에서는 기본적으로 비활성화되어 있고, 종종 키 전용이므로 먼저 머신에 공개 키를 넣어야 합니다. 어떻게 할까요? 이메일이나 USB 스틱이 보통 가장 간단한 방법입니다. bitbang은 대신 6자리 코드 교환으로 연결을 설정합니다. 전화로 안전하게 하거나 방 건너편에 소리쳐 전달할 수 있는 방법입니다. 또한 일반 사용자로 실행됩니다. 루트, 데몬, 설정 파일이 필요 없습니다.

프록시. 해당 머신의 네트워크에 있는 웹 앱에 접근하려면 SSH는 앱마다 별도의 터널을 미리 이름을 붙여 만들어야 합니다. bitbang 프록시는 범용적입니다. 연결 시점에 웹 앱의 URL을 지정하면 됩니다.

브라우저 클라이언트. SSH는 연결하는 쪽에 SSH 클라이언트와 키 또는 비밀번호가 필요합니다. bitbang은 브라우저만 필요합니다. 즉, 휴대폰, 빌린 노트북, 또는 터미널을 한 번도 열어본 적 없는 사람도 가능합니다. URL을 건네주면 당신이 부여한 접근 권한을 얻게 됩니다.

bitbang 사용하기

모든 연결에는 두 끝이 있습니다: 리스너(접근 대상 머신에서 실행되는 bitbang serve)와 커넥터(브라우저 또는 접근하는 머신의 bitbang CLI). 하나의 리스너 URL로 두 종류의 커넥터를 모두 서빙합니다.

리스너: 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

각각 QR 코드, URL, 페어링 코드를 출력합니다.

브라우저에서 연결하기

URL을 엽니다. 서빙되는 내용에 따라 다음을 얻을 수 있습니다:

• 셸 -- 페이지에 전체 터미널(색상, 크기 조절, 복사/붙여넣기).
• 파일 -- 탐색, 미리보기, 다운로드, 업로드.
• 프록시 -- LAN 주소(nas.local, 192.168.1.10:8080, localhost:3000/admin)를 입력하고 로컬에 있는 것처럼 앱을 사용합니다. 로그인, 쿠키, 업로드, 스트리밍 모두 동작합니다.

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

성공한 모든 connect 또는 페어링은 ~/.bitbang/devices.json에 저장되므로, 그 후에는 짧은 이름만으로 충분합니다: bitbang connect nas1.

설치

한 줄 명령은 아키텍처(amd64, arm64, armv7)를 감지하고, 최신 GitHub 릴리스에서 바이너리를 다운로드한 다음, 릴리스의 checksums.txt에 대해 SHA-256을 검증하고 ~/.local/bin/bitbang에 설치합니다.

버전을 고정하거나, 위치를 변경하거나, 스크립트를 먼저 감사하려면:

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 및 Windows 빌드가 예정되어 있습니다. 각각에 대한 이슈가 생성되었습니다(macOS, windows). 반응을 달거나 글을 남겨 관심을 보여주세요. 수동 설치: Releases에서 바이너리를 다운로드하여 PATH에 넣으세요. 소스에서 빌드: 아래를 참조하세요.

설치 URL이 동작하는 방식

bitba.ng/install은 호스팅된 스크립트가 아니라 리다이렉트입니다. 체인은 다음과 같습니다:

1. curl이 https://bitba.ng/install에 접속하면 이 리포지토리(main 브랜치)의 install.sh로 302 응답합니다.
2. 스크립트가 셸에서 실행되어 OS+아키텍처를 감지하고 https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>에서 바이너리 에셋을 다운로드합니다.
3. 같은 릴리스에서 checksums.txt를 가져와 바이너리의 SHA-256을 검증합니다.
4. ~/.local/bin에 설치합니다(재정의 가능).

설치 스크립트는 설치하는 코드와 같은 이 리포지토리에 있습니다. 즉, 바이너리와 함께 검토할 수 있고, 표준 bitba.ng 호스트는 짧은 URL만 소유합니다. 자체 호스팅 사용자는 자신의 호스트의 /install을 자신이 배포하는 어떤 스크립트로든 지정할 수 있습니다. 시그널링 서버의 INSTALL_URL 환경 변수가 리다이렉트 대상을 제어합니다(비어 있으면 404).

보안

• 자기 인증 신원. 첫 실행 시 bitbang은 ~/.bitbang/<program>/ 아래에 RSA 키페어를 생성합니다. 기기 UID는 공개 키에서 파생되므로, 기기를 사칭하려면 UID의 두 번째 원상을 찾아야 합니다.
• 비밀은 서버에 닿지 않습니다. 접근 코드는 URL 프래그먼트(#…)에 있으며, 브라우저는 이를 절대 전송하지 않습니다. bitba.ng는 연결을 승인하는 자격 증명을 전혀 보지 않고 연결을 중개합니다.
• 종단 간 암호화. 모든 트래픽은 WebRTC의 DTLS를 사용합니다. 시그널링 서버는 공개 키, 파생된 UID, 연결 메타데이터만 볼 수 있으며 데이터는 절대 볼 수 없습니다. TURN 릴레이가 필요하면 암호문만 볼 수 있습니다.
• 검증된 페어링. 코드 페어링에서 소리 내어 읽는 숫자는 SAS(짧은 인증 문자열)로, 협상된 DTLS 지문과 두 개의 커밋된 nonce로부터 양쪽에서 독립적으로 계산됩니다. 지문이 필연적으로 다른 중간자 공격자는 두 숫자를 일치시킬 수 없습니다.
• 선택적 PIN(--pin)은 영구 또는 헤드리스 설정용이며, 휘발성 모드(-ephemeral)는 실행할 때마다 새 신원을 사용합니다.

양쪽 끝이 시그널링 서버를 신뢰하지 않고 서로를 인증하는 방법은 여기에 자세히 설명되어 있습니다: 신뢰 없는 시그널링: 중앙 권한 없는 인증.

비교

명령 참조

플래그는 두 형식 모두 허용합니다(-pin 또는 --pin). 불리언 플래그는 별도 표시가 없으면 기본적으로 꺼짐입니다.

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 -- 리스너 실행

공용 플래그 (serve의 네 가지 형식 모두):

셸 플래그 (serve 및 serve shell):

파일 플래그:

(고급: -video-fd N은 상속된 소켓페어 FD를 외부 비디오 헬퍼에 전달합니다. 내부/임베딩용입니다.)

bitbang connect <target> [-- command …] -- 클라이언트 셸

<target>은 다음 중 하나일 수 있습니다:

• 저장된 이름 -- 예: nas1; 알려진 호스트 테이블에서 확인됨 (아래 참조)
• 6자리 페어 코드 -- 예: 482731; 페어링 흐름을 실행한 후 연결
• URL -- https://bitba.ng/<id>#<code>, bitba.ng/<id>#<code> 또는 id>#<code> 형태

-- command가 없으면 대화형 셸을 엽니다(stdin이 터미널이면 PTY). -- command args…가 있으면 해당 단일 명령을 비대화형으로 실행하고 그 상태 코드로 종료합니다(신호 종료는 128로 보고).

bitbang cp <src> <dst> -- 파일 복사

<src> / <dst> 중 정확히 하나가 원격이며 <URL>:/path 형식입니다(URL은 connect에서 허용되는 모든 형식). -는 stdin/stdout을 의미하므로 cp <URL>:/f -는 stdout으로 스트리밍하고 cp - <URL>:/f는 stdin에서 업로드합니다. 로컬 쪽의 끝에 붙는 / 또는 .은 원격 기본 이름을 유지합니다(scp 스타일).

기기 이름 및 알려진 호스트 테이블

성공한 모든 connect 또는 페어링은 ~/.bitbang/devices.json(모드 0600)에 저장되므로, URL이나 코드 대신 짧은 이름으로 다시 연결할 수 있습니다:

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

• -name NAME 은 이름을 선택하며 새 호스트에만 적용됩니다. 생략하면 자동 이름(device1, device2, …)이 지정되어 출력됩니다(Saved as "device1".).
• 이름 규칙: 이름은 문자로 시작해야 하며 문자, 숫자, -, _만 포함할 수 있습니다. 따라서 6자리 코드나 URL로 오인될 수 없습니다. 조회와 고유성은 대소문자를 구분하지 않습니다.
• connect를 통한 이름 변경 불가: bitbang connect nas1 -name nas2는 거부됩니다. -name은 최초 저장 전용입니다.
• 저장 시점: SAS가 검증되는 즉시 페어링이 기록됩니다(불안정한 재연결로 인해 손실되지 않음). URL connect는 연결된 후 기록됩니다.
• 각 항목은 {name, uid, access_code, server, paired_at}을 저장합니다. 알려진 호스트에 이름이나 URL로 다시 연결하면 항목이 그 자리에서 갱신되고 이름이 유지됩니다.

소스에서 빌드

Go 1.25+ 필요. 순수 Go, 정적 링크(CGO_ENABLED=0) -- 크로스 컴파일이 간단하며 런타임 의존성이 없습니다.

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/

다이어그램

로드맵

현재 제공 중: 셸, 파일, 프록시 -- 브라우저 또는 CLI에서 접근 가능하며, scp 스타일 파일 복사와 저장된 기기 테이블을 이용한 임시 페어링도 포함합니다. 설계가 끝났고 진행 중인 기능:

• 시리얼 브리징 -- 로컬 가상 포트에서 원격 /dev/ttyUSB0 구동 (예: 인터넷으로 Arduino IDE 실행). 이슈가 여기에 열려 있습니다.
• TCP 포트 포워딩 -- -L 5432:db.internal:5432로 LAN 전용 서비스에 접근. 이슈가 여기에 열려 있습니다.
• 원격 데스크톱 -- WebRTC 비디오 트랙으로 화면, 데이터 채널로 키보드/마우스.

라이선스

MIT -- LICENSE 참조.

기여

이슈와 PR을 환영합니다.