Activate NK-WP-0009/0011; add tutorials slice and proposed ADR-0009
- docs/tutorials: template, OpenBao and SSH tutorials (unexercised) - tools/tutorial-verify + make tutorials-verify (NK-WP-0009-T06) - ADR-0009 proposed: expanded-mode Keycloak trigger and topology Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: sonnet Assistant-Process: 295952@bnt-lap001 Assistant-Session: e93f64ad-516c-46eb-9666-aad8d300c477
This commit is contained in:
parent
5c4bc16706
commit
0d460e3c02
11 changed files with 469 additions and 8 deletions
36
docs/tutorials/README.md
Normal file
36
docs/tutorials/README.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# NetKingdom Security Pattern Tutorials
|
||||
|
||||
Hands-on paths for operating the canonical NetKingdom security patterns
|
||||
(NK-WP-0009). Each tutorial is a file in this directory, written from
|
||||
[`TEMPLATE.md`](TEMPLATE.md) and checked by `make tutorials-verify`.
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Exercise status is mandatory.** Per
|
||||
[`docs/attended-procedure-standard.md`](../attended-procedure-standard.md), a
|
||||
tutorial header says `exercised <date> by <operator>` or `unexercised`.
|
||||
Nothing is labelled exercised until someone has run it.
|
||||
2. **Every concrete step names its owning repo.** This repo owns canon and
|
||||
reference tooling only (see `SCOPE.md`); deployment belongs to owners.
|
||||
3. **Verification and rollback are required**, not optional happy-path extras.
|
||||
4. **No secrets, ever.** Tutorials show paths and commands, never values.
|
||||
5. **Consume, don't copy.** Link owner runbooks; do not paste runtime
|
||||
manifests. Use the named `openbao-ui-railiance01` tunnel, never a public
|
||||
Bao URL (`bao.coulomb.social` is retired).
|
||||
|
||||
## Index
|
||||
|
||||
| Tutorial | Workplan task | Owners | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| [OpenBao: consume, attend, recover](openbao-operating-path.md) | T03 | railiance-platform, net-kingdom | unexercised |
|
||||
| [Short-lived SSH credentials](ssh-certificates-and-tunnels.md) | T04 | ops-warden, ops-bridge | unexercised |
|
||||
|
||||
Deferred (see NK-WP-0009): T02 object-storage STS (needs an owner-backed
|
||||
issuer and refusal/lease proof — ADR-0008 is architecture, not evidence) and
|
||||
T05 flex-auth protected consumer.
|
||||
|
||||
## Pattern mapping
|
||||
|
||||
NK-WP-0008 (the pattern library) has no file in this repo, so tutorials map to
|
||||
the canonical documents directly: `docs/platform-identity-security-architecture.md`,
|
||||
`docs/responsibility-map.md`, `docs/platform-root-custody.md`.
|
||||
41
docs/tutorials/TEMPLATE.md
Normal file
41
docs/tutorials/TEMPLATE.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# <Tutorial title>
|
||||
|
||||
Exercise status: unexercised
|
||||
Workplan task: NK-WP-NNNN-TNN
|
||||
Pattern(s): <canonical doc and section this teaches>
|
||||
|
||||
## Outcome
|
||||
|
||||
<One sentence: what is true when you are done.>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- <Access, tools, and state required. Name the owner of each.>
|
||||
|
||||
## Architecture context
|
||||
|
||||
<Who owns what. Which boundaries this crosses.>
|
||||
|
||||
## Steps
|
||||
|
||||
1. **[owner: <repo>]** <step and command>
|
||||
|
||||
## Verification
|
||||
|
||||
Done when:
|
||||
|
||||
- <Observable, repeatable check. Command plus expected result.>
|
||||
|
||||
## Rollback
|
||||
|
||||
- <How to undo each step, or "not reversible" and why.>
|
||||
|
||||
## Threat checks
|
||||
|
||||
- <What could go wrong; what must never be logged, committed, or pasted.>
|
||||
|
||||
## Ownership notes
|
||||
|
||||
| Concern | Owner |
|
||||
| --- | --- |
|
||||
| <concern> | <repo> |
|
||||
76
docs/tutorials/openbao-operating-path.md
Normal file
76
docs/tutorials/openbao-operating-path.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# OpenBao: consume, attend, recover
|
||||
|
||||
Exercise status: unexercised
|
||||
Workplan task: NK-WP-0009-T03
|
||||
Pattern(s): platform-root custody (`docs/platform-root-custody.md`); credential routing
|
||||
|
||||
## Outcome
|
||||
|
||||
You can reach the already-deployed private OpenBao, read a secret you are
|
||||
entitled to, know which unseal custody model governs it, and follow the
|
||||
attended recovery path without exposing shares or tokens.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **[owner: ops-bridge]** `bridge` CLI and the named `openbao-ui-railiance01`
|
||||
tunnel; an SSH certificate (see the SSH tutorial).
|
||||
- **[owner: ops-warden]** `warden` CLI for credential routing.
|
||||
- **[owner: railiance-platform]** OpenBao is already deployed and private.
|
||||
Greenfield deployment is a lab exercise only, never against the live estate.
|
||||
|
||||
## Architecture context
|
||||
|
||||
OpenBao is the runtime secret authority. railiance-platform deploys and
|
||||
operates it; net-kingdom owns the custody canon and the guarded bootstrap
|
||||
console, which refuses live `bao operator init`. Three unseal custody models
|
||||
exist (`docs/openbao-unseal-custody-models.md`); production blocks the
|
||||
`sops-held-automation` lab model.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **[owner: ops-warden]** Find the owner of your need:
|
||||
`warden route find "read a database password" --json`.
|
||||
2. **[owner: ops-bridge]** Check and, if needed, restore the tunnel:
|
||||
`bridge status`, then `bridge up openbao-ui-railiance01`.
|
||||
3. **[owner: railiance-platform]** Authenticate with your own identity and read
|
||||
only the path the routing result names. Use the owner's
|
||||
`railiance-platform/docs/openbao.md` for exact commands.
|
||||
4. **[owner: net-kingdom]** Know your custody model:
|
||||
`python3 tools/security-bootstrap-console/security_bootstrap_console.py openbao-unseal-custody-models`.
|
||||
5. **[owner: net-kingdom + railiance-platform]** Recovery after a seal event
|
||||
follows `docs/openbao-attended-ceremony-runbook.md`: operator and witness
|
||||
present, shares escrowed out of band, root token revoked after handoff.
|
||||
Record the ceremony in a non-secret record and run
|
||||
`make security-bootstrap-validate-openbao-ceremony-record`.
|
||||
|
||||
## Verification
|
||||
|
||||
Done when:
|
||||
|
||||
- `bridge status` shows `openbao-ui-railiance01` up.
|
||||
- `make security-bootstrap-console` reports no unmet custody gate for the
|
||||
selected model.
|
||||
- `make security-bootstrap-validate-openbao-ceremony-record` passes on a
|
||||
ceremony record, and fails on one containing a token-shaped marker.
|
||||
|
||||
## Rollback
|
||||
|
||||
- Close the tunnel: `bridge down openbao-ui-railiance01`.
|
||||
- Read-only steps need no rollback. A ceremony cannot be undone; a mistaken
|
||||
share transcription is corrected by re-escrow per the custody roster.
|
||||
|
||||
## Threat checks
|
||||
|
||||
- Init output, shares and tokens go to the operator's screen only: never to
|
||||
chat, State Hub, logs, or a Git checkout.
|
||||
- Never use a public Bao URL; `bao.coulomb.social` is retired.
|
||||
- Never place root token and unseal shares in one artifact outside lab.
|
||||
|
||||
## Ownership notes
|
||||
|
||||
| Concern | Owner |
|
||||
| --- | --- |
|
||||
| OpenBao deployment, config, unseal execution | railiance-platform |
|
||||
| Custody canon, ceremony record validator | net-kingdom |
|
||||
| Tunnel | ops-bridge |
|
||||
| Credential routing | ops-warden |
|
||||
65
docs/tutorials/ssh-certificates-and-tunnels.md
Normal file
65
docs/tutorials/ssh-certificates-and-tunnels.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
# Short-lived SSH credentials for admins, agents and automations
|
||||
|
||||
Exercise status: unexercised
|
||||
Workplan task: NK-WP-0009-T04
|
||||
Pattern(s): credential routing; ops-warden `AccessManagementDirective`
|
||||
|
||||
## Outcome
|
||||
|
||||
An actor obtains a short-lived CA-signed SSH certificate and uses it through
|
||||
an ops-bridge tunnel, with no static key doing the work.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **[owner: ops-warden]** `warden` CLI installed; actor registered in the
|
||||
principals inventory.
|
||||
- **[owner: ops-bridge]** `bridge` CLI and a tunnel definition.
|
||||
- **[owner: railiance-infra]** Target hosts trust the SSH CA and carry the
|
||||
actor's principal.
|
||||
|
||||
## Architecture context
|
||||
|
||||
ops-warden issues SSH certificates only (`warden sign`). ops-bridge runs the
|
||||
tunnel and calls the `cert_command` before each connect. Max TTLs: `adm` 48 h,
|
||||
`agt` 24 h, `atm` 8 h; the caller refreshes about 5 minutes before expiry.
|
||||
See `ops-warden/wiki/CertCommandInterface.md`.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **[owner: ops-warden]** Sign a public key for the actor:
|
||||
`warden sign <actor> --pubkey ~/.ssh/<actor>_ed25519.pub`.
|
||||
2. **[owner: ops-bridge]** Set `cert_command` to that command in the tunnel
|
||||
definition. Leave static-key mode unused.
|
||||
3. **[owner: ops-bridge]** `bridge up <tunnel>` then `bridge status`.
|
||||
4. **[owner: ops-warden]** Inspect the cert: `warden status`; audit history via
|
||||
`warden log`.
|
||||
|
||||
## Verification
|
||||
|
||||
Done when:
|
||||
|
||||
- `ssh-keygen -L -f ~/.local/state/warden/<actor>-cert.pub` shows the expected
|
||||
principal and a `Valid before` within the actor-type TTL.
|
||||
- `warden status` exits 0 (it exits 1 if any cert is expired).
|
||||
- After expiry, the tunnel reconnects only after `cert_command` succeeds.
|
||||
|
||||
## Rollback
|
||||
|
||||
- `bridge down <tunnel>`; `warden cleanup` removes stale certificates.
|
||||
- Certificates expire on their own; there is no long-lived credential to
|
||||
revoke. Remove the actor from the inventory to stop future signing.
|
||||
|
||||
## Threat checks
|
||||
|
||||
- Cert files must be mode 600; never reuse a cert across reconnects.
|
||||
- A non-zero `cert_command` exit is a failure and must trigger backoff.
|
||||
- ops-warden never vends API keys or passwords; route them with
|
||||
`warden route find`.
|
||||
|
||||
## Ownership notes
|
||||
|
||||
| Concern | Owner |
|
||||
| --- | --- |
|
||||
| Certificate issuance and TTL policy | ops-warden |
|
||||
| Tunnel lifecycle and refresh | ops-bridge |
|
||||
| Host CA trust and principals | railiance-infra |
|
||||
Loading…
Add table
Add a link
Reference in a new issue