vulnerability attestation: ITE-9 specification

[hectorj2f]

As a continuation of the discussion initiated in #58 and the Slack thread, I decided to propose a vulnerability scan-specific in-toto predicate.

This ITE-9 document describes a vulnerability predicate type to represent vulnerability reports from the scanners in an "exportable" manner and independently of the format chosen to output the scanning results.

Note that, the fields proposed for this new predicate type are inspired by the cosign specification for the vulnerability attestations.

[pxp928]

As this is the most important, we should have a set struct that people should follow. For example, a field to specify vulnerabilityIDs and such.

[TomHennen]

Agreed.

I'd probably expect a list of vulnerability identifiers coupled with severity. If you'd like to allow scanners to add additional custom information perhaps let them add annotations?

E.g.

scanner.result = [{"id": "CVE-123", "severity": "medium", "annotations": { "cvss_score": 5.2 }}, {...}]

I could see having different lists for CVEs vs OSV results?

[hectorj2f]

It sounds good to me 👍🏻 !

[hectorj2f]

@TomHennen @pxp928 This suggestion makes sense to me. But I wanted to stay away from the defined format to represent the results at least for now. Users may prefer to use SARIF,or any other custom JSON format to set the results of the scan. I'd say a second iteration should define the format of this result struct.

wdyt ?

[TomHennen]

IMO the real value from predicates is having the predicates be well defined so that consumers know how to use it. Without result being well defined I don't think there's much value. Perhaps I'm missing something?

[hectorj2f]

@TomHennen Sure! I highlighted it on the Purpose section. My initial goal was to define the metadata around the results which could help to exchange these attestations without having to solve the problem of which format to use when sharing the results of a vulnerability scan by any scanner.

However I am happy to move on defining a structure for the result's section if we feel we are ready to come to an agreement. cc @znewman01

[pxp928]

Hey @hectorj2f, yes we should define a starting structure for the results for an initial release that we can iterate on if needed. For example, having a list of vulnerabilityIDs might be a start. Not sure if we want to include this but we could also have severity:

{
	"severity": [ {
		"type": string,
		"score": string
	} ]
}

similar to the osv implementation: https://ossf.github.io/osv-schema/#severity-field

[hectorj2f]

Sgtm! I'll add these suggestions.

[TomHennen]

nit: for some reason Markdown doesn't seem to identify this as a header?

[hectorj2f]

having a look at this!

[TomHennen]

nit: resuls -> results

[TomHennen]

Agreed.

I'd probably expect a list of vulnerability identifiers coupled with severity. If you'd like to allow scanners to add additional custom information perhaps let them add annotations?

E.g.

scanner.result = [{"id": "CVE-123", "severity": "medium", "annotations": { "cvss_score": 5.2 }}, {...}]

I could see having different lists for CVEs vs OSV results?

[colek42]

@hectorj2f can you talk about what the benefits of this attestation format vs wrapping SARIF in an in-toto statement?

[hectorj2f]

@colek42 Without going into details of defining a specific output format here (e.g. Sarif) for the scanner results, the main purpose consists on defining a set of metadata fields to exchange these attestations without having to worry about which output format was used by the scanner to share the results here. These metadata fields will help anyone consuming these attestations to know things about the used scanner, the state of the database and other values. It is more of a standarization of a set of fields that could help to exchange and trust the results from these attestations. For instance, if I get a vulnerability attestation but I know the vulnerability database used by this scanner hasn't been updated since months. I'll discard these results. Other aspects, such as the version/source of the scanner can represent for certain customers and reason to ignore these attestations.

However if I now focus on the benefits of a different format versus Sarif. I'd say Sarif is a language conceived to render data in a GUI and consequently it ignores additional data that you can only get from custom output formats (e.g. grype json or trivy json output formats). In addition to that, the sarif specification is massive because it is used to render all kind of scanning results (not just vulnerability scanning).

[colek42]

@hectorj2f thank you. That makes complete sense.

[hectorj2f]

@marcelamelara Thanks for the review. I've addressed your comments. Could you have another look :) ?

[pxp928]

LGTM! This looks good for an initial release. Thanks @hectorj2f!

[adityasaky]

@hectorj2f do you think you could add a proto definition for this predicate in https://github.com/in-toto/attestation/tree/main/protos/in_toto_attestation/predicates?

[hectorj2f]

@adityasaky Sure. Would it be okay to add it as part of a separate PR ?

[adityasaky]

Sure, I think that's fine.

[hectorj2f]

@TomHennen Could you have another look at this PR ?

[TomHennen]

Thanks for making this changes, this is looking good!

[hectorj2f]

@TomHennen Thanks for the review, I addressed your comments.

[TomHennen]

Thanks for the changes, just a couple minor things to cleanup.

[TomHennen]

Thanks! Just one minor comment.

[TomHennen]

Thanks for working through this Hector!

[hectorj2f]

Thanks to everyone for the reviews 🎉 !