Watch
0
0
Fork
You've already forked hyperhive
0

sign ssh certificates on demand from ssh itself, warn before setup, say what to do when a host key changes

This commit is contained in:
atlas 2026-11-16 19:42:44 +01:00 • committed by mara
commit 3d7541c0af
3 changed files with 521 additions and 67 deletions

View file

@ -5,6 +5,13 @@ key onto it. The agent holds no standing SSH key. While you allow it, the agent
gets a certificate from the swarm's SSH certificate authority (CA) that lasts
an hour. The machine trusts the CA, so it needs no list of keys.
> **Warning:** SSH access with no constraints on the machine makes the agent
> unconstrained there. Whatever the agent's own sandbox stops it doing, it can
> do on a machine it can log in to. Switch SSH on only for machines you would let
> the agent control completely. What the agent can do on the machine is up to
> the account you let it use: give it an account with only the rights you want
> it to have.
Two things have to be true before an agent gets in:
1. **You switch SSH on for that agent**, in the swarm UI.
@ -16,9 +23,14 @@ certificate unit. The switch alone decides whether the swarm signs.
## 1. Switch it on for an agent
Open the agent's card in the swarm UI and find the **ssh** row. Select it and
tick **allow the agent to get SSH certificates**. The default is off. The
agent has a certificate within about 25 minutes of the change. Untick the box
to stop new certificates. The row also shows the three forms of the target
tick **allow the agent to get SSH certificates**. The default is off. Untick the
box to stop new certificates.
The change takes seconds, not minutes. The swarm updates the agent's login
within a few seconds. The agent gets its certificate the first time it runs
`ssh` after that, so there is nothing to wait for on the agent. If it ran `ssh`
just before you ticked the box, the next run within ten seconds still finds the
refusal remembered; after that it signs. The row also shows the three forms of the target
setup below, already filled in with the swarm's CA key and the agent's name.
The agent then runs `ssh user@host`, with no other setup. It offers its
@ -29,6 +41,25 @@ shows on the first connection, keeps it in its state directory (so it survives
restarts), and refuses a changed key afterwards. A swapped machine on the first
contact would go unnoticed. The row's explainer says so.
### When a host's key changes
The agent refuses a machine whose key differs from the one it kept, and `ssh`
says the host identification changed. A rebuilt or replaced machine does this.
Verify the new key out of band first: read the machine's host key on the machine
itself (`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`) and compare it with
the fingerprint the agent reports. If it matches, tell the agent to forget the
old one. On the hive host, as root:
```bash
ssh-keygen -R <host> -f /agents/<agent>/state/ssh_known_hosts
```
The next connection records the new key. You can also delete the line, or the
whole file, at that path. To work inside the agent's container instead, see
[`hivectl`](../hives/hivectl.md) for the shell it opens as the agent user. If the
key changed and you didn't change the machine, don't clear it: something else
answers at that address.
This doesn't open the network. If you set the hive's `egress.forward` to
`reject`, the hive refuses the agent's direct connection to the machine's port
until a separate allowance exists; the default `log` lets it through. See
@ -77,8 +108,8 @@ bao read -field=public_key ssh-agents/config/ca
entry, or the `cert-authority` line) and deploy the machine. The next login
attempt fails.
- **One agent from every machine:** untick the switch. The swarm stops signing
for it within five minutes; an agent already signed in can still sign
for up to an hour. Destroying the agent cuts its store identity off within
for it within seconds; a token the agent got while the switch was on can still
sign for up to an hour. Destroying the agent cuts its store identity off within
minutes. Either way a certificate already signed stays valid until it
expires, at most three hours, so removing the principal on a machine is what
cuts it off there at once.

View file

@ -81,11 +81,16 @@ and attaches it to the agent's cert-auth role `hive-agent-<name>` as a second
- the key is `/run/hive-agent-ssh-cert/key` (directory `0700`, files `0400`,
`UMask=0377`), generated when absent; the certificate is
`key-cert.pub` beside it;
- each run logs in to the store with the cert identity `hive-agent-bao-identity`
keeps, signs `key.pub` through the role, checks the answer parses as a
certificate and renames it into place. A `403` from the signing call is the
switch being off: the unit prints one line and exits 0, and the next tick asks
again. Any other failure fails the unit, which retries;
- the unit's script is also the **helper** `ssh` runs: one text, two entries. Each
run logs in afresh to the store with the cert identity
`hive-agent-bao-identity` keeps, signs `key.pub` through the role, checks the
answer parses as a certificate and renames it into place. A `403` from the
signing call is the switch being off: the unit prints one line and exits 0,
and the next tick asks again. Any other failure fails the unit, which retries.
One run at a time (`flock` on the directory), the unit's or an `ssh`'s;
- the unit copies the store's CA out of its credentials into
`server-ca.pem` beside the key, so that an `ssh` run, which has no
credentials directory, can reach the store;
- the timer fires 20 minutes after each run, a third of the 60-minute lifetime,
from the same file as the role's TTL;
- the system `/etc/ssh/ssh_config` has one `Host *` block: `IdentityFile` and
@ -94,7 +99,16 @@ and attaches it to the agent's cert-auth role `hive-agent-<name>` as a second
`UserKnownHostsFile /agents/<name>/state/ssh_known_hosts`. The host binds the
state directory in, so the pins survive a restart; the container root
doesn't. The agent trusts the first key a host shows and refuses a changed
one.
one;
- the same config starts with `Match exec "HIVE_SSH_CERT_ENSURE=1 <helper> </dev/null"`,
with no settings of its own. `ssh` runs the command while it reads the config,
before it loads an identity. With `HIVE_SSH_CERT_ENSURE` the helper is silent and
its exit status says whether a usable certificate exists: it exits 0 at once
when the certificate has more than ten minutes left, asks the store nothing
for ten seconds after a refusal, and otherwise logs in and signs. Nothing in
the config depends on the answer; the point is the certificate it leaves
behind. Every `ssh` on the agent runs this, so a loop of them while the switch
is off costs one login per ten seconds.
## The target module

View file

@ -857,10 +857,12 @@ checkbox that does a `PUT` of `ssh` with the stored permissions beside it, and
a folded **on the target** section. That section reads `GET /api/ssh/ca` and
shows the swarm's CA key and the agent's name as the lines for a NixOS machine,
a home-manager user and a plain `authorized_keys` file, with a copy button; the
card builds the text in `frontend/packages/swarm-ui/src/agent/detail/ssh.ts`. A `PUT`
card builds the text in `frontend/packages/swarm-ui/src/agent/detail/ssh.ts`. Above the checkbox the card shows a warning (SSH access to an
unconstrained machine leaves the agent with no limits there), the explainer with the delays,
and how to forget a host key that changed. The card says the change takes seconds, and why: the controller rewrites the role
when the field changes and the agent signs on its next `ssh`. A `PUT`
that leaves `ssh` out, and the `DELETE` of **use the default**, keep it. The
controller attaches the signing policy to the agent's login role within five
minutes; see [the SSH CA](../swarm/ssh-ca.md#the-switch-and-the-signing-policy).
controller attaches the signing policy to the agent's login role at once; see [the SSH CA](../swarm/ssh-ca.md#the-switch-and-the-signing-policy).
A saved change isn't instant. The hive reads the grant about every 30 seconds
and the agent takes it at its next turn. A change to `manage_root_agent`