Chainguard Libraries for Java overview

Introduction

Chainguard Libraries for Java provides enhanced security for the Java ecosystem by rebuilding popular Maven dependencies with the latest patches and comprehensive supply chain protection. As the first supported ecosystem in Chainguard Libraries, this service addresses critical vulnerabilities in the vast Java/JVM ecosystem that spans hundreds of projects from organizations like the Apache Software Foundation, Eclipse Foundation, and numerous independent maintainers.

Chainguard Libraries for Java provides access to all open source libraries commonly used. New releases of common libraries or artifacts requested by customers are added to the growing index by an automated system. The number of included libraries continues to grow.

The main public repository for binary artifacts is the Maven Central Repository. It has been in operation for nearly 20 years and hosts artifacts of all releases of most open source projects in the Java community. It is the default repository in all commonly used build tools from the Java community including Apache Maven, Gradle, and others, and uses the Maven repository format. Chainguard Libraries for Java covers a broad and growing set of artifacts from Maven Central.

While Maven Central is the primary reference repository, Chainguard Libraries for Java also builds binaries for open source projects available in other repositories like the Google or Confluent repositories. This covers libraries not found on Maven Central, sourced from Google, Oracle, JetBrains, CERN, Confluent, Gradle, and other public artifact repositories. Note that coverage is not exhaustive for any single repository; the index continues to grow, and any request for a missing library or version automatically triggers a process to provision the artifacts from relevant sources if available.

You can use Chainguard Libraries for Java alongside third-party software repositories to create a single source of truth with your repository manager application.

Runtime requirements

The runtime requirements for Java artifacts available from Chainguard Libraries for Java are identical to the requirements of the original upstream project. For example, if a JAR retrieved from Maven Central requires Java 17 or higher, the same Java 17 runtime requirement applies to the binary artifact from Chainguard Libraries for Java.

Technical details

You must use the username and password retrieved with chainctl to access the Chainguard Libraries for Java repository.

The URL for the repository is:

https://libraries.cgr.dev/java/

The repository root at https://libraries.cgr.dev/java/ is not browsable, but you can access artifacts directly by their Maven repository format path: list the available versions of a library through its maven-metadata.xml file, view the files for a specific version in that version’s directory, and download individual files by their full path. Learn more under Manual access.

This Chainguard Libraries for Java repository uses the Maven repository format and only includes release artifacts of the libraries built by Chainguard from source. It does not include all artifacts from Maven Central or other repositories. Snapshot versions are not available.

The following components can be required by your application builds, but are not included:

• Binary versions of closed-source libraries. The Maven Central Repository and other repositories often include such libraries. They enable interoperability with open source applications and development of internal applications as a combination of these libraries and other open source libraries. Examples include JDBC drivers for proprietary databases such as Oracle
• Other artifacts that are found in the Maven Central Repository with incomplete information about the location of the source code or a pointer to a location with access restrictions or an incomplete source, that prevents creation of a binary by Chainguard.

Some types of artifacts are included if the source build produces them, but are often not available:

• JAR artifacts containing the source code
• JAR artifacts containing JavaDoc HTML files
• Distributable versions of artifacts such JARs with dependencies or tar.gz archives
• Other package formats sometimes found such as RPMs, SO files, Android AARs, and similar, rarely used artifacts

As a result, you must configure the repository as the first point of contact and request for any retrieval of a library. This ensures that any library that is available from Chainguard is also used. In addition, any failed requests are flagged at Chainguard and backfill processes are run where possible.

At the same time, you must continue to use the Maven Central Repository, and any other repository that fills the needs for libraries that are not available from the Chainguard Libraries repository.

Typically the access is configured globally on a repository manager for your organization. This approach is strongly recommended.

Alternatively, you can use the token for direct access from a build tool as discussed in Build configuration.

CVE remediation

Chainguard Libraries for Java includes the CVE Remediation feature, available in beta for Spring Boot. Remediated libraries include an appended local version identifier of -0.cgr.N.

For example, if org.apache.commons:commons-lang3:3.18.0 has a remediated build, that build is published as org.apache.commons:commons-lang3:3.18.0-0.cgr.1. If Chainguard publishes another remediated iteration for the same base version, the trailing number increases, such as -0.cgr.2 or -0.cgr.3.

Maven and Gradle treat the -0 as part of the version ordering. In practice, 3.18.0-0.cgr.1 sorts higher than 3.18.0. This means version ranges or dependency management rules can resolve to the remediated build when the overlay repository is available.

Manual access

To manually access artifacts in the Chainguard Libraries for Java repository, use the URL https://libraries.cgr.dev/java/ with your username and password retrieved with chainctl.

The repository follows the Maven repository format, where the groupId and artifactId of a library form a nested directory structure, similar to the package structure within Java projects. The repository root at https://libraries.cgr.dev/java/ is not browsable, but you can discover and retrieve artifacts directly as described below.

For example, the Maven coordinates for Apache Commons Lang are the following:

<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.13.0</version>

Find available versions

List the versions that Chainguard has built for a library by requesting its maven-metadata.xml file at the groupId/artifactId path. The groupId org.apache.commons becomes the nested directories org/apache/commons, and the artifactId adds the commons-lang3 directory:

https://libraries.cgr.dev/java/org/apache/commons/commons-lang3/maven-metadata.xml

The repository only includes release artifacts that Chainguard builds from source, so the versions listed may differ from those available on Maven Central.

List the files for a version

Each version has its own leaf directory, formed by appending the version to the groupId/artifactId path. This version directory is browsable and lists all files for that specific library version:

https://libraries.cgr.dev/java/org/apache/commons/commons-lang3/3.13.0/

For the org.apache.commons:commons-lang3:3.13.0 library, this directory includes the main Maven metadata file commons-lang3-3.13.0.pom, the main JAR file commons-lang3-3.13.0.jar, related checksum files, and the SBOM and attestation files described below. Specific files vary between libraries.

All filenames can be used to download individual files.

Use curl, specify the username and password retrieved with chainctl for basic user authentication and use the URL of the file to download and save the file with the original name.

With .netrc authentication:

curl -n -L \
  -O https://libraries.cgr.dev/java/commons-io/commons-io/2.13.0/commons-io-2.13.0.pom

With environment variables:

curl -L --user "$CHAINGUARD_JAVA_IDENTITY_ID:$CHAINGUARD_JAVA_TOKEN" \
  -O https://libraries.cgr.dev/java/commons-io/commons-io/2.13.0/commons-io-2.13.0.pom

The option -L is required to follow redirects for the actual file locations.

Use checksums of any file to verify if it originates from the Chainguard repository.

SBOM and attestation files

Chainguard Libraries for Java include files that contain software bill of material (SBOM) information. Additional files attest details about build infrastructure with the Supply-chain Levels for Software Artifacts (SLSA) provenance information.

The related files for Chainguard Libraries for Java are located in the same location as the .pom, .jar, and other artifacts for a specific library version and uses the same artifactId-version naming convention with the following extensions:

• .slsa-attestation.json for the SLSA provenance attestation
• .spdx.json for the SBOM information

For example, the files for artifactId commons-compress and version 1.23.0 are located in the version directory https://libraries.cgr.dev/java/org/apache/commons/commons-compress/1.23.0/. It includes the following files:

• commons-compress-1.23.0.pom
• commons-compress-1.23.0.jar
• commons-compress-1.23.0.slsa-attestation.json
• commons-compress-1.23.0.spdx.json