stern-event-agent/ssh-image

ssh-image — key-only Dropbear SSH for a Stern Spike 2 raw SD image

Turns a factory Spike 2 raw SD image (King Kong LE 0.97.0, 16 GiB) into an SSH-enabled image, reproducing the working setup documented in /Users/matt/src/pinball-assets/README.md sections 1 and 3. The original image is only ever read; the result is a new image file you choose.

enable-ssh.sh -i <factory>.raw -o <factory>.ssh.raw -k <your>.pub

No password is ever set or needed — Dropbear is compiled without password auth. The public key is an explicit input (-k); no private key is read, stored, or embedded anywhere by this tool.

What gets injected (into the ext3 rootfs partition, p2, only)

Path on the machine	Source here	Mode	Owner
/usr/local/bin/dropbear	bin/dropbear	0755	0:0
/usr/local/bin/dropbearkey	bin/dropbearkey	0755	0:0
/usr/libexec/sftp-server	bin/sftp-server	0755	0:0
/etc/init.d/sshd	files/sshd	0755	0:0
/etc/rc5.d/S30sshd	symlink → ../init.d/sshd	0777	0:0
/home/root/.ssh	new directory	0700	0:0
/home/root/.ssh/authorized_keys	your -k file	0600	0:0

Byte-identical to the deployed king_kong_le-0_97_0.ssh.16G.sdcard.raw (verified against it with debugfs dump + sha256 for all three binaries).

• dropbear / dropbearkey — 2025.88, static musl armhf. Password auth compiled out (DROPBEAR_SVR_PASSWORD_AUTH 0), DROPBEAR_REEXEC=0 (the Spike 2 kernel is 3.14 and predates execveat).
• sftp-server — static Go binary (pkg/sftp). dropbear dropped its built-in scp upstream; this makes scp/rsync work. It lives at /usr/libexec/sftp-server because that is dropbear's compile-time SFTPSERVER_PATH default — no -s flag in the init script is needed.
• /etc/init.d/sshd — SysV init script: on start it generates Dropbear host keys (rsa/ecdsa/ed25519) into /data/dropbear if absent (host keys are per-machine, so they are generated on first boot rather than baked in), then runs dropbear on port 22.
• /etc/rc5.d/S30sshd — boot hook; S30 runs before the game's S95game.

Everything else in the image — p1 (boot, FAT), the game partition, and every data/dump byte — is untouched and verified byte-identical after the run (cmp over both regions outside p2).

Requirements

• macOS (Homebrew). The image work uses cp, dd, cmp, shasum — all stock.
• brew install e2fsprogs — provides debugfs and e2fsck (1.4x).
• python3 (system) — for MBR parsing and path resolution.
• For validate-image.sh only: Docker (any linux container) — it runs privileged (bind mounts for /dev, /proc) and uses qemu-user-static to boot the ARM rootfs. build-binaries.sh also needs Docker plus network access (musl.cc, GitHub, codeload).

Usage

# 1. make sure you have a public key (the private half never enters this repo)
ssh-keygen -t ed25519 -a 100 -f ~/.ssh/spike2      # if you don't have one
#    use ~/.ssh/spike2.pub as the -k input

# 2. dry run: parses the MBR, inspects p2, prints the exact plan, writes nothing
./enable-ssh.sh -i ~/images/king_kong_le-0_97_0.Release.16G.sdcard.raw \
    -o /tmp/king_kong_le-0_97_0.ssh.16G.sdcard.raw \
    -k ~/.ssh/spike2.pub --dry-run

# 3. real run (APFS clone is instant; a full 16 GiB copy on other volumes takes a while)
./enable-ssh.sh -i ~/images/king_kong_le-0_97_0.Release.16G.sdcard.raw \
    -o ~/images/king_kong_le-0_97_0.ssh.16G.sdcard.raw \
    -k ~/.ssh/spike2.pub

# 4. optional deep check before flashing (Docker, qemu-arm, real ssh login)
./validate-image.sh -i ~/images/king_kong_le-0_97_0.ssh.16G.sdcard.raw \
    -k ~/.ssh/spike2.pub

Options: -b DIR / -f DIR point at alternative binary / init-script directories (defaults are ./bin and ./files beside the script); --force accepts a p2 geometry other than the known King Kong layout (12 MiB offset, 336 MiB size — the script parses the MBR, it does not assume); --overwrite replaces an existing output file (refused by default); --dry-run writes nothing.

The script refuses to run if: input/output are the same file, the output already exists, the key file contains a private key or unrecognised lines, the image has no MBR / no ext3 rootfs partition, or the rootfs fails a read-only e2fsck -fn before or after injection.

Safety model

• The input image is opened read-only and is never written; its size is re-checked at the end.
• The output is created fresh (cp -c APFS clone when possible, else full copy) and must be a different path from the input.
• Only one region is ever written back: p2, exactly skip/count in 512-byte sectors. Afterwards cmp proves every byte before and after p2 equals the input — including wherever the data/dump partitions live.
• Host keys are generated on the machine at first boot (/data/dropbear), never baked into the image.
• Before flashing over a card that is in use: back up its data partition (scores/settings/NVM). The image's /data is factory-empty; flashing it over a live card erases that data. (The original setup lost it once — restored from a pre-SSH backup via tar-over-ssh.)
• Flash to a full-size SD card in the machine's mmcblk0 slot. Never flash to the machine's live SD while it is the boot device.

Validation

enable-ssh.sh self-verifies every run (filesystem health before/after, presence + mode + owner of all injected objects, sha256 of the three binaries inside the result, and the cmp preservation proof).

validate-image.sh goes further: it extracts the output image's p2 into a scratch rootfs tree (debugfs rdump, no loop device needed) in a privileged Docker container, starts dropbear via the image's own /etc/init.d/sshd (first-boot path: the image's dropbearkey generates the host keys into /data/dropbear), and then from the container (a) logs in as root over ssh with a throwaway ed25519 key generated inside the container (your private key is never read or stored), (b) confirms password auth is refused, and (c) runs sftp put/get to prove the sftp-server wiring. It also statically checks that the deployed authorized_keys in the image equals the -k file you gave enable-ssh.sh. The image file is only ever read; all test mutations happen on a scratch copy of p2.

Building the binaries (provenance and rebuild)

bin/dropbear, bin/dropbearkey and bin/sftp-server were built once, on 2026-10-11, in the pinball-assets/.ssh-build/ tree:

binary	build	notes
dropbear, dropbearkey	dropbear 2025.88, ./configure --host=arm-linux-musleabihf --disable-zlib --enable-static, localoptions.h: DROPBEAR_SVR_PASSWORD_AUTH 0, DROPBEAR_CLI_PASSWORD_AUTH 0, DROPBEAR_SVR_PUBKEY_AUTH 1, DROPBEAR_REEXEC 0	musl.cc arm-linux-musleabihf cross toolchain; Debian 12 container
sftp-server	Go 1.19+ in GOPATH mode from codeload tarballs (pkg/sftp v1.13.2, kr/fs v0.1.0, golang.org/x/crypto v0.7.0, x/sys v0.7.0), GOARCH=arm GOARM=7 CGO_ENABLED=0, go build -trimpath -ldflags="-s -w"	static, stripped

To rebuild them from this directory (requires Docker):

./build-binaries.sh     # rewrites bin/ and prints file(1) + sha256 for each

The originals live on at pinball-assets/.ssh-build/out-musl/{dropbear,dropbearkey} and pinball-assets/.ssh-build/out-sftp/sftp-server with the build scripts build.sh (dropbear) and build-sftp-go.sh (sftp).

Files

Path	What
enable-ssh.sh	the injection tool (input image + public key → output image)
validate-image.sh	Docker/qemu functional test of an output image (optional)
build-binaries.sh	rebuilds bin/ in a Docker container (optional)
files/sshd	the SysV init script injected to /etc/init.d/sshd
bin/dropbear, bin/dropbearkey, bin/sftp-server	the static armhf binaries injected into the image