ITE-13: Git Repository Attestation Storage Specification #61
Conversation
Proposes an attestation storage format for how to store attestations within a Git repo. Signed-off-by: Billy Lynch <[email protected]>
| Attestations are stored in [git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References), | ||
| and can be pushed or pulled like any other Git ref. | ||
|
|
||
| The latest commit in each attestation ref represents the current state of attestations for that Git object type. |
There was a problem hiding this comment.
Do we make any statement that the storage of attestations must strictly grow (i.e. each new commit has all previous attestations inside plus any new ones)?
There was a problem hiding this comment.
No - I kinda few this like OCI attestations in that that probably makes the most sense, but there's no harm in removing them beyond you may not be able to verify anymore (which sometimes may be a feature).
SantiagoTorres
left a comment
SantiagoTorres
left a comment
There was a problem hiding this comment.
I think this is cool! I'd like to move forward a bit. I think some clarification and we can start gathering comments
| | Git Repository Attestation Storage Specification | ||
|
|
||
| | Sponsor | ||
| | link:https://github.com/wlynch[Billy Lynch] |
There was a problem hiding this comment.
I think the sponsor here should be an ITSC editor, rather than the author
| 2. **Check the appropriate namespace**: Look in the corresponding `refs/attestations/<type>` namespace | ||
| 3. **Navigate to the object directory**: Find the directory named with the target object's hash | ||
| 4. **Enumerate attestation files**: List all `.intoto.jsonl` files in that directory | ||
| 5. **Parse and verify**: Read the attestation bundles and verify signatures as needed |
There was a problem hiding this comment.
I am trying to picture this in my head. This is to say that an attestation collection is inside a worktree? is this separate from the standard worktree? or is storage tangential and we don't care?
There was a problem hiding this comment.
I'm not sure I fully understand, but the ref structure is more about discoverability of attestations - e.g. the same way for OCI you can use referrers / <digest>.att, you should be able to use refs/attestations/... to locate attestations in git repos. From there is a matter of iterating through the candidates to find what you need - either an attestation for a certain type/subject/signer, etc.
| If your ITE includes code changes, provide some links to the prototype | ||
| implementation of these changes. | ||
|
|
||
| TODO (we will use one or all of the existing tools as a prototype implementation) |
There was a problem hiding this comment.
I wonder if instead of TODO we could just point out to all of these frameworks that are, admittedly, quite mature already.
There was a problem hiding this comment.
Part of the motivation for this was to settle on a common way that these tools can interop with each other by storing things in similar formats. Some use refs/attestations (but different format) today, some use git notes, etc.
ITE/13/README.adoc
Outdated
| - **Tree attestations**: `refs/attestations/trees` | ||
| - **Blob attestations**: `refs/attestations/blobs` | ||
|
|
||
| Additional types may be created under the `refs/attestations` namespace to store attestations about other types, even non-Git objects. |
There was a problem hiding this comment.
Might be worth thinking about the scope here: if the attestations are about the git objects in the same repo, it makes sense for them to live in refs/attestations/<>, i.e., out of the way of "regular" repo contents in main etc. If we want to store attestations for non Git objects, does it need to go in the special ref namespace in the first place?
There was a problem hiding this comment.
Up to the user? This is intentionally written to not be prescriptive, the same way you can extend refs/... in generally to store information about what ever you want.
| ├── a1b2c3d4e5f6789012345678901234567890abcd/ | ||
| │ └── attestations.intoto.jsonl | ||
| └── b2c3d4e5f6789012345678901234567890abcdef1/ | ||
| ├── pull_request.intoto.jsonl |
There was a problem hiding this comment.
Should we allow multiple blobs? Can we consistently have attestations.intoto.jsonl that is a union of all the jsonl files in this example? That might simplify client logic. We can determine later if multiple files are necessary, perhaps.
We could even argue for commitID.intoto.jsonl instead of having a directory for the commit ID with a single item in it, but that might be problematic to extend.
There was a problem hiding this comment.
I think we should. While it might make verification more complex, it's much easier as an implementor to stake claim of a particular file namespace without care of other integrations instead of having to do read-modify-write workflows.
e.g. the gittuf app might always write observations as github_<app-id>.json.
|
|
||
| All source attestations MUST use the [Attestation bundle](./bundle.md) format. | ||
|
|
||
| Attestations in the bundle MAY have different subjects, but they SHOULD |
There was a problem hiding this comment.
I suggest bumping this up to MUST to keep things simpler. Attestations in the bundle may have 1+ subjects but at least one of those subjects must be for the object whose directory it's in to avoid scenarios where an attestation is assumed to apply to the Git object whose directory it's in.
There was a problem hiding this comment.
From a structural standpoint it doesn't really matter if these don't match?
Verifiers should validate but the biggest issue if you don't follow this is discoverability is hindered.
We want to avoid cruft here, but the security properties still holds if this is mucked with, so SHOULD feels appropriate?
Signed-off-by: Billy Lynch <[email protected]>
patzielinski
left a comment
patzielinski
left a comment
There was a problem hiding this comment.
No further suggestions from me from the gittuf perspective 🙂.
Co-authored-by: patzielinski <[email protected]>
4 participants
Proposes an attestation storage format for how to store attestations within a Git repo.