Skip to main content
Exporting an SBOM gives you a standardized, portable inventory of a project’s or package version’s components that you can share with customers, auditors, or other tools, independent of Endor Labs. A VEX export adds vulnerability exploitability status for those components, so recipients know which findings actually apply. 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, VEX format, and SPDX format. Endor Labs renders CycloneDX documents, including VEX documents, in specification version 1.5, 1.6, or 1.7, and renders SPDX documents in specification version 2.3. Endor Labs uses CycloneDX 1.5 and SPDX 2.3 by default.

Export SBOM or VEX through the Endor Labs user interface

You can export an SBOM or VEX document for a project, a package version, or from a finding.

Export SBOM or VEX for a project

When you export an SBOM or VEX at the project level, Endor Labs includes all packages and package versions by default, combining them into a single consolidated file. A consolidated SBOM or VEX enables quick identification and assessment of vulnerabilities across all software components in the project. Endor Labs generates SBOM and VEX exports as background jobs. Start an export from a project, then track its progress and download the file from the Reports page once the job succeeds.
  1. Select Projects from the left sidebar and select the project for which you want to export the SBOM.
  2. Click Export, then select SBOM.
  3. Under Packages, select the packages and package versions to include in the SBOM and click Confirm. If you don’t select any packages, Endor Labs includes all packages and package versions. You can filter by ecosystem to narrow the list of packages, and search to select multiple versions of the same package.
  4. Select CycloneDX or SPDX in Format.
  5. Select Application or Library in Artifact type. If you select Application, enter a name in Application Name.
  6. Select the output format in File format.
    • CycloneDX supports JSON or XML.
    • SPDX supports JSON or Tag-Value.
  7. Optionally, select Include test dependencies to include test and other non-production dependencies in the SBOM. By default, Endor Labs excludes test dependencies.
  8. Click Export.
Endor Labs submits the SBOM export as a background job and shows a confirmation message. Select View Reports in the confirmation message to track the job status and download the SBOM once it completes.You can also track the job status and download the SBOM once it completes by following these steps:
  1. Select Reports from the left sidebar.
  2. Find the SBOM export job in the list and click View.
  3. Click the three vertical dots and select Download to download the SBOM.
See Reports for more information about report statuses and downloading reports.

Export SBOM or VEX from findings

When you export an SBOM or VEX for findings, Endor Labs scopes the export to the project you select and includes all its packages and package versions by default, combining them into a single consolidated file. This lets you generate a consolidated SBOM or VEX for a project directly from its findings.
  1. Select Findings from the left sidebar.
  2. In the Project column, click the name of the project you want to export, then select Export SBOM or Export VEX.

Export SBOM or VEX for a package version

When you export an SBOM or VEX for a package version, Endor Labs scopes the export to the package version you select and includes all its dependencies by default, combining them into a single consolidated file. This lets you generate a consolidated SBOM or VEX for a package version directly from its dependencies.
  1. Select Discover from the left sidebar.
  2. Search and select an open source package.
  3. Select a package version to view its details.
  4. Click Export, then select SBOM or VEX. See Export an SBOM or VEX for a package version for more information about selecting packages, choosing a format, and completing the export.

Export an SBOM or VEX through the REST API

Endor Labs generates SBOM and VEX exports through the AsyncJob resource. This lets you export SBOMs and VEX documents for large projects without the request timing out.
1

Submit an export job

Submit an export job with POST /v1/namespaces/{namespace}/async-jobs. Set spec.type to TYPE_SBOM or TYPE_VEX, and provide the export parameters in spec.request.sbom or spec.request.vex.To request a specification version, set spec.request.sbom.cyclonedx_spec_version or spec.request.sbom.spdx_spec_version for an SBOM, and spec.request.vex.cyclonedx_spec_version for a VEX document. Set the field that matches the format you export.Endor Labs returns an AsyncJob with a UUID and spec.state set to JOB_STATE_NEW.
2

Poll the job status

Poll the job with GET /v1/namespaces/{namespace}/async-jobs/{uuid} until spec.state is JOB_STATE_SUCCESS, JOB_STATE_FAILED, or JOB_STATE_CANCELLED.
3

Download the file

On success, download the file from the signed URL in spec.response.sbom.report_url or spec.response.vex.report_url.
The signed download URL expires after 5 minutes. If it expires before you download the file, call GetAsyncJob again to get a fresh URL.

Export SBOM through endorctl

You can use the following options with the SBOM export command. You can export an SBOM in CycloneDX or SPDX format using endorctl, for a single package version or across multiple package versions. To export the CycloneDX SBOM as a library rather than an application use --component-type=library.
To export the CycloneDX SBOM in XML format rather than json use --output-format with the XML parameter.
To export a VEX document use the flag --with-vex
To export a document that conforms to a specific specification version, use --spec-version.
To export the SPDX SBOM using the tag-value format instead of json, use --output-format=tag-value.
endorctl generates SBOMs in the CycloneDX format by default.

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.

Patch data in SBOM

CycloneDX SBOMs generated by Endor Labs include patch data for components that use an Endor patch. This allows consumers of the SBOM to see exactly which upstream version was patched, what changes were applied, and which vulnerabilities those patches resolve. The following fields describe how patch data appears in the exported SBOM. The following example shows a patched component in a CycloneDX SBOM.

VEX Format

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

Vulnerability analysis state

Endor Labs sets vulnerabilities[].analysis.state to not_affected with the justification code_not_reachable when reachability analysis determines that your code doesn’t reach the vulnerable function or dependency. Endor Labs doesn’t set an analysis state for any other vulnerability. Dismissing a finding doesn’t set the analysis state to not_affected. A VEX export includes every vulnerability finding in its scope, including dismissed findings. Dismissal exempts a finding from action policies in your own workflow. It isn’t an assertion that the component is unaffected, so a dismissed finding appears in the exported VEX document with the same vulnerability statement as any other finding. See Dismiss findings to learn the ways you can dismiss a finding.

SPDX Format

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