Export SBOMs and VEX

Learn more about software transparency and the role of SBOMs in your organization.

Software producers, those who create and sell software, need to be able to provide software transparency through an SBOM to their customers on request to reduce sales cycles, establish trust and in some cases as a regulatory or business requirement.

A Vulnerability Exploitability eXchange (VEX) document conveys the potential risks associated with components that have known vulnerabilities within the specific context of the product.

Software producers may need to, upon request, provide justification for known vulnerabilties and how they impact an application they sell.

How to export an SBOM

To export an SBOM you’ll need to have first performed a successful open-source scan. If you haven’t successfully scanned a project see our quick start for more information.

Export an SBOM through the Endor Labs UI

To export an SBOM for a package version in the Endor Labs UI:

  1. Navigate to My Packages and search for the package name in the Search filter.
  2. Select the version to create an SBOM
  3. Click Export Data in the top right-hand corner.
  4. Select the container format.
  5. Select the output format and type of SBOM you would like to generate and click Export SBOM. A file containing the SBOM will download from your browser.
  6. Click Export VEX to generate a Vulnerability Exchange (VEX) file for the package version.

Export an SBOM through the API using endorctl

To export an SBOM you will need the package version name for which you’d like to create an SBOM or its UUID.

Pass the package name or UUID to the command endorctl sbom export using the --package-version-name or --uuid flags.

To get the package version name through the API and export an SBOM you must first find the package version name through the API.

You can easily export a reference package name and the scanned version you’d like to export as environment variables.

export PACKAGE_NAME=<insert_package_name>
export VERSION=<insert_package_version>

Then query the API for the package version name and set this as an environment variable:

export PACKAGE_VERSION_NAME=$(endorctl api list -r PackageVersion --filter "meta.name matches $PACKAGE_NAME AND meta.name matches $VERSION" --field-mask=meta.name | jq -r ".list.objects[].meta.name")

Use this name to export an SBOM using endorctl.

endorctl sbom export --package-version-name=$PACKAGE_VERSION_NAME >> cyclonedx.json

To export the SBOM as a library rather than an application use the flag --component-type=library:

endorctl sbom export --component-type=library --package-version-name=$PACKAGE_VERSION_NAME >> cyclonedx.json

To export the SBOM in XML format rather than json use the --output-format flag with the XML parameter:

endorctl sbom export --output-format=xml --package-version-name=$PACKAGE_VERSION_NAME >> cyclonedx.xml

How to export a VEX Document

You can export an SBOM through the API using endorctl or through the Endor Labs user interface.

Import an SBOM into Endor Labs

Import your project’s SBOM into the Endor Labs application to discover vulnerabilities and view findings. You can either upload the file from the user interface or through endorctl.

  1. Click SBOM Hub on the left-hand side navigation menu.
  2. Click Import SBOM in the top right-hand corner.
  3. Choose Upload File to upload a CycloneDX SBOM file in JSON or XML format.
  4. From *Advanced, you can see the instructions to upload the file through endorctl. After initializing endorctl, use the following command to upload the SBOM.
endorctl sbom import --sbom-file-path <path_to_sbom_file>

Manage SBOMs

Manage the SBOMs on the Endor Labs application.

  • Delete SBOM - Select one or more SBOMs, click the vertical ellipsis at the right side and click Delete SBOM.
  • Include Tags for an SBOM - Select one or more SBOMs and click Edit Tags on the top right-hand corner. Tags are labels or keywords that you can use to categorize SBOMs. They help classify and group related SBOMs, making it easier to search, filter, and manage the SBOMs. Tags can have a maximum of 63 characters and can contain letters A-Z, numbers (0-9), or any of (=@_.-) special characters.