clarify relationship between attestations and refs / branches

[TomHennen]

          > you do not need to review each change to cut a release branch

This seems really tricky.
If I create a new release ref that points to the tip of main, I must ensure that the tip of main complies with all requirements that govern the release ref.
It's normal for the requirements to be different between those contexts.

Moving fully reviewed content from one context to another still requires review, except for well-understood automatic processes

This makes sense to me. I'm not sure the example expresses this though.

Originally posted by @zachariahcox in #1037 (comment)

[TomHennen]

See also this discussion

[zachariahcox]

we discussed this at the AUG26 2024 meeting.

https://docs.google.com/document/d/1PwhekVB1iDpcgCQRNVN_aesoVdOiTruoebCs896aGxw/edit#heading=h.gy85hsmlw9iy

(copy paste for posterity)

• How should source ref names be included into source attestations?
  • content: draft: define how downstream users can verify the SLSA source track level of revisions #1094
  • Aditya
    • Updating the ref must have its own attestations
    • gittuf: When refs/heads/main moves from commit A to commit B, we add a signed entry that indicates the new state of the branch, and the signature is by the actor updating the state of the branch
      • Zac: it seems like there should be a set of claims that are required according to branch policy. If there are “adequate claims” on B, the ref can move to B, etc.
      • Aditya: correct, but it depends on the type of claim on B. If the claim is about code review, then arguably the ref matters because B was reviewed in the context of updating a specific branch. So the claim is actually over (ref, B). OTOH, if some automated checks are run across all branches, then the claim may just be about B. This ties into my thought about whether we can actually have a single attestation predicate for source provenance.
    • Example policy: “only authorized actors Alice, Bob, and Carol can make changes to the main branch”
      • So, meeting this requirement means we need to know who moved the branch pointer, even if it points to a Git object that already exists
  • Andrew
    • What are consumers trying to verify?
      • If a branch has special meaning, you might want to verify actions that convey differences in meaning.
  • Michael:
    • Branches (named branches and tags) need to have more durable characteristics for the downstream consumer to be willing to trust claims associated with the name.
    • Somewhere in there, Zac stopped making any sense at all 😂
    • The claims we want to track should be associating claims in tech agnostic ways – how would a user make a risk assessment from ref names?
    • Can we
  • Brandon
    • What does it mean when we sign a digest of an image
    • There are people that say the name of the image matters
    • The name of the branch might matter, but we’re ina better place with slsa
    • We could start saying why we’re signing something – we can say what criteria inspired us to sign it.
    • The same code can be subject to different scrutiny when proposed to move into different contexts
      • We should be clear about what those checks are
  • Zac, a kind of summary
    • According to group discussion, it seemed non-controversial that “if you want to add claims to a sha, you can write a new attestation.”
      • If you find a revision of a repo somewhere, you should feel free to go ask all the attestation providers “everything they know about it” until you have enough evidence or lack of it to move on.
      • A common way to “add claims” is during the “context promotion process”, EG, making a sha which was only reachable from the “experimental” context reachable from the “release” context.
      • Making a sha reachable from experimental might only require unit test, or even only a subset.
      • Making a sha reachable from releases/* might require expert code review and more or different unit tests, different kinds of tests, etc.
    • Further thought and discussion is needed to tease out how we recommend refs updates be considered.
      • At least to zac, it seems that we shouldn’t recommend teams to depend on ref names too much: they are mutable and customers would need to be aware of what they mean to each producer.
      • It’s at least clearer to have an org write a claim that says explicitly “we think this revision can be released” and to recommend verifiers just look for this “seal of quality” concept instead of trying to reason about branches.

[zachariahcox]

I think this is the high-level summary:

• a revision exists as soon as it's received by the canonical server.
• Attestations are written at any point afterwards, and describe "why a revision is allowed to be 'reachable' from a specific branch (or for non-git setups, 'why a revision is included in a certain context')"
• Attestations for a revision can be written more than once by the same issuer.
• A single revision on a single SCP may have an attestation describing why it is reachable from refs/heads/experimental, refs/heads/dev, refs/heads/main, and refs/tags/releases/1
• VSA issuers will need to understand the way provenance issuers create attestations and summarize their findings appropriately.

cc: @TomHennen to double check my math.
I'm not sure where we'd store this content -- maybe the verifying-source.md file?

[TomHennen]

It seems I dropped the ball on responding to this.

I think this may be covered here? https://slsa.dev/spec/draft/source-requirements#summary-attestation:~:text=Example%20implementations%3A