Generating and Using CycloneDX SBOMs

While Quarkus integrates with build tools such as Maven and Gradle, it could itself be categorized as a build tool with its own component and dependency model, build steps, and build outcomes. One of the essential component types of a Quarkus application is a Quarkus extension, which consists of runtime and build time artifacts, and their dependencies.

To properly resolve Quarkus extension and other application dependencies, Quarkus uses its own dependency resolver, which is implemented on top of the dependency resolver provided by the underlying build tool: Maven or Gradle.

As a consequence, in the case of Maven, for example, the results of dependency:tree will not include all the dependencies Quarkus will use to build an application. A similar issue will affect other dependency analysis tools that assume a project adheres to the standard Maven dependency model: they will not be able to capture the effective Quarkus application dependency graph. Unfortunately, that includes the implementation of the CycloneDX Maven plugin.

In addition to manifesting dependencies (the input to a build), there is also an outcome of the build that is the final distribution of an application. Users of an application may request an SBOM manifesting not only the dependencies (the input to a build) but also the final distribution (the outcome of the build) before they agree to deploy the application. Quarkus allows application developers to choose various packaging types for their applications, some of which are Quarkus-specific. Providing certain Quarkus-specific details about components included in a distribution may help better evaluate the impact of potential security-related issues.

Dependency SBOMs manifest the dependencies of an application before it is built. In other words, they describe the input to a build. These SBOMs can be used to perform vulnerability and compliance related analysis before building applications.

In addition to generating dependency SBOMs as separate files, Quarkus can embed a dependency SBOM directly into the built application as a classpath resource. This allows the application to carry its own bill of materials at runtime, which can be useful for runtime auditing or to expose via a REST endpoint (see SBOM REST Endpoint).

To embed a dependency SBOM in the application:

The SBOM will be embedded as a classpath resource at META-INF/sbom/dependency.cdx.json by default. The resource name can be customized:

The format is determined by the resource name extension: .json for JSON, .xml for XML.

By default, the embedded SBOM is compressed with GZIP to reduce the application size. The classpath resource name will have a .gz extension appended (e.g., META-INF/sbom/dependency.cdx.json.gz). If the SBOM is exposed through the REST endpoint, it will be served with Content-Encoding: gzip, so HTTP clients will decompress it transparently. Compression can be disabled with:

The embedded dependency SBOM can be exposed through a REST endpoint, making it accessible to external tools and scanners at runtime. To enable the endpoint:

The embedded SBOM will be served at /.well-known/sbom with the application/vnd.cyclonedx+json content type (or application/vnd.cyclonedx+xml for XML SBOMs). Since the embedded SBOM is compressed by default, the response will include Content-Encoding: gzip, which HTTP clients handle transparently. The path can be customized using the quarkus.cyclonedx.endpoint.path property.

Enabling the endpoint will automatically trigger SBOM embedding, even if quarkus.cyclonedx.embedded.enabled is not explicitly set to true.

For an example of scanning a running application through the endpoint, see Scanning via the SBOM Endpoint.

The SBOM endpoint is also available when running in dev mode (quarkus dev), which can be useful for scanning during development.

Distribution SBOMs manifest the outcomes of Quarkus builds — the final application distributions. Unlike dependency SBOMs, which describe the input to a build, distribution SBOMs describe what was actually produced.

During the build and package assembly process, Quarkus captures details about the produced distribution and allows an SBOM generator to record that information in an SBOM format.

To generate CycloneDX distribution SBOMs, add io.quarkus:quarkus-cyclonedx as a project dependency. It will generate SBOMs every time an application is built. SBOMs will be saved in the project’s build output directory under <executable-name>-cyclonedx.<format> name, where

By default, generated JSON SBOMs are not pretty-printed. To enable pretty-printing:

SBOMs can be fed into vulnerability scanners such as Grype to identify known vulnerabilities in application dependencies. This section demonstrates how to use Quarkus-generated SBOMs with Grype.

Every generated SBOM includes a serialNumber field in urn:uuid: format, as defined by the CycloneDX specification. The serial number is derived from the BOM’s content hash, which covers metadata, components, dependency relationships, and other structural fields.

When project.build.outputTimestamp is configured in the Maven project (the standard property for reproducible builds), the SBOM metadata timestamp is set to that value, making the entire BOM — including its serial number — fully deterministic across identical builds. Without a reproducible timestamp, the metadata timestamp defaults to the current time, meaning the serial number will vary between builds even if the dependencies have not changed.

By default, Quarkus generates SBOMs from the application’s Maven dependency model and the packaging output. Extensions that manage additional software components — for example, npm packages or other non-Maven artifacts — can contribute those components to the application SBOM by producing SbomContributionBuildItem instances from their @BuildStep methods.

Extension contributions are merged with the core application contribution by the SBOM generator. Components marked as top-level will appear as direct dependencies of the main application component in the generated SBOM.

ビルド時に固定された設定プロパティー。その他の設定プロパティーは、すべて実行時にオーバーライド可能です。