Add more examples for the ResourceDescriptor field type

[joshuagl]

The ResourceDescriptor is an extremely versatile field type with multiple uses. It would be helpful for implementers to understand the versatility and utility of the field type if we provided more, and richer, examples of its use in the type specification.

Specific examples to add:

• Multi-arch images (per Does "subjects" and "materials" field support multi-arch images? #105)

Originally requested by @marcelamelara in #251 (review)

[fred-jonkhart]

In general I cant find any example of any attestation on the internet. If you want people to adopt this methodology you need to lower the threshold. Same for SLSA, not a single example.

[marcelamelara]

@fred-jonkhart Thanks for this feedback, we can certainly always improve upon the documentation in this repo.

Without knowing where you have searched or what exactly you're looking for, I'd recommend you take a look at our https://github.com/in-toto/scai-demos repo, which in fact contains several real in-toto attestation examples (incl. SLSA). Hope that helps.

[fred-jonkhart]

@marcelamelara, Thanks for your response. Half an hour after adding my remark I found some examples at the SLSA site (https://slsa.netlify.app/blog/2023/05/in-toto-and-slsa). What I noticed is that many predicateType URIs are non-existing. The TypeURI spec reads "SHOULD resolve to a human-readable description, but MAY be unresolvable.", so it is allowed to not be there I guess. The same is true for the the examples in the repo your provided. For instance the "https://in-toto.io/attestation/scai/attribute-report/v0.2" page does not exist.

I try to understand if using in-toto would be beneficial for our internal use case, establish internal policy compliance for software artifacts. Currently our pipelines generate telemetry messages that needs to be refactored / reevaluated for both technical and functional reasons. We generate lots of messages including related to quality assurance steps, e.g. doing a SonarQube scan and have some quality gate evaluation result.

I see potential use of a system like GUAC and hence the benefit of refactoring our telemetry towards in-toto. This in contrast to writing our own solution.

However.......

I see the predicateType as the thing to match with our current messages. In other words; is there a suitable predicateType that fits our current message payload. I have a hard time doing this with the missing or sometimes very rudimentary descriptions of the predicateTypes. I had hoped that examples would shed some light, but many examples are trivial or have many missing attributes. In short, I am stuck. If I cant convince myself, how am I to convince my colleagues?

[jkjell]

💯 agree with improving the docs and details. Just adding for reference some "real-world" examples for SLSA build provenance and their verification:

• ArgoCD Verification: https://argo-cd.readthedocs.io/en/stable/operator-manual/signed-release-assets/
• ArgoCD CLI Provenance: https://github.com/argoproj/argo-cd/releases/download/v2.9.2/argocd-cli.intoto.jsonl (I parsed this with cat ~/Downloads/argocd-cli.intoto.jsonl| jq -r .payload | base64 -D | jq .
• OCI.fyi will let you browse images with attestations: https://oci.fyi/?image=cgr.dev%2Fchainguard%2Fstatic is an example
• Traversing far enough leads you to the actual SLSA Provenance (the length of traversal is because of the OCI spec and how images are stored, nothing to do with in-toto): https://oci.dag.dev/?blob=cgr.dev%2Fchainguard%2Fstatic%40sha256%3A58e948f98600147c7c3343c008377914b940f17750f164b27364761954e10190&jq=.payload&jq=base64+-d&jq=jq
• GitHub Action created attestation (disclaimer I work for TestifySec and am paid to work on Witness): https://github.com/testifysec/swf/actions/runs/6959264446

[adityasaky]

I also want to plug SLSA provenance generated for NPM packages. Eg: https://search.sigstore.dev/?logIndex=33351527 (see "Attestation")

[adityasaky]

I see the predicateType as the thing to match with our current messages. In other words; is there a suitable predicateType that fits our current message payload. I have a hard time doing this with the missing or sometimes very rudimentary descriptions of the predicateTypes.

There are descriptions of "vetted" predicate types here: https://github.com/in-toto/attestation/tree/main/spec/predicates. I agree supplementing them with real world examples would be neat. I think a new one may be necessary for what you describe, which is documented here: https://github.com/in-toto/attestation/blob/main/docs/new_predicate_guidelines.md.