From 66c8729f4bdcdd1e3e260643e290b33971e6729d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 19 Oct 2026 06:43:06 +0000 Subject: [PATCH 1/4] feat(sbom): describe the project root, and document the shared VCS locator (ADR-0049) The synthesized primary component now says what it is: a source tree described from its manifests and lockfiles, or a container image inventoried from its filesystem, neither a distributed artifact, so a consumer finds in the document why the root carries no content hash (issue #508). The text goes through the SDK's ProjectRoot.Description, rendered as the component description both formats define. docs/SBOM.md no longer says a revision appears only in the SPDX form: with the SDK change this release adopts, a pinned repository origin is written as the same version-control locator, git+@, in both exports, and an unpinned one stays a plain URL in CycloneDX. ADR-0049 records the decision and why the SHA-1 hash of a pinned action stays beside the locator. Requires the bomly-sdk release that carries bomly-dev/bomly-sdk#115; the pin bump follows that tag. Refs #508. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01VUD8N7Sz1FkMYsYadadYnu --- ...igin-is-one-vcs-locator-in-every-export.md | 72 +++++++++++++++++++ dev-docs/adr/README.md | 1 + docs/SBOM.md | 11 ++- internal/cli/scan_cmd.go | 24 ++++++- internal/cli/scan_cmd_test.go | 27 +++++++ 5 files changed, 131 insertions(+), 4 deletions(-) create mode 100644 dev-docs/adr/0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md 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..28c634d0 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: 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 From e41b8536959f00eadd38f36874fdf6173baf43c7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 05:17:13 +0000 Subject: [PATCH 2/4] build(deps): bump bomly-sdk to v0.14.9 The release carries bomly-dev/bomly-sdk#115: ProjectRoot.Description and the shared VCS locator this branch depends on. make generate produced no docs drift. Refs #508. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01VUD8N7Sz1FkMYsYadadYnu --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index eab4eeec..c6aa4b90 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.9 github.com/charmbracelet/bubbles v1.0.0 github.com/charmbracelet/bubbletea v1.3.10 github.com/charmbracelet/lipgloss v1.1.0 diff --git a/go.sum b/go.sum index 411edc22..bf0663a2 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.9 h1:5ZJzpNsF9cUPeXkUqfIvRabkVzB7xut29OfgrS2r+IY= +github.com/bomly-dev/bomly-sdk v0.14.9/go.mod h1:B/km/swnrS1Tblgpv+5hpVdWHJjyaY5BFdF1cUS38C0= 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= From 191ee531fa7e2aad3c34c547dc29415fbd3881b2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 05:23:40 +0000 Subject: [PATCH 3/4] build(deps): bump bomly-sdk to v0.14.10 The release follows v0.14.9 with the SDK's dependency bumps, among them github.com/github/go-spdx/v2 v2.7.1, which this module now resolves as well. make generate produced no docs drift. Refs #508. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01VUD8N7Sz1FkMYsYadadYnu --- go.mod | 4 ++-- go.sum | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/go.mod b/go.mod index c6aa4b90..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.9 + 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 bf0663a2..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.9 h1:5ZJzpNsF9cUPeXkUqfIvRabkVzB7xut29OfgrS2r+IY= -github.com/bomly-dev/bomly-sdk v0.14.9/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= From 081c6c481990e42f3b862cb329a67bcc061057bb Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 05:24:39 +0000 Subject: [PATCH 4/4] docs(sbom): the origin section no longer calls SPDX the only home of a revision One sentence in the origin-validation paragraph still said the SPDX locator was the only place a revision appears, contradicting the table above it now that CycloneDX writes the same locator for a pinned repository. Refs #508. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01VUD8N7Sz1FkMYsYadadYnu --- docs/SBOM.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/SBOM.md b/docs/SBOM.md index 28c634d0..9eb9b49e 100644 --- a/docs/SBOM.md +++ b/docs/SBOM.md @@ -311,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