You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
:summary: This guide explains how to generate SBOMs for Quarkus applications in the CycloneDX format.
11
11
:topics: sbom
12
12
:extensions: io.quarkus:quarkus-cyclonedx
13
13
14
-
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.
15
-
SBOMs would typically be used by software security and software supply chain risk management tools to perform vulnerability and compliance related analysis.
14
+
An SBOM (Software Bill of Materials) 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.
15
+
SBOMs are typically used by software security and software supply chain risk management tools to perform vulnerability and compliance related analysis.
16
16
17
-
This guide describes Quarkus SBOM generation capabilities following https://cyclonedx.org/[CycloneDX] specification.
17
+
This guide describes Quarkus SBOM generation capabilities following the https://cyclonedx.org/[CycloneDX] specification.
18
18
19
19
== Why Quarkus-specific tooling?
20
20
21
21
While Quarkus integrates with build tools such as https://maven.apache.org/[Maven] and https://gradle.org/[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.
22
22
23
-
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.
23
+
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.
24
24
25
-
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 https://github.com/CycloneDX/cyclonedx-maven-plugin[CycloneDX Maven plugin].
25
+
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 https://github.com/CycloneDX/cyclonedx-maven-plugin[CycloneDX Maven plugin].
26
26
27
27
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.
28
28
29
29
== Dependency SBOMs
30
30
31
-
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.
31
+
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.
32
32
33
33
=== Maven Dependency SBOMs
34
34
35
-
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 https://cyclonedx.org/[CycloneDX] `JSON` format.
35
+
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 https://cyclonedx.org/[CycloneDX] `JSON` format.
36
36
37
-
`XML` format can be requested by setting `format` goal parameter (or `quarkus.dependency.sbom.format` property) to `xml`.
37
+
`XML` format can be requested by setting the `format` goal parameter (or `quarkus.dependency.sbom.format` property) to `xml`.
38
38
39
-
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.
39
+
Each component in the generated SBOM will include the `quarkus:component:scope` property indicating whether the component is used at runtime or only at development/build time.
40
40
[source,json]
41
41
----
42
42
{
@@ -53,7 +53,7 @@ The complete set of parameters and their description can be obtained by executin
53
53
54
54
Unlike Maven, the https://github.com/CycloneDX/cyclonedx-gradle-plugin[Gradle CycloneDX plugin implementation] can be used in Quarkus projects to generate dependency SBOMs, since the implementation manifests dependency configurations registered by configured plugins.
55
55
56
-
Please, refer to the https://github.com/CycloneDX/cyclonedx-gradle-plugin[Gradle CycloneDX plugin] documentation for its configuration options. Here is a list of Quarkus dependency configurations that would be relevant for manifesting:
56
+
Please refer to the https://github.com/CycloneDX/cyclonedx-gradle-plugin[Gradle CycloneDX plugin] documentation for its configuration options. Here is a list of Quarkus dependency configurations that would be relevant for manifesting:
57
57
58
58
* `quarkusProdRuntimeClasspathConfiguration` - Quarkus application production runtime dependencies;
59
59
* `quarkusProdRuntimeClasspathConfigurationDeployment` - Quarkus application production runtime and build time dependencies;
@@ -62,18 +62,54 @@ Please, refer to the https://github.com/CycloneDX/cyclonedx-gradle-plugin[Gradle
62
62
* `quarkusDevRuntimeClasspathConfiguration` - Quarkus application dev mode runtime dependencies;
63
63
* `quarkusDevRuntimeClasspathConfigurationDeployment` - Quarkus application dev mode runtime and build time dependencies.
64
64
65
-
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.
65
+
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 to indicate which scope to target.
66
+
67
+
=== Embedded Dependency SBOMs
68
+
69
+
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-endpoint>>).
70
+
71
+
To embed a dependency SBOM in the application:
72
+
73
+
[source,properties]
74
+
----
75
+
quarkus.cyclonedx.embedded.enabled=true
76
+
----
77
+
78
+
The SBOM will be embedded as a classpath resource at `META-INF/sbom/application.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.
86
+
87
+
[[sbom-endpoint]]
88
+
=== SBOM REST Endpoint
89
+
90
+
The embedded SBOM can be exposed through a REST endpoint, making it accessible to external tools and scanners at runtime. To enable the endpoint:
91
+
92
+
[source,properties]
93
+
----
94
+
quarkus.cyclonedx.endpoint.enabled=true
95
+
----
96
+
97
+
This will serve the embedded SBOM at `/.well-known/sbom` with the `application/vnd.cyclonedx+json` content type (or `application/vnd.cyclonedx+xml` for XML SBOMs). The path can be customized using the `quarkus.cyclonedx.endpoint.path` property.
98
+
99
+
NOTE: Enabling the endpoint will automatically trigger SBOM embedding, even if `quarkus.cyclonedx.embedded.enabled` is not explicitly set to `true`.
100
+
101
+
The endpoint requires `quarkus-vertx-http` to be present on the classpath, which is the case for most web applications (e.g., those using `quarkus-rest`).
66
102
67
103
== Distribution SBOMs
68
104
69
-
This chapter describes SBOMs that manifest outcomes of Quarkus builds that are final application distributions.
105
+
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.
70
106
71
-
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.
107
+
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.
72
108
73
-
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
109
+
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
74
110
75
-
* `<executable-name>` is the base file name (without the extension) of the executable that launches an application;
76
-
* `<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`.
111
+
* `<executable-name>` is the base file name (without the extension) of the executable that launches the application;
112
+
* `<format>` is either `json` (the default) or `xml`, which can be configured using the `quarkus.cyclonedx.format` property. If both formats are desired, `quarkus.cyclonedx.format` can be set to `all`.
77
113
78
114
=== Fast JAR
79
115
@@ -161,7 +197,7 @@ SBOMs for native images will use the native executable file as their main compon
161
197
162
198
Since native executables are not currently attached to projects as Maven artifacts, their SBOMs will not be attached as Maven artifacts either.
163
199
164
-
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.
200
+
As in the case of an Uber JAR, runtime components in an SBOM generated for a native executable will not include `evidence.occurrences.location` since their corresponding code and resources are included in a single native executable file.
165
201
166
202
=== Mutable JAR
167
203
@@ -195,4 +231,4 @@ SBOMs generated for Mutable JAR distributions will also record locations of comp
195
231
196
232
|`quarkus:component:scope` |`runtime` or `development` |Indicates whether a component is a runtime or a build/development time dependency of an application.
197
233
|`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.
0 commit comments