Generate the SBOM

A Software Bill of Materials (SBOM) lists the components shipped in a product.

MicroEJ SDK exposes the list of Managed Code artifacts embedded in the executable through a dedicated Gradle configuration. It can be used as input by any SBOM generation tool that integrates with Gradle. The sections below show how to generate the SBOM with a given tool and format. For now, only the Gradle SPDX plugin is documented, but the CycloneDX format is also supported.

Scope of the Generated SBOM

The microejSbomClasspath configuration resolves to the following components:

the application’s runtime dependencies.
the VEE Port components shipped in the executable (Architecture, Packs, runtime implementations).

It does not include:

simulator-only artifacts (Front Panel, Mocks).
test code, build tools, the SDK itself.
native C code linked by the BSP.

The resulting SBOM covers Managed Code only. For a complete product SBOM, combine it with the SBOMs of the other software parts shipped in the product (BSP, third-party native components).

Prerequisites

MicroEJ SDK 6 1.7.0 or later.
An application project, i.e. a project applying the com.microej.gradle.application plugin.
A module repository built with MicroEJ SDK 6 1.7.0 or later, which includes Maven metadata for SDK 5 modules. SBOM generation tools rely on Maven metadata, so resolving from a module repository built with an older SDK version would produce an incomplete SBOM.

Note

Modules built with MicroEJ SDK 6 1.2.0 or earlier do not include license information in their POM file. Their entries in the generated SBOM have incomplete license fields. Use module versions published with MicroEJ SDK 6 1.3.0 or later to get complete license information.

Generate an SBOM in SPDX Format

This section uses the Gradle SPDX plugin, which generates SBOMs in the SPDX format.

Configure the Gradle SPDX Plugin

Apply the SPDX plugin and declare an SBOM target that reads microejSbomClasspath in the application’s build.gradle.kts:

plugins {
    id("com.microej.gradle.application") version "1.7.0"
    id("org.spdx.sbom") version "0.11.0"
}

spdxSbom {
    targets {
        create("release") {
            configurations.set(listOf("microejSbomClasspath"))

            document {
                name.set("My Product SBOM")
                namespace.set("https://my.company.org/spdx/")
                creator.set("Organization: My Company")
                packageSupplier.set("Organization: My Company")
            }

            // Uncomment the line below to ignore SDK 5 modules
            // ignoreNonMavenDependencies.set(true)
        }
    }
}

Warning

If you must use an older module repository that does not provide Maven metadata for all modules, add ignoreNonMavenDependencies.set(true) to the SPDX target. The resulting SBOM is partial: it does not list all components shipped in the executable and does not meet CRA completeness expectations. Use this option only as a temporary workaround while migrating the module repository to SDK 6 1.7.0 or later.

Declare the Gradle Plugin Portal as a plugin repository in settings.gradle.kts so that the SPDX plugin can be resolved:

pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

Refer to the Gradle SPDX plugin documentation for the full list of configuration options, supported Gradle and JDK versions, and advanced use cases.

Generate the SBOM

To generate the SBOM for all declared targets:

./gradlew spdxSbom

To generate the SBOM for a specific target only (for example the release target declared above):

./gradlew spdxSbomForRelease

The SBOM files are written under build/spdx/ in SPDX JSON format.

Include Additional Configurations

If the application ships components that are not part of microejSbomClasspath (for example resources packaged by a custom task), add their configurations to the SBOM target:

configurations.set(listOf("microejSbomClasspath", "myExtraConfiguration"))

Integrate SBOM Generation into the Build

The steps below apply to any generator. The examples use the SPDX task names from the section above; adapt them to the task of your chosen generator.

Generate the SBOM When Building the Executable

To produce the SBOM every time the executable is built, make the buildExecutable task run the SBOM generation task:

tasks.named("buildExecutable") {
    finalizedBy("spdxSbom")
}

Running ./gradlew buildExecutable then also generates the SBOM.

Publish the SBOM as an Artifact

The MicroEJ SDK declares a Maven publication named microej. Add the generated SBOM to this publication so that it is published together with the Application:

publishing {
    publications.named<MavenPublication>("microej") {
        artifact(tasks.named("spdxSbomForRelease")) {
            classifier = "sbom"
            extension = "spdx.json"
        }
    }
}

Running ./gradlew publish then uploads the SBOM alongside the Application, as <module>-<version>-sbom.spdx.json.