154 lines
6.6 KiB
Markdown
154 lines
6.6 KiB
Markdown
# 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.
|