diff --git a/dev-docs/adr/0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md b/dev-docs/adr/0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md new file mode 100644 index 00000000..2700ddd4 --- /dev/null +++ b/dev-docs/adr/0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md @@ -0,0 +1,72 @@ +# ADR-0049: A pinned origin is one VCS locator in every export + +- **Date:** 2026-10-19 +- **Status:** Accepted + +## Context + +A detector that resolves a package from a repository at a revision records +both on the node's origin (ADR-0033). The SPDX export wrote the pair in the +version-control locator form the specification defines in section 7.7, +`git+@`. The CycloneDX export wrote only the repository URL, +on the reasoning that CycloneDX external references have no revision field. +Issue #508 measured the result on Bomly's own CycloneDX export: every +SHA-pinned GitHub Action carried its commit only as a `SHA-1` hash, which a +CISA 2026 validator classed as a weak content digest, and nothing in the +component said the value was a version-control object identifier. + +bomly-cli#518 made the detector record the origin. What remained was the +codec's decision to drop the revision on one side. The vendored CycloneDX +schema defines the `vcs` reference type only as "Version Control System" and +types the `url` as an IRI reference; it neither offers a revision slot nor +restricts what the URL may carry. Where a specification is silent, the +mapping is Bomly's policy, and the policy had been chosen for the format's +convenience rather than the reader's. + +The synthesized primary component raised the same question from the other +side: it describes a source tree, which has no content hash, and the document +did not say so. The SPDX package `comment` could not carry the explanation, +because Bomly's codec parses that field back as the `bomly:` scope and type +carrier. + +## Decision + +A repository origin pinned to a revision is written as one string in both +exports: the version-control locator `git+@`, which SPDX 2.3 +section 7.7 defines and the package-URL `vcs_url` qualifier shares. In SPDX +it is the download location, as before; in CycloneDX it is the URL of the +`vcs` external reference. An origin with no revision keeps the plain +repository URL in CycloneDX, because that is a location a reader can open and +the locator grammar adds nothing to it. `bomly-sdk/sbom.vcsLocator` holds the +grammar for both encoders, and a repository already carried by an origin is +not written a second time without its revision. + +The synthesized project root carries a description, set by the CLI from the +execution target: a source tree is described from its manifests and lockfiles +and is not a distributed artifact, so no content hash applies to it; a +container image is inventoried from its filesystem rather than an archive. It +is rendered in the field both formats define for a component's description, +so a consumer reading either document finds the reason where it looks first. + +The hash itself stays. A Git object identifier is a SHA-1, both formats name +that algorithm, and relabelling it would misstate what was computed. The +locator beside it is what says the value is a commit rather than a content +digest. + +## Consequences + +- CycloneDX documents change for every component whose detector recorded a + revision: Python git sources, cargo git dependencies, SwiftPM and pub pins, + and GitHub Actions references. Unpinned and enrichment-sourced `vcs` + references are unchanged. +- The codec does not ingest CycloneDX `vcs` references (the laundering rule + in `isOriginDerivedReferenceType`), so the locator cannot be read back as a + repository URL with `@` in its path. SPDX ingest already splits + the locator. +- Resolving a tag or branch reference to a commit needs the network and stays + outside the manifest detector; such a reference carries the repository and + the ref as written, and no hash. +- Validators that score hash strength are free to keep scoring a SHA-1 as + weak. Bomly answers with the locator, not by relabelling the hash; a + validator that wants a stronger statement about a pinned action needs a + content digest of the action's tree, which no manifest records. diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index cc1ea793..bba18c59 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -69,3 +69,4 @@ status to `Superseded by [ADR-NNNN](NNNN-slug.md)`; do not rewrite history | ADR-0046 | 2026-09-24 | [The scan output is the SDK's scan record](0046-the-scan-output-is-the-sdk-scan-record.md) | Accepted | | ADR-0047 | 2026-10-03 | [Release assurance is a declarative catalog plus a per-check result contract](0047-release-assurance-is-a-catalog-and-a-result-contract.md) | Accepted | | ADR-0048 | 2026-10-19 | [OSV stays opt-in; Grype keeps its database fresh](0048-osv-stays-opt-in-and-grype-keeps-its-database-fresh.md) | Accepted | +| ADR-0049 | 2026-10-19 | [A pinned origin is one VCS locator in every export](0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md) | Accepted | diff --git a/docs/SBOM.md b/docs/SBOM.md index 037c45cc..9eb9b49e 100644 --- a/docs/SBOM.md +++ b/docs/SBOM.md @@ -233,11 +233,16 @@ A detector reports one of two things, or nothing at all: | What the lockfile records | SPDX 2.3 | CycloneDX | |---|---|---| | The exact file the package was fetched from | `downloadLocation` | `distribution` external reference | -| The repository it was resolved from, and the revision when the manifest names one: a commit, or for GitHub Actions the tag or branch exactly as written | `downloadLocation` as `git+`, with `@` when present; `sourceInfo` when a download location is already taken by an artifact | `vcs` external reference (URL only) | +| The repository it was resolved from, and the revision when the manifest names one: a commit, or for GitHub Actions the tag or branch exactly as written | `downloadLocation` as `git+`, with `@` when present; `sourceInfo` when a download location is already taken by an artifact | `vcs` external reference: `git+@` when a revision is recorded, the plain repository URL otherwise | | Neither | `NOASSERTION` | no reference | -CycloneDX external references have no field for a revision, so the revision a -detector reported appears only in the SPDX form. +A pinned repository is written as the same string in both formats, +`git+@`, which is the version-control locator form SPDX 2.3 +defines and the package-URL `vcs_url` qualifier uses. CycloneDX has no field +of its own for a revision and does not say what a `vcs` URL may carry, so the +locator goes in the URL; a reader who sees `git+` knows to parse a revision +from it rather than open it. A repository with nothing to pin stays a plain +URL in CycloneDX, because that is a location a reader can open. What each ecosystem yields: @@ -306,9 +311,9 @@ Every origin a detector reports is an absolute `http`/`https` URL with a host, a non-empty path, and no embedded credentials. Values are re-serialized from a parse rather than copied from the lockfile, and the same check runs again at export, so origin supplied by a plugin is held to the same rule as origin from a -built-in detector. SPDX then composes the validated repository URL into its -`git+@` locator form, which is the only place a revision -appears. +built-in detector. Both formats then compose the validated repository URL +into the `git+@` locator form when a revision is recorded; +CycloneDX keeps the plain URL when none is. ### Document identity diff --git a/go.mod b/go.mod index eab4eeec..ca6b2a0d 100644 --- a/go.mod +++ b/go.mod @@ -14,7 +14,7 @@ require ( github.com/bomly-dev/bomly-plugin-pyreach-analyzer v0.4.0 github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0 github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0 - github.com/bomly-dev/bomly-sdk v0.14.8 + github.com/bomly-dev/bomly-sdk v0.14.10 github.com/charmbracelet/bubbles v1.0.0 github.com/charmbracelet/bubbletea v1.3.10 github.com/charmbracelet/lipgloss v1.1.0 @@ -157,7 +157,7 @@ require ( github.com/felixge/httpsnoop v1.1.0 // indirect github.com/fsnotify/fsnotify v1.10.1 // indirect github.com/gabriel-vasile/mimetype v1.4.15 // indirect - github.com/github/go-spdx/v2 v2.7.0 // indirect + github.com/github/go-spdx/v2 v2.7.1 // indirect github.com/glebarez/go-sqlite v1.23.0 // indirect github.com/glebarez/sqlite v1.11.0 // indirect github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect diff --git a/go.sum b/go.sum index 411edc22..8fb40313 100644 --- a/go.sum +++ b/go.sum @@ -263,8 +263,8 @@ github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0 h1:CB4M5/N7vR2OlMuxKs github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0/go.mod h1:g62nlreSY249tHBl8uoECIan2FW8r+S1xNFZkbdqSBw= github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0 h1:4U/YOzWujQx1LK+VpPhPEpt2ikwiBciDzaE0V5iNN6M= github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0/go.mod h1:B17C01ssOWdoUGa3geCaouPSge+23QiD2ssFLao0g94= -github.com/bomly-dev/bomly-sdk v0.14.8 h1:3yYkwB8lQAXhMkDvQuNhCRNcnYgerdR7FI/V8zrr/rQ= -github.com/bomly-dev/bomly-sdk v0.14.8/go.mod h1:B/km/swnrS1Tblgpv+5hpVdWHJjyaY5BFdF1cUS38C0= +github.com/bomly-dev/bomly-sdk v0.14.10 h1:ZFb4pXYofXeB6Zd8Rh36vj64X31u9MuD7TB5LwU11hw= +github.com/bomly-dev/bomly-sdk v0.14.10/go.mod h1:XzJZ6B9fNewalouISppzR52Fev4XGIDPElO9OjJTU5M= github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M= github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0= github.com/bufbuild/protocompile v0.14.1 h1:iA73zAf/fyljNjQKwYzUHD6AD4R8KMasmwa/FBatYVw= @@ -450,8 +450,8 @@ github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxv github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI= github.com/gabriel-vasile/mimetype v1.4.15/go.mod h1:azpTcoLcDZRNgFou5j+APrqQx9HqVPWa6ijYQIIVswQ= github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04= -github.com/github/go-spdx/v2 v2.7.0 h1:GzfXx4wFdlilARxmFRXW/mgUy3A4vSqZocCMFV6XFdQ= -github.com/github/go-spdx/v2 v2.7.0/go.mod h1:Ftc45YYG1WzpzwEPKRVm9Jv8vDqOrN4gWoCkK+bHer0= +github.com/github/go-spdx/v2 v2.7.1 h1:+siV9wnsncI5pg4otH/sKvqGL8UkcLdPh16TSJYY1V4= +github.com/github/go-spdx/v2 v2.7.1/go.mod h1:Ftc45YYG1WzpzwEPKRVm9Jv8vDqOrN4gWoCkK+bHer0= github.com/gkampitakis/ciinfo v0.3.4 h1:5eBSibVuSMbb/H6Elc0IIEFbkzCJi3lm94n0+U7Z0KY= github.com/gkampitakis/ciinfo v0.3.4/go.mod h1:1NIwaOcFChN4fa/B0hEBdAb6npDlFL8Bwx4dfRLRqAo= github.com/gkampitakis/go-snaps v0.5.23 h1:okh5QR48zpUjpWtu65AtqxdCY8huJq+dEDuUzd1PuKg= diff --git a/internal/cli/scan_cmd.go b/internal/cli/scan_cmd.go index b9de3d03..0e17b48c 100644 --- a/internal/cli/scan_cmd.go +++ b/internal/cli/scan_cmd.go @@ -279,11 +279,33 @@ func scanSBOMBuildOptions(logger *zap.Logger, target plugin.ExecutionTarget, pro } if name := strings.TrimSpace(project.Name); name != "" { opts.DocumentName = name - opts.ProjectRoot = &sbom.ProjectRoot{Name: name, Version: sbomProjectVersion(logger, target, project)} + opts.ProjectRoot = &sbom.ProjectRoot{ + Name: name, + Version: sbomProjectVersion(logger, target, project), + Description: sbomProjectRootDescription(target), + } } return opts } +// sbomProjectRootDescription says what the synthesized primary component is, +// so a consumer finds the reason it carries no content hash in the document +// itself rather than in Bomly's documentation (issue #508). A source tree is +// described from its manifests and lockfiles and is not a distributed +// artifact, so no hash applies to it; a container image is inventoried from +// its filesystem, not from an archive of it. Other targets, such as a +// re-exported SBOM, describe themselves and get no statement from Bomly. +func sbomProjectRootDescription(target plugin.ExecutionTarget) string { + switch target.Kind { + case plugin.ExecutionTargetGitRepository, plugin.ExecutionTargetFilesystem: + return "Source tree of the scanned project, described from its manifests and lockfiles. A source tree is not a distributed artifact, so no content hash applies to it and no files were analyzed." + case plugin.ExecutionTargetContainerImage: + return "Container image the scan inventoried from its filesystem. The document describes the image's contents, not an archive of it, so no content hash applies to the root." + default: + return "" + } +} + // sbomProjectVersion picks the version the SBOM's primary component carries // (issue #504). The checkout the scan actually ran against -- the temporary // clone of a --url target, or the local --path -- is described first, so a diff --git a/internal/cli/scan_cmd_test.go b/internal/cli/scan_cmd_test.go index 7a50e380..9cbb6d2f 100644 --- a/internal/cli/scan_cmd_test.go +++ b/internal/cli/scan_cmd_test.go @@ -417,6 +417,33 @@ func TestSBOMProjectVersionDescribesTheCheckoutNotTheURL(t *testing.T) { // TestSBOMProjectVersionFallsBackToCommitThenRef covers the targets git // cannot describe: the resolved commit is the next best identity, and the // ref as typed is the last resort rather than an omitted version. +// The root's description explains the absence of a content hash in the +// document itself, per target kind; a target that describes itself gets none. +func TestSBOMProjectRootDescriptionFollowsTheTargetKind(t *testing.T) { + cases := []struct { + kind plugin.ExecutionTargetKind + want string + }{ + {plugin.ExecutionTargetFilesystem, "Source tree"}, + {plugin.ExecutionTargetGitRepository, "Source tree"}, + {plugin.ExecutionTargetContainerImage, "Container image"}, + {plugin.ExecutionTargetKind(""), ""}, + {plugin.ExecutionTargetKind("sbom"), ""}, + } + for _, tc := range cases { + got := sbomProjectRootDescription(plugin.ExecutionTarget{Kind: tc.kind}) + if tc.want == "" { + if got != "" { + t.Errorf("kind %q: description = %q, want none", tc.kind, got) + } + continue + } + if !strings.HasPrefix(got, tc.want) || !strings.Contains(got, "no content hash") { + t.Errorf("kind %q: description = %q, want one starting %q that says no content hash applies", tc.kind, got, tc.want) + } + } +} + func TestSBOMProjectVersionFallsBackToCommitThenRef(t *testing.T) { cases := []struct { name string