Watch
0
0
Fork
You've already forked hyperhive
0

add an ssh ca to bao, agent ssh certificates and a target module

This commit is contained in:
atlas 2026-11-16 16:24:37 +01:00 • committed by mara
commit 0afb111862
5 changed files with 1056 additions and 17 deletions

View file

@ -14,3 +14,5 @@ homeserver are in [`swarm/`](../swarm/README.md).
`hive-forge -f <label>`.
- **[Matrix](matrix.md)** — an account on another homeserver, beside the
agent's own.
- **[SSH](ssh.md)** — let an agent SSH into a machine with short-lived
certificates from the swarm's SSH CA, and make that machine trust them.

View file

@ -0,0 +1,92 @@
# SSH access to a machine
Let an agent SSH into a machine you name, such as a test VM, without copying a
key onto it. The agent holds no standing SSH key. It asks the swarm's secret
store for a certificate that lasts an hour, and the machine trusts the swarm's
SSH certificate authority (CA) instead of a list of keys.
Nothing changes until you do both of these:
1. Switch SSH on for the agent and name the machines it may reach.
2. Make each machine trust the CA and list the agents allowed in.
## 1. Switch it on for an agent
In the agent's config:
```nix
services.hyperhive.agent.ssh = {
enable = true;
hosts.testvm = {
hostName = "10.0.0.7";
user = "test";
port = 22; # the default
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
};
};
```
`hostKey` is the machine's own host public key, the one line in
`/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a
machine that presents any other key, and never trusts a key on first sight.
The agent then runs `ssh testvm` with no other flag. The agent's SSH client
offers its certificate and nothing else. The option needs the agent to have a
store identity, the same as for its other store credentials.
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
[the network page](../../4-implementation/networking/network.md).
## 2. Make a machine trust the CA
On the swarm's store host, read the CA's public key:
```bash
bao read -field=public_key ssh-agents/config/ca
```
The store also serves the same key without a token at
`<store address>/v1/ssh-agents/public_key`. The key is public and you set it
once. Then import the module on the machine, which can be any NixOS machine,
and not only a hive host:
```nix
{
imports = [ hyperhive.nixosModules.agent-ssh-target ];
services.hyperhive.agentSshTarget = {
enable = true;
caPublicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
principals.test = [ "atlas" "maia" ];
};
}
```
`principals.<user>` lists the agents that may log in as that local account. The
account has to exist. An account with no entry accepts no certificate. The
module writes no `authorized_keys`.
## What an agent can and can't do
- It can only get a certificate for **its own name**. The store signs for the
name its identity carries, so atlas can't obtain one that says maia.
- The certificate lasts an hour, and the agent signs a new one every 20
minutes. The key lives in the agent's `/run` (memory) and never reaches disk.
A new container start makes a new key.
- It signs ed25519 user keys only, and the certificate allows a terminal
(`permit-pty`) and nothing else.
## Revoking access
- **One agent from one machine:** remove its name from that user's
`principals` and deploy the machine. The next login attempt fails.
- **One agent from every machine:** delete its cert-auth role
`hive-agent-<name>` in the store. It can no longer log in to the store, so
nothing signs for it, and its last certificate lapses within three hours.
- **The CA itself:** if the CA key changes, every machine needs the
new public key. Nothing replaces the CA by itself.
For the bao paths, field names and units, see
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).

View file

@ -38,6 +38,7 @@ the rest of the cell says how.
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
| `swarm/agents/<agent>/proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds |
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
| `swarm/hives/<hive>/squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes |
| `swarm/hives/<hive>/oidc/client` | authelia, first boot, straight into the store | the hive | ❌ minted once, straight into the store; minted again only when the store holds none | ✅ re-read when authelia refuses it |
| `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |

View file

@ -0,0 +1,83 @@
# The SSH CA for agents
Agents SSH out with certificates signed by an OpenBao SSH secrets engine mount.
The operator view, how to enable it and how to trust it on a machine, is
[SSH access to a machine](../../2-handbook/external-accounts/ssh.md).
## The mount and its role
`swarm-bao-agent-ssh-policy.service` runs on the store's host under the
granter's identity, like the agent PKI unit in
[the store page](bao.md). Each run:
1. enables the `ssh-agents` mount (type `ssh`) when it isn't there;
2. generates the CA key inside the mount, once, with
`config/ca generate_signing_key=true key_type=ssh-ed25519`. It does that
only when `ssh-agents/issuers` lists none. Nothing replaces or deletes the
CA, and the granter holds no read on it;
3. writes the role `ssh-agents/roles/swarm-agent`.
The mount and role names come from `nix/host-modules/lib/ssh-agent-ca.nix` and
are `SSH_MOUNT` and `SSH_ROLE` in `swarm-secret-client/src/policy.rs`; the
`bao-grants` module-eval suite fails when they differ.
The role signs for every agent:
| field | value |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `key_type` | `ca` |
| `allow_user_certificates` / `allow_host_certificates` | `true` / `false` |
| `allowed_users`, `default_user` | `{{identity.entity.name}}`, with `allowed_users_template` and `default_user_template` on |
| `allowed_user_key_lengths` | `{"ssh-ed25519": 0}`: ed25519 keys only |
| `allowed_extensions`, `default_extensions` | `permit-pty` |
| `allow_user_key_ids` | `false` |
| `ttl`, `max_ttl` | 60 minutes, 180 minutes |
The entity name is the agent's name: `swarm-controller` names the entity of
each agent's cert login after the agent
(`swarm-controller/src/agent_entity.rs`). A request for any other principal,
a glob, host certificates, other key types or another extension is a refusal
from the store.
## What an agent may call
The shared agent policy `hive-agent` (`render_shared_agent`) holds one more
stanza: `update` on `ssh-agents/sign/swarm-agent`, and nothing on the rest of
the mount. `swarm-controller` writes the policy at every start and at every
agent mint, so a deploy that adds the stanza reaches existing agents when the
controller restarts. A token already issued picks the change up on its next
request, because bao reads policies per request.
## The agent's unit
With `services.hyperhive.agent.ssh.enable`, `nix/agent-modules/ssh.nix` adds
`hive-agent-ssh-cert.service` and its timer, as the agent user:
- 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;
- 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 generated `/etc/ssh/ssh_config` has one `Host <name>` block per entry
(`HostName`, `User`, `Port`, `IdentityFile`, `CertificateFile`,
`IdentitiesOnly yes`, `StrictHostKeyChecking yes`), and
`/etc/ssh/ssh_known_hosts` one pinned line per `hostKey` (`[host]:port` for a
port other than 22).
## The target module
`nixosModules.agent-ssh-target` (`nix/target-modules/agent-ssh.nix`) sets
`services.hyperhive.agentSshTarget`: `caPublicKey`, written to
`/etc/ssh/hyperhive-agent-ssh-ca.pub` and named by `TrustedUserCAKeys`, and
`principals.<user>`, which becomes `users.users.<user>.openssh.authorizedPrincipals`.
NixOS then writes `/etc/ssh/authorized_principals.d/<user>` and sets
`AuthorizedPrincipalsFile` to it.
## Not covered
Egress. The default `egress.forward = "log"` lets a direct connection from an
agent to a machine's SSH port through, and `reject` blocks it; there is no
per-agent allowance for it yet.

View file

@ -100,6 +100,10 @@ Accounts outside the swarm that an agent can hold. Start at
the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/github.md).
- **How to give an agent GitLab accounts (`glab` + `git push`, more than one
instance)?** → [`2-handbook/external-accounts/gitlab.md`](2-handbook/external-accounts/gitlab.md).
- **How to let an agent SSH into a machine (short-lived certificates, a target
module)?** → [`2-handbook/external-accounts/ssh.md`](2-handbook/external-accounts/ssh.md);
the bao role and units in
[`4-implementation/swarm/ssh-ca.md`](4-implementation/swarm/ssh-ca.md).
## 3. Options reference