Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.4 and 2.4.x are fine; a name with a space is refused with a 422. Encode / as %2F and + as %2B in 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 version keep 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 version to 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).

  1. Open the project page; the Versions table lists every version with its open findings.
  2. 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.

  1. On the version’s row, select Delete.
  2. 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_on counts 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.4 does not ignore it in main. 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: projectVersion is the version, and isLatest the latest flag (Upload with Dependency-Track clients).