Package: esp-idf-sbom
ESP-IDF SBOM Tool (esp-idf-sbom):warning:This is experimental implementation, which is subject to change without prior
notice and no backward compatibility is guaranteed.The esp-idf-sbom tool createsSoftware bill of materials(SBOM)
files in theSoftware Package Data Exchange(SPDX) format for applications
generated by theEspressif IoT Development Framework(ESP-IDF).
It also allows to check generated SBOM files for know vulnerabilities against
theNational Vulnerability Database(NVD) based on theCommon Platform Enumeration(CPE) provided in the SBOM.Required ESP-IDF versionsAll release branches of currently supported ESP-IDF versions allow to
generate the SBOM file.ESP-IDF versionbranch with SBOM supportcommits4.3release/v4.3befb32b45bc9314b48c29624f9a2c2ef30e34260f1eef50947ab5770ae4d904c07615e7acab060024.4release/v4.4ee505a996045c3657711c3d70c58af8dd48b142653f271ce108d6fa99cf92d59fe9b9dcc4b8fb45b5.0release/v5.030735b33efabd6cf038bcb258b674cf828ad5ecf9156bbb55c920d6704329975311c331b931ed6bc5.1release/v5.10f781c718c8548cd2b0e41a30e1814f1c6ed93a203162bb276d4155760e8aa839020f0587f5ef599latestmasterOlder versions, e.g.v5.0.2, do not have the required code merged and the following error
message will be printed.E: Project description file "build/project_description.json" does not support SBOM generation. Please see the list of IDF versions required by esp-idf-sbom.If you see this error message and want to tryesp-idf-sbom, you canswitch to the release branch for version you are using. For examplerelease/v5.0if you are usingv5.0.2.use future ESP-IDF versions to experiment with esp-idf-sbom.usegit-cherry-pickand apply commits for your release from the table above. For example forv5.0.2use$ git cherry-pick 30735b33efabd6cf038bcb258b674cf828ad5ecf 9156bbb55c920d6704329975311c331b931ed6bcInstallationCurrently esp-idf-sbom is not integrated into ESP-IDF and needs to by installed
separately from Python Package Index (PyPI) withpip install esp-idf-sbomAfter installation theesp-idf-sbomcommand should be available or the esp_idf_sbom
python module can be used withpython -m esp_idf_sbomCreating SBOMThe application has to be built before the SBOM file can be created. This step should
not be required in the future once esp-idf-sbom is integrated into ESP-IDF.The SBOM file can be created withesp-idf-sbom create <project description file>Theproject description fileis a path to theproject_description.jsonfile, which
is by default created by the ESP-IDF build system in the project'sbuilddirectory.
The generated SBOM file is printed to the standard output stream by default or can be
saved in a file if the--output-fileoption is used.Checking vulnerabilitiesVulnerabilities are checked based on theCommon Platform Enumeration(CPE) information
included in the SBOM file for SPDX packages. While checking for vulnerabilities, only packages
with direct or indirect relationship to theprojectpackage are examined. For example if mbedtls
component is compiled, due to component dependecies, but it's actually not linked into the
final binary, it will be by default presented in the SBOM file, but it will not be reachable
from the rootprojectpackage and hence it will not be checked for vulnerabilities.
The reason for this is to avoid possible false positives, because such packages
have no direct impact on the resulting application. This can be changed with the--check-all-packagesoption. If used, all packages in the SBOM file will be checked for possible vulnerabilities
regardless their relationships to the application binary.SBOM file generated by the esp-idf-sbom tool can be checked for known vulnerabilities
withesp-idf-sbom check [SBOM file]IfSBOM fileis not provided, the standard input stream is used.The default report format consists of multiple tables:Report summaryPackages with identified vulnerabilitiesPackages with excluded vulnerabilitiesPackages with no identified vulnerabilitiesPackages without CPE information not applicable for vulnerability checkThe output format may be changed with the--formatoption, which supports exporting
the report intojson,csvormarkdownformat.If package is not vulnerable to a specific CVE, it can be added to the manifestcve-exclude-listlist and checker will not report it as identified vulnerability, but as excluded vulnerability.Usage exampleThis is an example of basic usage for the blink project, which is part of the ESP-IDF.
It's expected that ESP-IDF is installed and set.$ cd examples/get-started/blink/ # In esp-idf directory go to the blink example
$ idf.py build                   # Project has to be built first
$ esp-idf-sbom create -o blink.spdx build/project_description.json
$ esp-idf-sbom check blink.spdx

$ esp-idf-sbom create build/project_description.json | esp-idf-sbom checkThe resultingblink.spdxsbom file can be found in theblinkproject directory.SPDX SBOM layoutThe SBOM file is created based on application sources, build artefacts, information
provided by the ESP-IDF build system and SBOM manifest files. The resulting SBOM
file contains SPDX packages for the finalprojectapplication, usedtoolchain,componentsused during build, gitsubmodulesandsubpackages. Thesubpackagesare created based onsbom.ymlmanifest files found insubmodulesandsubpackagessub-directories or referenced manifest files. Please seeManifest file.Packages are linked together with SPDXDEPENDS_ONrelationships with theprojectpackage
as the root package. By default packages for configuration only components and components not
linked into the application are present in SBOM, but are not linked through SPDX
relationships. In other worlds dependencies on such packages are removed. This behaviour
can be altered with--add-config-depsand--add-unused-depscommand line options.Manifest fileDuring SBOM generation the esp-idf-sbom tool is looking forsbom.ymlmanifest files.
They are used as a source of information for the corresponding SPDX package in the SBOM file
as described above.The manifest file may be present at root ofproject,component,submoduleor
in any of their sub-directories. Ifsbom.ymlis found in a sub-directory a newsubpackageSPDX package is created and linked with the parent SPDX package. This can be used in cases
where e.g. onecomponentcontains multiple libraries and they should be represented
by separate SPDX packages.Example of multiplesbom.ymlfiles usage for theconsolecomponent.console
├── argtable3
│   └── sbom.yml
├── linenoise
│   └── sbom.yml
└── sbom.ymlTheesp-idf-sbomtool will create main consolecomponentpackage, which will
contain twosubpackagesforargtable3andlinenoiselibraries. Please note that
the manifest file in theconsolecomponent root directory is not necessary to create
SPDX package, becauseesp-idf-sbomautomatically creates SPDX package for eachcomponent. Thesbom.ymlfiles may be placed at any sub-directory depth andesp-idf-sbomwill create proper SPDX package hierarchy for them.Thesbom.ymlis a simple yaml file, which may contain the following entries.name:
Package name that will be used in the SPDX package.version:
Package version.description:
Short package description.repository:
Link to git repository.url:
Link to package download location.cpe:
CPE used for vulnerabilities check against NVD. This can be single CPE value or a
list of CPEs.supplier:
Package supplier. Person or organization distributing the package. Should be prefixed
withPerson:orOrganization:as described in SPDX specification.originator:
Package originator. If the package comes from another person or organization
that has been identified as a supplier. For example if a component is based
on 3rd party code with some modifications, the originator is the 3rd party code
author, but the supplier is the person or organization distributing the final
component. For more detailed information please see the SPDX specification.
As for supplier,Person:orOrganization:prefix should be used for
originator value.hash:
SHA of the directory(git-treeobject) the manifest file describes or HEAD SHA of a submodule. This value
is used during the manifest file validation to check if the hash in the manifest file matches the
SHA recorded in thegit-tree. Its purpose is to make sure that the information in the manifest
file is up-to-date. For example if a submodule or 3rd party library is updated, the
version in the manifest file should be probably updated too. The SHA value can be obtained
e.g. withgit ls-tree HEAD <path>, where<path>is a package directory, which is described by
the manifest file. Please note that a hash value for a directory, not a submodule, cannot
be placed in manifest file, which is stored within the same directory, because the directory SHA
ingit-treewill change every time the manifest file changes(chicken egg problem). To make
the hash variable work, it needs to be placed in a referenced manifest, which is not stored
within a directory it describes. For example freertos component can have mainsbom.ymlmanifest file, which refers tosbom_FreeRTOS-Kernel.ymlmanifest describing theFreeRTOS-Kernelpackage in theFreeRTOS-Kerneldirectory.components/freertos/sbom.ymlmanifests:
  - path: sbom_FreeRTOS-Kernel.yml
    dest: FreeRTOS-Kernelcomponents/freertos/sbom_FreeRTOS-Kernel.ymlname: 'freertos'
version: '10.4.3'
cpe: cpe:2.3:o:amazon:freertos:{}:*:*:*:*:*:*:*
supplier: 'Organization: Espressif Systems (Shanghai) CO LTD'
originator: 'Organization: Amazon Web Services'
description: An open-source, real-time operating system (RTOS) with additional features and patches from Espressif.
hash: 4e8101b6f57a0640ae54c6da605c1b532c0f8f89
cve-exclude-list:
  - cve: CVE-2021-43997
    reason: This vulnerability only affects ARMv7-M and ARMv8-M ports of FreeRTOS and hence does not affect Espressif SoCs which are not based on these architectures.license:
License expression explicitly declared by the author.copyright:
Copyright explicitly declared by the author. This can be single string or a
list of copyrights.cve-exclude-list:
List of already evaluated CVEs, which do not apply to this package. This can be used
to exclude CVEs from theesp-idf-sbomchecker report in case the package is not
vulnerable to specific CVEs. Each CVE in the exclude list is represented as dictionary with
thecveandreasonkeys. Information about excluded CVEs is added to the generated
SBOM file intoPackageCommentSPDX tag and later used by the checker.cve: CVE-IDreason : description why this package is not vulnerable to this CVEversion: 0.1.0
      description: Blink application example
      cve-exclude-list:
        - cve: CVE-2023-1234
          reason: Description why this package is not vulnerablemanifests:
List of manifest files which cannot be added directly into thecomponentorsubmodulesub-directories to createsubpackage. For example the following will create a new
SPDX package for thesubpackagedirectory with information from thesubpackage.ymlmanifest file.
This manifest file is treated as it would be actually stored in thesubpackagedirectoery.path: path of manifest file relatitve to the sbom.ymldest: destination directory for path, again relative to sbom.ymlversion: 0.1.0
      description: Blink application example
      manifests:
        - path: subpackage.yml
          dest: subpackageExample of thesbom.ymlmanifest file for the ESP-IDF blink project.version: 0.1.0
description: Blink application example
url: https://blink.org/blink-0.1.0.tar.gz # non-existing package download URL example
cpe: cpe:2.3:a:hrbata:blink:{}:*:*:*:*:*:*:* # non-existing CPE example
supplier: 'Person: Frantisek Hrbata (frantisek.hrbata@espressif.com)'
originator: 'Organization: Espressif Systems (Shanghai) CO LTD'
cve-exclude-list:
   - cve: CVE-2023-1234
     reason: Description why this package is not vulnerable
   - cve: CVE-2023-1235
     reason: Description why this package is not vulnerableInformation from thesbom.ymlmanifest file are mapped to the following SPDX tags.manifestSPDXnamePackageNameversionPackageVersiondescriptionPackageSummaryrepositoryExternalRef OTHER repositoryurlPackageDownloadLocationcpeExternalRef cpe23TypesupplierPackageSupplieroriginatorPackageOriginatorlicensePackageLicenseDeclaredcopyrightPackageCopyrightTextcve-exclude-listPackageCommentEven though thesbom.ymlfile is the primary source of information, the esp-idf-sbom tool
is also looking at other places if it's not present. Theidf_component.ymlmanifest file,
used for components managed by the component manager, may containsbomdictionary/namespace,
which will be used by esp-idf-sbom if presented. This dictionary may contain the same information
assbom.yml.Example of theidf_component.ymlmanifest file for led_strip managed component.dependencies:
  idf:
    version: '>=5.0'
description: Driver for Addressable LED Strip (WS2812, etc)
url: https://github.com/espressif/idf-extra-components/tree/master/led_strip
version: 2.4.1
sbom:
  cpe: cpe:2.3:a:hrbata:led_strip:{}:*:*:*:*:*:*:* # non-existing CPE example
  supplier: 'Organization: Espressif Systems (Shanghai) CO LTD'
  cve-exclude-list:
     - cve: CVE-2023-1234
       reason: Description why this package is not vulnerable
     - cve: CVE-2023-1235
       reason: Description why this package is not vulnerableIf thesbomdictionary is not presented inidf_component.ymlor it's missing some information,
the version, description, maintainers and url information fromidf_component.ymlmanifest is used.Information from theidf_component.ymlmanifest file are mapped to the following SPDX tags.manifestSPDXnamePackageNameversionPackageVersiondescriptionPackageSummarymaintainersPackageSupplierurlPackageDownloadLocationComponent version may be guessed based on git-describe and Espressif
as a default supplier may be guessed based on git repository or package URL. The guessing
may be disabled by using the '--no-guess' option.For git submodules, the.gitmodulesconfiguration file is also checked for additional submodule
information. Submodule configuration may contain variables with thesbom-prefix, which are considered as
SBOM manifest information. All keys used in thesbom.ymlmanifest file can also be specified in.gitmoduleswith thegit-configformat instead of yaml.Example of manifest information added for themicro-eccsubmodule in.gitmodules.[submodule "components/bootloader/subproject/components/micro-ecc/micro-ecc"]
        path = components/bootloader/subproject/components/micro-ecc/micro-ecc
        url = ../../kmackay/micro-ecc.git
        sbom-version = 1.0
        sbom-cpe = cpe:2.3:a:micro-ecc_project:micro-ecc:{}:*:*:*:*:*:*:*
        sbom-supplier = Person: Ken MacKay
        sbom-url = https://github.com/kmackay/micro-ecc
        sbom-description = A small and fast ECDH and ECDSA implementation for 8-bit, 32-bit, and 64-bit processors
        sbom-hash = d037ec89546fad14b5c4d5456c2e23a71e554966
        sbom-cve-exclude-list = CVE-2023-1234 Description why this package is not vulnerable
        sbom-cve-exclude-list = CVE-2023-1235 Description why this package is not vulnerableManifest information is gathered in the following order and only missing
values are added. If e.g.versionis found insbom.ymlany otherversionvalue found e.g. in.gitmodulesis ignored.referenced manifest from parent packagesbom.ymlsbomdictionary/namespace inidf_component.ymlsbom information contained in submodule configuration in.gitmodulesidf_component.ymlinformation provided for component managerValidating manifest filesManifest files are validated while the SBOM is generated. They can be also validated explicitly
with theesp-idf-sbom manifest validatecommand.esp-idf-sbom manifest validate [PATH_TO_VALIDATE...]PATH_TO_VALIDATEis an optional path to a manifest file(sbom.yml, idf_manifest.yml or .gitmodules) or
directory, which will be searched for manifest files. IfPATH_TO_VALIDATEis not provided, the current
working directory is used.Usage example:$ esp-idf-sbom manifest validate ~/work/esp-idf ~/work/idf-extra-components/
$ esp-idf-sbom manifest validate ~/work/esp-idf/.gitmodules ~/work/esp-idf/components/freertos/FreeRTOS-Kernel/sbom.ymlChecking manifest files for vulnerabilitiesTheesp-idf-sbomtool uses the generated SBOM SPDX file to check for possible vulnerabilities.
It also allows to scan for vulnerabilities based on the information presented in manifest
files. This can be used e.g. to scan a whole repository without a need to generate the SBOM SPDX file.esp-idf-sbom validate-submodule-hash [PATH_TO_CHECK...]PATH_TO_CHECKis an optional path to a manifest file(sbom.yml, idf_manifest.yml or .gitmodules) or
directory, which will be searched for manifest files. IfPATH_TO_CHECKis not provided, the current
working directory is used.Usage example:$ esp-idf-sbom manifest check ~/work/esp-idf ~/work/idf-extra-components/
$ esp-idf-sbom manifest check ~/work/esp-idf/.gitmodules ~/work/esp-idf/components/freertos/FreeRTOS-Kernel/sbom.ymlLicenses and CopyrightsAdding licenses and copyrights information into the SBOM file has to be explicitly
requested by using the--file-tagsoption. This requires to scan all files and
may take some time. It also may result in a quite big SBOM file.Allcomponentandsubmodulefiles are scanned for theSPDX-License-Identifier,SPDX-FileCopyrightTextandSPDX-FileContributorSPDX file tags. Information from
these tags is used in the generated SBOM file to specify licenses and copyrights for
SPDX packages which representproject,componentorsubmodule. The project's
final license expression is a logical AND of all licenses concluded fromcomponentsandsubmodulesused in the final project binary.The license can be also explicitly declared by the author in thesbom.ymlfile with thelicensevariable. This information is used as a value for thePackageLicenseDeclaredSPDX tag for
givenproject,componentorsubmodule.Return Values0:
No error, no vulnerability found, manifest file(s) valid.1:
Vulnerability found or manifest file not valid.128:
Fatal error.