generated from coulomb/repo-seed
Define INTENT, refresh SCOPE, and plan NetKingdom stewardship
Add ops-warden INTENT as operational access steward for NetKingdom security (route credential lanes, align docs, issue SSH certs only). Refresh SCOPE for stewardship scope, persist INTENT↔SCOPE gap assessment, and open WARDEN-WP-0006 for routing runbooks and platform alignment.
This commit is contained in:
173
SCOPE.md
173
SCOPE.md
@@ -3,111 +3,147 @@
|
||||
> 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.
|
||||
> Aspirational direction lives in `INTENT.md`.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Operational access steward for the NetKingdom security model — issues short-lived
|
||||
SSH certificates for `adm`/`agt`/`atm` actors, documents how to obtain other
|
||||
credential types from the right platform subsystems, and keeps ops access guidance
|
||||
aligned with NetKingdom canon.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
**Today:** implements the SSH certificate lane from `wiki/AccessManagementDirective.md`
|
||||
§§1–5 — CA signing, actor inventory, TTL policy, cert-side scorecard, and the
|
||||
`cert_command` interface for ops-bridge.
|
||||
|
||||
**Direction (INTENT):** become the custodian-domain desk that understands NetKingdom
|
||||
identity, authorization, secrets, and SSH lanes — routing dev workers to key-cape,
|
||||
flex-auth, OpenBao, ops-bridge, and railiance components instead of centralizing
|
||||
all secrets here.
|
||||
|
||||
Signing backends: `local` (ssh-keygen, labs) and `vault` (OpenBao or other
|
||||
Vault-compatible SSH secrets engine API, production).
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
### Implemented (SSH lane)
|
||||
|
||||
- Local CA backend (`ssh-keygen -s`)
|
||||
- OpenBao / Vault-compatible SSH engine backend
|
||||
- Actor identity registry (`inventory.yaml`)
|
||||
- `cert_command`: `warden sign <actor> --pubkey <path>` → cert on stdout
|
||||
- TTL enforcement per `ActorType` (`adm` 48 h, `agt` 24 h, `atm` 8 h)
|
||||
- `warden status`, cleanup, scorecard, signatures log
|
||||
- `warden issue` and `ops-ssh-wrapper`
|
||||
- Runbooks for OpenBao config and Inter-Hub bootstrap SSH envelope
|
||||
|
||||
### Stewardship (documentation and alignment)
|
||||
|
||||
- NetKingdom security routing guidance — which subsystem owns which credential type
|
||||
- Wiki and config references aligned with OpenBao-first platform standard
|
||||
- Capability registry entry for SSH certificate issuance
|
||||
- Keeping ops access patterns consistent with `net-kingdom` platform architecture
|
||||
|
||||
### Planned (see workplan)
|
||||
|
||||
- NetKingdom cross-links and responsibility-map alignment
|
||||
- Credential routing runbook for dev workers
|
||||
- Standard actor inventory patterns for agents and CI
|
||||
- flex-auth policy hook design for gated SSH issuance
|
||||
- Production OpenBao SSH engine operational checklist
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
- **Issuing** non-SSH secrets (API keys, DB creds, S3 STS, Inter-Hub keys) → OpenBao
|
||||
with flex-auth policy where required; ops-warden documents paths only
|
||||
- Identity / OIDC / MFA → key-cape, Keycloak
|
||||
- Authorization policy decisions → flex-auth
|
||||
- Tunnel lifecycle → `ops-bridge`
|
||||
- Host principal deployment → `railiance-infra`
|
||||
- OpenBao / Vault cluster deployment → `railiance-platform`
|
||||
- Human admin SSH key generation (self-service `ssh-keygen`)
|
||||
- Session recording, SIEM, SSO / Teleport at scale
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
- Issuing or refreshing an **SSH cert** for `adm`/`agt`/`atm`
|
||||
- A dev worker needs to know **where to get credentials** in the NetKingdom stack
|
||||
- `ops-bridge` needs a `cert_command` for a tunnel
|
||||
- Adding actors to the principals inventory
|
||||
- Inter-Hub or bootstrap tasks need a **short-lived agent SSH envelope**
|
||||
- Checking cert-side compliance (scorecard)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
- Storing or vending **API keys or runtime secrets** (→ OpenBao)
|
||||
- Policy decisions on resource access (→ flex-auth)
|
||||
- Managing tunnels without SSH cert issuance (→ ops-bridge)
|
||||
- Static-key-only legacy access (ops-bridge static key mode)
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
- Registry: `capability.security.ssh-certificate-issuance` published in
|
||||
`registry/indexes/capabilities.yaml` (federation index live on Gitea raw URL)
|
||||
- **SSH CLI:** shipped v0.1.0 (WARDEN-WP-0001–0003)
|
||||
- **Docs:** OpenBao-first config (WARDEN-WP-0005), Inter-Hub bootstrap runbook
|
||||
- **Registry:** `capability.security.ssh-certificate-issuance` published
|
||||
- **INTENT:** defined 2026-06-17; stewardship layer largely **documentation-only**
|
||||
- **Gap:** see `history/2026-06-17-intent-scope-assessment.md`
|
||||
|
||||
---
|
||||
|
||||
## How It Fits
|
||||
## How It Fits (NetKingdom)
|
||||
|
||||
- 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)
|
||||
```text
|
||||
key-cape / Keycloak identity claims
|
||||
→ flex-auth authorization decisions
|
||||
→ OpenBao runtime secrets & dynamic credentials
|
||||
→ ops-warden SSH certs + operational access guidance
|
||||
→ ops-bridge tunnel transport (cert_command consumer)
|
||||
→ railiance-* deployment and host enforcement
|
||||
```
|
||||
|
||||
Upstream: CA key (local file or OpenBao SSH engine). Actor inventory in Git or
|
||||
operator config.
|
||||
|
||||
Downstream: `ops-bridge` (primary), kaizen agents, CI automations, human operators.
|
||||
|
||||
---
|
||||
|
||||
## 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`)
|
||||
- `ActorType`: `adm` | `agt` | `atm`
|
||||
- `cert_command`: shell command returning a cert on stdout
|
||||
- `inventory.yaml`: actor → principals + TTL registry
|
||||
- `LocalCA` / `VaultCA`: signing backends (`backend: local` | `vault`)
|
||||
|
||||
---
|
||||
|
||||
## Related / Overlapping Repositories
|
||||
## Related 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
|
||||
| Repo | Relationship |
|
||||
| --- | --- |
|
||||
| `net-kingdom` | Canonical security architecture; ops-warden aligns to it |
|
||||
| `ops-bridge` | Primary cert_command consumer |
|
||||
| `railiance-infra` | Host-side SSH principals and hardening |
|
||||
| `railiance-platform` | OpenBao deployment and platform secrets |
|
||||
| `flex-auth` | Authorization; future pre-sign policy gate |
|
||||
| `key-cape` | Identity / IAM Profile lightweight mode |
|
||||
| `state-hub` | Workstream registry |
|
||||
|
||||
---
|
||||
|
||||
@@ -117,19 +153,22 @@ callers never need to know which backend is in use.
|
||||
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]
|
||||
pluggable cert_command interface; documents NetKingdom operational access routing;
|
||||
supports local CA and OpenBao/Vault-compatible SSH engine backends.
|
||||
keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, openbao, vault, netkingdom]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
| Read first | Purpose |
|
||||
| --- | --- |
|
||||
| `INTENT.md` | Why ops-warden exists and where it is going |
|
||||
| `SCOPE.md` | What is implemented today (this file) |
|
||||
| `history/2026-06-17-intent-scope-assessment.md` | INTENT ↔ SCOPE gaps |
|
||||
| `wiki/AccessManagementDirective.md` | SSH actor model |
|
||||
| `wiki/OpsWardenConfig.md` | warden.yaml and OpenBao |
|
||||
| `wiki/CertCommandInterface.md` | cert_command contract |
|
||||
| `wiki/InterHubBootstrapAccessLane.md` | Bootstrap SSH envelope |
|
||||
| `net-kingdom/docs/platform-identity-security-architecture.md` | Platform security canon |
|
||||
Reference in New Issue
Block a user