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

When you export an SBOM at the project level, it includes all the packages in the project and all the package versions. This allows you to combine the SBOMs of multiple packages and versions into a single SBOM. A consolidated SBOM for the project enables quick identification and assessment of vulnerabilities across all software components.

Navigate to Projects.
Select the project for which to create an SBOM.
Click Export SBOM in the top right-hand corner.
Select the container format.

Currently, you can export in the CycloneDX format.
Choose whether to export as an application or a library.

If you choose to export as an application, enter an application name.
Select the output format and type of SBOM you would like to generate.
Click Add More to select the packages and package versions you want to include in the SBOM.

If you do not select specific packages, the SBOM will include information for all packages and package versions.

You can filter by ecosystem to select the type of packages to include in the SBOM.

You can also search and select multiple package versions of the same package.
Click Export SBOM.

A file containing the SBOM will download from your browser.
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.

Feedback

Was this page helpful?

Thanks for the feedback. Write to us at support@endor.ai to tell us more.