Skip to content

docs(evidence): clarify pointer-contract gate verifies claimed signer#1544

Merged
mchmarny merged 2 commits into
NVIDIA:mainfrom
njhensley:docs/evidence-gate-claimed-signer
Jun 29, 2026
Merged

docs(evidence): clarify pointer-contract gate verifies claimed signer#1544
mchmarny merged 2 commits into
NVIDIA:mainfrom
njhensley:docs/evidence-gate-claimed-signer

Conversation

@njhensley

Copy link
Copy Markdown
Member

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 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 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.yamlVerifySignature + 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

  • Documentation update

Component(s) Affected

  • Validator (pkg/validator)
  • Docs/examples (docs/, examples/)
  • Other: pkg/evidence, tools/evidence-pointercheck, CI workflow

Implementation Notes

  • pkg/evidence/verifier/discover.goCheckEvidenceTree godoc now spells out structural-not-cryptographic and the ingest trust anchor; checkPointerFile carries a one-line pointer; "verified" → "claimed".
  • pkg/evidence/attestation/source.goSourceSlug doc 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

  • Low — Comment/doc-only, no executable logic changed, trivially revertable.

Rollout notes: N/A

Checklist

  • Tests pass locally (make test with -race)
  • Linter passes (make lint)
  • I did not skip/disable tests to make CI green
  • I added/updated tests for new functionality
  • I updated docs if user-facing behavior changed
  • Changes follow existing patterns in the codebase
  • Commits are cryptographically signed (git commit -S)

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]>
@njhensley njhensley requested review from a team as code owners June 29, 2026 21:19
@njhensley njhensley added the theme/supply-chain SLSA, SBOM, Sigstore, and provenance verification label Jun 29, 2026
@github-actions

Copy link
Copy Markdown
Contributor

@github-actions

Copy link
Copy Markdown
Contributor

Recipe evidence check

No leaf overlays affected by this PR.

This gate is warning-only and never blocks merge.

@coderabbitai

coderabbitai Bot commented Jun 29, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 25c6bea1-ee0c-4418-a7f6-8e80f141ff2b

📥 Commits

Reviewing files that changed from the base of the PR and between 0a4b416 and ef99825.

📒 Files selected for processing (1)
  • docs/contributor/evidence-publishing.md

📝 Walkthrough

Walkthrough

All 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 (CheckEvidenceTree, evidence-pointercheck) performs only offline path-ownership and allowlist checks against pointer-supplied signer fields, while cryptographic binding is enforced separately during ingest.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested labels

theme/validation, area/cli

Suggested reviewers

  • yuanchen8911
🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: clarifying the pointer-contract gate uses a claimed signer.
Description check ✅ Passed The description matches the changeset and explains the doc/comment-only trust-boundary clarification.
Linked Issues check ✅ Passed The PR satisfies #1535 by documenting that the gate trusts a claimed signer and that cryptographic verification happens at ingest.
Out of Scope Changes check ✅ Passed The changes are confined to docs, comments, and a log message, with no unrelated functional scope added.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands.

@mchmarny mchmarny merged commit b0dd96e into NVIDIA:main Jun 29, 2026
6 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/ci area/docs size/M theme/supply-chain SLSA, SBOM, Sigstore, and provenance verification

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Evidence pointer-contract gate trusts pointer-supplied signer (no crypto verification)

2 participants