ops-warden/SCOPE.md

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
• Active maintenance: WARDEN-WP-0005 (OpenBao doc alignment) complete; capability registry publish remains a separate follow-up

---

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)

---

Related / Overlapping Repositories

• 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)