From 4fd1020de889c576d8a8ee0053effbc4f2a74365 Mon Sep 17 00:00:00 2001 From: Hector Fernandez Date: Mon, 24 Jul 2023 00:34:05 +0200 Subject: [PATCH 1/4] add vulnerability predicate type Signed-off-by: Hector Fernandez --- spec/predicates/README.md | 2 + spec/predicates/vuln.md | 136 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 spec/predicates/vuln.md diff --git a/spec/predicates/README.md b/spec/predicates/README.md index 0a9a4035..6c8d963b 100644 --- a/spec/predicates/README.md +++ b/spec/predicates/README.md @@ -23,6 +23,7 @@ our [vetting process], and may be of general interest: artifact. - [SPDX]: SPDX-formatted BOM for software artifacts. - [CycloneDX]: CycloneDX BOM for software artifacts. +- [Vulnerability]: Defines the metadata to share the results of vulnerability scanning on software artifacts. - [Test Result]: A generic schema to express results of any type of tests. [CycloneDX]: https://cyclonedx.org/ @@ -30,6 +31,7 @@ our [vetting process], and may be of general interest: [New Predicate Guidelines]: ../../docs/new_predicate_guidelines.md [Runtime Traces]: runtime-trace.md [SCAI Report]: scai.md +[Vulnerability]: vuln.md [SLSA Provenance]: https://slsa.dev/provenance [SLSA Verification Summary]: vsa.md [SPDX]: spdx.md diff --git a/spec/predicates/vuln.md b/spec/predicates/vuln.md new file mode 100644 index 00000000..c9d147ff --- /dev/null +++ b/spec/predicates/vuln.md @@ -0,0 +1,136 @@ +# Predicate type: Vulnerabilities + +Type URI: https://in-toto.io/attestation/vulns/attribute-report + +Version: 0.1 + +## Purpose + +The definition of a vulnerability attestation type has been discussed in the past in [in-toto attestation](https://github.com/in-toto/attestation/issues/58) and [issue](https://github.com/sigstore/cosign/issues/442). However we need to identify two different purposes from these initial conversations: + +* The definition of a common format to represent the results of a vulnerability report. + +* The definition of a certain set of metadata fields that could help to consume these vulnerability attestations from the different scanning tools. + +Obviously the first goal is quite challenging and requires a bigger community to agree upon a specific format. As a consequence, the following attestation type focuses on the definition of that common metadata which could enable the beginning of an exportable and manageable vulnerability attestation. + +This document describes a vulnerability attestation type to represent vulnerability reports from the scanners in an "exportable" manner and independently of the format chosen to output the results. + +## Prerequisites + +The in-toto [attestation] framework and a [Vulnerability scanner tool]. + +## Use Cases + +When sharing the results of a vulnerability scan using an attestation, there is certain metadata that is crucial to trust and reuse this information. +Information about the scanner used during the scanning is relevant to trust these resuls. The state of the vulnerability database used to search for vulnerabilities defines the accuracy of the results. Other metadata information such as the timestamp when the scan finished could define the reusability of these results. + +## Model + +This is a predicate type that fits within the larger [Attestation] framework. + +## Schema + +The schema of this predicate type is documented below. + +### Fields + +The fields that make up this predicate type are: + +The `subject` contains whatever software artifacts are to be associated with this vulnerability report document. +The `predicate` contains a JSON-encoded data with the following fields: + +**scanner** + +> There are lots of container image scanners such as Trivy, Grype, Clair, etc. +> This field describes which scanner is used while performing a container image scan, +> as well as version information and which Vulnerability DB is used. + +**scanner.uri** string (ResourceURI), optional + +> > URI indicating the identity of the source of the scanner. + +**scanner.version** string (ResourceURI), optional + +> The version of the scanner. + +**scanner.db.uri** string (ResourceURI), optional + +> URI indicating the identity of the source of the Vulnerability DB. + +**scanner.db.version** string, optional + +> The version of the Vulnerability DB. + +**scanner.db.lastUpdate string (Timestamp), required** + +> The timestamp of when the vulnerability DB was updated last time. + +**scanner.result** object + +> This is the most important part of this field because it'll store the scan result as a whole. So, people might want +> to use this field to take decisions based on them by making use of Policy Engines tooling whether allow or deny these images. + +**metadata.scanStartedOn string (Timestamp), required** + +> The timestamp of when the scan started. + +**metadata.scanFinishedOn string (Timestamp), required** + +> The timestamp of when the scan completed. + +## Example + +```jsonc +{ + "_type": "https://in-toto.io/Statement/v0.1", + "subject": [ + { + ... + } + ], + // Predicate: + "predicateType": "https://in-toto.io/attestation/vulns/attribute-report/v0.1", + "predicate": { + "invocation": { + "parameters": [], + // [ "--format=json", "--skip-db-update" ] + "uri": "", + // https://github.com/developer-guy/alpine/actions/runs/1071875574 + "event_id": "", + // 1071875574 + "builder.id": "" + // GitHub Actions + }, + "scanner": { + "uri": "", + // pkg:github/aquasecurity/trivy@244fd47e07d1004f0aed9 + "version": "", + // 0.19.2 + "db": { + "uri": "", + // pkg:github/aquasecurity/trivy-db/commit/4c76bb580b2736d67751410fa4ab66d2b6b9b27d + "version": "", + // "v1-2021080612" + "lastUpdate": "" + // 2021-08-06T17:45:50.52Z + }, + "result": {} + }, + "metadata": { + "scanStartedOn": "", + // 2021-08-06T17:45:50.52Z + "scanFinishedOn": "" + // 2021-08-06T17:50:50.52Z + } + } +} +``` + +## Changelog and Migrations + +Not applicable for this initial version. + +[Attestation]: ../README.md + + From 69d51fc3263960b6b5f5abc20daf221648039230 Mon Sep 17 00:00:00 2001 From: Hector Fernandez Date: Sun, 6 Aug 2023 14:09:56 +0200 Subject: [PATCH 2/4] address reviewer comments Signed-off-by: Hector Fernandez --- spec/predicates/vuln.md | 61 +++++++++++++++++++++++++++++++++-------- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/spec/predicates/vuln.md b/spec/predicates/vuln.md index c9d147ff..35319ce8 100644 --- a/spec/predicates/vuln.md +++ b/spec/predicates/vuln.md @@ -20,14 +20,17 @@ This document describes a vulnerability attestation type to represent vulnerabil The in-toto [attestation] framework and a [Vulnerability scanner tool]. -## Use Cases +## Use cases When sharing the results of a vulnerability scan using an attestation, there is certain metadata that is crucial to trust and reuse this information. -Information about the scanner used during the scanning is relevant to trust these resuls. The state of the vulnerability database used to search for vulnerabilities defines the accuracy of the results. Other metadata information such as the timestamp when the scan finished could define the reusability of these results. +Information about the scanner used during the scanning is relevant to trust these results. The state of the vulnerability database used to search for vulnerabilities defines the accuracy of the results. Other metadata information such as the timestamp when the scan finished could define the reusability of these results. ## Model This is a predicate type that fits within the larger [Attestation] framework. +The following model aims to provide a well defined list of fields so that consumers know how to start exchaging their scanner results. + +This predicate model is inspired by [cosign vulnerability attestation](https://github.com/sigstore/cosign/blob/main/specs/COSIGN_VULN_ATTESTATION_SPEC.md). ## Schema @@ -52,32 +55,57 @@ The `predicate` contains a JSON-encoded data with the following fields: **scanner.version** string (ResourceURI), optional -> The version of the scanner. +> > The version of the scanner. **scanner.db.uri** string (ResourceURI), optional -> URI indicating the identity of the source of the Vulnerability DB. +> > > URI indicating the identity of the source of the Vulnerability DB. **scanner.db.version** string, optional -> The version of the Vulnerability DB. +> > > The version of the Vulnerability DB. **scanner.db.lastUpdate string (Timestamp), required** -> The timestamp of when the vulnerability DB was updated last time. +> > > The timestamp of when the vulnerability DB was updated last time. + +**scanner.result** list + +> > The result contains a list of vulnerabilities. +> > This is the most important part of this field because it'll store the scan result as a whole. So, people might want +> > to use this field to take decisions based on them by making use of Policy Engines tooling whether allow or deny these images. + +**scanner.result.[*].vulnerability** object + +> > > The vulnerability object defines information about each one of the vulnerabilities found by the scanner. + +**scanner.result.[*].vulnerability.id** string + +> > > > This is the identifier of the vulnerability, e.g. GHSA-r9p9-mrjm-926w, CVE-123. + +**scanner.result.[*].vulnerability.severity** object + +> > > > The severity contains a list to describe the severity of a vulnerability using one or more quantitative scoring method. + +**scanner.result.[*].vulnerability.severity.type** string + +> > > > > The type describes the quantitative method used to calculate the associated. + +**scanner.result.[*].vulnerability.severity.score** string + +> > > > > This is a string representing the severity score based on the selected method. -**scanner.result** object +**scanner.result.[*].vulnerability.annotations** list -> This is the most important part of this field because it'll store the scan result as a whole. So, people might want -> to use this field to take decisions based on them by making use of Policy Engines tooling whether allow or deny these images. +> > > > > This is a list of key/value pairs where scanners can add additional custom information. **metadata.scanStartedOn string (Timestamp), required** -> The timestamp of when the scan started. +> > The timestamp of when the scan started. **metadata.scanFinishedOn string (Timestamp), required** -> The timestamp of when the scan completed. +> > The timestamp of when the scan completed. ## Example @@ -115,7 +143,16 @@ The `predicate` contains a JSON-encoded data with the following fields: "lastUpdate": "" // 2021-08-06T17:45:50.52Z }, - "result": {} + "result": [ + { + "id": "CVE-123", + "severity": [ + { "type": "nvd", "score": "medium"}, + { "type": "cvss_score", "score", "5.2" } + ] + }, + {...} + ] }, "metadata": { "scanStartedOn": "", From 89b4d481d726347006b7ba8117c68bfaea5d8bf2 Mon Sep 17 00:00:00 2001 From: Hector Fernandez Date: Thu, 17 Aug 2023 11:53:12 +0200 Subject: [PATCH 3/4] address reviewer comments Signed-off-by: Hector Fernandez --- spec/predicates/vuln.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/spec/predicates/vuln.md b/spec/predicates/vuln.md index 35319ce8..20716c24 100644 --- a/spec/predicates/vuln.md +++ b/spec/predicates/vuln.md @@ -1,6 +1,6 @@ # Predicate type: Vulnerabilities -Type URI: https://in-toto.io/attestation/vulns/attribute-report +Type URI: https://in-toto.io/attestation/vulns Version: 0.1 @@ -8,9 +8,8 @@ Version: 0.1 The definition of a vulnerability attestation type has been discussed in the past in [in-toto attestation](https://github.com/in-toto/attestation/issues/58) and [issue](https://github.com/sigstore/cosign/issues/442). However we need to identify two different purposes from these initial conversations: -* The definition of a common format to represent the results of a vulnerability report. - -* The definition of a certain set of metadata fields that could help to consume these vulnerability attestations from the different scanning tools. +- The definition of a common format to represent the results of a vulnerability report. +- The definition of a certain set of metadata fields that could help to consume these vulnerability attestations from the different scanning tools. Obviously the first goal is quite challenging and requires a bigger community to agree upon a specific format. As a consequence, the following attestation type focuses on the definition of that common metadata which could enable the beginning of an exportable and manageable vulnerability attestation. @@ -18,7 +17,7 @@ This document describes a vulnerability attestation type to represent vulnerabil ## Prerequisites -The in-toto [attestation] framework and a [Vulnerability scanner tool]. +The in-toto [attestation] framework and a Vulnerability scanner tools such as [Grype](https://github.com/anchore/grype), [Trivy](https://github.com/aquasecurity/trivy) and others. ## Use cases @@ -28,7 +27,7 @@ Information about the scanner used during the scanning is relevant to trust thes ## Model This is a predicate type that fits within the larger [Attestation] framework. -The following model aims to provide a well defined list of fields so that consumers know how to start exchaging their scanner results. +The following model aims to provide a well defined list of fields so that consumers know how to start exchanging their scanner results. This predicate model is inspired by [cosign vulnerability attestation](https://github.com/sigstore/cosign/blob/main/specs/COSIGN_VULN_ATTESTATION_SPEC.md). @@ -43,7 +42,7 @@ The fields that make up this predicate type are: The `subject` contains whatever software artifacts are to be associated with this vulnerability report document. The `predicate` contains a JSON-encoded data with the following fields: -**scanner** +**scanner** object > There are lots of container image scanners such as Trivy, Grype, Clair, etc. > This field describes which scanner is used while performing a container image scan, @@ -65,7 +64,7 @@ The `predicate` contains a JSON-encoded data with the following fields: > > > The version of the Vulnerability DB. -**scanner.db.lastUpdate string (Timestamp), required** +**scanner.db.lastUpdate, required** string (timestamp) > > > The timestamp of when the vulnerability DB was updated last time. @@ -99,11 +98,11 @@ The `predicate` contains a JSON-encoded data with the following fields: > > > > > This is a list of key/value pairs where scanners can add additional custom information. -**metadata.scanStartedOn string (Timestamp), required** +**metadata.scanStartedOn, required** string (timestamp) > > The timestamp of when the scan started. -**metadata.scanFinishedOn string (Timestamp), required** +**metadata.scanFinishedOn, required** string (timestamp) > > The timestamp of when the scan completed. @@ -169,5 +168,3 @@ The `predicate` contains a JSON-encoded data with the following fields: Not applicable for this initial version. [Attestation]: ../README.md - - From 3caded856d17ff4da2a65f578e4f474bbfed244b Mon Sep 17 00:00:00 2001 From: Hector Fernandez Date: Thu, 17 Aug 2023 14:54:04 +0200 Subject: [PATCH 4/4] add few links to examples Signed-off-by: Hector Fernandez --- spec/predicates/vuln.md | 76 ++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 43 deletions(-) diff --git a/spec/predicates/vuln.md b/spec/predicates/vuln.md index 20716c24..bc5849d7 100644 --- a/spec/predicates/vuln.md +++ b/spec/predicates/vuln.md @@ -42,25 +42,25 @@ The fields that make up this predicate type are: The `subject` contains whatever software artifacts are to be associated with this vulnerability report document. The `predicate` contains a JSON-encoded data with the following fields: -**scanner** object +**scanner, required** object > There are lots of container image scanners such as Trivy, Grype, Clair, etc. > This field describes which scanner is used while performing a container image scan, > as well as version information and which Vulnerability DB is used. -**scanner.uri** string (ResourceURI), optional +**scanner.uri, required** string (ResourceURI) > > URI indicating the identity of the source of the scanner. -**scanner.version** string (ResourceURI), optional +**scanner.version, optional** string (ResourceURI) > > The version of the scanner. -**scanner.db.uri** string (ResourceURI), optional +**scanner.db.uri, optional** string (ResourceURI) > > > URI indicating the identity of the source of the Vulnerability DB. -**scanner.db.version** string, optional +**scanner.db.version, optional** string > > > The version of the Vulnerability DB. @@ -68,41 +68,41 @@ The `predicate` contains a JSON-encoded data with the following fields: > > > The timestamp of when the vulnerability DB was updated last time. -**scanner.result** list +**scanner.result, required** list -> > The result contains a list of vulnerabilities. +> > The result contains a list of vulnerabilities. Note that an empty list means the **scanner** found no vulnerabilities. > > This is the most important part of this field because it'll store the scan result as a whole. So, people might want > > to use this field to take decisions based on them by making use of Policy Engines tooling whether allow or deny these images. -**scanner.result.[*].vulnerability** object +**scanner.result.[*].vulnerability, optional** object > > > The vulnerability object defines information about each one of the vulnerabilities found by the scanner. -**scanner.result.[*].vulnerability.id** string +**scanner.result.[*].vulnerability.id, required** string -> > > > This is the identifier of the vulnerability, e.g. GHSA-r9p9-mrjm-926w, CVE-123. +> > > > This is the identifier of the vulnerability, e.g. [GHSA-fxph-q3j8-mv87](https://github.com/advisories/GHSA-fxph-q3j8-mv87) whose CVE id is [CVE-2017-5645](https://nvd.nist.gov/vuln/detail/CVE-2017-5645). -**scanner.result.[*].vulnerability.severity** object +**scanner.result.[*].vulnerability.severity, required** object > > > > The severity contains a list to describe the severity of a vulnerability using one or more quantitative scoring method. -**scanner.result.[*].vulnerability.severity.type** string +**scanner.result.[*].vulnerability.severity.method, required** string -> > > > > The type describes the quantitative method used to calculate the associated. +> > > > > The method describes the quantitative method used to calculate the associated severity score such as nvd, cvss and others. -**scanner.result.[*].vulnerability.severity.score** string +**scanner.result.[*].vulnerability.severity.score, required** string > > > > > This is a string representing the severity score based on the selected method. -**scanner.result.[*].vulnerability.annotations** list +**scanner.result.[*].vulnerability.annotations, optional** list > > > > > This is a list of key/value pairs where scanners can add additional custom information. -**metadata.scanStartedOn, required** string (timestamp) +**metadata.scanStartedOn, required** Timestamp > > The timestamp of when the scan started. -**metadata.scanFinishedOn, required** string (timestamp) +**metadata.scanFinishedOn, required** Timestamp > > The timestamp of when the scan completed. @@ -110,54 +110,44 @@ The `predicate` contains a JSON-encoded data with the following fields: ```jsonc { - "_type": "https://in-toto.io/Statement/v0.1", + "_type": "https://in-toto.io/Statement/v1", "subject": [ { - ... + "name": "foo.jar", + "digest": {"sha256": "fe4fe40ac7250263c5dbe1cf3138912f3f416140aa248637a60d65fe22c47da4"} } ], // Predicate: - "predicateType": "https://in-toto.io/attestation/vulns/attribute-report/v0.1", + "predicateType": "https://in-toto.io/attestation/vulns/v0.1", "predicate": { "invocation": { "parameters": [], - // [ "--format=json", "--skip-db-update" ] - "uri": "", - // https://github.com/developer-guy/alpine/actions/runs/1071875574 - "event_id": "", - // 1071875574 - "builder.id": "" - // GitHub Actions + "uri": "https://github.com/developer-guy/alpine/actions/runs/1071875574", + "event_id": "1071875574", + "builder.id": "GitHub Actions" }, "scanner": { - "uri": "", - // pkg:github/aquasecurity/trivy@244fd47e07d1004f0aed9 - "version": "", - // 0.19.2 + "uri": "pkg:github/aquasecurity/trivy@244fd47e07d1004f0aed9", + "version": "0.19.2", "db": { - "uri": "", - // pkg:github/aquasecurity/trivy-db/commit/4c76bb580b2736d67751410fa4ab66d2b6b9b27d - "version": "", - // "v1-2021080612" - "lastUpdate": "" - // 2021-08-06T17:45:50.52Z + "uri": "pkg:github/aquasecurity/trivy-db/commit/4c76bb580b2736d67751410fa4ab66d2b6b9b27d", + "version": "v1-2021080612", + "lastUpdate": "2021-08-06T17:45:50.52Z" }, "result": [ { "id": "CVE-123", "severity": [ - { "type": "nvd", "score": "medium"}, - { "type": "cvss_score", "score", "5.2" } + { "method": "nvd", "score": "medium"}, + { "method": "cvss_score", "score", "5.2" } ] }, {...} ] }, "metadata": { - "scanStartedOn": "", - // 2021-08-06T17:45:50.52Z - "scanFinishedOn": "" - // 2021-08-06T17:50:50.52Z + "scanStartedOn": "2021-08-06T17:45:50.52Z", + "scanFinishedOn": "2021-08-06T17:50:50.52Z" } } }