From 687941390eb56d9dd353cf97f5ce8cad1988fd15 Mon Sep 17 00:00:00 2001 From: saso Date: Wed, 10 Aug 2022 21:47:40 +0900 Subject: [PATCH] docs(sbom): improve SBOM docs by adding a description for scanning SBOM attestation (#2690) --- docs/docs/attestation/sbom.md | 67 ++++++++++++++++++++++++++--------- docs/docs/sbom/index.md | 5 ++- 2 files changed, 52 insertions(+), 20 deletions(-) diff --git a/docs/docs/attestation/sbom.md b/docs/docs/attestation/sbom.md index 8c5c4abad21..87e545b4a20 100644 --- a/docs/docs/attestation/sbom.md +++ b/docs/docs/attestation/sbom.md @@ -1,6 +1,7 @@ # SBOM attestation [Cosign](https://github.com/sigstore/cosign) supports generating and verifying [in-toto attestations](https://github.com/in-toto/attestation). This tool enables you to sign and verify SBOM attestation. +And, Trivy can take an SBOM attestation as input and scan for vulnerabilities !!! note In the following examples, the `cosign` command will write an attestation to a target OCI registry, so you must have permission to write. @@ -8,44 +9,76 @@ ## Sign with a local key pair -Cosign can generate key pairs and use them for signing and verification. Read more about [how to generate key pairs](https://docs.sigstore.dev/cosign/key-generation). - -In the following example, Trivy generates an SBOM in the spdx format, and then Cosign attaches an attestation of the SBOM to a container image with a local key pair. +Cosign can generate key pairs and use them for signing and verification. After you run the following command, you will get a public and private key pair. Read more about [how to generate key pairs](https://docs.sigstore.dev/cosign/key-generation). +```bash +$ cosign generate-key-pair ``` -$ trivy image --format spdx -o sbom.spdx -$ cosign attest --key /path/to/cosign.key --type spdx --predicate sbom.spdx + +In the following example, Trivy generates an SBOM in the CycloneDX format, and then Cosign attaches an attestation of the SBOM to a container image with a local key pair. + +```bash +# The cyclonedx type is supported in Cosign v1.10.0 or later. +$ trivy image --format cyclonedx -o sbom.cdx.json +$ cosign attest --key /path/to/cosign.key --type cyclonedx --predicate sbom.cdx.json ``` Then, you can verify attestations on the image. -``` -$ cosign verify-attestation --key /path/to/cosign.pub +```bash +$ cosign verify-attestation --key /path/to/cosign.pub --type cyclonedx ``` You can also create attestations of other formatted SBOM. -``` +```bash +# spdx +$ trivy image --format spdx -o sbom.spdx +$ cosign attest --key /path/to/cosign.key --type spdx --predicate sbom.spdx + # spdx-json $ trivy image --format spdx-json -o sbom.spdx.json $ cosign attest --key /path/to/cosign.key --type spdx --predicate sbom.spdx.json - -# cyclonedx -# The cyclonedx type is supported in Cosign v1.10.0 or later. -$ trivy image --format cyclonedx -o sbom.cdx.json -$ cosign attest --key /path/to/cosign.key --type cyclonedx --predicate sbom.cdx.json ``` ## Keyless signing You can use Cosign to sign without keys by authenticating with an OpenID Connect protocol supported by sigstore (Google, GitHub, or Microsoft). -``` -$ trivy image --format spdx -o sbom.spdx -$ COSIGN_EXPERIMENTAL=1 cosign attest --type spdx --predicate sbom.spdx +```bash +# The cyclonedx type is supported in Cosign v1.10.0 or later. +$ trivy image --format cyclonedx -o sbom.cdx.json +$ COSIGN_EXPERIMENTAL=1 cosign attest --type cyclonedx --predicate sbom.cdx.json ``` You can verify attestations. +```bash +$ COSIGN_EXPERIMENTAL=1 cosign verify-attestation --type cyclonedx ``` -$ COSIGN_EXPERIMENTAL=1 cosign verify-attestation + +## Scanning + +Trivy can take an SBOM attestation as input and scan for vulnerabilities. Currently, Trivy supports CycloneDX-type attestation. + +In the following example, Cosign can get an CycloneDX-type attestation and trivy scan it. You must create CycloneDX-type attestation before trying the example. To learn more about how to create an CycloneDX-Type attestation and attach it to an image, see the [Sign with a local key pair](#sign-with-a-local-key-pair) section. + +```bash +$ cosign verify-attestation --key /path/to/cosign.pub --type cyclonedx > sbom.cdx.intoto.jsonl +$ trivy sbom ./sbom.cdx.intoto.jsonl + +sbom.cdx.intoto.jsonl (alpine 3.7.3) +========================= +Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 2) + +┌────────────┬────────────────┬──────────┬───────────────────┬───────────────┬──────────────────────────────────────────────────────────┐ +│ Library │ Vulnerability │ Severity │ Installed Version │ Fixed Version │ Title │ +├────────────┼────────────────┼──────────┼───────────────────┼───────────────┼──────────────────────────────────────────────────────────┤ +│ musl │ CVE-2019-14697 │ CRITICAL │ 1.1.18-r3 │ 1.1.18-r4 │ musl libc through 1.1.23 has an x87 floating-point stack │ +│ │ │ │ │ │ adjustment im ...... │ +│ │ │ │ │ │ https://avd.aquasec.com/nvd/cve-2019-14697 │ +├────────────┤ │ │ │ │ │ +│ musl-utils │ │ │ │ │ │ +│ │ │ │ │ │ │ +│ │ │ │ │ │ │ +└────────────┴────────────────┴──────────┴───────────────────┴───────────────┴──────────────────────────────────────────────────────────┘ ``` diff --git a/docs/docs/sbom/index.md b/docs/docs/sbom/index.md index 94f8af8f5ad..924ed0551f1 100644 --- a/docs/docs/sbom/index.md +++ b/docs/docs/sbom/index.md @@ -211,8 +211,7 @@ Total: 3 (CRITICAL: 3) CycloneDX XML and SPDX are not supported at the moment. You can also scan an SBOM attestation. -In the following example, [Cosign][Cosign] can get an attestation and trivy scan it. -To learn more about how to create an SBOM attestation and attach it to an image, see the [SBOM attestation page][sbom_attestation]. +In the following example, [Cosign][Cosign] can get an attestation and trivy scan it. You must create CycloneDX-type attestation before trying the example. To learn more about how to create an CycloneDX-Type attestation and attach it to an image, see the [SBOM attestation page][sbom_attestation]. ```bash $ cosign verify-attestation --key /path/to/cosign.pub --type cyclonedx > sbom.cdx.intoto.jsonl $ trivy sbom ./sbom.cdx.intoto.jsonl @@ -237,4 +236,4 @@ Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 2) [cyclonedx]: cyclonedx.md [spdx]: spdx.md [Cosign]: https://github.com/sigstore/cosign -[sbom_attestation]: ../attestation/sbom.md \ No newline at end of file +[sbom_attestation]: ../attestation/sbom.md#sign-with-a-local-key-pair \ No newline at end of file