From e97c5b1fc9f9c931e45adbe1ef117abbae3317cf Mon Sep 17 00:00:00 2001 From: Philipp Horstenkamp Date: Sun, 13 Sep 2026 20:40:38 +0200 Subject: [PATCH] docs: add comparison between built-in Syft SBOMs and direct Trivy scanning --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 39ef788..e0eac07 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ A self-contained Gitea and GitHub Actions composite action that extracts multi-p | `output-delta` | Output path for the CVE delta Markdown report | No | `cve-delta.md` | | `output-summary` | Output path for the full vulnerability Markdown summary | No | `cve-summary.md` | | `write-summary` | Whether to append the generated reports to the job summary (`$GITHUB_STEP_SUMMARY`) | No | `true` | +| `use-inbuild-sbom` | Whether to inspect and use built-in image SBOM attestations. If false, generates SBOMs directly with Trivy | No | `false` | --- @@ -39,6 +40,31 @@ A self-contained Gitea and GitHub Actions composite action that extracts multi-p --- +## 🔍 Built-in SBOM Attestations vs. Trivy Direct Scanning (Syft vs. Trivy) + +This action supports two modes for obtaining SBOMs: + +### 1. Direct Image Scanning with Trivy (`use-inbuild-sbom: false` — Default & Recommended) +By default, the action uses `trivy image --format spdx-json` to generate the SBOM directly from the container images: +- **Full Filesystem Fidelity**: Inspects the entire flattened root filesystem, reading `/etc/os-release` and native package databases (e.g. `/var/lib/dpkg/status`, RPM databases, apk). +- **Accurate OS & Language Package Detection**: Successfully catalogs both OS packages (Debian, Alpine, RHEL, etc.) and application dependencies (Python, Node.js, Go, etc.). +- **Symmetric, Apples-to-Apples Comparisons**: Both `head` and `target` images are analyzed using the identical Trivy engine and vulnerability database, preventing skewed diffs. + +### 2. Built-in Attestation Extraction (`use-inbuild-sbom: true`) +When enabled, the action extracts SBOM attestations attached to the container image using `docker buildx imagetools inspect`: +- **Speed**: Extracts the SBOM JSON metadata directly from the registry manifest index in seconds without pulling image layer blobs. +- **Underlying Generator (Syft)**: Docker Buildx (`sbom: true`) uses BuildKit's embedded Syft scanner (`moby/buildkit-syft-scanner`). +- **Known Limitations with Trivy**: + - **Testing/Rolling Distributions**: Embedded Syft versions may not recognize newer or unreleased distributions (such as Debian 13 "Trixie"), recording the OS as `family="none"` and skipping OS package vulnerability matching. + - **Multi-Stage Builds**: Analyzing layer diffs rather than the flattened container rootfs can cause package database paths to be omitted or detached from the OS manifest. + - **Schema/PURL Discrepancies**: Syft and Trivy express certain package qualifiers and namespaces differently in SPDX. When Trivy scans a Syft SPDX file that lacks explicit distro qualifiers, Trivy will silently skip OS vulnerability checks. + - **Differential Skew**: If a `head` image uses an incomplete Syft SBOM (detecting only language packages) while `target` is scanned directly with Trivy (detecting 400+ OS packages), the differential report will erroneously show hundreds of "resolved" CVEs. + +> [!TIP] +> If your builds run on stable base images where BuildKit's Syft scanner accurately captures all OS packages, you can set `use-inbuild-sbom: 'true'` to speed up CI runs. Otherwise, leave it as `false` to ensure consistent and comprehensive scans. + +--- + ## 🚀 Usage Example ```yaml @@ -52,7 +78,6 @@ jobs: with: context: . push: true - sbom: true tags: registry.example.com/my-app:git-${{ github.sha }} - name: Compare Vulnerabilities (Head vs Target)