SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

SSH Certificate Authority and credential issuance for the ops fleet — signs short-lived certificates for adm/agt/atm actors; provides the cert_command interface consumed by ops-bridge and other tooling.

Core Idea

Implements wiki/AccessManagementDirective.md §§1–5. Owns the CA key, actor identity inventory, signing logic, and scorecard. Two backends: local (ssh-keygen, for labs / offline use) and vault (OpenBao or other Vault-compatible SSH secrets engine API, for production). Both expose the same CLI surface and the same cert_command interface — callers never need to know which backend is in use.

In Scope

Local CA backend (ssh-keygen -s) — fully functional without platform secrets access
OpenBao / Vault-compatible SSH engine backend — production signing via HTTP API
Actor identity registry (inventory.yaml) — maps actors to principals and TTL policy
cert_command interface: warden sign <actor> --pubkey <path> → cert text on stdout
TTL policy enforcement per ActorType (adm 48 h, agt 24 h, atm 8 h)
Certificate status inspection (warden status)
Stale-cert cleanup and scorecard checks (cert-side; see §5 of directive)
warden issue — generate keypair + sign in one step (for agt/atm actors)
ops-ssh-wrapper script — wraps SSH commands with automatic cert acquisition

Out of Scope

Tunnel lifecycle management → ops-bridge
Host-side principal deployment (/etc/ssh/auth_principals/) → railiance-infra Ansible
SSH key generation for human admins (self-service: ssh-keygen)
OpenBao / Vault cluster setup, HA, or PKI secrets engine deployment
Session recording, SIEM forwarding, audit log aggregation
SSO / Teleport integration (trigger when §6.2 scale thresholds are hit)
Host-side scorecard checks (password auth disabled, root login disabled) → railiance-infra

Relevant When

Issuing or refreshing a cert for any adm/agt/atm actor
Checking cert validity or running the compliance scorecard
ops-bridge needs a cert_command to be defined for a tunnel
Adding a new actor to the principals inventory
Bootstrapping the CA for a new environment
Reaching a trusted execution host for attended Inter-Hub bootstrap work with a short-lived agent certificate

Not Relevant When

Managing tunnel lifecycle (→ ops-bridge)
Deploying SSH principal config to hosts (→ railiance-infra)
All access is via static keys with no TTL (ops-bridge static key mode handles this)
Human admins manually managing their own certificates

Current State

Status: shipped — WARDEN-WP-0001 through WARDEN-WP-0003 complete (v0.1.0)
Implementation: full warden CLI with local and vault backends, inventory, scorecard, cleanup, signatures log, and ops-ssh-wrapper
Registry: capability.security.ssh-certificate-issuance published in registry/indexes/capabilities.yaml (federation index live on Gitea raw URL)

How It Fits

Upstream: CA key (file or Vault); actor inventory in Git
Downstream consumers: ops-bridge calls warden sign via cert_command; any other tool needing short-lived SSH certs can use the same interface
Often used with: ops-bridge (primary consumer), railiance-infra (host-side principal sync)

Terminology

ActorType: adm (human operator), agt (LLM agent), atm (deterministic automation)
cert_command: shell command that a caller (e.g. ops-bridge) runs to obtain a cert
CertSpec: signing request (actor name, pubkey path, TTL, principals)
CertRecord: result of signing (identity, valid_before, cert_path, signed_at)
principals: SSH roles embedded in the cert, matched against /etc/ssh/auth_principals/%u
inventory.yaml: authoritative registry of actor → principals + TTL policy
LocalCA: file-based CA backend using ssh-keygen -s
VaultCA: OpenBao / Vault-compatible SSH engine backend (backend: vault)

ops-bridge — primary consumer; calls warden sign via cert_command in tunnel config
railiance-infra — owns host-side principal deployment and host-side scorecard checks
the-custodian/state-hub — domain/workstream registry

Provided Capabilities

type: security
title: SSH certificate issuance
description: Issues short-lived CA-signed SSH certificates for adm/agt/atm actors via a
  pluggable cert_command interface; supports local CA (ssh-keygen) and OpenBao/Vault-compatible SSH engine backends.
keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, openbao, vault]

Getting Oriented

Start with: SCOPE.md (this file), then wiki/AccessManagementDirective.md
Config reference: wiki/OpsWardenConfig.md
cert_command contract: wiki/CertCommandInterface.md
Inter-Hub bootstrap access lane: wiki/InterHubBootstrapAccessLane.md
Config files: ~/.config/warden/warden.yaml, ~/.config/warden/inventory.yaml
State: ~/.local/state/warden/ (certs, generated keypairs)
Entry point: warden --help
Workplans: workplans/ (active); workplans/archived/ (finished)

5.3 KiB Raw Blame History Unescape Escape