ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide ESP-IDF Programming Guide Edit on GitHub ESP-IDF Programming Guide [中文] This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S, ESP32-C, ESP32-H and ESP32-P Series SoCs. This document describes using ESP-IDF with the ESP32 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left. Get Started API Reference API Guides Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Application Startup Flow Bluetooth® Architecture Bluetooth® Classic Bluetooth® Low Energy ESP-BLE-MESH Bootloader Build System Build System v2 RF Coexistence C Support C++ Support Code Quality Core Dump Current Consumption Measurement of Modules Deep-sleep Wake Stubs Error Handling ESP-WIFI-MESH Support for External RAM Fatal Errors File System Considerations Hardware Abstraction High Priority Interrupts JTAG Debugging Project Configuration Linker Script Generation Low Power Modes lwIP Memory Types OpenThread Partition Tables Performance Reproducible Builds RF Calibration Standard I/O and Console Output Thread Local Storage Tools IDF Frontend - idf.py IDF Monitor IDF Docker Image IDF Component Manager IDF Clang-Tidy Downloadable IDF Tools IDF Size IDF SBOM Generating an SBOM File for ESP-IDF Project Checking an SBOM File for Vulnerabilities Checking Components for Vulnerabilities IDF Diag Build Standalone Files - build-file QEMU Emulator Tracing Unit Testing in ESP32 Running ESP-IDF Applications on Host Wi-Fi Driver Wi-Fi Security Wi-Fi Expansion PHY Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide API Guides Tools IDF SBOM Edit on GitHub IDF SBOM A Software Bill of Materials (SBOM) is a comprehensive inventory that identifies all the components and libraries within a software application, along with their relationships. This is essential for the software supply chain, as it enables the tracking and management of components obtained from various vendors or open-source projects. The component in an SBOM is described with information such as its name and version, among other details that may include, for example, licenses. This helps in identifying potential vulnerabilities, ensuring compliance with licensing requirements, and managing risks associated with third-party components. The minimal data fields each component must contain, according to National Telecommunications and Information Administration (NTIA), is described by The Minimum Elements for a Software Bill of Materials (SBOM). Data Field Description Supplier Name The name of an entity that creates, defines, and identifies components. Component Name Designation assigned to a unit of software defined by the original supplier. Version of the Component Identifier used by the supplier to specify a change in software from a previously identified version. Other Unique Identifiers Other identifiers that are used to identify a component, or serve as a look-up key for relevant databases. Dependency Relationship Characterizing the relationship that an upstream component X is included in software Y. Author of SBOM Data The name of the entity that creates the SBOM data for this component. Timestamp Record of the date and time of the SBOM data assembly. To generate an NTIA‑compliant SBOM file for an ESP‑IDF project, use the idf.py sbom-create command. By default, this command generates an SBOM file in the Software Package Data Exchange (SPDX) format, version 2.2. Other formats can be selected with the --format option: SPDX JSON, SPDX 3.0 JSON-LD, and CycloneDX. The generated SBOM can then be scanned for known vulnerabilities in the National Vulnerability Database (NVD) using Common Platform Enumeration (CPE) identifiers with the idf.py sbom-check command, which detects the SBOM format automatically. The idf.py sbom-create and idf.py sbom-check commands provide basic integration of the esp-idf-sbom tool into idf.py. For more detailed information, see the documentation in the esp-idf-sbom project. Generating an SBOM File for ESP-IDF Project The generated SBOM file contains information derived from the project’s build artifacts. To ensure these artifacts are up-to-date, the idf.py sbom-create command depends on the idf.py build command. If the project has not yet been built, or if source files have changed, a build is automatically triggered before the SBOM is generated. This guarantees that the resulting SBOM always accurately reflects the current state of the project. To generate a default minimal SBOM file for your project, run the following command in your project directory. $ idf.py sbom-create By default, the SBOM file is created in the build directory and named after the project, with an extension matching the selected format (.spdx for the default SPDX 2.2 tag/value format). For example, for the hello_world example project, the file will be located at build/hello_world.spdx by default. The output format is selected with the --format option, which accepts spdx-tag-value (SPDX 2.2 tag/value, the default), spdx-json (SPDX 2.2 JSON), spdx-json-ld (SPDX 3.0 JSON-LD), and cyclonedx-json (CycloneDX 1.6 JSON). The output location can be changed with the --file option (the former --spdx-file name is still accepted). For more information and additional options, see idf.py sbom-create --help. The idf.py sbom-create command generates the default SBOM file for a project. If more control is required over how the SBOM file is generated and what information it contains, refer to the esp-idf-sbom tool documentation. That documentation also provides detailed information about the component layout within the SBOM file and the manifest files used to describe components. Checking an SBOM File for Vulnerabilities The idf.py sbom-check command scans a project's SBOM file for known vulnerabilities and detects the SBOM format automatically. While this command is the primary method within ESP-IDF, you can also use any other third-party utility that supports the format you generated, such as cve-bin-tool for SPDX. To check an SBOM file for vulnerabilities, use the following syntax: $ idf.py sbom-check --file For example, to scan the SBOM file generated for the hello_world example, run: $ idf.py sbom-check --file build/hello_world.spdx By default, the idf.py sbom-check command uses a local mirror of the NVD database. You can choose between two modes of operation: Local Mirror (Default): This requires approximately 900 MB of disk space. While the initial population of the database may take some time, this method is convenient for frequent, fast, and offline scans. NVD REST API: Use the --nvd-api option to query the NVD database directly online. This is better suited for occasional or ad hoc scans where you want to avoid the disk space overhead of a local mirror. Without an API key, NVD's rate limit makes this mode slow; set the NVDAPIKEY environment variable with a free key requested from NVD to raise the limit and speed up online scans roughly 10x. idf.py sbom-check returns a non-zero exit status when any vulnerability is found, so it can be used to gate a CI pipeline. The command by default generates a report table summarizing any potential vulnerabilities found. Below is an example of a shortened report for a hypothetical project that intentionally uses an outdated version of the expat component to demonstrate the detection capabilities. For more information and additional options, see idf.py sbom-check --help. Report summary ┌───────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────┐ │ Date: │ 2024-11-13T14:20:23Z │ │ Project name: │ project-expat_test │ │ Project version: │ 6c23b9cdb268 │ │ Vulnerability database: │ NATIONAL VULNERABILITY DATABASE REST API (https://nvd.nist.gov) │ │ Generated by tool: │ esp-idf-sbom (0.19.1) │ │ Generated with command: │ esp-idf-sbom check sbom.spdx │ │ Number of scanned packages: │ 32 │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────┤ │ CRITICAL CVEs found: │ CVE-2024-45491, CVE-2024-45492 │ │ Packages affect by CRITICAL CVEs: │ libexpat │ │ Number of CRITICAL CVEs: │ 2 │ ├─────────