Jon Chery
6ed93f0311
---ci--- project: acdl phase: 7 milestone: v1.1 status: plan-as-execute persona: security-engineer task: [T-7.4, T-7.5, T-7.6, T-7.7, T-7.8] requirements.covered: [REQ-18, REQ-20, REQ-21] ---/ci--- Wave 3 (security-engineer, 5 files sequential): - T-7.4: schemas/policy_check_result.schema.json (REQ-18 schema half) — canonical shape from ARCHITECTURE.md §12.6; engine enum [checkov,kyverno,opa]; severity enum [critical,high,medium,low,info]; result enum [pass,fail,skipped,error]. Validates as Draft 2020-12; valid instance validates. - T-7.5: adapters/terraform/policy/checkov_adapter.py (REQ-18 adapter half) — Checkov JSON -> PolicyCheckResult; RULE_MAP has all 11 Checkov rule IDs (CKV_AWS_41/45/46/20/57/24/25/1/40/7/33) mapped to the 4 L2 checks + tag/naming; emits ACDL_TAG_NAMING SKIPPED per D-043; stdlib only; tolerates both Checkov JSON shapes. Synthetic fixture produces 3 records all valid against the schema. - T-7.6: platform/audit_ledger_design.md (REQ-20) — three tiers (S3 Object Lock compliance 7yr, acdl-evidence hot index, DynamoDB outbox RPO=0); spike scope (D-041) = hash chain + outbox write; v1.2 build-out = Object Lock + JWS (KMS key, quarterly rotation) + async worker + DLQ + daily checkpoints. Outbox item shape, RPO/RTO table, decision trail. - T-7.7: platform/hitl_matrix_design.md (REQ-21 design half) — pre-execution gate model; Gitea-specific mechanics (workflow_dispatch + gitea.actor per D-042, no Environments API); full 8-concern matrix verbatim from §10.4; timeout 1d warn / 2d freeze; rejection -> HELD + supersedes; CODEOWNERS routing; SoD pointer to the .py. - T-7.8: platform/separation_of_duties.py (REQ-21 impl half) — check(outbox_client, contract_id, current_prod_approver) -> (ok, reason); None outbox -> no-op; equal -> SEPARATION_OF_DUTIES_VIOLATION; distinct -> ok; route_halt_artifact stub; stdlib only (duck-typed outbox_client). All 5 SoD cases verified.
115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
# ACDL Human-in-the-Loop Matrix + Separation-of-Duties Design (REQ-21)
|
|
|
|
> **Status:** design authored in Phase 07 (milestone v1.1); v1.2 wires the
|
|
> gates. The spike (Phases 08-10) is **dev-only**; HITL is not exercised
|
|
> (the spike contract has `environment: dev`).
|
|
|
|
The vision's "Lower Environments are Autonomous; Higher Environments are
|
|
Attested" tenet [1] and the "deliberate human attestation — not as a
|
|
rubber stamp" requirement [1] are the binding constraints.
|
|
|
|
## Gate model (ARCHITECTURE.md §10.1)
|
|
|
|
**Pre-execution gates.** The contract is held in a "validated but not
|
|
applied" state until the human attests. qa, prod, dr are attestation
|
|
gates. No partial deployment to roll back on rejection (qa, prod); dr is
|
|
a separate deployment against a separate cluster/region. The
|
|
canary/deployment-rollback model is explicitly not in scope for v1.
|
|
|
|
## Gitea-specific gate mechanics (D-042)
|
|
|
|
Gitea has **no Environments API** and ignores `environment:` blocks
|
|
(v1.0 D-013; re-confirmed in RESEARCH TARGET 1). The pre-execution gate
|
|
is modeled as a `workflow_dispatch` with approval inputs:
|
|
|
|
- **qa gate:** `workflow_dispatch` with `approve_qa: true`; the dispatch
|
|
run's `gitea.actor` is the QA approver.
|
|
- **prod gate:** `workflow_dispatch` with `approve_prod: true`;
|
|
`gitea.actor` is the SRE approver.
|
|
- **dr gate:** `workflow_dispatch` with `approve_dr: true`; same.
|
|
|
|
The approver identity of record = `gitea.actor` of the dispatch run
|
|
(D-042). There is no other approval-identity signal in Gitea. The v1.2
|
|
real-OIDC path (blocked on go-gitea/gitea#36988) does not change this —
|
|
OIDC authorizes the *runner* to AWS, it does not change how the platform
|
|
records the *human* approver.
|
|
|
|
## Reviewer routing (ARCHITECTURE.md §10.2)
|
|
|
|
Gitea CODEOWNERS routes the right reviewer to the right gate:
|
|
|
|
- qa → QA team
|
|
- prod → SRE team
|
|
- dr → SRE team
|
|
|
|
CODEOWNERS **routes**; it does **not** enforce identity distinctness (that
|
|
is the platform-internal outbox check in
|
|
`platform/separation_of_duties.py`).
|
|
|
|
## Full 8-concern attestation matrix (§10.4, lifted verbatim)
|
|
|
|
| Env | Concern | Evidence artifact | Freshness | Source | Attester |
|
|
|---|---|---|---|---|---|
|
|
| qa | Functional correctness | Last successful run of contract-declared validation.e2eSuite with pass rate ≥ 99% | Last 24h | Test runner declared in contract | QA |
|
|
| qa | Performance baseline | Load test report (k6 / Gatling / Locust) showing p99 latency < declared NFR and throughput > declared minimum | Last 7d | Load test runner declared in contract | QA |
|
|
| qa | Security posture | Vulnerability scan (Trivy, Snyk, or contract-declared equivalent) with no criticals/highs, signed by Security on-call | Last 24h | Security scanner + Security team signature | QA |
|
|
| qa | Contract NFRs | Platform-generated report: schema valid, NFR assertions (latency, throughput, error rate) within declared bounds | At submission | Platform contract validator | QA |
|
|
| prod | Operational readiness | Runbook published, dashboard exists, on-call rotation assigned, alerts configured | At submission, validated against last 30d history | Platform + SRE | SRE |
|
|
| prod | Incident response | Sev-1 runbook tabletop or live drill completed | Last 90d | SRE drill record | SRE |
|
|
| prod | Capacity / cost | FinOps forecast for next 30d within budget envelope, cost anomaly baseline stored, budget alert configured | Forecast valid for next 30d | FinOps + SRE | SRE |
|
|
| prod | Resilience | DR drill, chaos engineering report, backup verified | DR: 180d; chaos: 90d; backup: 30d | SRE + Platform | SRE |
|
|
| dr | dr-region deploy with the most recent prod-bound dr drill as canary evidence | dr drill report | Last 180d | SRE | SRE |
|
|
|
|
## Timeout behavior (§10.5)
|
|
|
|
| Time | State | Action |
|
|
|---|---|---|
|
|
| Submission | PENDING_ATTESTATION | Notify responsible team |
|
|
| 1 business day | PENDING_ATTESTATION_WARNING | Notify team + platform on-call (elevated path); emit `PENDING_ATTESTATION_TIMEOUT_WARNING` event |
|
|
| 2 business days | PENDING_ATTESTATION_AUTO_FREEZE | Auto-freeze; require re-submission; emit `PENDING_ATTESTATION_AUTO_FREEZE` event; new submission linked via `supersedes` |
|
|
|
|
**Implementation:** a Gitea `on: schedule` workflow (runs hourly) that
|
|
scans the DynamoDB outbox for `PENDING_ATTESTATION` events with `ts`
|
|
older than 1/2 business days and emits the warn/freeze events. Not
|
|
implemented in the spike (dev-only).
|
|
|
|
## Rejection and rollback (§10.6)
|
|
|
|
Rejection returns the contract to a `HELD` state with the rejection
|
|
reason captured as a `PROMOTION_REJECTED` event. The consumer fixes the
|
|
cause and re-submits; the new submission is linked to the rejected one
|
|
via `supersedes` (a contract-schema field — `schemas/contract.schema.json`).
|
|
The audit chain is **extended, not torn up** (the "Not a mutable audit
|
|
log" anti-goal). No partial deployment to roll back at any v1 gate.
|
|
|
|
## Separation of duties (§10.3) — pointer to the .py
|
|
|
|
The identity-distinctness check is platform-internal, not GitHub-native,
|
|
not Kyverno (in v1). Sequence:
|
|
|
|
1. On promotion dev → qa, the platform reads the QA approver's identity
|
|
from the `workflow_dispatch` run's `gitea.actor` and writes it to the
|
|
DynamoDB outbox keyed by `contractId` (attribute `approver_qa`).
|
|
2. On promotion qa → prod, the platform reads the stored `approver_qa`
|
|
from the outbox and the new SRE approver's `gitea.actor` from the
|
|
prod-dispatch run.
|
|
3. If `approver_qa == approver_prod`, the platform blocks the prod
|
|
promotion, writes a `SEPARATION_OF_DUTIES_VIOLATION` event to the
|
|
evidence stream, and routes a halt artifact to the SRE on-call.
|
|
4. The check is implemented in `platform/separation_of_duties.py`
|
|
(T-7.8). The platform is the only writer to the outbox; the check is
|
|
in the same process that has authority to block the promotion.
|
|
|
|
## Spike scope note
|
|
|
|
The spike is dev-only (REQ-27 contract has `environment: dev`), so HITL
|
|
is not exercised. Phase 07 authors the design; Phase 10's
|
|
`verify_phase10.sh` does not assert HITL behavior. v1.2 wires the gates
|
|
against this design.
|
|
|
|
## Decision trail
|
|
|
|
- **D-042** — approver identity = `gitea.actor` of the `workflow_dispatch`
|
|
run; no Environments API in Gitea.
|
|
- **D-013** (v1.0) — the `workflow_dispatch` approval-input fallback,
|
|
re-used for the real platform's pre-execution gate model. |