docs: add Rekor SBOM attestation scanning (#2893)

Signed-off-by: knqyf263 <knqyf263@gmail.com>
aquasecurity · Sep 16, 2022 · 585985e · 585985e
1 parent d30fa00
commit 585985e
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 3 deletions.
diff --git a/docs/docs/attestation/rekor.md b/docs/docs/attestation/rekor.md
@@ -0,0 +1,58 @@
+# Scan SBOM attestation in Rekor
+
+!!! warning "EXPERIMENTAL"
+    This feature might change without preserving backwards compatibility.
+
+Trivy can retrieve SBOM attestation of the specified container image in the [Rekor][rekor] instance and scan it for vulnerabilities.
+
+## Prerequisites
+1. SBOM attestation stored in Rekor
+    - See [the "Keyless signing" section][sbom-attest] if you want to upload your SBOM attestation to Rekor.
+
+
+## Scanning
+You need to pass `--sbom-sources rekor` so that Trivy will look for SBOM attestation in Rekor.
+
+!!! note
+    `--sbom-sources` can be used only with `trivy image` at the moment.
+
+```bash
+$ trivy image --sbom-sources rekor otms61/alpine:3.7.3                                                                            [~/src/github.com/aquasecurity/trivy]
+2022-09-16T17:37:13.258+0900	INFO	Vulnerability scanning is enabled
+2022-09-16T17:37:13.258+0900	INFO	Secret scanning is enabled
+2022-09-16T17:37:13.258+0900	INFO	If your scanning is slow, please try '--security-checks vuln' to disable secret scanning
+2022-09-16T17:37:13.258+0900	INFO	Please see also https://aquasecurity.github.io/trivy/dev/docs/secret/scanning/#recommendation for faster secret detection
+2022-09-16T17:37:14.827+0900	INFO	Detected SBOM format: cyclonedx-json
+2022-09-16T17:37:14.901+0900	INFO	Found SBOM (cyclonedx) attestation in Rekor
+2022-09-16T17:37:14.903+0900	INFO	Detected OS: alpine
+2022-09-16T17:37:14.903+0900	INFO	Detecting Alpine vulnerabilities...
+2022-09-16T17:37:14.907+0900	INFO	Number of language-specific files: 0
+2022-09-16T17:37:14.908+0900	WARN	This OS version is no longer supported by the distribution: alpine 3.7.3
+2022-09-16T17:37:14.908+0900	WARN	The vulnerability detection may be insufficient because security updates are not provided
+
+otms61/alpine:3.7.3 (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 │                │          │                   │               │                                                          │
+│            │                │          │                   │               │                                                          │
+│            │                │          │                   │               │                                                          │
+└────────────┴────────────────┴──────────┴───────────────────┴───────────────┴──────────────────────────────────────────────────────────┘
+
+```
+
+If you have your own Rekor instance, you can specify the URL via `--rekor-url`.
+
+```bash
+$ trivy image --sbom-sources rekor --rekor-url https://my-rekor.dev otms61/alpine:3.7.3
+```
+
+[rekor]: https://github.com/sigstore/rekor
+[sbom-attest]: sbom.md#keyless-signing
diff --git a/docs/docs/attestation/sbom.md b/docs/docs/attestation/sbom.md
@@ -48,6 +48,7 @@ You can use Cosign to sign without keys by authenticating with an OpenID Connect
 ```bash
 # The cyclonedx type is supported in Cosign v1.10.0 or later.
 $ trivy image --format cyclonedx -o sbom.cdx.json <IMAGE>
+# The following command uploads SBOM attestation to the public Rekor instance.
 $ COSIGN_EXPERIMENTAL=1 cosign attest --type cyclonedx --predicate sbom.cdx.json <IMAGE>
 ```
 

diff --git a/docs/tutorials/kubernetes/kyverno.md b/docs/tutorials/kubernetes/kyverno.md
@@ -8,7 +8,7 @@ This tutorial details
 
 ### Prerequisites
 1. [Attestation of the vulnerability scan uploaded][vuln-attestation]
-3. A running Kubernetes cluster that kubectl is connected to
+2. A running Kubernetes cluster that kubectl is connected to
 
 ### Kyverno Policy to check attestation
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -98,6 +98,7 @@ nav:
       - Attestation:
           - SBOM: docs/attestation/sbom.md
           - Cosign Vulnerability Scan Record: docs/attestation/vuln.md
+          - SBOM Attestation in Rekor: docs/attestation/rekor.md
       - Advanced:
           - Modules: docs/advanced/modules.md
           - Plugins: docs/advanced/plugins.md

diff --git a/pkg/flag/scan_flags.go b/pkg/flag/scan_flags.go
@@ -42,13 +42,13 @@ var (
 		Name:       "sbom-sources",
 		ConfigName: "scan.sbom-sources",
 		Value:      []string{},
-		Usage:      "EXPERIMENTAL: SBOM sources (rekor)",
+		Usage:      "[EXPERIMENTAL] try to retrieve SBOM from the specified sources (rekor)",
 	}
 	RekorURLFlag = Flag{
 		Name:       "rekor-url",
 		ConfigName: "scan.rekor-url",
 		Value:      "https://rekor.sigstore.dev",
-		Usage:      "EXPERIMENTAL: URL of Rekor server",
+		Usage:      "[EXPERIMENTAL] address of rekor STL server",
 	}
 )