Track several versions of a product
When a product has maintenance branches next to its main one (main ships 3.x while release/2.4
still gets security fixes), upload each branch to its own version of the same project. Each
version keeps its own components, findings and triage, so a dependency fixed on main still
shows as vulnerable on the branch that ships the old one. How versions work is explained in
Concepts; the parameters are in the
upload API reference.
Name the version in the upload
Add version to the upload URL. The first upload naming a version creates it, with the open and
ignored findings of the latest version, so a release branch starts with the triage already done
on main.
curl --fail-with-body --silent --show-error \
--request PUT \
--header "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
"$NANOBOM_URL/api/organizations/acme/projects/web/sbom?version=$BRANCH&fail_on=high"
- A version name is 1 to 64 letters, digits,
.,_,+,/or-, and is case-sensitive:release/2.4and2.4.xare fine; a name with a space is refused with a422. Encode/as%2Fand+as%2Bin the URL. - Name a version after something that lasts: a release branch or a release line. A build number or a commit hash creates a new version at every build; past 50 active versions, each new one makes the version uploaded to the longest ago inactive (the cap).
- Projects that never name a version keep their single, unnamed version: nothing changes for
them. Uploads without
versionkeep going to the unnamed version.
Keep the latest version on the main branch
The latest version is the one the project page, the read API and the VEX export show when
they are not asked for another. A version an upload creates becomes the latest, which is right
for the branch that will ship next, and wrong for a maintenance branch. Upload maintenance
branches with latest=false:
name: SBOM
on:
push:
branches: [main, "release/**"]
jobs:
sbom:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7.0.1
# Writes sbom.json: see Generate an SBOM.
- run: cargo install cargo-cyclonedx --locked && cargo cyclonedx --format json --override-filename sbom
- name: Upload the SBOM
env:
NANOBOM_URL: ${{ vars.NANOBOM_URL }}
NANOBOM_TOKEN: ${{ secrets.NANOBOM_TOKEN }}
VERSION: ${{ github.ref_name }}
LATEST: ${{ github.ref_name == 'main' }}
run: |
VERSION=$(printf %s "$VERSION" | sed 's|/|%2F|g; s|+|%2B|g')
curl --fail-with-body --silent --show-error \
--request PUT \
--header "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
"$NANOBOM_URL/api/organizations/acme/projects/web/sbom?version=$VERSION&latest=$LATEST&fail_on=high"
Uploads from main keep the main version latest (latest=true), and uploads from
release/2.4 go to the release/2.4 version without taking the flag (latest=false). The
workflow runs on the main and release branches only: on pull request branches, ref_name would
create a version per branch.
To version by release line rather than by branch, send the line instead: version=2.4 from
every v2.4.* tag.
Read one version
-
On the project page, the Version field of the filters shows the latest version by default; choose another and select Filter. The other filters are sent with it, so they stay as they are. The findings, the summary of open findings, the license violations, the component count and the Export VEX button follow the version shown. The upload history lists every upload of the project, with its version.
-
With the read API, add
versionto the findings, components and license violations endpoints, and list the versions with/versions(reference):curl --silent --header "Authorization: Bearer $NANOBOM_TOKEN" \ "$NANOBOM_URL/api/organizations/acme/projects/web/findings?version=release%2F2.4" -
VEX documents are exported from and imported into one version with the same parameter (VEX API).
Compare a vulnerability across versions
Open a finding: Versions of this project lists every version of the project, newest first,
with where it stands with that vulnerability (open, ignored, fixed or not affected, aliases
included) and a link to its finding. Use it to see which releases still need a fix. The read
API’s finding has the same list in versions
(reference).
The component search lists a package once per version that has it, with the version’s name.
Retire a version
When a release is no longer supported, make its version inactive rather than deleting it: runs stop checking it, and it no longer counts on the organization page, shows up in searches or sends notifications, while its findings and triage stay readable and exportable (what changes).
- Open the project page; the Versions table lists every version with its open findings.
- Select Make inactive on the version’s row. The latest version has no such button: make another version latest first.
The project page shows an inactive version on request, marked inactive. To check it again, select Make active: a run starts at once. An upload to an inactive version also makes it active again.
These buttons, and the ones below, are for organization admins and owners.
Change the latest version
Select Make latest on the version’s row. Pipelines usually keep the flag where it belongs
(latest=true from the main branch); use the button to fix it after a wrong upload, or when
the main line moves to another version without an upload yet. An inactive version cannot be the
latest: make it active first.
Delete a version
Deleting a version deletes its components, upload history and findings, with their triage and history, for good; other versions keep what they inherited from it. To keep the history, make the version inactive instead.
- On the version’s row, select Delete.
- Tick the box confirming what is deleted, and select Delete version.
The latest version cannot be deleted (make another one latest first), nor the only version of a project: delete the project instead.
What to expect
- The gate judges the version uploaded.
fail_oncounts the findings of the version the upload went to, not those of the other versions: a release branch fails on its own vulnerabilities only. - Triage is per version. Ignoring a finding in
release/2.4does not ignore it inmain. Versions created later inherit the ignores of the latest version at the time. - Notifications are per vulnerability. A new advisory against a dependency several versions share is announced once, with the list of the versions it affects; findings a new version inherits are never announced (payloads).
- Counts are per issue. The organization page counts a vulnerability of a package once per project, at its highest severity, however many active versions have it.
- Dependency-Track clients already send a version:
projectVersionis the version, andisLatestthe latest flag (Upload with Dependency-Track clients).