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.

{
  "$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.

./.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:

./.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.

6.6 KiB Raw Blame History