diff --git a/AGENTS.md b/AGENTS.md index 709928e..4e4829e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -166,6 +166,29 @@ get wrong. +## Secrets practice guide + +From 2026-10-11, secrets practice follows SecurityCanon `SEC-DSM` 1.0.0: + +`../security-canon/infospace/standards/devops-secrets-management/SecurityCanonDevOpsSecretsManagementStandard.md` + +Gate House teaches that standard. This repo builds routes inside it. Read these +parts before proposing a credential: + +- §5 preference hierarchy, highest practical mechanism first +- §37 decision procedure, questions Q1 through Q5, in order +- §35 OpenBao/Vault mapping — a broker is not the default store for every value +- §36 Kubernetes mapping — projected workload identity before a secret broker; + Kubernetes Secrets are a delivery copy, not the authority +- `DSM-ARCH-001` through `DSM-ARCH-004`, `DSM-TRANS-002`, `DSM-TRANS-003`, + `DSM-K8S-001` through `DSM-K8S-004` + +A new static secret, AppRole, or KV path is allowed when Q1–Q3 are no. The plan +records that answer, the owner, the consumers, the authority, and how the +residual secret is rotated and revoked (`DSM-TRANS-002`). Do not add an issuance +layer only to look dynamic (`DSM-TRANS-003`). Do not put secret values in the +plan, the workplan, or chat. + --- ## Workplan Convention (ADR-001) diff --git a/docs/construction-plan-format.md b/docs/construction-plan-format.md index 4a254aa..6d2ba54 100644 --- a/docs/construction-plan-format.md +++ b/docs/construction-plan-format.md @@ -98,6 +98,23 @@ one-line reuse-vs-new rationale referencing section 2. Every item names exactly what OpenBao object it touches (policy name, AppRole name, KV path) — no vague "provision access" line items. +Before any new credential, answer SecurityCanon `SEC-DSM` §37 in order and +name the preference-hierarchy level (§5) the proposal lands on: + +```text +Q1 Can the operation use identity directly? If yes, do not create a secret. +Q2 Can the target accept federated identity? If yes, federate. +Q3 Can the target issue an ephemeral credential? If yes and viable, issue dynamically. +Q4 Can an existing static credential be rotated automatically? If yes, manage it centrally. +Q5 Must a persistent static credential exist? If yes, vault it and name owner, + consumer, authority, delivery, copies, rotation, revocation, detection, and + what would eliminate it. +``` + +A plan that creates a static secret or AppRole without those answers is not +ready for section 4. `DSM-TRANS-003`: do not add an issuance layer only to +claim dynamic maturity. + ### 4. Review notes (phase 2) Filled in during the self-review pass, before a human ever sees the diff --git a/docs/review-optimize-checklist.md b/docs/review-optimize-checklist.md index 5e95a4c..dd26381 100644 --- a/docs/review-optimize-checklist.md +++ b/docs/review-optimize-checklist.md @@ -34,19 +34,24 @@ for their own deferred decisions). changes are fully drafted, not skipping it because section 2 already looked. -4. **Compaction opportunity.** Does satisfying this demand make any +4. **Preference hierarchy.** Does section 3 answer `SEC-DSM` §37 Q1–Q5 and name + the hierarchy level? A new static secret or AppRole with no answer is a + review finding. A broker or extra issuance hop that does not raise the + practical level (`DSM-TRANS-003`) is a finding too. + +5. **Compaction opportunity.** Does satisfying this demand make any *existing* lane redundant or mergeable? Not every plan will find one — most won't — but the check should be asked every time, not only when it's obviously true. -5. **Ease of use for the consumer.** Is the credential-acquisition path +6. **Ease of use for the consumer.** Is the credential-acquisition path this plan builds toward straightforward for the actual consuming code to use (e.g. does it match an env-var/file-path convention the consumer's code already expects, per its own `credentials.py` or equivalent)? A technically-correct plan that's awkward for the consumer to actually integrate is a real review finding. -6. **Posture check.** Do the choices here (TTL length, rotation policy, +7. **Posture check.** Do the choices here (TTL length, rotation policy, `secret_id_ttl` expiry-or-not) match current organizational posture (`ops-warden/wiki/WorkloadSecurityPosture.md` — build phase today) — not assuming production-tier rigor that isn't the current posture, and @@ -55,9 +60,9 @@ for their own deferred decisions). ## Worked example -`plans/rein-openweights-openrouter-approle.md` section 4 applies all six -checks against a real plan — including one genuine finding (the TTL +`plans/rein-openweights-openrouter-approle.md` section 4 applies the six +checks that existed when it was written — including one genuine finding (the TTL values were carried over from `agent-harness-binky-mail` by direct analogy rather than re-derived from scratch, which is exactly check 2 working as intended: matching an existing lane rather than inventing a -new number). +new number). New plans also answer check 4, the `SEC-DSM` preference hierarchy.