docs(evidence): clarify pointer-contract gate verifies claimed signer#1544
Conversation
The blocking Evidence Pointer Contract gate (verifier.CheckEvidenceTree / tools/evidence-pointercheck) establishes signer identity from the issuer/identity fields the committed pointer itself supplies, then derives the source slug and runs the allowlist classification against those same supplied values. It is an offline, structural anti-squat check; it does not pull the bundle or verify a Fulcio/Rekor signature binds that identity to the bundle digest. The code, CI workflow, and docs all described this signer as *verified*, overstating what the gate proves. The cryptographic binding is enforced separately at ingest (evidence-ingest.yaml -> VerifySignature + CrossCheckPointerSigner): a pointer that claims a signer it does not control passes the merge gate but fails ingest and is never counted in corroboration. Correct the language across the gate path (claimed, not verified) and state the trust boundary explicitly: trust derives from the ingest verification, not from passing the merge gate. No behavior change. Fixes NVIDIA#1535 Signed-off-by: Nathan Hensley <[email protected]>
Recipe evidence checkNo leaf overlays affected by this PR. This gate is warning-only and never blocks merge. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAll changes are documentation and comment updates with no functional code modifications. They consistently replace "verified signer" with "claimed signer" across the evidence pointer pipeline, and explicitly document that the structural gate ( Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Summary
Corrects the language across the blocking Evidence Pointer Contract gate to say it establishes a claimed (not cryptographically verified) signer, and states the trust boundary explicitly: the cryptographic binding is enforced at ingest, not at the merge gate. Documentation/comments only — no behavior change.
Motivation / Context
The gate (
verifier.CheckEvidenceTree/tools/evidence-pointercheck) establishes signer identity from theissuer/identityfields the committed pointer itself supplies, then derives the source slug and runs the allowlist classification against those same supplied values. It is an offline, structural anti-squat check — it does not pull the bundle or verify a Fulcio/Rekor signature binds that identity to the bundle digest. The code, CI workflow comment, and docs nonetheless described this signer as verified, overstating what the gate proves.Pulling Sigstore verification into the offline merge gate (issue Option 1) is architecturally wrong (the gate runs with a read-only token and no registry/Sigstore egress, so it stays fork-safe) and redundant: the cryptographic binding already runs as a blocking step at ingest (
evidence-ingest.yaml→VerifySignature+CrossCheckPointerSigner). A pointer that claims an allowlisted signer it does not control passes the merge gate but fails ingest and is never counted in corroboration. This PR takes Option 2 — make every gate-path surface honest about the claimed signer and state where trust actually derives.PR #1528 already added a claimed-signer note to ADR-007; this completes the picture across the code, the CLI tool, the workflow, and the contributor guide, and adds the missing ingest-as-trust-anchor detail.
Fixes: #1535
Related: #1528, #1530
Type of Change
Component(s) Affected
pkg/validator)docs/,examples/)pkg/evidence,tools/evidence-pointercheck, CI workflowImplementation Notes
pkg/evidence/verifier/discover.go—CheckEvidenceTreegodoc now spells out structural-not-cryptographic and the ingest trust anchor;checkPointerFilecarries a one-line pointer; "verified" → "claimed".pkg/evidence/attestation/source.go—SourceSlugdoc corrected.tools/evidence-pointercheck/main.go— package doc clarified; success message now notes the check is structural and that signature verification runs at ingest..github/workflows/evidence-pointer-contract.yaml— header comment updated.docs/design/007-recipe-evidence.md,docs/contributor/evidence-publishing.md— trust-derivation paragraph and "claimed" wording.Testing
go build ./pkg/evidence/... ./tools/evidence-pointercheck/... go test ./pkg/evidence/verifier/... ./pkg/evidence/attestation/... golangci-lint run -c .golangci.yaml ./pkg/evidence/... ./tools/evidence-pointercheck/...Build, affected unit tests, and lint all pass (0 issues). No behavior change, so no new tests; coverage unaffected.
Risk Assessment
Rollout notes: N/A
Checklist
make testwith-race)make lint)git commit -S)