SSH access

shortspan ssh prod-web-1

An interactive session on a server you have never held a key for. The alias is what an admin registered the server under; shortspan ssh with an unknown alias lists what is available in the active project.

1. 1

   The alias is resolved to a target

   Route binding is by id, so the CLI looks the alias up first. A target you cannot see is not in the list, so an unauthorized alias is indistinguishable from a wrong one.

2. 2

   A proxy token is issued

   Not the credential - a single-use, short-lived token standing in for it. Permission, plan, and any required grant are all checked here, and the request is audited.

3. 3

   The proxy token is exchanged

   A second call redeems it for the credential itself. The credential is therefore never in the response to the request that was authorized.

4. 4

   The session is established

   The key or password becomes an in-memory SSH auth method and is zeroed immediately after the handshake. Nothing is written to ~/.ssh.

# One server
shortspan ssh exec prod-web-1 "systemctl status nginx"

# Every server tagged "web"
shortspan ssh exec @web "systemctl status nginx"

A leading @ means a tag rather than an alias. Tags are set on the target when it is registered, so @web, @db, and @eu-west are yours to define.

Targets are visited in sequence, with each one's output prefixed by its alias. A failure on one host is reported and the run continues to the next - a fleet command that stops at the first unreachable machine tells you less than one that finishes.

Each SSH target can carry a runner policy, set by an admin under Infrastructure → the target → Security. It is two fields, and they are easy to confuse with the login account, so it is worth being exact:

login user

The SSH username on the target - how Shortspan connects. It is set when the server is registered, and it is who you are in an interactive shortspan ssh session.

run as

The account on the server that runbook steps and ssh exec commands run as, through sudo -n -u <run-as> --. It must exist on the server, and it may not be root.

allowed executables

Absolute paths to the programs those commands may start - /usr/bin/git, not git pull or cd /var/www. The first word of every command is checked against this list.

The policy applies to ssh exec and runbooks only. An interactive shortspan ssh is a real shell as the login user, so the login user's own privileges are the ceiling there.

The part the server enforces is its sudoers rule: the login user may run exactly the allowed executables as the run-as account, without a password. Deploying with a runbook walks through setting all of it up.

shortspan ssh check prod-web-1

Connects with the brokered credential and checks, without changing anything, that the server matches the policy: the run-as account exists and is not privileged, sudo is installed, the rule covers every allowed executable, each executable exists, and the run-as account can start the tools it is allowed.

Every check prints the command it ran and what came back. When something is wrong, the report ends with What to do next: each fix once, failures first, as commands you can paste on the server.

The report is recorded in the audit log and shown on the target's security page, with its history. --json prints it for a pipeline, --no-upload keeps it local, and -v shows the evidence behind passing checks too. The command exits non-zero when a check fails.

Registration is a console action, because it means handing a credential to the platform and that should be deliberate. An admin supplies:

alias

What people type. prod-web-1, not 10.0.0.5.

host and port

Where it actually is. Port defaults to 22.

username

The account to connect as.

authentication

A password or a private key. Either is encrypted at rest and never shown again after it is saved.

tags

Free-form labels, used by ssh exec @tag.

See Infrastructure for the full flow, including bastions.

SSH target 'x' not found

Either the alias is wrong, or it is in a different project. Check shortspan config list and shortspan ssh with no arguments.

failed to parse private key

The stored key is malformed, or it is passphrase-protected. Encrypted private keys are not supported - the broker has no passphrase to supply.

403 on the credential request

You hold viewer rather than developer on this project, or the target requires a temporary grant you do not have. shortspan access request asks for one.

Connection succeeds, commands are refused

The server-side account lacks the permission, not the broker. Shortspan authenticates you as the registered user; what that user may do is your server's business. shortspan ssh check <alias> shows which part is missing.

sudo: unknown user

The run-as account does not exist on the server yet. Shortspan stores its name; it never creates accounts.

sudo: a password is required

The sudoers rule is missing or lacks NOPASSWD. ssh check prints the exact rule for this target.