Export SBOMs and VEX

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

To export an SBOM you must first perform a successful endorctl scan. If you haven’t successfully scanned a project see quick start for more information.

Endor Labs supports export in the CycloneDX format and the VEX format.

Export an SBOM through the Endor Labs user interface

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

  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 SBOM 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 SBOM through endorctl

You can export SBOM of a specific or multiple package versions with endorctl.

You can use the following options with the SBOM export command.

Flag Environment Variable Description
component-type ENDOR_SBOM_COMPONENT_TYPE Set the SBOM component type (application, or library). (default application)
output-format ENDOR_SBOM_OUTPUT_FORMAT Set the SBOM format (json, or xml) (default json).
package-version-name ENDOR_SBOM_PACKAGE_VERSION_NAME Name of the package version for which you want to generate an SBOM.
package-version-uuid ENDOR_SBOM_PACKAGE_VERSION_UUID The UUID of the package version for which you want to generate an SBOM.
timeout ENDOR_SBOM_TIMEOUT Set the timeout for the SBOM generation (default 30s).
with-vex ENDOR_SBOM_WITH_VEX Generate the corresponding VEX document along with the SBOM.
project-uuid ENDOR_SBOM_PROJECT_UUID The UUID of the project for which you want to generate an SBOM.
project-name ENDOR_SBOM_PROJECT_NAME Name of the project for which you want to generate an SBOM.
app-name ENDOR_SBOM_APP_NAME Name of the application/library. Required for multi-package SBOM export.
package-version-uuids ENDOR_SBOM_PACKAGE_VERSION_UUIDS The list of package version UUIDs to export an SBOM.

To export an SBOM you will need the package version name for which you’d like to create an SBOM or its UUID. You can also export an SBOM with multiple package versions. To export an SBOM with multiple package versions, you need the package version UUIDs or the project name.

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

To export an SBOM, you must first retrieve 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 multiple package versions in an SBOM, you need the UUIDs of package versions, or the name or UUID of the project to which the package versions belong.

To create an SBOM based on project details, either provide the project UUID with the --project-uuid flag or the project name with the --project-name flag. You also need to provide a name for the package with the --app-name flag.

Run the following command to create an SBOM with multiple package versions with the project UUID.

endorctl sbom export -n test --project-uuid=<Project UUID> --app-name=<Application Name> >> <SBOM Name>.json

For example:

endorctl sbom export -n test --project-uuid=66e345c340669666c22979d6 --app-name=actions-hu/app-java-demo >> cycloneDx-sbom.json

Run the following command to create an SBOM with multiple package versions with the project name.

endorctl sbom export -n test --project-name=<Project Name> --app-name=<Application Name> >> <SBOM Name>.json

For example:

endorctl sbom export -n test --project-name=actions-hu/app-java-demo --app-name=actions-hu/app-java-demo >> cycloneDx-sbom.json

To generate an SBOM based on package version UUIDs, provide the package version UUIDs with the --package-version-uuids flag. You also need to provide a name for the package with the --app-name flag.

endorctl sbom export -n test --package-version-uuids=<Package Version UUID 1>,<Package Version UUID 2>,... <Package Version UUID N> --app-name=<Application Name> >> <SBOM Name>.json

For example:

endorctl sbom export -n test --package-version-uuids=66e345c340669666c22979d6,89f456c340669666c229854a,43a56b1340669666c289d4a2 --app-name=actions-hu/app-java-demo >> cycloneDx-sbom.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

To export a VEX document use the flag --with-vex

endorctl sbom export --with-vex

Endor Labs Export Formats

Endor Labs provides the following fields to map to the NTIA minimum elements of an SBOM standard.

CycloneDX Format

Endor Labs supports export in the CycloneDX format.

The following table lists the mandatory and some optional fields in the SBOM file that Endor Labs exports.

Field Description
bomFormat Specifies the format of the SBOM. Required.
specVersion The version of the specification used (for example, “1.4”). Required.
serialNumber A unique identifier for the SBOM document. Optional.
version The revision number of the SBOM. Required.
metadata Contains metadata about the SBOM and primary component. Optional.
metadata.timestamp The date and time when the SBOM was generated. Optional.
metadata.component Information about the main component described by the SBOM. Optional.
metadata.component.bom-ref A reference identifier for the component within the BOM. Optional.
metadata.component.type The type of the main component (for example, “application” or “library”). Optional.
metadata.component.name The name of the main component. Optional.
metadata.component.version The version of the main component. Optional.
metadata.component.hashes Cryptographic hashes of the main component. Optional.
metadata.component.purl The Package URL (purl) for the main component. Optional.
metadata.supplier Information about the supplier of the software. Optional.
metadata.supplier.name The name of the supplier. Optional.
metadata.supplier.url URLs associated with the supplier. Optional.
metadata.supplier.contact Contact information for the supplier. Optional.
metadata.licenses License information for the main component. Optional.
components List of software components included in the SBOM. Required.
components[].bom-ref A reference identifier for each component within the BOM. Optional.
components[].type The type of each component (for example, “library”). Required.
components[].name The name of each component. Required.
components[].version The version of each component. Optional.
components[].licenses License information for each component. Optional.
components[].licenses[].license.name The name of the license. Optional.
components[].purl The Package URL (purl) for each component. Optional.
components[].externalReferences External references for components. Optional.
components[].externalReferences[].url The URL of the external reference. Optional.
components[].externalReferences[].type The type of the external reference (for example, “vcs”). Optional.
dependencies Describes the relationships between components. Optional.
dependencies[].ref Reference to a component in the dependency relationship. Optional.
dependencies[].dependsOn List of components that this component depends on. Optional.

VEX Format

The following table lists the mandatory and some optional fields in the VEX file that Endor Labs exports.

Field Description
bomFormat Specifies the format of the VEX document. Required.
specVersion The version of the specification used. Required.
serialNumber A unique identifier for the VEX document. Required.
version The revision number of the VEX document. Required.
metadata Contains metadata about the VEX document and primary component. Required.
metadata.timestamp The date and time when the VEX document was generated. Required.
metadata.tools Information about tools used to generate the VEX document. Required.
metadata.tools.services List of services used in generating the VEX document. Required.
metadata.tools.services[].provider Information about the provider of the service. Required.
metadata.tools.services[].provider.name The name of the service provider. Required.
metadata.tools.services[].provider.url URLs associated with the service provider. Required.
metadata.tools.services[].name The name of the service. Required.
metadata.tools.services[].version The version of the service. Required.
metadata.tools.services[].description A description of the service. Required.
metadata.component Information about the main component described by the VEX document. Required.
metadata.component.bom-ref A reference identifier for the component within the VEX. Required.
metadata.component.type The type of the main component. Required.
metadata.component.name The name of the main component. Required.
metadata.component.version The version of the main component. Required.
metadata.component.hashes Cryptographic hashes of the main component. Required.
metadata.component.purl The Package URL (purl) for the main component. Required.
vulnerabilities List of vulnerabilities associated with the component. Required.
vulnerabilities[].id The identifier of the vulnerability. Optional.
vulnerabilities[].references References related to the vulnerability. Optional.
vulnerabilities[].references[].source.url URL of the reference source. Optional.
vulnerabilities[].ratings Severity ratings for the vulnerability. Optional.
vulnerabilities[].ratings[].score Numerical score of the severity. Optional.
vulnerabilities[].ratings[].severity Textual representation of the severity. Optional.
vulnerabilities[].ratings[].method The method used for rating (for example, “CVSSv3”). Optional.
vulnerabilities[].ratings[].vector The vector string for the rating. Optional.
vulnerabilities[].cwes Common Weakness Enumeration (CWE) identifiers. Optional.
vulnerabilities[].description A description of the vulnerability. Optional.
vulnerabilities[].detail Detailed information about the vulnerability. Optional.
vulnerabilities[].recommendation Recommended actions to address the vulnerability. Optional.
vulnerabilities[].advisories List of advisories related to the vulnerability. Optional.
vulnerabilities[].advisories[].url URL of the advisory. Optional.
vulnerabilities[].published The date when the vulnerability was published. Optional.
vulnerabilities[].updated The date when the vulnerability information was last updated. Optional.
vulnerabilities[].credits Credits for individuals or organizations related to the vulnerability. Optional.
vulnerabilities[].credits.individuals List of individuals credited. Optional.
vulnerabilities[].analysis Analysis of the vulnerability’s impact on the component. Optional.
vulnerabilities[].analysis.state The state of the analysis (for example, not_affected). Optional.
vulnerabilities[].analysis.justification Justification for the analysis state. Optional.
vulnerabilities[].affects Information about which components are affected by the vulnerability. Optional.
vulnerabilities[].affects[].ref Reference to the affected component. Optional.