feat: enforce signed target maturity evidence
This commit is contained in:
@@ -0,0 +1,153 @@
|
||||
# Target Maturity Evidence Runbook
|
||||
|
||||
This runbook turns retained target-environment results into a sanitized,
|
||||
signed GovOPlaN capability-fit proof. It does not make a deployment suitable,
|
||||
certified, supported, or production-approved by itself. The proof records what
|
||||
independent authorities assessed against one exact installed release.
|
||||
|
||||
## Roles and custody
|
||||
|
||||
Use separate trust domains for release signing, installation receipts,
|
||||
boundary assessment, and production approval. A private proof key must be
|
||||
provisioned outside the assessed application and its matching public key must
|
||||
already exist in a separately managed
|
||||
`capability-fit-proof-authority-keyring.schema.json` document. Do not store
|
||||
private keys, raw reports, credentials, personal data, backup material, or
|
||||
target endpoints in Git.
|
||||
|
||||
Each authority key lists only the scopes that role may attest. At least one
|
||||
supplied signing key must cover every claim, and the issuer rejects a key that:
|
||||
|
||||
- is absent, inactive, expired, or revoked in the authority keyring;
|
||||
- expires before the proof;
|
||||
- does not match its independently provisioned public key;
|
||||
- reuses release-catalog or installer-authority key material.
|
||||
|
||||
## Target run
|
||||
|
||||
Install one pinned catalog release and issue its installed-composition receipt
|
||||
with `tools/assessments/installer-receipt.py`. Exercise the actual target
|
||||
topology, including:
|
||||
|
||||
- PostgreSQL and Redis as shared state services;
|
||||
- shared S3-compatible object storage;
|
||||
- at least two stateless API replicas and the intended worker topology;
|
||||
- fenced singleton work, ingress, certificates, proxy headers, and the real
|
||||
network/trust boundary;
|
||||
- provider health and freshness for every provider required by the product;
|
||||
- monitoring, alerting, failure response, accessibility, privacy, and security
|
||||
controls;
|
||||
- backup, isolated restore, failed-deployment rollback, and forward recovery.
|
||||
|
||||
For the recovery claim, retain the observed recovery point, measured RPO and
|
||||
RTO, database/object-store consistency result, and semantic reconstruction of
|
||||
the institutional and Service/Form reference journeys. Measure RPO from the
|
||||
last acknowledged durable effect that survives recovery and RTO until service
|
||||
health plus semantic reconstruction pass. Failed runs are evidence too and
|
||||
must use a negative result.
|
||||
|
||||
The private reports stay in the approved evidence store. Give each report an
|
||||
opaque artifact ID and each evaluated control a versioned opaque control ID.
|
||||
|
||||
## Private claim manifest
|
||||
|
||||
Create a private manifest conforming to
|
||||
`capability-fit-boundary-run.schema.json`. Relative artifact paths resolve from
|
||||
the manifest directory. Paths are read and hashed by the issuer and are never
|
||||
copied into the signed output.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "./capability-fit-boundary-run.schema.json",
|
||||
"schema_version": "0.1.0",
|
||||
"evidence_kind": "govoplan.capability-fit-boundary-run",
|
||||
"proof_id": "target:production:20260802",
|
||||
"expires_at": "2026-09-01T00:00:00Z",
|
||||
"claims": [
|
||||
{
|
||||
"scope": "target_environment",
|
||||
"result": "passed",
|
||||
"control_ids": ["topology:shared-state-v1"],
|
||||
"artifacts": [
|
||||
{"artifact_id": "target:run-20260802", "path": "private/target.json"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"scope": "recovery",
|
||||
"result": "passed",
|
||||
"control_ids": ["recovery:restore-rollback-v1"],
|
||||
"artifacts": [
|
||||
{"artifact_id": "recovery:run-20260802", "path": "private/recovery.json"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Reference readiness needs positive `target_environment`, `accessibility`,
|
||||
`privacy`, `security`, `operations`, and `recovery` claims. Provider acceptance
|
||||
and production approval are separate scopes. A production-approval authority
|
||||
must not approve its own unreviewed target run.
|
||||
|
||||
## Issue and verify
|
||||
|
||||
Issue only while the signed installer observation is current. Repeat
|
||||
`--signing-key` when multiple independent roles are needed. The command first
|
||||
verifies the catalog, independent catalog trust root, exact installed payload,
|
||||
installer receipt, and installer authority. It then hashes artifacts, signs the
|
||||
sanitized proof, verifies it immediately, and writes both proof and review with
|
||||
atomic private-file permissions.
|
||||
|
||||
```bash
|
||||
./.venv/bin/python tools/assessments/boundary-evidence.py \
|
||||
--assessment /srv/govoplan/assessment.json \
|
||||
--catalog /srv/govoplan/catalogs/stable.json \
|
||||
--keyring /srv/govoplan/catalogs/keyring.json \
|
||||
--trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
|
||||
--installed-evidence /srv/govoplan/evidence/installed.json \
|
||||
--installer-receipt /srv/govoplan/evidence/installer-receipt.json \
|
||||
--installer-authority-keyring /srv/govoplan/trust/installer-authorities.json \
|
||||
--claims /srv/govoplan/evidence/private/target-run.json \
|
||||
--authority-keyring /srv/govoplan/trust/proof-authorities.json \
|
||||
--signing-key authority-target=/run/secrets/target-proof-ed25519.pem \
|
||||
--output /srv/govoplan/evidence/target-proof.json \
|
||||
--review-output /srv/govoplan/evidence/target-proof-review.json
|
||||
```
|
||||
|
||||
Add `--expected-external-provider-subject provider-production` when the claim
|
||||
manifest contains `external_providers`. This value is an opaque deployment ID,
|
||||
not a URL or credential.
|
||||
|
||||
## Promotion gate
|
||||
|
||||
The general verifier can now be made admission-enforcing. These switches return
|
||||
a blocking exit status when a required claim is absent, expired, negative,
|
||||
revoked, or bound to another assessment, release, installation, or subject:
|
||||
|
||||
```bash
|
||||
./.venv/bin/python tools/assessments/capability-fit.py \
|
||||
--catalog /srv/govoplan/catalogs/stable.json \
|
||||
--keyring /srv/govoplan/catalogs/keyring.json \
|
||||
--trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
|
||||
--installed-evidence /srv/govoplan/evidence/installed.json \
|
||||
--installer-receipt /srv/govoplan/evidence/installer-receipt.json \
|
||||
--installer-authority-keyring /srv/govoplan/trust/installer-authorities.json \
|
||||
--boundary-evidence /srv/govoplan/evidence/target-proof.json \
|
||||
--boundary-authority-keyring /srv/govoplan/trust/proof-authorities.json \
|
||||
--require-reference-readiness \
|
||||
--require-production-approval \
|
||||
--output /srv/govoplan/evidence/admission-review.json
|
||||
```
|
||||
|
||||
Use `--require-external-provider-proof` as well when the promoted product
|
||||
requires an external provider. Live admission must not use
|
||||
`--verification-time`; that switch is only for clearly labelled historical
|
||||
review.
|
||||
|
||||
## Renewal and failure
|
||||
|
||||
Renew evidence after release, installed composition, deployment, control, or
|
||||
provider changes and before expiry. Revoke an authority key immediately after
|
||||
custody loss and rerun the affected assessment with a new independent key.
|
||||
Never copy a previous positive claim to a new release. Preserve negative and
|
||||
superseded receipts according to the approved evidence-retention policy.
|
||||
Reference in New Issue
Block a user