From 649925b303c9f388d86777350d1538b4a7464317 Mon Sep 17 00:00:00 2001 From: sjat Date: Tue, 9 Jun 2026 17:46:51 +0200 Subject: [PATCH] docs(access): gate ACCESS.md in checklist + new-role runbook (ADR-021) Co-Authored-By: Claude Sonnet 4.6 --- docs/runbooks/new-role.md | 14 +++++++++++++- docs/security/service-checklist.md | 4 ++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/runbooks/new-role.md b/docs/runbooks/new-role.md index 9fdcde8..037dc2c 100644 --- a/docs/runbooks/new-role.md +++ b/docs/runbooks/new-role.md @@ -91,7 +91,19 @@ For a **service** role, copy `docs/testing/service-verify-template.md` to Level 4 `/verify-service` check (ADR-008 / ADR-017) and is part of the pre-production service-clearance gate (`docs/security/service-checklist.md`). -### 11. Commit +### 11. Write the per-service operational-access record (services) + +For a **service** role, copy `docs/access/service-access-template.md` to +`roles//ACCESS.md` and populate the role's `access__*` data +(`access__service`, `access__compose_project`/`_path`, `access__containers`, +`access__log.loki_labels`, and `access__api` — `enabled` + endpoint + `firewall_ref` + +`auth.vault_ref` + `health_path`, or `enabled: false` with a reason). `ACCESS.md` is +rendered from that data; the admin-API path must `firewall_ref` an entry in the +`group_vars` firewall catalog, never open a port itself (ADR-020/021). Once hosts exist, +`/check-access ` proves the documented paths are live — part of the +service-clearance gate (`docs/security/service-checklist.md`). + +### 12. Commit ```bash git checkout -b role/ diff --git a/docs/security/service-checklist.md b/docs/security/service-checklist.md index 8b472eb..ea30151 100644 --- a/docs/security/service-checklist.md +++ b/docs/security/service-checklist.md @@ -51,6 +51,10 @@ This checklist is the generic **bar**. Each service answers it in its own - [ ] Passed Level 4 service-UI verification (`/verify-service`) against staging — the service has a populated `roles//VERIFY.md` and its critical journeys verified (ADR-008 Level 4 / ADR-017) +- [ ] Operational access recorded and verifiable (ADR-021): the role carries `access__*` + data, `roles//ACCESS.md` is rendered, and `/check-access` reports the + documented paths green — or a deviation is recorded in + `docs/security/accepted-risks.md` > Deviations are allowed but must be **conscious**: record them in > `docs/security/accepted-risks.md`, don't leave them implicit.