Por Versão

Generating CycloneDX BOMs

An SBOM (Software Bill of Material) is a manifest that describes what a given software distribution consists of in terms of components. In addition to that, it may include a lot more information such as relationships between those components, licenses, provenance, etc. SBOMs would typically be used by software security and software supply chain risk management tools to perform vulnerability and compliance related analysis.

This guide describes Quarkus SBOM generation capabilities following CycloneDX specification.

Why Quarkus-specific tooling?

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 a runtime and a 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 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.

Besides the dependencies, that are an input to a build process, 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

This chapter describes how to generate SBOMs manifesting only the dependencies of an application before it is built. In other words, these SBOMs will manifest the input into a build. These SBOMs could be used to perform vulnerability and compliance related analysis before building applications.

Maven Dependency SBOMs

For Quarkus Maven projects dependency SBOMs can be generated with the quarkus:dependency-sbom goal. The outcome of the goal will be saved in a target/<artifactId>-<version>-dependency-cyclonedx.json file (which can be changed by setting the outputFile goal parameter or the quarkus.dependency.sbom.output-file property). The complete Quarkus build and runtime dependency graphs will be recorded in the CycloneDX JSON format.

XML format can be requested by setting format goal parameter (or quarkus.dependency.sbom.format property) to xml.

Each component in the generated SBOM will include the quarkus:component:scope property that will indicate whether this component is used at runtime or only development/build time.

        {
          "name" : "quarkus:component:scope",
          "value" : "runtime"
        }

By default, quarkus:dependency-sbom captures the dependencies of a production build. Quarkus supports three application bootstrap modes: normal (production), test, and dev. In all three modes, an application may have different dependency graphs. The mode parameter can be used to indicate which dependency graph should be recorded. If the mode is set to test or dev, the target file name will become target/<artifactId>-<version>-<mode>-dependency-cyclonedx.json.

The complete set of parameters and their description can be obtained by executing mvn help:describe -Dcmd=quarkus:dependency-sbom -Ddetail.

Gradle Dependency SBOMs

Unlike Maven, the Gradle CycloneDX plugin implementation can be used in Quarkus projects to generate dependency SBOMs, since the implementation manifests dependency configurations registered by configured plugins.

Please, refer to the Gradle CycloneDX plugin documentation for its configuration options. Here is a list of Quarkus dependency configurations that would be relevant for manifesting:

quarkusProdRuntimeClasspathConfiguration - Quarkus application production runtime dependencies;
quarkusProdRuntimeClasspathConfigurationDeployment - Quarkus application production runtime and build time dependencies;
quarkusTestRuntimeClasspathConfiguration - Quarkus application test runtime dependencies;
quarkusTestRuntimeClasspathConfigurationDeployment - Quarkus application test runtime and build time dependencies;
quarkusDevRuntimeClasspathConfiguration - Quarkus application dev mode runtime dependencies;
quarkusDevRuntimeClasspathConfigurationDeployment - Quarkus application dev mode runtime and build time dependencies.

Given that the plugin is not aware of how Quarkus uses these dependencies, it will not be able to set the quarkus:component:scope property for components. On the other hand, the requested configuration name can be used indicate which scope to target.

Distribution SBOMs

This chapter describes SBOMs that manifest outcomes of Quarkus builds that are final application distributions.

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

At this point, the only SBOM generator available for Quarkus users that can manifest application distributions is io.quarkus:quarkus-cyclonedx. Once it’s added 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

<executable-name> is the base file name (without the extension) of the executable that launches an application;
<format> is either json (the default) or xml, which can be configured using quarkus.cyclonedx.format property. If both formats are desired quarkus.cyclonedx.format can be set to all.

Fast JAR

Fast JAR packaging uses a Quarkus-specific filesystem directory layout that contains files generated by Quarkus and Maven artifacts that are runtime dependencies of an application.

SBOMs for Fast JAR packaging type will use the executable JAR file as their main component and record both runtime and build time Quarkus application dependencies.

Runtime Components

Every file in the resulting Fast JAR distribution will appear in the SBOM with the quarkus:component:scope property set to runtime and evidence.occurrences.location field pointing to the location of the component in the application distribution directory, for example

      "purl" : "pkg:maven/org.jboss.slf4j/slf4j-jboss-logmanager@2.0.0.Final?type=jar",
      "properties" : [
        {
          "name" : "quarkus:component:scope",
          "value" : "runtime"
        }
      ],
      "evidence" : {
        "occurrences" : [
          {
            "location" : "lib/main/org.jboss.slf4j.slf4j-jboss-logmanager-2.0.0.Final.jar"
          }
        ]
      }

evidence.occurrences.location was introduced in CycloneDX schema version 1.5, for older versions the location will be indicated using the quarkus:component:location property.

Pedigree

Pedigree is a way to provide information that certain patches, or changes in general, have been applied to a certain component.

In certain cases, Quarkus may copy modified versions of dependency artifacts to an application distribution. Manipulating the original content of a component will change its hash sums which may get highlighted as suspicious by the tools comparing original component hash sums to those found in the distribution.

When Quarkus applies modifications to artifacts resolved from Maven repositories, it can manifest these changes as pedigree notes in the generated SBOM. For example, if an application developer decided to remove certain classpath resources from a dependency, such as

quarkus.class-loading.removed-resources."jakarta.transaction\:jakarta.transaction-api"=META-INF/NOTICE.md,jakarta/transaction/package.html

The resulting SBOM will include

      "purl" : "pkg:maven/jakarta.transaction/jakarta.transaction-api@2.0.1?type=jar",
      "pedigree" : {
        "notes" : "Removed META-INF/NOTICE.md,jakarta/transaction/package.html"
      },

Build time dependencies

Build time dependencies will be recorded with the quarkus:component:scope property set to development:

      "purl" : "pkg:maven/org.apache.httpcomponents/httpclient@4.5.14?type=jar",
      "properties" : [
        {
          "name" : "quarkus:component:scope",
          "value" : "development"
        }
      ]

They will not include evidence.occurrences.location since they will not be found in the distribution.

Uber JAR

SBOMs for Uber JARs will use the Uber JAR Maven artifact as their main component.

Since an Uber JAR is published as a Maven artifact itself, SBOMs generated for Uber JARs will also be automatically published as Maven artifacts. This, however, can be disabled by setting the attachSboms parameter of the quarkus:build goal to false.

Gradle users will have to explicitly configure a publishing plugin to deploy SBOMs as Maven artifacts.

Runtime components in an SBOM generated for an Uber JAR will not include evidence.occurrences.location since their content is merged in a single JAR file.

Native image

SBOMs for native images will use the native executable file as their main component.

Since native executables are not currently attached to projects as Maven artifacts, their SBOMs will not be attached as Maven artifacts either.

As in the case of an Uber JAR, runtime components in an SBOM generated for an native executable will not include evidence.occurrences.location since their corresponding code and resources are included in a single native executable file.

Mutable JAR

Mutable JAR distribution is similar to the Fast JAR one except it also includes build time dependencies to support re-augmentation (re-building) of an application.

SBOMs generated for Mutable JAR distributions will also record locations of components that will be used during re-augmentation process using evidence.occurrences.location but keeping their quarkus:component:scope property set to development. For example:

      "purl" : "pkg:maven/org.apache.httpcomponents/httpcore@4.4.16?type=jar",
      "properties" : [
        {
          "name" : "quarkus:component:scope",
          "value" : "development"
        }
      ],
      "evidence" : {
        "occurrences" : [
          {
            "location" : "lib/deployment/org.apache.httpcomponents.httpcore-4.4.16.jar"
          }
        ]
      }

Quarkus Property Taxonomy

Name Value range Descrição

Name	Value range	Descrição
`quarkus:component:scope`	`runtime` or `development`	Indicates whether a component is a runtime or a build/development time dependency of an application.
`quarkus:component:location`	String representing a file system path using `/` as a path element	Used in SBOMs with schema versions 1.4 or older. Starting from schema 1.5, `evidence.occurrences.location` is used instead. This property is used only if a component is found in the distribution. The value is a relative path to a file pointing to the location of a component in a distribution using `/` as a path element separator.

quarkus:component:scope

runtime or development

Indicates whether a component is a runtime or a build/development time dependency of an application.

quarkus:component:location

String representing a file system path using / as a path element

Used in SBOMs with schema versions 1.4 or older. Starting from schema 1.5, evidence.occurrences.location is used instead. This property is used only if a component is found in the distribution. The value is a relative path to a file pointing to the location of a component in a distribution using / as a path element separator.

Why Quarkus-specific tooling?
Dependency SBOMs
- Maven Dependency SBOMs
- Gradle Dependency SBOMs
Distribution SBOMs
Quarkus Property Taxonomy