propose intoto format for source provenance attestations

Ideally someone familiar with generation of intoto specifications will propose a suitable, exensible solution to "provenance claims" made from the perspective of the SCP.

Here is a very rough summary of what we discussed in the originating 🧠 🌩 document.


subject:
  - name: github:sigstore/sigstore-conformance@95d23843cf9c4b83524ade2ec683052d1ea2b2f9
    digest:
      sha512: 0123456789abcdef...
predicateType: https://slsa.dev/changeset/v0.1
predicate:
  changeset:
    uri: https://api.github.com/repos/sigstore/sigstore-conformance/pulls/95
    createdAt: 2011-01-26T19:01:12Z
    closedAt: 2011-01-26T19:01:12Z
    mergedAt: 2011-01-26T19:01:12Z

    # maps to the confusingly-named "head" GitHub object
    topicRef:
      ref: refs/heads/ww/xfail
      sha: c4f1973d00d2272f78979cac8581d6b6d7ee0752
      repo: 
        id: 541893186
        uri-html: https://github.com/sigstore/sigstore-conformance

    # maps to the confusingly-named "base" GitHub object
    targetRef:
      ref: refs/heads/main
      shaAfter: 95d23843cf9c4b83524ade2ec683052d1ea2b2f9 # maps to GH merge_commit_sha
      shaBefore: 1abc82cdefe80bd907855d8447f903ba8b4918e0 # best merge base
      repo: 
        id: 541893186
        uri-html: https://github.com/sigstore/sigstore-conformance

    # optional: list of all constituent commits in the changeset? 
    commits: 
      - sha: c4f1973d00d2272f78979cac8581d6b6d7ee0752
        uri: https://api.github.com/repos/sigstore/sigstore-conformance/git/commits/c4f1973d00d2272f78979cac8581d6b6d7ee0752
        signature: "-----BEGIN SSH SIGNATURE----... entire signature ..  \n-----END SSH SIGNATURE-----"
        author: 
          uri: https://github.com/woodruffw
        committer: 
          uri: https://github.com/woodruffw
        pusher: 
          uri: https://github.com/woodruffw

    # optional: how would we want to list all contributors to the changeset? 
    contributors:
      - uri: https://github.com/woodruffw
        roles: [pr_author, committer?, pusher, merger]
      - uri: https://github.com/jleightcap
        roles: [reviewer]

    # what rules were enforced that allowed this version to be created? 
    #   this might also reasonably be called "security_measures" or something less GitHubby.
    #   Each rule schema would be versioned independently, but there may be commonalities between different products. 
    rules:
      - id: 1111 # the instance of the pull request rule? maybe uri of the ruleset itself, or the ruleset evaluation run that approved it. 
        type: github/pull-request/v0.1 # some way to version the results
        configuration: # context for interpreting the results
          requiredReviewers: 2
          dismissStaleReviews: true

        result: 
          reviews:
            - reviewedAt: 2011-01-26T19:01:12Z
              reviewerUri: https://github.com/jleightcap
              role: Contributor
              result: accept
              topicSha: <sha256>
              targetSha: <sha256>
              bestMergeBase: <sha256>

            - reviewedAt: 2011-01-26T19:01:12Z
              reviewerUri: https://github.com/zachariahcox
              result: reject
              role: Collaborator
              topicSha: <sha256>
              targetSha: <sha256>
              bestMergeBase: <sha256>

      - id: 2222
        type: github/signed_commits/v0.1
        configuration: 
          enabled: true # this is just a checkbox, but maybe it should include any required signing tech?

      - id: 3333 
        type: github/required_workflow/v0.1
        configuration:
          workflowFileName: sigstore/sigstore-conformance/.github/workflows/conformance.yml
          sha: c4f1973d00d2272f78979cac8581d6b6d7ee0752
          ref: refs/heads/main
          uri: https://github.com/sigstore/sigstore-conformance/blob/c4f1973d00d2272f78979cac8581d6b6d7ee0752/.github/workflows/conformance.yml
        result:
          uri: https://github.com/sigstore/sigstore-conformance/pull/95/checks?check_run_id=15533071514
          status: pass

How would you feel if we decided to leave this out of scope for the initial release of the source track and leave source provenance formats up to the SCS? I think we could sink a ton of time into getting this right, and I don't think we'd gain that much vs getting the source track published sooner?

leave source provenance formats up to the SCS

Depending on what you mean, I disagree 🙂 We should at the very least standardise on using in-toto attestations at all across tracks. Do you mean the specific predicate type tho? Why not at least get started on an early draft tho?

leave source provenance formats up to the SCS

Depending on what you mean, I disagree 🙂 We should at the very least standardise on using in-toto attestations at all across tracks. Do you mean the specific predicate type tho? Why not at least get started on an early draft tho?

I think we can probably do something like we do for Build Provenance: https://slsa.dev/spec/v1.0/requirements#provenance-generation:~:text=It%20is%20RECOMMENDED%20to%20use%20the%20SLSA%20Provenance%20format%20and%20associated%20suite%20because%20it%20is%20designed%20to%20be%20interoperable%2C%20universal%2C%20and%20unambiguous%20when%20used%20for%20SLSA.%20See%20that%20format%E2%80%99s%20documentation%20for%20requirements%20and%20implementation%20guidelines.

where we recommend they use the suite and define their predicate types as in-toto predicates.

I think getting started on an early draft of a common predicate type would be fine so long as it doesn't block release of the source track. My suspicion is that it would take a very long time to get agreement between 1) how a system like GitHub would emit these things, 2) how gittuf would handle it, 3) how Scorecards would handle it. I could be wrong though! If it is possible and the type is ready then we can absolutely include it.

I think a primary goal of the source track is the standardized format fwiw.

It doesn't seem like it has to be fancy.

We need the three shas for git, timestamps and subject/ predicateType stuff clarified. The rest can be essentially up to the issuer if we need to punt? Wdyt?

So, I wonder if we could be talking about different things. I think there are a number of ways to interpret this (and I'm going to inject my commentary in there to make this easier for me :p):

Use

We want something that end users can verify when they consume the source (e.g. we don't think the VSA is sufficient)
1. In other discussions we seemed to be pretty happy with the VSA approach so this would surprise me.
We want something that the SCS's VSA issuing authority can use when deciding to issue the VSA
1. If this is just used within the VSA, how necessary is it to make it standardized? Do we just want to make it easier for implementors by giving them someplace to start?
We want something a third party auditors can use when checking on the SCS's VSA issuer?
1. This could be settled by the 'documented' requirement, but I'm realizing that requirement isn't reflected later in the doc, we should probably fix that.

Scope

We want to provide a standardized source provenance attestation that supports all SCS types (e.g. includes GitHub, GitLab, GitTuf, Perforce, Mercurial, merges managed with GitHub, merges managed with Gerrit, etc...)
1. In the current draft we had previously documented this wasn't necessary and actually stated we expected different SCS implementations to have different provenance formats (text).
We want to provide a standardized source provenance attestation that supports all git based SCS types (e.g. all of the above that use Git)
1. Would this conflict with the existing formats gittuf is already using? Would we want them to change their formats? Issue these in-addition to their existing formats? CC @adityasaky
We want to provide a standardized source provenance attestation that supports all hosted git based SCS types (e.g. all of the above but excluding distributed systems like GitTuf)
1. Could work
We just want to provide an example that folks could use if they wanted to.
1. Seems straightforward
We just want to tell folks they should use in-toto to handle the predicates
1. We already suggest this, we could strengthen it.

Are there any other possibilities I'm missing?

FWIW, this issue was filed before #1071 was proposed, so I had imagined 1071 had settled this discussion. Perhaps not!

Here's some other discussion we had in the meeting on the topic.

FYI We'd (@adityasaky and I) had also (perhaps incorrectly) stated in other venues that SLSA was planning to leave the detailed provenance format up to the implementors.

Oh, and FYI @marcelamelara has pointed out that we have this list of example 'provenance attestations' already.

Which makes me realize I'm missing another part of 'scope' which is "what do we want this provenance to attest to?" Just that history was retained and the content not mutated? More?

We want something that end users can verify when they consume the source (e.g. we don't think the VSA is sufficient) In other discussions we seemed to be pretty happy with the VSA approach so this would surprise me.

I think possibly not all end users may be satisfied with a VSA? I also thought we were happy with the VSA approach as a starting point for the track but we do want the VSA to be backed by full attestations so the VSA producer can be kept honest.

We want something that the SCS's VSA issuing authority can use when deciding to issue the VSA If this is just used within the VSA, how necessary is it to make it standardized? Do we just want to make it easier for implementors by giving them someplace to start?

A consumer of a repository may rely on multiple VSAs. For example, they may use a VSA from within the SCS of the repository but also one from a third party organization or service (e.g. a source focused equivalent to independent rebuilders / programs like assured OSS, etc.) which in turn relies on the full attestations. In my mind, this makes full attestations less "internal" and the gains are more than just a place to start for implementers, because it enables this sort of independent monitoring and verification.

(Sorry, addressing scope in a different order than it's presented above.)

We just want to tell folks they should use in-toto to handle the predicates We already suggest this, we could strengthen it.

We should have this be the same strength as in the build track, as this is really a SLSA-wide recommendation. Maybe not saying anything in the source track about in-toto but pointing to the other SLSA docs where in-toto is the recommended format is more straightforward. cc @trishankatdatadog

We just want to provide an example that folks could use if they wanted to. Seems straightforward

I think any example we provide will quickly become the baseline that implementers use, irrespective of any disclaimers. So while it may not be a SLSA responsibility today, it probably will be tomorrow? :smile:

So, we'd want to be really careful with examples, meaning we'd basically be putting in most of the work required to standardize formats, I think.

We want to provide a standardized source provenance attestation that supports all hosted git based SCS types (e.g. all of the above but excluding distributed systems like gittuf)

I think the distributed vs hosted types may not differ much. For example, gittuf has a lightweight type to indicate approval for some change. In a gittuf-model case, the approver is authenticated using their signature on the attestation. At the same time, we have a type for github PR approvals generated by watching a repository's webhook events. The base format is the same but here the approver is recorded within the attestation's predicate.

In other words, @zachariahcox's point about requiring a baseline of the three hashes (or some way to infer them) gets us quite far, and is closely related to:

We want to provide a standardized source provenance attestation that supports all git based SCS types (e.g. all of the above that use Git) Would this conflict with the existing formats gittuf is already using? Would we want them to change their formats? Issue these in-addition to their existing formats? CC @adityasaky

It likely would require a change, but one that we've expected. We've always wanted to adopt the SLSA standardized attestation predicates to maximize interoperability. Also, gittuf's attestation production / verification model is sufficiently different from the hosted SCP model that I think a predicate type that works for both is likely to be broadly applicable across the Git ecosystem at least. I think these benefits outweigh the downsides of having to make changes. :smile:

We want to provide a standardized source provenance attestation that supports all SCS types (e.g. includes GitHub, GitLab, gittuf, Perforce, Mercurial, merges managed with GitHub, merges managed with Gerrit, etc...) In the current draft we had previously documented this wasn't necessary and actually stated we expected different SCS implementations to have different provenance formats (text).

I think this may be the one that's incredibly difficult, if not impossible. I propose we start with predicate(s) for systems whose implementers are here (so basically Git?) and expand outward organically? And having something for an SCS that uses Git may still be a good starting point for an SCS that uses another VCS as it'll be a question of finding equivalents to the VCS-specific data in the predicate.

Which makes me realize I'm missing another part of 'scope' which is "what do we want this provenance to attest to?" Just that history was retained and the content not mutated? More?

There's more, because these attestations are a way of checking the documented format was followed (and producing a VSA saying the documented process was followed). Also, for an attestation to state history was retained and the content not mutated in a verifiable way, we likely need the attestations themselves to be tracked in some way so the SCS can't present split views to different consumers / at different times. Related: https://github.com/slsa-framework/slsa/issues/1129#issuecomment-2453548431

Finally, wrt the discussion about releasing the track with just a VSA requirement in the call on Oct 28, 2024, I think we can't go back and add full attestation requirements / standardized formats once this release happens (which I believe some people mentioned on the call as well). I think we should instead focus on lightweight predicates with room for different systems to extend within reason for code review, etc., like what @zachariahcox proposed above. Since the source track is best served by having multiple predicate types (like what @marcelamelara pointed to in the current draft) rather than a single source provenance type, we can move faster as we can punt defining the ones we think are going to be less commonly used to the next minor release.

We want something that the SCS's VSA issuing authority can use when deciding to issue the VSA

If this is just used within the VSA, how necessary is it to make it standardized? Do we just want to make it easier for implementors by giving them someplace to start?

Absolutely necessary IMHO because I imagine we will be asked how to concretely produce those Source Track VSAs in the first place.

We should have this be the same strength as in the build track, as this is really a SLSA-wide recommendation. Maybe not saying anything in the source track about in-toto but pointing to the other SLSA docs where in-toto is the recommended format is more straightforward. cc @trishankatdatadog

I'd go further: I'm not sure what value we would get by not prescribing in-toto attestations, especially when we would want attestations from different tracks to interoperate. Are there any other practical alternatives to "digital" attestations?

slsa-framework / slsa

propose intoto format for source provenance attestations #1161