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.- SBOM export
- VEX export
- Select Projects from the left sidebar and select the project for which you want to export the SBOM.
- Click Export, then select SBOM.
- 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.
- Select CycloneDX or SPDX in Format.
- Select Application or Library in Artifact type. If you select Application, enter a name in Application Name.
-
Select the output format in File format.
- CycloneDX supports JSON or XML.
- SPDX supports JSON or Tag-Value.
- Optionally, select Include test dependencies to include test and other non-production dependencies in the SBOM. By default, Endor Labs excludes test dependencies.
- Click Export.
- Select Reports from the left sidebar.
- Find the SBOM export job in the list and click View.
- Click the three vertical dots and select Download to download the SBOM.
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.- Select Findings from the left sidebar.
- 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.- Select Discover from the left sidebar.
- Search and select an open source package.
- Select a package version to view its details.
- 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 theAsyncJob 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.
--output-format with the XML parameter.
--with-vex
--spec-version.
--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 setsvulnerabilities[].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.