- GraalVM for JDK 23 (Latest)
- GraalVM for JDK 24 (Early Access)
- GraalVM for JDK 21
- GraalVM for JDK 17
- Archives
- Dev Build
This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.
Software Bill of Materials (SBOM) in Native Image
GraalVM Native Image can assemble a Software Bill of Materials (SBOM) at build time to detect any libraries that may be susceptible to known security vulnerabilities.
Native Image provides the --enable-sbom
option to embed an SBOM into a native executable (only available in Oracle GraalVM).
In addition to being embedded, the SBOM can be added to the classpath or exported as a JSON file by using --enable-sbom=classpath,export
.
The CycloneDX format is supported and is the default.
To embed a CycloneDX SBOM into a native executable, pass the --enable-sbom
option to the native-image
command.
The implementation constructs the SBOM by recovering all version information observable in external library manifests for classes included in a native executable.
The SBOM is compressed to limit the SBOM’s impact on the native executable size.
The SBOM is stored in the gzip
format with the exported sbom
symbol referencing its start address and the sbom_length
symbol referencing its size.
After embedding the compressed SBOM into the executable, the Native Image Inspect Tool is able to extract the compressed SBOM using an optional --sbom
parameter accessible through $JAVA_HOME/bin/native-image-inspect --sbom <path_to_binary>
from both executables and shared libraries.
It outputs the SBOM in the following format:
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"components": [
{
"bom-ref": "pkg:maven/io.netty/netty-codec-http2@4.1.104.Final",
"type": "library",
"group": "io.netty",
"name": "netty-codec-http2",
"version": "4.1.104.Final",
"purl": "pkg:maven/io.netty/netty-codec-http2@4.1.104.Final",
"properties": [
{
"name": "syft:cpe23",
"value": "cpe:2.3:a:codec:codec:4.1.76.Final:*:*:*:*:*:*:*"
},
{
"name": "syft:cpe23",
"value": "cpe:2.3:a:codec:netty-codec-http2:4.1.76.Final:*:*:*:*:*:*:*"
},
{
"name": "syft:cpe23",
"value": "cpe:2.3:a:codec:netty_codec_http2:4.1.76.Final:*:*:*:*:*:*:*"
},
...
]
},
...
],
"dependencies": [
{
"ref": "pkg:maven/io.netty/netty-codec-http2@4.1.104.Final",
"dependsOn": [
"pkg:maven/io.netty/netty-buffer@4.1.104.Final",
"pkg:maven/io.netty/netty-codec-http@4.1.104.Final",
"pkg:maven/io.netty/netty-codec@4.1.104.Final",
"pkg:maven/io.netty/netty-common@4.1.104.Final",
"pkg:maven/io.netty/netty-transport@4.1.104.Final"
]
},
...
],
"serialNumber": "urn:uuid:51ec305f-616e-4139-a033-a094bb94a17c"
}
Vulnerability Scanning #
To scan for vulnerable libraries, use either the GraalVM GitHub Action for automated scanning, or submit the SBOM to a vulnerability scanner directly.
GitHub Integration #
When using the GraalVM GitHub Action, the SBOM can be automatically generated and submitted to GitHub’s dependency submission API for continuous scanning. This enables:
- Vulnerability tracking with GitHub’s Dependabot.
- Dependency tracking with GitHub’s Dependency Graph.
If you use GitHub, this integration offers you the simplest setup and powerful security tooling.
Command-Line Scanning #
The popular Anchore software supply chain management platform makes the grype
scanner available for free.
You can check whether the libraries given in your SBOMs have known vulnerabilities documented in Anchore’s database.
For this purpose, the output of the tool can be fed directly to the grype
scanner to check for vulnerable libraries, using the command $JAVA_HOME/bin/native-image-inspect --sbom <path_to_binary> | grype
which produces the following output:
NAME INSTALLED VULNERABILITY SEVERITY
netty-codec-http2 4.1.76.Final CVE-2022-24823 Medium
You can then use this report to update any vulnerable dependencies found in your executable.
Note: Running
native-image-inspect
without--sbom
executes code from the native binary to extract class information. Do not use it on untrusted binaries. This extraction method is deprecated—use class-level SBOMs instead.
Dependency Tree #
The SBOM provides information about component relationships through its dependencies
field.
This dependency information is derived from Native Image’s static analysis call graph.
Analyzing the dependency graph can help you understand why specific components are included in your application.
For example, discovering an unexpected component in the SBOM allows for tracing its inclusion through the dependency graph to identify which parts of the application are using it.
With the GraalVM GitHub Action, you get access to GitHub’s Dependency Graph feature.
Enhanced SBOMs with Maven Plugin for Native Image #
To generate more accurate SBOMs with richer component metadata, consider using the Maven plugin for GraalVM Native Image. This plugin integrates with Native Image to enhance the SBOM creation.
The plugin creates a “baseline” SBOM by using the cyclonedx-maven-plugin
.
This baseline SBOM includes additional metadata that otherwise is not available to the native-image generator, such as licenses
, externalReferences
, hashes
, and copyright
.
See the CycloneDX specification for more information about the fields.
The baseline SBOM also defines which package names belong to a component, helping Native Image associate classes with their respective components—a task that can be challenging when shading or fat JARs are used. In this collaborative approach, Native Image is also able to prune components and dependencies more aggressively to produce a minimal SBOM.
These enhancements are available starting with plugin version 0.10.4 and are enabled by default when the --enable-sbom
option is used.
Including Class-Level Metadata in the SBOM #
Using --enable-sbom=class-level
adds class-level metadata to the SBOM components.
This metadata includes Java modules, classes, interfaces, records, annotations, enums, constructors, fields, and methods that are part of the native executable.
This information can be useful for:
- Advanced vulnerability scanning: When the affected classes or methods of a vulnerability are published as part of a CVE, the class-level metadata can be checked to determine if a native executable with the affected SBOM component is actually vulnerable, thereby reducing the false positive rate of vulnerability scanning.
- Understanding image contents: Quickly browse and search the class-level metadata to examine what is included in the native executable.
Including class-level metadata increases the SBOM size substantially. For this Micronaut Hello World Rest application, the SBOM size is 1.1 MB when embedded, and 13.7 MB when exported. The SBOM without class-level metadata is 3.5 kB when embedded, and 64 kB when exported. The size of the native image without an embedded SBOM is around 52 MB.
Data Format #
The CycloneDX specification allows the use of a hierarchical representation by nesting components that have a parent-child relationship. It is used to embed class-level information in SBOM components in the following way:
[component] SBOM Component
└── [component] Java Modules
└── [component] Java Source Files
├── [property] Classes
├── [property] Interfaces
├── [property] Records
├── [property] Annotations
├── [property] Enums
├── [property] Fields
├── [property] Constructors
└── [property] Methods
Each SBOM component lists its Java modules in the components
field.
Each module is identified by its name and lists its Java source files in the components
field.
Each source file is identified by its path relative to the component’s source directory and lists its classes, interfaces, records, annotations, enums, fields, constructors, and methods in the properties
field.
Consider an example of a simple component containing one Java source file in mymodule
:
// src/com/sbom/SBOMTestApplication.java
package com.sbom;
import org.apache.commons.validator.routines.RegexValidator;
public class SBOMTestApplication {
private static final boolean IS_EMPTY_OR_BLANK = new RegexValidator("^[\\s]*$").isValid(" ");
public static void main(String[] argv) {
System.out.println(String.valueOf(IS_EMPTY_OR_BLANK));
ClassInSameFile someClass = new ClassInSameFile("hello ", "world");
someClass.doSomething();
}
}
class ClassInSameFile {
private final String value1;
private final String value2;
ClassInSameFile(String value1, String value2) {
this.value1 = value1;
this.value2 = value2;
}
String concatenate() {
System.out.println(value1 + value2);
}
// This method is unreachable and will therefore not be included in the SBOM
String unreachable() {
return value;
}
}
The class-level SBOM component would look like this:
{
"type": "library",
"group": "com.sbom",
"name": "sbom-test-app",
"version": "1.0.0",
"purl": "pkg:maven/com.sbom/sbom-test-app@1.0.0",
"bom-ref": "pkg:maven/com.sbom/sbom-test-app@1.0.0",
"properties": [...],
"components": [
{
"type": "library",
"name": "mymodule",
"components": [
{
"type": "file",
"name": "com/sbom/SBOMTestApplication.java",
"properties": [
{
"name": "class",
"value": "com.sbom.ClassInSameFile"
},
{
"name": "class",
"value": "com.sbom.SBOMTestApplication"
},
{
"name": "field",
"value": "com.sbom.ClassInSameFile.value1:java.lang.String"
},
{
"name": "field",
"value": "com.sbom.ClassInSameFile.value2:java.lang.String"
},
{
"name": "field",
"value": "com.sbom.SBOMTestApplication.IS_EMPTY_OR_BLANK:boolean"
},
{
"name": "constructor",
"value": "com.sbom.ClassInSameFile(java.lang.String, java.lang.String)"
},
{
"name": "method",
"value": "com.sbom.ClassInSameFile.concatenate():java.lang.String"
},
{
"name": "method",
"value": "com.sbom.SBOMTestApplication.<clinit>():void"
},
{
"name": "method",
"value": "com.sbom.SBOMTestApplication.main(java.lang.String[]):void"
}
]
}
]
}
]
}
The following table specifies the format of class-level metadata:
Kind | CycloneDX Object | type |
name |
value |
Notes |
---|---|---|---|---|---|
Module | Component | library |
module name | - | Unnamed module’s name is unnamed module |
Source File | Component | file |
path relative to the src directory | - | Ends in .java , / separator, path derived from package name |
Class | Property | - | class |
fully qualified name | Includes anonymous, inner, and sealed classes |
Interface | Property | - | interface |
fully qualified name | - |
Record | Property | - | record |
fully qualified name | - |
Annotation | Property | - | annotation |
fully qualified name | - |
Field | Property | - | field |
className.fieldName:fieldType |
Field declaration |
Constructor | Property | - | constructor |
className(paramType1, paramType2) |
Parameter types comma-space separated |
Method | Property | - | method |
className.methodName(paramType1, paramType2):returnType |
Method with parameters and return type |
Some additional notes:
- Array types are suffixed with
[]
. For example, an array of strings becomesjava.lang.String[]
. - Synthetically generated lambda classes are not included.
When using shaded or fat JARs, the class-level metadata can sometimes not be accurately associated with a component. When this happens, all unresolved metadata gets collected in a placeholder component:
{
"type": "data",
"name": "class-level metadata that could not be associated with a component",
"components": [
...
]
}