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`
|