feat: add release conformance attestation format (relay-conform-attestation/1), spec §20.6 - #183
Merged
Merged
Conversation
…tation/1), spec §20.6 - New §20.6 defines the shape an implementation MAY publish to make §20.1's CI gates externally verifiable rather than self-asserted: an in-toto Statement whose subject digest is the SHA-256 of the attested binary file, and whose predicate bundles the full §17.2 conformance manifest, the attestation-generating tool's own embedded vectors_version (§15.8 - explicitly NOT observed from the attested binary, which a black-box invocation cannot introspect), and an optional implementation-defined safety_evidence_summary. - Scope decision, documented in the CHANGELOG rather than silently narrowed: this PR ships spec-only. The originating issue also proposed cryptographic signing, publishing alongside a release's container image, surfacing the digest in version --format json, and having relay probe/relay report treat an unverifiable release as non-conformant. None of that ships here - RELAY's own CI does not currently push container images to any registry, and fabricating an unreal 'signature' without real key management would be worse than not signing at all. predicate.signed MUST be false on an unsigned attestation; this section defines shape only. - New embedded schema spec/schemas/relay-conform-attestation.json. - Reference implementation: relay conform --attestation <binary> in cmd/relay/conform.go. New REQ-RELAY-098. - Real bug found and fixed while implementing this: buildManifest's Requirements slice was missing entry 16 (Vector manifest) - PR #181 added the §17 Requirement 16 spec text and verifier-table row but never added the corresponding code entry, so every relay-conform/1 manifest generated since v2.4 silently omitted it despite the spec's own text mandating 'exactly one entry per §17 requirement (1-16, ...)'. Fixed; the two manifest-shape tests that should have caught this (TestBuildManifestSelf, TestRunConformManifestFlag) were also stale at a hardcoded 15 and are corrected alongside it. Mutation-tested: reverted the fix, confirmed both tests failed, restored. - 6 new tests for the attestation feature, including independent cross-checks: subject digest matches a separately-computed sha256 of the binary file, vectors_version matches the tool's own parsed vectors_manifest.json, and schema validation against the new embedded schema. - SpecVersion bumped 2.5 -> 2.6 (MINOR, new optional format + CLI flag). Closes #142. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements a scoped-down version of issue #142 (NEW-SPEC-4), per explicit direction to scope this spec-only rather than stand up real signing/publishing infrastructure.
Scope decision
The originating issue proposed a signed SLSA/in-toto attestation published alongside a release's container image, with its digest surfaced in
version --format jsonandrelay probe/relay reporttreating unverifiable releases as non-conformant. This PR ships spec-only: it defines the predicate format an implementation MAY publish, without actual signing or publishing.Two concrete blockers made "full implementation" the wrong call here:
docker buildas a smoke test — it doesn't push images to any registry. "Published alongside the release's container image" presupposes infrastructure that doesn't exist.predicate.signedMUST befalseon an unsigned attestation. This section defines shape only — it does not mandate a signing mechanism or publication channel.What's added
relay-conform-attestation/1predicate: an in-toto Statement whosesubjectdigest is the SHA-256 of the attested binary file, and whose predicate bundles the full §17.2 conformance manifest, the attestation-generating tool's own embeddedvectors_version(§15.8 — explicitly not observed from the attested binary, since a black-box invocation cannot introspect it), and an optional implementation-definedsafety_evidence_summary.spec/schemas/relay-conform-attestation.json.relay conform --attestation <binary>incmd/relay/conform.go.REQ-RELAY-098.Bug found and fixed along the way
While wiring the attestation's
conformance_manifestfield, I foundbuildManifest'sRequirementsslice was missing entry 16 (Vector manifest) — PR #181 added the §17 Requirement 16 spec text and verifier-table row but never added the corresponding code entry. Everyrelay-conform/1manifest generated since v2.4 has silently omitted it, despite the spec's own text mandating "exactly one entry per §17 requirement (1–16, ...)". Fixed; the two manifest-shape tests that should have caught this (TestBuildManifestSelf,TestRunConformManifestFlag) were also stale at a hardcoded15and are corrected alongside it.Version
SpecVersionbumped2.5→2.6(MINOR, new optional format + CLI flag).Verification
vectors_versionmatches the tool's own parsedvectors_manifest.json, and schema validation against the new embedded schema.TestBuildManifestSelfandTestRunConformManifestFlagcorrectly failed, restored and confirmed green.relay conform --attestationend-to-end: digest independently matched viahashlib.sha256,overall: PASS,signed: false, 16 requirement entries.go build ./... && go vet ./... && go test ./...— all packages green.gofmt -l .andgolangci-lint run(latest) — clean.gofusa check(pinned v0.48.0): 0 errors.gofusa trace -req-coverage 100: 100% (98/98).Closes #142.