generated from coulomb/repo-seed
tegwick
bdd532d835
Establish follow-up after WP-0007: E2E OpenBao sign verification, post-policy reassessment, task-status canon migration, and archive hygiene. Refresh SCOPE to reflect shipped policy gate and active WP-0008.
192 lines
7.0 KiB
Markdown
192 lines
7.0 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.
|
||
> Aspirational direction lives in `INTENT.md`.
|
||
|
||
---
|
||
|
||
## One-liner
|
||
|
||
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
|
||
|
||
**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
|
||
|
||
### 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
|
||
|
||
### Stewardship (shipped WP-0006)
|
||
|
||
- `wiki/CredentialRouting.md` — credential type → subsystem routing
|
||
- `wiki/NetKingdomSecurityMap.md` — NetKingdom component literacy
|
||
- `wiki/ActorInventoryPatterns.md` + `examples/inventory.seed.yaml`
|
||
- `wiki/OpenBaoSshEngineChecklist.md` — production SSH signing verify
|
||
- `wiki/PolicyGatedSigning.md` — flex-auth integration design
|
||
|
||
### Shipped (WARDEN-WP-0007)
|
||
|
||
- Opt-in flex-auth policy gate before `warden sign` / `warden issue` (`policy.enabled`)
|
||
- `policy_decision_id` in `signatures.log` when gate allows
|
||
- Production OpenBao health evidence (`history/2026-06-17-openbao-production-verify.md`)
|
||
|
||
### Planned (WARDEN-WP-0008)
|
||
|
||
- End-to-end production OpenBao `warden sign` verification on Railiance
|
||
- Post-WP-0007 INTENT/SCOPE reassessment and archive hygiene
|
||
- State Hub task status canon in `AGENTS.md`
|
||
- NK-WP-0009 SSH tutorial joint with net-kingdom (parallel)
|
||
|
||
---
|
||
|
||
## Out of Scope
|
||
|
||
- **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 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
|
||
|
||
- 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
|
||
|
||
- **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:** operational access steward (2026-06-17)
|
||
- **Stewardship docs:** WP-0006 complete — routing, inventory patterns, OpenBao checklist
|
||
- **Policy gate:** WP-0007 complete — opt-in flex-auth pre-sign
|
||
- **Active workplan:** WP-0008 — production SSH path verification and stewardship closeout
|
||
- **Gap reassessment:** `history/2026-06-17-intent-scope-reassessment.md` (pre-WP-0007)
|
||
|
||
---
|
||
|
||
## How It Fits (NetKingdom)
|
||
|
||
```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` | `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 Repositories
|
||
|
||
| 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 |
|
||
|
||
---
|
||
|
||
## 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; 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
|
||
|
||
| Read first | Purpose |
|
||
| --- | --- |
|
||
| `INTENT.md` | Why ops-warden exists and where it is going |
|
||
| `SCOPE.md` | What is implemented today (this file) |
|
||
| `wiki/CredentialRouting.md` | Which subsystem for each credential need |
|
||
| `wiki/NetKingdomSecurityMap.md` | Platform security component map |
|
||
| `history/2026-06-17-intent-scope-reassessment.md` | Latest INTENT ↔ SCOPE assessment |
|
||
| `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 | |