diff --git a/docs/ops/historical-provenance-draft.md b/docs/ops/historical-provenance-draft.md index 52b9e85..686afce 100644 --- a/docs/ops/historical-provenance-draft.md +++ b/docs/ops/historical-provenance-draft.md @@ -4,6 +4,12 @@ Status: draft for auditor review. This document is not yet the umbrella CivicSuite disclosure and must not be treated as published policy until it lands through the authorized CivicSuite documentation path. +Baseline placeholder: the final policy version must name the first attested +baseline release and date before publication. Expected format: +`civiccore v0.22.1, released YYYY-MM-DD, is the baseline release under the +attested provenance model.` Until that value is filled and separately +authorized, this document remains a draft. + ## Summary CivicSuite strengthened its release provenance model during the synthetic @@ -18,10 +24,20 @@ The new model treats tags as release pointers and makes a Sigstore-signed must include the attestation, cosign bundle, artifact checksums, evidence bundle hashes, and an exact per-repo/per-tag verification command. +This model shift was driven by the CivicSuite synthetic-phase adversarial audit +contract. The external auditor flagged that the release-page "Verified" signal +was misleading for release provenance, the development team built a +fixture-driven gate, the gate surfaced an organization-wide historical baseline +issue, and the project chose transparent disclosure and forward correction over +rewriting release history. + ## Historical State - Historical releases before the baseline date were produced under a weaker GitHub-native provenance model. +- The backfill scan covered CivicSuite release tags across the organization as + of 2026-05-04 and found 119 historical releases failing the strengthened + gate: 83 lightweight tags and 36 unsigned annotated tag objects. - Those releases are not retroactively deleted or rewritten. - Current/latest live-surface releases receive additive attestations only after per-release authorization. @@ -41,6 +57,46 @@ A post-baseline release is independently verifiable when: - the cosign bundle verifies with the documented issuer and trust roots, and - release notes include the exact verification command. +Worked example placeholder for the first attested CivicCore baseline release: + +```bash +cosign verify-blob release-attestation.json \ + --bundle release-attestation.json.bundle \ + --certificate-identity "https://github.com/CivicSuite/civiccore/.github/workflows/release.yml@refs/tags/v0.22.1" \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com + +sha256sum -c SHA256SUMS.txt +python scripts/verify-release-provenance.py v0.22.1 \ + --repo CivicSuite/civiccore \ + --attestation release-attestation.json \ + --bundle release-attestation.json.bundle \ + --artifacts-dir . +``` + +Replace `v0.22.1` with the final baseline tag if the authorized baseline +release uses a different version. + +## Canonical Sources + +- Gate implementation: + [`civiccore/release_provenance.py`](../../civiccore/release_provenance.py) +- Thin CLI wrapper: + [`scripts/verify-release-provenance.py`](../../scripts/verify-release-provenance.py) +- Versioned attestation schema: + [`docs/ops/release-attestation.schema.json`](release-attestation.schema.json) +- Adversarial fixture suite: + [`tests/fixtures/release_provenance/`](../../tests/fixtures/release_provenance/) +- Release-signing runbook: + [`docs/ops/release-signing.md`](release-signing.md) + +## Verification Support + +If a procurement reviewer or city IT reviewer cannot verify a post-baseline +release with the documented commands, report it through +[`SECURITY.md`](../../SECURITY.md). Treat unverifiable provenance as a release +verification failure until the project provides a corrected evidence bundle or +a documented explanation. + ## Audit Interpretation This disclosure does not minimize the prior state. It records a baseline shift: diff --git a/docs/ops/release-signing.md b/docs/ops/release-signing.md index 9b2a5a0..c628825 100644 --- a/docs/ops/release-signing.md +++ b/docs/ops/release-signing.md @@ -190,3 +190,23 @@ burden for CivicSuite. Historical releases are disclosed honestly rather than mass-deleted. The new baseline begins with releases that include Sigstore-signed release attestations and exact workflow-identity verification commands. + +## Maintainer Environment Hygiene + +Maintainer desktops and cloud-synced folders are scratchpads, not audit +surfaces. Drafts, runbooks, schemas, fixture analyses, defect statements, and +other artifacts under audit review must live in a CivicSuite repository on a +branch and move through a verified PR before review. If an artifact is too +sensitive for a public repository, it must live in an appropriate private +organization repository with the same verified-merge discipline. + +Do not store signing keys, sensitive seed data, realistic PII-shaped mock data, +or release evidence requiring custody controls in consumer cloud-sync folders. +Public documentation drafts are not sensitive, but the pattern is still a +hygiene signal. + +Maintainer notes copied from auditor conversations are auditor input, not +auditor output. Auditor decisions become operative only when explicitly written +in the chat as directives, approvals, or authorizations. Code, PRs, fixtures, +and runbooks produced by the development swarm are separate artifact classes +and must preserve that distinction in the audit trail.