generated from coulomb/repo-seed
130 lines
4.7 KiB
Markdown
130 lines
4.7 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 /
|
||
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
|
||
|
||
---
|
||
|
||
## 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 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`
|