cert_command Interface

Version: 1.0 Date: 2026-03-28 Purpose: Define the contract between OpsWarden (issuer) and callers such as ops-bridge (consumer) for just-in-time SSH certificate acquisition.

Overview

cert_command is a shell string that a caller executes to obtain a short-lived, CA-signed SSH certificate for a named actor. The caller passes the cert to the SSH process alongside the actor's private key.

This interface is intentionally tool-agnostic: the caller (ops-bridge, a script, a CI pipeline) does not need to know whether the CA is a local file or HashiCorp Vault. Any command that writes a cert to stdout and exits 0 satisfies the contract.

Contract

Invocation

warden sign <actor-name> --pubkey <path/to/actor.pub>

Or any equivalent shell command:

vault write -field=signed_key ssh/sign/agt-role public_key=@/tmp/key.pub
ssh-keygen -s /path/to/ca -I agt-test -n agt-task -V +24h /tmp/key.pub && cat /tmp/key-cert.pub

Success (exit 0)

Stdout: certificate text only — a single line starting with the key type, e.g.:
```
ssh-ed25519-cert-v01@openssh.com AAAA...
```
Stderr: ignored by the caller (warden may print warnings there)
Side effect: cert is also written to ~/.local/state/warden/<actor>-cert.pub by warden (for use by warden status and warden scorecard)

Failure (exit non-zero)

Exit code: any non-zero value
Stdout: ignored
Stderr: passed through to caller logs / audit detail field
Caller behaviour: treat as a transient error; apply reconnect backoff and retry

Caller Responsibilities (ops-bridge)

Run cert_command via subprocess.run(shell=True) before each SSH subprocess launch
Write stdout to a tempfile in the state dir: ~/.local/state/bridge/<tunnel>-cert.pub
Add -i <cert_path> after -i <key_path> in the ssh command
Parse ssh-keygen -L -f <cert> to extract Key ID → log as cert_identity in audit
Parse Valid before: → schedule pre-emptive cert refresh ~5 min before expiry
On cert_command failure: log BRIDGE_DISCONNECTED with stderr; apply backoff

What the Caller Must NOT Do

Cache or reuse a cert across reconnects (always re-run cert_command per reconnect)
Write the cert to disk with world-readable permissions (mode 600)
Ignore a non-zero exit from cert_command (must treat as failure, trigger backoff)

Example: ops-bridge tunnels.yaml

tunnels:
  state-hub-coulombcore:
    host: coulombcore
    remote_port: 8001
    local_port: 8000
    ssh_user: agt-state-hub-bridge
    ssh_key: ~/.ssh/agt-state-hub-bridge_ed25519
    actor: agt-state-hub-bridge
    # cert_command is optional. When absent, ssh_key is used directly (static key mode).
    cert_command: "warden sign agt-state-hub-bridge --pubkey ~/.ssh/agt-state-hub-bridge_ed25519.pub"

TTL Guidelines (AccessManagementDirective §2)

Actor type	Max TTL	Pre-emptive refresh
`adm`	48 h	5 min before expiry
`agt`	24 h	5 min before expiry
`atm`	8 h	5 min before expiry

ops-bridge enforces the refresh schedule. OpsWarden enforces the max TTL at signing time.

Backward Compatibility

Callers that do not set cert_command continue to use the static key (ssh_key) with no TTL, cert logic, or refresh. The two modes are fully independent.

3.3 KiB Raw Permalink Blame History