Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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+<url>@<revision>`. 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+<url>@<revision>`, 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 `@<revision>` 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.
1 change: 1 addition & 0 deletions dev-docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
17 changes: 11 additions & 6 deletions docs/SBOM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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+<url>`, with `@<revision>` 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+<url>`, with `@<revision>` when present; `sourceInfo` when a download location is already taken by an artifact | `vcs` external reference: `git+<url>@<revision>` 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+<url>@<revision>`, 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.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

What each ecosystem yields:

Expand Down Expand Up @@ -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+<url>@<revision>` locator form, which is the only place a revision
appears.
built-in detector. Both formats then compose the validated repository URL
into the `git+<url>@<revision>` locator form when a revision is recorded;
CycloneDX keeps the plain URL when none is.

### Document identity

Expand Down
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
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
Comment thread
bomly-guy marked this conversation as resolved.
Resolved
github.com/charmbracelet/bubbles v1.0.0
github.com/charmbracelet/bubbletea v1.3.10
github.com/charmbracelet/lipgloss v1.1.0
Expand Down Expand Up @@ -157,7 +157,7 @@
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
Expand Down
8 changes: 4 additions & 4 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -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=
Expand Down Expand Up @@ -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=
Expand Down
24 changes: 23 additions & 1 deletion internal/cli/scan_cmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 27 additions & 0 deletions internal/cli/scan_cmd_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading