Security and threat model
Your keys stay on your machine. Everything else is built around that.
This page says what Runlease protects, from whom, and where the protection stops. Each claim names the code that backs it, so you can check it.
The short version
Keys never leave
The SSH login key is generated on your machine, for one VM, and its private half never goes anywhere else.
The relay is blind
It copies bytes. It holds no key and no cloud credential, so it cannot read, change or impersonate a session.
The VM dials out
No public address, and SSH listens on localhost only. The VM connects outward to the relay and waits.
Identity fixed before boot
Your machine chooses the VM's SSH host key before the VM exists. Nothing is trusted on first use.
Verified, then unprivileged
The VM checks the agent binary against a SHA-256 before running it, then runs it with no privileges.
Every machine expires
A timer inside the VM deletes it when the lease ends, whether or not anyone is still watching.
Who holds what
Four parties are involved in a session. Read down the highlighted column: the relay, the only shared and internet-facing part, ends up holding almost nothing.
| Secret | Your machine | The relay | Your VM | The network |
|---|---|---|---|---|
| Login private keyProves you to the VM | – | – | ||
| VM host private keyProves the VM to you | – | – | ||
| Session contentsCommands, files, forwarded traffic | ciphertext | ciphertext | ||
| Cloud credentialsWhat launches and deletes VMs | – | only what you attach | – | |
| Slot tokenMatches your connections to your VM | hidden by TLS | |||
| Who you areThe email you signed in with | – | hidden by TLS |
holds it public half only– never sees it
The relay holds two things: a slot token and your email address. The token is a routing label. It gets a connection as far as the VM's SSH server and no further, because logging in still needs the login key. Your email is how the relay applies limits.
The tunnel
There are two layers of encryption, and they end in different places. TLS protects each hop to the relay. SSH runs inside it, from your machine all the way to the VM, with keys only those two ends have.
Both connections to the relay are outbound: one from your machine, one from the VM. That is why the VM needs no inbound port, and why the relay is the only part that must be reachable from the internet.
Pick an attacker
The useful question about any security design is what a specific attacker walks away with. Choose one.
The relay is compromised, or its operator is hostile
The case the design is built for. This applies to the public relay and to one you run yourself.
They get
- The power to refuse or drop your connections
- Connection metadata: your email, source addresses, timing, byte counts, slot tokens
- A TCP connection to your VM's SSH server, where they can try to log in
- The chance to serve a different agent binary to a booting VM
They do not get
- Your commands, files or forwarded traffic. They see ciphertext
- A way to pose as your VM. The host key was fixed before boot, and the CLI accepts no other
- A login. They hold no key, and password login is off
- Their binary executed. The VM checks its SHA-256 and stops on a mismatch
- Anything in your cloud account
If this mattersRun your own relay to keep the metadata inside your organisation. Nothing else changes.
Someone has a slot token
For example from a leaked log line or a copied registry file.
They get
- A TCP connection, through the relay, to that one VM's SSH server
- The ability to release the slot, which interrupts your session
They do not get
- A login. That needs the login private key
- Your existing sessions. Each one is its own SSH connection
- Any other VM. A token names one slot
Built inA token is 256 random bits, lives only in the relay's memory, and dies with its slot after 24 hours at most.
Someone is watching the network
Between you and the relay, or between the VM and the relay.
They get
- That you are talking to a relay, when, and how much
- On a plain
ws://relay only: the slot token and the agent download, in the clear
They do not get
- Session contents. SSH protects them on any transport
- Any key
- On
wss://: the slot token or your identity
What to doUse a wss:// relay address anywhere outside a private network. The public relay is wss:// only.
Someone can read instances in your cloud project
An IAM principal with instance read access. This is the weakest point, and the reason your cloud account counts as trusted.
They get
- The VM's boot script, which contains the host private key and the slot token
- With both, plus control of a relay, a way to present the right host key to your CLI and pose as the VM
They do not get
- A login to the real VM. The login private key is not in the boot script
- Your past sessions
What to doKeep instance read access in that project narrow. Launch agent machines in a project of their own.
Code you do not trust runs on the VM
Which is the normal case: the VM exists to run an agent and whatever it downloads.
It gets
- Everything on that VM, for as long as the lease lasts
- The instance metadata server, and so the boot script with the host key and slot token
- The permissions of any service account or instance profile you attached
- Root, only if the manifest set
sudo: passwordless
It does not get
- Your login private key, or the keys of any other VM
- A path back to your machine. Sessions are opened from your side only
- Your cloud credentials, unless you put them there
What to doAttach no service account, or one with a single narrow role. Leave sudo off. Keep leases short. Treat the VM as already lost and make sure nothing on it is worth keeping.
Guarantees, and the code behind them
The relay cannot read or alter a session
The relay bridges a raw byte stream between the CLI and the agent. What flows through it is the SSH protocol, negotiated end to end between the CLI and the VM's sshd. SSH encrypts and authenticates every packet with keys the relay never sees.
The relay cannot impersonate the VM
The CLI generates the VM's host key before the VM exists and pins it on every connection. A relay that routes you to any other machine fails the host key check and the connection is dropped. There is no trust-on-first-use anywhere in the code base, and host key checking is never turned off.
cmd/runlease/forward.go
The relay cannot log in
It never holds the login key. sshd on the VM accepts public-key authentication only, for one user, with root login off.
The agent binary is verified before it runs
The VM downloads runlease-agent from the relay at boot. The relay is not trusted, so the boot script checks the download against a SHA-256 and stops if it does not match. Release builds of the CLI have the digest of the matching agent compiled in. With a self-built relay, pin the digest in the manifest:
relay: addr: wss://relay.internal.example.com agentSha256: 3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855e
A plain go build of the CLI has no digest and prints a warning at up.
cmd/runlease/up.go · resolveAgentSHA256
The agent has no privileges
The agent only dials out to the relay and connects to localhost:22. Its systemd unit runs as an unprivileged user with NoNewPrivileges, an empty capability set, a read-only view of the system and no access to home directories or devices.
SSH listens on localhost only
With a relay, the VM gets no public address by default and its SSH server is bound to 127.0.0.1. The only way in is the agent, which dials out to the relay and hands each connection to SSH on localhost. The boot script writes the SSH settings first in the file, where SSH honours them, then asks SSH what it will enforce and stops if passwords are on, root login is allowed, or it would listen beyond localhost.
No NAT gateway on your subnet? Set publicIp: true. The address then carries outbound traffic only. See known limit 1.
pkg/manifest/manifest.go · PublicIP
sudo is off by default
The login user may run two fixed scripts as root: one that deletes the VM and one that moves the deletion timer. General sudo needs sudo: passwordless in the manifest, set before launch.
The relay fails closed
It refuses to start without authentication unless you pass --insecure-no-auth. It validates every slot token, caps live slots in total and per signed-in identity, gives a slot back when its machine has gone, and expires a slot after at most 24 hours.
pkg/relay/server.go
AWS instances require IMDSv2
Instances are launched with HttpTokens: required, which blocks the usual request-forgery route to instance metadata.
Known limits
These are real. We would rather you read them here than find them yourself.
Without a NAT gateway, the VM needs a public address to reach the relay. That is the
publicIp: truesetting. Runlease's own SSH server still listens on localhost only, but anything else you start on the VM that listens on all interfaces is then exposed to whatever your cloud firewall allows. With no relay at all, the VM always has a public address and SSH listens on it.Give the subnet a NAT gateway and keep the default, so the VM has no public address at all.
The boot script contains the host private key and the slot token. Anything that can read instance metadata can read them: an IAM principal with instance read access, and any process on the VM that can reach the metadata server. With both, an attacker who can also take the agent's place at the relay could present the right host key to your CLI. They still could not log in to the real VM.
Keep instance read access narrow. On AWS, IMDSv2 is required; on GCP the metadata server already requires a custom header.
A slot token is a bearer secret. Whoever holds it can open a TCP connection to the VM's
sshdthrough the relay, and can release the slot. They cannot get past SSH authentication.Stored keys are only as safe as your user account. Key pairs are encrypted at rest, but the key that encrypts them sits beside them, readable by your user. This stops casual copying of the credentials directory. It does not stop someone who already runs code as you.
Relay sign-in is Google identity only, for now. The relay learns the email address of whoever signs in, and logs it with each slot they open.
Limits are per identity, not per person. Someone with several Google accounts gets the free allowance for each. A cap on total slots is the backstop.
The relay sees who talks to what, and when.
Run your own if that metadata matters.
ws://and barehost:portrelay addresses are plaintext at the transport layer. SSH still protects the session, but the slot token and the agent download cross the network in the clear.Use
wss://outside a private network.A manifest is code. Its
setupsteps run as root on the VM.Read a manifest before you launch one you did not write.
Self-deletion on GCP needs the VM's service account to be able to delete the VM. A custom
gcp.serviceAccountis attached with thecloud-platformscope, so its IAM roles are the only limit on what code on the VM can do. Without that permission the VM powers itself off at the end of the lease instead: compute billing stops, but the stopped instance and its disk stay until something removes them.Use a dedicated service account with only that permission.
Spot VMs can be reclaimed by the cloud at any time. That is a property of spot capacity, not a failure.
Leases: making sure machines go away
A VM that outlives its purpose costs money and widens your attack surface. Three mechanisms overlap, so that no single failure leaves one running.
- Inside the VM
A systemd timer deletes the instance at the end of the lease. It is armed before anything in the boot script that can fail, and it does not depend on your machine being online.
- In your cloud
Every VM is tagged
runlease-managed, with who created it and when it expires, so anything that reads your inventory can find and remove strays. - On your machine
runlease daemonwatches leases from your side and terminates what has expired.
On GCP a reclaimed spot VM is deleted, not stopped. On AWS the instance terminates on shutdown.
Verify a release
Every release publishes checksums.txt with the SHA-256 of each binary. The install script checks it for you.
$ sha256sum --check --ignore-missing checksums.txt
checksums.txt is signed with Sigstore keyless signing, bound to the identity of the release workflow:
$ cosign verify-blob checksums.txt \
--bundle checksums.txt.sigstore.json \
--certificate-identity-regexp '^https://github.com/marshal-org/runlease/\.github/workflows/release-please\.yml@refs/heads/main$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
Each binary also carries a build provenance attestation:
$ gh attestation verify runlease-linux-amd64 --repo marshal-org/runlease
How the project itself is protected
- Every pull request runs tests, static analysis, a known-vulnerability scan and a secret scan.
- Pull requests from forks run on GitHub-hosted machines with a read-only token and no secrets.
- Cloud credentials exist only in one workflow that never runs on a pull request.
- Every GitHub Action is pinned to a commit, and dependencies are updated weekly.
Report a vulnerability
Please do not open a public issue. Email security@marshal.codes, or use the private advisory form on the GitHub repository. Say what an attacker can do, what they need to already have, the version, and how to reproduce it.
| When | What |
|---|---|
| Within 2 working days | We confirm we received the report |
| Within 7 days | We tell you whether we can reproduce it and how serious we think it is |
| Within 30 days | A fix is released for confirmed issues, sooner for critical ones |
| At release | An advisory is published, with credit to you unless you prefer otherwise |
We will not take legal action against anyone who reports in good faith.