breakglass

README

breakglass

breakglass is a gokrazy package which provides emergency/debugging access to a gokrazy installation.

It breaks the gokrazy model in that it allows you to run payloads implemented in any language (e.g. busybox, implemented in C).

To repeat, breakglass’s whole idea is remote code execution (via SSH/SCP, listening only on private network addresss). Hence, it should usually not be present on your gokrazy installation, but it might be useful for development/debugging. As a safety measure, breakglass will not automatically be started on boot, but needs to explicitly be started via the gokrazy web interface.

Installation

Please see the gokrazy quickstart instructions if you’re unfamiliar with gokrazy.

When creating a new gokrazy instance, the gok new command automatically installs breakglass and authorizes ~/.ssh/id_*.pub.

If you want to repeat this installation for some reason, use:

gok add github.com/gokrazy/breakglass
gok add github.com/gokrazy/serial-busybox

Then, create an authorized_keys(5) file in breakglass.authorized_keys and install it as an extrafile:

{
    "Hostname": "hello",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ],
    "PackageConfig": {
        "github.com/gokrazy/breakglass": {
            "CommandLineFlags": [
                "-authorized_keys=/etc/breakglass.authorized_keys"
            ],
            "ExtraFilePaths": {
                "/etc/breakglass.authorized_keys": "/home/michael/gokrazy/repro/breakglass.authorized_keys"
            }
        }
    },
    "SerialConsole": "disabled"
}

Usage

Be sure to install the convenience SSH wrapper tool on the host:

go install github.com/gokrazy/breakglass/cmd/breakglass@latest

Start a shell

If you have github.com/gokrazy/serial-busybox installed on your gokrazy installation, you can directly start a shell without having to upload your own tools. Run:

breakglass gokrazy

If you prefer, you can also manually start breakglass in the gokrazy web interface and then use ssh gokrazy to log in.

Access control flags

breakglass has four opt-in flags to control when it runs and who may connect. All default to the existing behaviour, so leaving them unset changes nothing:

• -start_on_boot: start breakglass at boot instead of requiring a manual start via the gokrazy web interface. Pair this with -stop_after_idle so the server does not stay open indefinitely.
• -stop_after_idle=60s: shut the whole server down once no connection has been active for the given duration. This stops the process, it does not just disconnect an idle session. 0 (the default) disables it.
• -allowed_user=someuser: only accept connections whose SSH username matches this exact string, in addition to the public key check. This is a plain string comparison, not a real user account. Empty (the default) allows any username.
• -allowed_cidrs=10.0.0.0/16,10.2.0.0/16: only accept connections whose source IP is within one of these comma-separated CIDRs. Rejected before the SSH handshake. Empty (the default) allows any source. breakglass already listens only on private interfaces; this narrows further to specific ranges.

"PackageConfig": {
    "github.com/gokrazy/breakglass": {
        "CommandLineFlags": [
            "-authorized_keys=/etc/breakglass.authorized_keys",
            "-start_on_boot",
            "-stop_after_idle=60s",
            "-allowed_user=someuser",
            "-allowed_cidrs=10.0.0.0/16,10.2.0.0/16"
        ]
    }
}

Together these let breakglass sit through an automated SSH scan, such as the AWS Marketplace SSH base security scan, which needs a server that comes up on boot and is reachable without a manual start, then stops itself once the scan is done.

Run your own tools

1. Create a tarball containing your statically linked arm64 binaries and any other files you’ll need.
2. SCP that tarball to your gokrazy installation, where breakglass will unpack it into a temporary directory.
3. Execute a binary via SSH.

Here’s an example, assuming you unpacked and statically cross-compiled busybox in /tmp/busybox-1.22.0 and your gokrazy installation runs on host gokrazy:

$ cd /tmp/busybox-1.22.0
$ file busybox
busybox: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked,
for GNU/Linux 3.7.0, BuildID[sha1]=c9e20e9849ed0ca3c2bd058427ac31a27c008efe, stripped
$ ln -s busybox sh
$ tar cf breakglass.tar --dereference sh
$ breakglass -debug_tarball_pattern=breakglass.tar gokrazy
/tmp/breakglass564067692 # df -h
Filesystem                Size      Used Available Use% Mounted on
/dev/root                60.5M     60.5M         0 100% /
devtmpfs                445.3M         0    445.3M   0% /dev
tmpfs                    50.0M      1.8M     48.2M   4% /tmp
tmpfs                     1.0M      8.0K   1016.0K   1% /etc
/dev/mmcblk0p4           28.2G     44.1M     26.7G   0% /perm

Documentation

Overview

breakglass is a SSH/SCP server which unpacks received tar archives and allows to run commands in the unpacked archive.