generated from coulomb/repo-seed
tegwick
15bf8cb543
Document OpenBao as the platform production secrets service while keeping the vault-compatible warden.yaml config shape. Update OpsWardenConfig, SCOPE, and CertCommandInterface cross-references.
136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# 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
|
||
|
||
```capability
|
||
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)
|