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:
224
INTENT.md
Normal file
224
INTENT.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# INTENT
|
||||
|
||||
> This file captures **why this repository exists**, the **direction it is
|
||||
> moving toward**, and the **kind of system it is meant to become**.
|
||||
> It is intentionally **aspirational and stable**, not a description of
|
||||
> current implementation. See `SCOPE.md` for what is implemented today.
|
||||
|
||||
---
|
||||
|
||||
## One-liner
|
||||
|
||||
**Operational access steward for the NetKingdom security model — knows the platform
|
||||
credential lanes, keeps them aligned, and issues short-lived SSH certificates where
|
||||
that lane belongs to ops-warden.**
|
||||
|
||||
---
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Development workers — human operators, kaizen agents, CI automations, and
|
||||
custodian tooling — need **safe, attributable access** across an increasingly
|
||||
complex NetKingdom stack: identity, MFA, authorization, runtime secrets, SSH
|
||||
reachability, and tunnel transport.
|
||||
|
||||
That stack is easy to misuse:
|
||||
|
||||
- static SSH keys and pasted API tokens in chat or Git
|
||||
- wrong subsystem chosen for a credential need (OpenBao vs warden vs key-cape)
|
||||
- drift between NetKingdom architecture canon and what operators actually run
|
||||
- ad hoc rediscovery of bootstrap and custody rules every time a worker needs access
|
||||
|
||||
**ops-warden exists so operational access has a custodian-domain home** that
|
||||
understands NetKingdom security infrastructure, routes workers to the right
|
||||
subsystem, keeps local guidance current, and **directly operates only the SSH
|
||||
short-lived certificate lane** it owns.
|
||||
|
||||
---
|
||||
|
||||
## The Mission
|
||||
|
||||
> *Where we are going.*
|
||||
|
||||
ops-warden aims to become the **operational access desk** for the ops fleet:
|
||||
|
||||
1. **Know** the NetKingdom security model — identity, authorization, secrets,
|
||||
SSH access, tunnels, bootstrap custody, and tenant/platform boundaries.
|
||||
2. **Route** workers to the correct subsystem for each credential type instead
|
||||
of becoming a universal secret vending machine.
|
||||
3. **Align** runbooks, wiki, inventory patterns, and scorecard checks with
|
||||
NetKingdom canon as the platform evolves (OpenBao-first, flex-auth policy,
|
||||
key-cape IAM Profile, railiance deployment layers).
|
||||
4. **Issue** short-lived SSH certificates for `adm` / `agt` / `atm` actors when
|
||||
host or ops reachability requires the SSH lane — via `warden sign`,
|
||||
`cert_command`, and `ops-ssh-wrapper`.
|
||||
5. **Audit** SSH signing operations and cert-side compliance so gatekeeping is
|
||||
observable, not tribal knowledge.
|
||||
|
||||
---
|
||||
|
||||
## NetKingdom Security Literacy
|
||||
|
||||
ops-warden should be fluent in the platform architecture documented in
|
||||
`net-kingdom` — especially:
|
||||
|
||||
| Plane / component | Role in access | ops-warden relationship |
|
||||
| --- | --- | --- |
|
||||
| **key-cape / Keycloak** | Identity — who is the actor, MFA, IAM Profile claims | Instruct identity path; do not re-implement OIDC |
|
||||
| **flex-auth + Topaz** | Authorization — may this actor perform this action | Future policy gate before SSH issuance; document integration |
|
||||
| **OpenBao** | Runtime secrets — API keys, dynamic creds, leases, audit | Instruct secret custody paths; SSH engine is signing backend only |
|
||||
| **ops-warden** | Operational SSH certificates — short-lived host access | **Own and issue** this lane |
|
||||
| **ops-bridge** | Tunnel transport — consumes certs via `cert_command` | Primary consumer; document integration |
|
||||
| **railiance-infra** | Host principals, force-command, SSH hardening | Instruct host-side deployment; do not own Ansible |
|
||||
| **railiance-platform** | OpenBao/K8s/platform service deployment | Instruct production endpoints; do not deploy clusters |
|
||||
|
||||
Canonical references:
|
||||
|
||||
- `net-kingdom/docs/platform-identity-security-architecture.md`
|
||||
- `net-kingdom/docs/responsibility-map.md`
|
||||
- `wiki/AccessManagementDirective.md` (ops SSH actor model)
|
||||
|
||||
---
|
||||
|
||||
## Responsibility Boundary
|
||||
|
||||
### ops-warden owns
|
||||
|
||||
- NetKingdom-aligned **operational SSH access** guidance and stewardship
|
||||
- **SSH certificate issuance** for registered `adm` / `agt` / `atm` actors
|
||||
- Actor inventory, TTL/principal policy, cert-side scorecard, signatures log
|
||||
- `cert_command` contract and `ops-ssh-wrapper` automation surface
|
||||
- Keeping ops-warden docs and patterns aligned with NetKingdom security evolution
|
||||
|
||||
### ops-warden instructs but does not own
|
||||
|
||||
| Need | Route to |
|
||||
| --- | --- |
|
||||
| OIDC login, MFA, human identity claims | key-cape / Keycloak (NetKingdom IAM Profile) |
|
||||
| Policy decision — may actor X access resource Y | flex-auth |
|
||||
| API keys, provider secrets, DB creds, object-storage STS | OpenBao (+ flex-auth policy where required) |
|
||||
| Inter-Hub operator keys, LLM provider credentials | OpenBao or approved operator secret store |
|
||||
| Tunnel lifecycle, port forwarding | ops-bridge |
|
||||
| `/etc/ssh/auth_principals/`, host hardening | railiance-infra |
|
||||
| OpenBao cluster init/unseal, platform deploy | railiance-platform |
|
||||
|
||||
**ops-warden is not a general secrets manager.** It may document *how* workers
|
||||
obtain non-SSH credentials; it must not store long-lived secrets in Git, State
|
||||
Hub, workplans, logs, or chat.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### 1. Right lane, right subsystem
|
||||
|
||||
Every credential request should land in the subsystem NetKingdom designed for it.
|
||||
ops-warden optimizes for **correct routing** as much as for **fast issuance**.
|
||||
|
||||
### 2. Short-lived by default (SSH lane)
|
||||
|
||||
Operational SSH access uses CA-signed certificates with TTL and principals —
|
||||
never unbounded static keys in worker workflows.
|
||||
|
||||
### 3. Align with canon, reduce drift
|
||||
|
||||
When NetKingdom security architecture changes (e.g. OpenBao standardization,
|
||||
new bootstrap lanes), ops-warden updates its wiki, SCOPE, and runbooks so dev
|
||||
workers do not reconstruct decisions from stale chat history.
|
||||
|
||||
### 4. Attributable actors
|
||||
|
||||
Humans, agents, and automations are distinct actor types (`adm` / `agt` / `atm`)
|
||||
with naming, TTL, and principal conventions — matching the Access Management
|
||||
Directive and NetKingdom agent-operating model.
|
||||
|
||||
### 5. Implement narrowly, guide broadly
|
||||
|
||||
**Implement** only what belongs in the SSH certificate lane.
|
||||
**Guide** across the full NetKingdom security surface through documentation,
|
||||
scorecard checks, inventory patterns, and future policy-integration hooks.
|
||||
|
||||
### 6. Observable gatekeeping
|
||||
|
||||
Every successful SSH sign is auditable (`signatures.log`). Compliance checks
|
||||
(scorecard) make cert-side policy violations visible before they become incidents.
|
||||
|
||||
---
|
||||
|
||||
## Credential flow (target mental model)
|
||||
|
||||
```text
|
||||
Development worker needs access
|
||||
|
|
||||
v
|
||||
ops-warden (steward / desk)
|
||||
|
|
||||
+-- SSH host / ops reachability? ----> warden sign / cert_command
|
||||
|
|
||||
+-- Runtime API / platform secret? --> OpenBao path (documented)
|
||||
|
|
||||
+-- Authorization required? ---------> flex-auth decision (future hook)
|
||||
|
|
||||
+-- Identity / MFA required? --------> key-cape / Keycloak path
|
||||
|
|
||||
+-- Tunnel only? --------------------> ops-bridge + cert_command
|
||||
```
|
||||
|
||||
Today the **steward desk** is primarily documentation, runbooks, and the
|
||||
implemented SSH CLI. Routing automation and policy-gated issuance are intentional
|
||||
follow-ups, not current promises.
|
||||
|
||||
---
|
||||
|
||||
## Relationship to NetKingdom
|
||||
|
||||
NetKingdom owns the **canonical security architecture** and meta-orchestration
|
||||
across orchestrated repos. ops-warden is a **custodian-domain execution repo**
|
||||
for one security lane plus operational guidance.
|
||||
|
||||
- NetKingdom defines *what the platform security model is*
|
||||
- ops-warden keeps *operational SSH access and worker routing* aligned with it
|
||||
- Railiance repos *deploy* what NetKingdom and component repos specify
|
||||
|
||||
ops-warden should appear in NetKingdom responsibility and pattern material as
|
||||
the **operational SSH credential authority**, not as a replacement for
|
||||
OpenBao or flex-auth.
|
||||
|
||||
---
|
||||
|
||||
## Success criteria
|
||||
|
||||
ops-warden is succeeding when:
|
||||
|
||||
1. A dev worker can determine **which subsystem** to use for a credential need
|
||||
without guessing or pasting secrets into agent sessions.
|
||||
2. SSH access for agents and operators is **short-lived, inventoried, and audited**.
|
||||
3. ops-bridge and other consumers integrate via **stable cert_command** without
|
||||
backend-specific branching.
|
||||
4. NetKingdom security evolution (OpenBao, IAM Profile, bootstrap lanes) is
|
||||
reflected in ops-warden docs within the same maintenance cycle.
|
||||
5. Non-SSH secrets remain **out of ops-warden storage** — only documented paths.
|
||||
|
||||
---
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Universal credential broker for all secret types
|
||||
- Replacing OpenBao, flex-auth, key-cape, or railiance deployment ownership
|
||||
- Storing Inter-Hub, LLM provider, or other long-lived API keys
|
||||
- Host-side SSH configuration deployment
|
||||
- SSO / Teleport at scale (trigger per Access Management Directive §6.2)
|
||||
|
||||
---
|
||||
|
||||
## Evolution notes
|
||||
|
||||
The repository shipped the SSH CA CLI first (WARDEN-WP-0001–0003). The
|
||||
stewardship and NetKingdom-alignment mission is the **next stratum** — docs,
|
||||
routing canon, inventory standards, production OpenBao SSH engine alignment,
|
||||
flex-auth integration design, and NetKingdom cross-links — without collapsing
|
||||
platform boundaries.
|
||||
|
||||
See `history/2026-06-17-intent-scope-assessment.md` for the current SCOPE ↔
|
||||
INTENT gap analysis and `workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md`
|
||||
for the active execution plan.
|
||||
@@ -4,7 +4,9 @@ SSH Certificate Authority and certificate lifecycle manager for the ops fleet.
|
||||
Signs short-lived certs for `adm` / `agt` / `atm` actors and exposes the
|
||||
`cert_command` interface consumed by `ops-bridge` and other tooling.
|
||||
|
||||
See `SCOPE.md` for boundaries and `wiki/AccessManagementDirective.md` for policy.
|
||||
See `INTENT.md` for direction, `SCOPE.md` for current implementation, and
|
||||
`wiki/AccessManagementDirective.md` for SSH policy. Gap analysis:
|
||||
`history/2026-06-17-intent-scope-assessment.md`.
|
||||
|
||||
## Install
|
||||
|
||||
@@ -54,6 +56,8 @@ uv run ruff check .
|
||||
|
||||
## Documentation
|
||||
|
||||
- `INTENT.md` — operational access steward mission (NetKingdom-aligned)
|
||||
- `wiki/CredentialRouting.md` — *planned WP-0006* — which subsystem for each credential type
|
||||
- `wiki/OpsWardenConfig.md` — configuration reference
|
||||
- `wiki/CertCommandInterface.md` — `cert_command` contract for callers
|
||||
- `wiki/InterHubBootstrapAccessLane.md` — short-lived cert envelope for bootstrap tasks
|
||||
|
||||
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 |
|
||||
172
history/2026-06-17-intent-scope-assessment.md
Normal file
172
history/2026-06-17-intent-scope-assessment.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# INTENT ↔ SCOPE State Assessment — ops-warden
|
||||
|
||||
**Date:** 2026-06-17
|
||||
**Author:** codex
|
||||
**Trigger:** INTENT.md established; SCOPE.md refreshed to reflect stewardship
|
||||
mission alongside SSH CLI implementation.
|
||||
**Follow-up workplan:** `workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive summary
|
||||
|
||||
ops-warden **ships a complete SSH CA CLI** (v0.1.0, 100 unit tests, OpenBao-first
|
||||
docs, federation capability published). The new **INTENT** reframes the repo as an
|
||||
**operational access steward** for the NetKingdom security model: knowledgeable
|
||||
about platform credential lanes, routing workers to the right subsystems, keeping
|
||||
guidance aligned — while **issuing only SSH certificates** directly.
|
||||
|
||||
**Alignment:** strong on the **SSH implementation lane**; weak on the **stewardship
|
||||
and NetKingdom integration** lane declared in INTENT.
|
||||
|
||||
**Self-assessed vector (product):** `D4 / A3 / C2 / R2`
|
||||
|
||||
| Dimension | Level | Rationale |
|
||||
| --- | --- | --- |
|
||||
| Discovery (D) | D4 | SSH lane well documented; stewardship/routing canon immature |
|
||||
| Availability (A) | A3 | Installable CLI + cert_command; no desk API or policy gate |
|
||||
| Completeness (C) | C2 | SSH core works; INTENT stewardship largely undelivered |
|
||||
| Reliability (R) | R2 | Good test coverage; production OpenBao SSH path not verified end-to-end |
|
||||
|
||||
---
|
||||
|
||||
## 2. Delivery snapshot
|
||||
|
||||
| Area | State (2026-06-17) |
|
||||
| --- | --- |
|
||||
| SSH CLI | `warden sign/issue/status/scorecard/cleanup/log/inventory` |
|
||||
| Backends | `local` + `vault` (OpenBao-compatible API) |
|
||||
| Tests | 100 unit + integration marker suite |
|
||||
| Wiki | AccessManagementDirective, OpsWardenConfig, CertCommandInterface, InterHubBootstrapAccessLane |
|
||||
| Registry | `capability.security.ssh-certificate-issuance` (D4/A3/C3/R2 in entry) |
|
||||
| INTENT.md | **New** — stewardship + NetKingdom literacy |
|
||||
| NetKingdom cross-links | Minimal in SCOPE; responsibility-map still lists ops-warden out-of-scope |
|
||||
| Credential routing runbook | **Missing** — no single “which subsystem?” guide in wiki |
|
||||
| flex-auth pre-sign hook | **Not designed or implemented** |
|
||||
| Production OpenBao SSH engine | Documented; live mount/roles unverified from this repo |
|
||||
| Standard agent inventory templates | **Missing** — only example actors in docs |
|
||||
|
||||
---
|
||||
|
||||
## 3. INTENT alignment
|
||||
|
||||
### Aligned
|
||||
|
||||
| INTENT expectation | SCOPE evidence |
|
||||
| --- | --- |
|
||||
| Issue short-lived SSH certs for adm/agt/atm | Full CLI, TTL policy, scorecard, signatures log |
|
||||
| Stable cert_command for consumers | `wiki/CertCommandInterface.md`, ops-bridge integration contract |
|
||||
| Do not store long-lived API secrets | Repo boundary, InterHub runbook, CUST-WP-0049 non-goals |
|
||||
| OpenBao as production SSH signing backend | `wiki/OpsWardenConfig.md` (WP-0005) |
|
||||
| Auditable SSH gatekeeping | `signatures.log`, scorecard checks |
|
||||
| Actor attribution model | AccessManagementDirective alignment, ActorType enum |
|
||||
|
||||
### Partial
|
||||
|
||||
| INTENT expectation | Gap |
|
||||
| --- | --- |
|
||||
| Know NetKingdom security infrastructure | INTENT tables exist; no mirrored wiki summary or kept-in-sync process |
|
||||
| Route workers to correct subsystem | Scattered across SCOPE/repo-boundary; no `wiki/CredentialRouting.md` |
|
||||
| Keep guidance aligned with NetKingdom canon | No subscription to net-kingdom doc changes; responsibility-map outdated |
|
||||
| Operational access desk for dev workers | CLI-only; no guided flow or agent-facing routing surface |
|
||||
| flex-auth policy before SSH sign | Inventory allow-list only; no authorization integration |
|
||||
| Observable stewardship | SSH audit yes; routing/alignment maintenance not tracked |
|
||||
|
||||
### Not started (INTENT evolution)
|
||||
|
||||
| INTENT expectation | Notes |
|
||||
| --- | --- |
|
||||
| NetKingdom responsibility-map recognition | ops-warden still “out of scope” in net-kingdom map |
|
||||
| Platform architecture diagram includes ops-warden SSH path | Not in `platform-identity-security-architecture.md` |
|
||||
| NK-WP-0009 SSH tutorial linkage | Planned in net-kingdom, not wired to ops-warden |
|
||||
| Policy-gated issuance | Future phase; needs design doc |
|
||||
| MCP/HTTP cert request for agents | Future; CLI sufficient for now |
|
||||
|
||||
---
|
||||
|
||||
## 4. Success criteria scorecard (from INTENT.md)
|
||||
|
||||
| Criterion | Verdict |
|
||||
| --- | --- |
|
||||
| Worker knows which subsystem for each credential type | **No** — no canonical routing runbook |
|
||||
| SSH access short-lived, inventoried, audited | **Yes (tooling)** — production inventory discipline pending |
|
||||
| ops-bridge integrates via cert_command | **Yes (contract)** — live tunnel matrix not verified here |
|
||||
| NetKingdom evolution reflected in ops-warden docs | **Partial** — OpenBao done; no ongoing sync process |
|
||||
| Non-SSH secrets stay out of ops-warden | **Yes** — boundaries documented |
|
||||
|
||||
**Score: 2 yes, 2 partial, 1 no**
|
||||
|
||||
---
|
||||
|
||||
## 5. Completeness and reliability
|
||||
|
||||
### Completeness vs INTENT — **C2 (Partial)**
|
||||
|
||||
The central SSH use case is implemented. The new stewardship mission — NetKingdom
|
||||
literacy, routing, alignment maintenance — is **declared in INTENT and SCOPE but
|
||||
not yet operationalized** in wiki, net-kingdom cross-links, or worker-facing runbooks.
|
||||
|
||||
**Satisfied expectations:**
|
||||
|
||||
- SSH certificate issuance end-to-end (local backend)
|
||||
- cert_command contract
|
||||
- OpenBao-first production documentation
|
||||
|
||||
**Broken / missing expectations:**
|
||||
|
||||
- No credential routing guide for dev workers
|
||||
- No NetKingdom alignment workstream execution
|
||||
- No flex-auth integration path
|
||||
|
||||
**Out of scope (correctly excluded):**
|
||||
|
||||
- OpenBao cluster operations
|
||||
- flex-auth policy authoring
|
||||
- Object-storage STS vending
|
||||
|
||||
### Reliability vs INTENT — **R2 (Tolerable)**
|
||||
|
||||
Strong unit tests and scorecard for cert-side checks. Production reliance on
|
||||
OpenBao SSH engine and multi-worker inventory patterns not yet demonstrated.
|
||||
Consumers must expect manual operator steps for non-SSH credentials.
|
||||
|
||||
---
|
||||
|
||||
## 6. Open gaps (prioritized)
|
||||
|
||||
| Prio | Gap | Suggested outcome |
|
||||
| --- | --- | --- |
|
||||
| P1 | Credential routing runbook | `wiki/CredentialRouting.md` — decision tree for workers |
|
||||
| P1 | NetKingdom cross-link patch | PR/note in net-kingdom responsibility-map + platform doc SSH path |
|
||||
| P2 | Standard inventory templates | `wiki/ActorInventoryPatterns.md` + example `inventory.yaml` seed |
|
||||
| P2 | OpenBao SSH engine ops checklist | Verify/mount roles; link railiance-platform procedures |
|
||||
| P3 | flex-auth pre-sign design | `wiki/PolicyGatedSigning.md` — design only, no code yet |
|
||||
| P3 | Registry capability update | Reflect stewardship in capability entry summary |
|
||||
| P4 | Agent-facing routing | Evaluate `warden guide` CLI or doc-only desk page |
|
||||
| P4 | NK-WP-0009 coordination | Joint tutorial: short-lived SSH for agents |
|
||||
|
||||
Captured in **WARDEN-WP-0006**.
|
||||
|
||||
---
|
||||
|
||||
## 7. Recommendations
|
||||
|
||||
1. **Execute WARDEN-WP-0006** in order: routing runbook → NetKingdom
|
||||
cross-links → inventory templates → OpenBao ops checklist.
|
||||
2. **Keep SSH CLI stable** — stewardship work is docs/alignment first; defer
|
||||
flex-auth code until design is reviewed.
|
||||
3. **Coordinate net-kingdom** — small responsibility-map update is a
|
||||
dependency for INTENT success criterion #4.
|
||||
4. **Re-assess after WP-0006** — target C3/C4 completeness if routing runbook
|
||||
and NetKingdom links land.
|
||||
|
||||
---
|
||||
|
||||
## 8. Document map
|
||||
|
||||
| File | Role |
|
||||
| --- | --- |
|
||||
| `INTENT.md` | Aspirational steward + SSH authority mission |
|
||||
| `SCOPE.md` | Current implementation and planned stewardship scope |
|
||||
| This file | Gap analysis snapshot |
|
||||
| `workplans/WARDEN-WP-0006-*.md` | Execution plan |
|
||||
@@ -0,0 +1,197 @@
|
||||
---
|
||||
id: WARDEN-WP-0006
|
||||
type: workplan
|
||||
title: "NetKingdom Alignment and Operational Access Stewardship"
|
||||
domain: custodian
|
||||
repo: ops-warden
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: custodian
|
||||
planning_priority: high
|
||||
planning_order: 6
|
||||
created: "2026-06-17"
|
||||
updated: "2026-06-17"
|
||||
state_hub_workstream_id: "a5c9f24b-1ad4-46da-bc8e-b99897f8e302"
|
||||
---
|
||||
|
||||
# WARDEN-WP-0006 — NetKingdom Alignment and Operational Access Stewardship
|
||||
|
||||
**Scope:** Close gaps identified in `history/2026-06-17-intent-scope-assessment.md`
|
||||
between INTENT (operational access steward for NetKingdom security) and SCOPE
|
||||
(shipped SSH CLI only). Documentation and alignment first; code changes limited
|
||||
to optional CLI ergonomics.
|
||||
|
||||
**Out of scope:** flex-auth integration implementation, OpenBao cluster deploy,
|
||||
universal credential broker, net-kingdom INTENT.md rewrite.
|
||||
|
||||
**References:**
|
||||
|
||||
- `INTENT.md`, `SCOPE.md`, `history/2026-06-17-intent-scope-assessment.md`
|
||||
- `net-kingdom/docs/platform-identity-security-architecture.md`
|
||||
- `net-kingdom/docs/responsibility-map.md`
|
||||
- `NK-WP-0009` (SSH tutorial, net-kingdom)
|
||||
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
After this workplan, a development worker or agent can:
|
||||
|
||||
1. Read ops-warden material and know **which NetKingdom subsystem** handles each
|
||||
credential type.
|
||||
2. Obtain **SSH certs** via documented actor patterns and production OpenBao path.
|
||||
3. Find ops-warden recognized in **NetKingdom responsibility/platform** docs as
|
||||
the operational SSH credential authority.
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### T1 — Credential routing runbook
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "ffc6a0c2-4312-4584-be7a-c8411cb01899"
|
||||
```
|
||||
|
||||
Create `wiki/CredentialRouting.md`:
|
||||
|
||||
- Decision tree: SSH vs runtime secret vs identity vs authorization vs tunnel
|
||||
- Per-subsystem links (OpenBao, flex-auth, key-cape, ops-bridge, railiance-infra)
|
||||
- Explicit “do not ask ops-warden for API keys” examples
|
||||
- Link from `SCOPE.md`, `INTENT.md`, `README.md`
|
||||
|
||||
**Done when:** A worker with no prior context can route a credential request in
|
||||
under two minutes using this page alone.
|
||||
|
||||
### T2 — Actor inventory patterns
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "3816463d-7dfd-469d-9324-fd7880b50608"
|
||||
```
|
||||
|
||||
Create `wiki/ActorInventoryPatterns.md` with standard patterns:
|
||||
|
||||
- Tunnel agents (`agt-*-bridge`)
|
||||
- Kaizen / codex agents (`agt-codex-*`)
|
||||
- CI automations (`atm-*`)
|
||||
- Human admins (`adm-*`)
|
||||
- TTL and principal narrowing guidance
|
||||
|
||||
Optional: `examples/inventory.seed.yaml` (non-secret, Git-safe template).
|
||||
|
||||
**Done when:** Adding a new dev worker actor does not require inventing naming
|
||||
from scratch.
|
||||
|
||||
### T3 — NetKingdom cross-links (ops-warden side)
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "f158366a-5746-48b8-acce-472dce8f925e"
|
||||
```
|
||||
|
||||
- Add `wiki/NetKingdomSecurityMap.md` — condensed literacy table from INTENT
|
||||
- Update `registry/capabilities/capability.security.ssh-certificate-issuance.md`
|
||||
summary to mention stewardship/routing
|
||||
- Update `.claude/rules/repo-boundary.md` with NetKingdom routing table
|
||||
|
||||
**Done when:** ops-warden docs stand alone for NetKingdom operational access
|
||||
orientation without reading net-kingdom first (but link to canon).
|
||||
|
||||
### T4 — NetKingdom canon patch (coordination)
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T04
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "e40e4395-8f01-4f79-a539-d0de8e427321"
|
||||
```
|
||||
|
||||
Coordinate updates in `net-kingdom` (separate commit/PR there):
|
||||
|
||||
- `docs/responsibility-map.md` — move ops-warden from pure out-of-scope to
|
||||
**operational SSH credential dependency**
|
||||
- `docs/platform-identity-security-architecture.md` — add Operational SSH Path
|
||||
(ops-warden → ops-bridge → hosts)
|
||||
|
||||
**Done when:** NetKingdom canon names ops-warden’s lane; ops-warden wiki links
|
||||
back to the updated sections.
|
||||
|
||||
**Note:** Requires `net-kingdom` repo write access; may need `needs_human` if
|
||||
blocked on review.
|
||||
|
||||
### T5 — OpenBao SSH engine operational checklist
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "a94e20a2-970b-4a0c-bd23-8510b841b938"
|
||||
```
|
||||
|
||||
Create `wiki/OpenBaoSshEngineChecklist.md`:
|
||||
|
||||
- Prerequisites (OpenBao initialized/unsealed per railiance-platform)
|
||||
- Role creation commands (from OpsWardenConfig)
|
||||
- Token policy expectations (no root token in warden workflows)
|
||||
- Verification: `warden sign` against production endpoint
|
||||
- Failure modes and fallback boundaries
|
||||
|
||||
**Done when:** Operator can verify production SSH signing path without
|
||||
reconstructing steps from multiple repos.
|
||||
|
||||
### T6 — Policy-gated signing design (design only)
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T06
|
||||
status: todo
|
||||
priority: low
|
||||
state_hub_task_id: "b10a4b4d-bfa1-4f49-b6a5-f339f1e6a2e1"
|
||||
```
|
||||
|
||||
Create `wiki/PolicyGatedSigning.md`:
|
||||
|
||||
- flex-auth decision before `warden sign` — proposed flow
|
||||
- Claims needed from IAM Profile
|
||||
- What stays inventory-based in v1 vs policy-based in v2
|
||||
- Explicit non-implementation in this workplan
|
||||
|
||||
**Done when:** Reviewable design exists; no code dependency.
|
||||
|
||||
### T7 — Re-assess INTENT ↔ SCOPE
|
||||
|
||||
```task
|
||||
id: WARDEN-WP-0006-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "ef8b5c57-2343-4cfc-9fee-48db1e56f69a"
|
||||
```
|
||||
|
||||
After T1–T5 complete:
|
||||
|
||||
- Update `history/2026-06-17-intent-scope-assessment.md` or add
|
||||
`history/YYYYMMDD-intent-scope-reassessment.md`
|
||||
- Refresh SCOPE.md Current State and completeness notes
|
||||
- Run `make fix-consistency REPO=ops-warden`
|
||||
|
||||
**Done when:** Completeness target C3+ documented with evidence.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `wiki/CredentialRouting.md` exists and is linked from README/SCOPE
|
||||
- [ ] `wiki/ActorInventoryPatterns.md` exists
|
||||
- [ ] `wiki/NetKingdomSecurityMap.md` exists
|
||||
- [ ] NetKingdom responsibility-map recognizes ops-warden SSH lane (T4)
|
||||
- [ ] OpenBao SSH checklist documented (T5)
|
||||
- [ ] Policy-gated signing design drafted (T6)
|
||||
- [ ] INTENT ↔ SCOPE re-assessment recorded (T7)
|
||||
- [ ] `reuse-surface validate --root .` passes if registry entry changed
|
||||
Reference in New Issue
Block a user