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 / non-Vault use) and vault (HashiCorp Vault SSH engine, 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 Vault
Vault SSH engine backend — production-grade signing via Vault 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)
Vault cluster setup, HA, or PKI secrets engine
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

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: planned — WARDEN-WP-0001 not yet started
Implementation: scaffolding only (models, config, CA, inventory, scorecard, CLI stubs)

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: Vault SSH engine backend

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 Vault SSH engine backends.
keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, vault]

Getting Oriented

Start with: SCOPE.md (this file), then wiki/AccessManagementDirective.md
Config reference: wiki/OpsWardenConfig.md
cert_command contract: wiki/CertCommandInterface.md
Config files: ~/.config/warden/warden.yaml, ~/.config/warden/inventory.yaml
State: ~/.local/state/warden/ (certs, generated keypairs)
Entry point: warden --help
Workplan: workplans/WARDEN-WP-0001-initial-implementation.md

4.7 KiB Raw Permalink Blame History Unescape Escape