generated from coulomb/repo-seed
Initial Commit
This commit is contained in:
129
SCOPE.md
Normal file
129
SCOPE.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user