A complete and accurate inventory of all first-party and third-party components is essential for risk identification. A Software Bill of Materials (SBOM) is a document that provides transparency into the software components of an application.
SBOMs should ideally contain all direct and transitive components and the dependency relationships between them. They should also contain metadata associated with each of these components.
For software producers
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 sometimes 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 vulnerabilities and how they impact an application they sell.
Software consumers, or those who use software, need to understand their software inventory holistically. This includes both the software that they create and the software that they purchase.
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.
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.
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-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:
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.
2 - Import SBOMs
Learn more about software transparency and the role of importing SBOMs in your organization.
Software consumers, or those who use software, need to understand their software inventory holistically. This includes both the software that they create and the software that they purchase. For the software that a software consumer procures, they can request an SBOM to get visibility into the software composition of what they deploy in their environment.
If an information security analyst on your team sends a mass email to all your vendors asking them to provide SBOMs, you are likely to get some combination of confused replies, refusals to hand over anything, and a few incredibly detailed json and XML files. An inbox full of attachments is not the correct way to manage information. Storing these SBOMs in platforms like Google Drive, Dropbox, or any other information repository without active utilization will yield minimal benefits.
Endor Labs’ SBOM hub ingests, parses, analyzes, and tracks your vendor’s SBOMs and offers a structured method to track and version control every SBOM.
SBOM Hub
SBOM Hub is a central location for software consumers to store, search, and monitor their SBOMs. If you are building out an SBOM program you should visit our blog on Key questions for your SBOM program to learn more about SBOM best practices and program management.
You can use Endor Labs finding policies to identify vulnerabilities, unmaintained open source software, license risk and outdated dependencies in the SBOMs provided to you by your third-party software vendors.
Import an SBOM to Endor Labs
Once you have an SBOM from one of your third-party vendors, you should import the SBOM into Endor Labs to monitor and manage it.
Import SBOMs through the Endor Labs UI
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.
Click SBOM Hub on the left-hand side navigation menu.
Click Import SBOM in the top right-hand corner.
Choose Upload File and select the type of SBOM you would like to upload.
Use SPDX if your vendor has provided you with a SPDX format SBOM
Click Browse to upload your SBOM from your workstation or drag the SBOM into the Endor Labs UI.
Once you have imported your SBOM to Endor Labs, Endor Labs will schedule a scan in the background for the SBOM within the next few hours. To instantly scan the SBOM see Importing SBOMs through the Endor Labs CLI
Tip
Endor Labs supports CycloneDX or SPDX format SBOMs in XML or json format.
Import SBOMs through the Endor Labs CLI
To import an SBOM to Endor Labs with automation or using the CLI use the following command:
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.
Tagging strategies for SBOMs
To improve your team’s ability to search and manage SBOMs, you can tag them as they are received. Tagging SBOMs helps your team understand the applications, vendors, and their importance to your business.
Use Case
Rationale
Example Tags
Data Classification
Understand the kind of data a vendor or vendor application handles for you.
