Global configuration

Java and JVM library consumption in a large organization is typically managed by a repository manager. Commonly used repository manager applications are Cloudsmith, Google Artifact Registry, JFrog Artifactory, and Sonatype Nexus Repository. The repository manager acts as a single point of access for developers and development tools to retrieve the required libraries.

The recommended approach is to use the upstream fallback feature of Chainguard Repository, which allows you to configure your repository manager with a single upstream pointed at https://libraries.cgr.dev/java/ without a separate fallback to Maven Central. The Chainguard Repository handles fallback and policy enforcement; your repository manager handles local caching and access control. Chainguard retrieves packages from the public Maven Central repository on your behalf when upstream fallback is enabled. This includes protections such as malware scanning and a cooldown period for newly published packages.

At a high level, adopting the use of Chainguard Libraries consists of the following steps:

• Configure your environment to use https://libraries.cgr.dev/java/ as the single upstream source for Java package retrieval. This can be done either:
  • As a remote repository in your repository manager, or
  • Directly in your Java build configuration (for example, Maven or Gradle).
• Additional steps depend on your specific environment and preferences, and can include the following optional measures:
  • Remove all cached artifacts for Maven Central. This step ensures that any libraries you pull are from Chainguard Libraries, and not existing cached artifacts from upstream.
  • Remove any repositories that are no longer desired or necessary, depending on your organization’s preferences.

This page explains how to use Chainguard Libraries for Java with a repository manager. If your organization does not use a repository manager, you can pull directly from Chainguard. Refer to the direct access documentation for build tools for more information.

Manually managing fallback

Chainguard recommends using the Chainguard Repository’s built-in upstream fallback rather than configuring a fallback to the public Maven Central registry in your repo manager. Configuring your own fallback bypasses the protection that the Chainguard Repository provides.

However, if you intentionally want to manage fallback ordering yourself, you can configure https://libraries.cgr.dev/java/ as a remote repository alongside your Maven upstream, and combine them in a virtual or group repository with Chainguard as the first priority. If you configure a fallback to Maven Central, packages sourced from that registry are not covered by Chainguard’s malware-resistance guarantees.

The per-tool instructions on this page vary by repository manager. The JFrog Artifactory and Sonatype Nexus Repository sections use the recommended upstream fallback approach, which Chainguard has tested with those tools. The Cloudsmith and Google Artifact Registry sections use the manual Maven Central fallback pattern; Chainguard has not yet tested the upstream fallback with those tools.

Cloudsmith

Cloudsmith supports Maven repositories for proxying and hosting. Refer to the Maven Repository documentation and the Maven Upstream documentation for Cloudsmith for more information. Cloudsmith supports combining repositories by defining multiple upstream repositories.

Note: Chainguard has not yet tested the recommended upstream fallback approach — a single upstream pointed at https://libraries.cgr.dev/java/ — with Cloudsmith. The following steps instead configure Maven Central as an upstream fallback in your repository manager. Packages sourced from Maven Central are not covered by Chainguard’s malware-resistance guarantees.

Initial configuration

Use the following steps to add a repository with the Maven Central Repository and the Chainguard Libraries for Java repository as Maven upstream repositories.

Configure a java-all repository:

1. Log in as a user with administrator privileges.
2. Select the Repositories tab near the top of the screen.
3. On the Repositories page, click the + New repository button.
4. Enter the name java-all for your new repository. The name should include java to identify the ecosystem. This convention helps avoid confusion since repositories in Cloudsmith are multi-format.
5. Select a storage region that is appropriate for your organization and infrastructure.
6. Click +Create Repository.

Configure an upstream proxy for the Maven Central Repository:

1. Click the name of the new java-public repository on the repositories page to configure it.
2. Click the Upstreams tab, then click +Add Upstream Proxy.
3. Configure an upstream proxy with the format Maven.
4. Configure another upstream proxy with the following:
   • Name: java-public
   • Priority: 2
   • Upstream URL: https://repo1.maven.org/maven2/
   • Mode: Cache and Proxy
5. Click Create Upstream Proxy.

Configure an upstream proxy for the Chainguard Libraries for Java repository:

1. Click the name of the new java-chainguard repository on the repositories page to configure it.
2. Click the Upstreams tab, then click +Add Upstream Proxy.
3. Configure an upstream proxy with the format Maven and the following details:
   • Name: java-chainguard
   • Priority: 1
   • Proxy URL: https://libraries.cgr.dev/java/
   • Mode: Cache and Proxy
   • Authentication Settings: Enter the Username and Password value from Chainguard Libraries access.
4. Click Create Upstream Proxy.
5. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named java-chainguard-remediated with a URL set to https://libraries.cgr.dev/java-remediated/. Use the same authentication details.

Use this setup for initial testing with Chainguard Libraries for Java. For production usage, add the java-chainguard upstream proxy to your production repository.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Select the Packages tab.
2. Click Push/Pull Packages.
3. Choose the format Maven.
4. Copy the value in the <url> tag from the XML snippet with the <repositories> entry. For example, https://dl.cloudsmith.io/basic/exampleorg/java-all/maven/ with exampleorg replaced with the name of your organization. Note that the name of the repository java-all as well as maven as identifier for the format are part of the URL.
5. Copy the username and password values block from the second code snippet for authentication after choosing the desired authentication of Default or API Key.

Choose a different format and the equivalent sections if you are using another build tools such as Gradle.

Use the URL of the repository, the username, and the password for the server authentication block in the build configuration and build a first test project. In a working setup, all libraries retrieved from Chainguard are tagged with the name of the upstream proxy.

Google Artifact Registry

Google Artifact Registry supports the Maven format for hosting artifacts in Standard repositories and proxying artifacts from public repositories in Remote repositories. Use Virtual repositories to combine them for consumption with Maven and other build tools. Use the Java package documentation for Google Artifact Registry as the starting point for more details.

Note: Chainguard has not yet tested the recommended upstream fallback approach — a single upstream pointed at https://libraries.cgr.dev/java/ — with Google Artifact Registry. The following steps instead configure Maven Central as an upstream fallback in your repository manager. Packages sourced from Maven Central are not covered by Chainguard’s malware-resistance guarantees.

Initial configuration

Use the following steps to add the Maven Central Repository and the Chainguard Libraries for Java repository as remote repositories and combine them as a virtual repository:

1. Log in to the Google Cloud console as a user with administrator privileges.
2. Navigate to your project and find the Artifact Registry with the search.
3. Activate Artifact Registry if necessary.
4. Navigate to your project and find the Secret Manager with the search.
5. Activate Secret Manager if necessary.

Before configuring the repositories, you must create a secret with the password value as retrieved with chainctl:

1. Navigate to the Secret Manager
2. Click Create secret.
3. Set the Name to chainguard-libraries-java.
4. Set the Secret value to the password from your chainctl output.
5. Click Create secret.

Navigate to Artifact Registry and select Repositories in the left hand navigation under the Artifact Registry label to configure a remote repository for the Maven Central Repository:

1. Click Create a Repository (or the + button).
2. Configure the repository:
   • Name: java-public
   • Format: Maven
   • Mode: Remote
   • Remote repository source: Maven Central
   • Location type > Region: Select a region.
3. Click Create.

Configure a remote repository for the Chainguard Libraries for Java repository:

1. Click + to add another repository.
2. Configure the repository:
   • Name: java-chainguard
   • Format: Maven
   • Mode: Remote
   • Remote repository source: Custom
   • Custom repository URL: https://libraries.cgr.dev/java/
   • Remote repository authentication mode: Authenticated
   • Username for the upstream repository: Set this to the value as retrieved with chainctl.
   • Secret: Select the chainguard-libraries-java secret in the list.
   • Location type > Region: Select the same region configured for your java-public repository.
3. Click Create.
4. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named java-chainguard-remediated with a URL set to https://libraries.cgr.dev/java-remediated/. Use the same authentication details.

Combine the repositories in a new virtual repository:

1. Click the + button to add another repository.
2. Configure the repository:
   • Name: java-all
   • Format: Maven
   • Mode: Virtual
3. Under Virtual upstream repositories, click Add upstream repository.
4. Use the Browse button to locate and select the java-chainguard repository as Repository 1 and set the Policy name 1 to java-chainguard.
5. Use the Browse button to locate and select the java-public repository as Repository 1 and set the Policy name 1 to java-public.
6. Under Virtual upstream repositories, click Add upstream repository.
7. Set the Priority value for the java-chainguard policy name to a higher value than the java-public priority value.
   • If you are using the remediated repository, add the java-chainguard-remediated repository and ensure it is the first in the displayed list. If not, ensure the java-chainguard repository is first.
8. Under Location type, choose the same suitable Region for your development as configured for the java-public repository.
9. Click Create.

Build tool access

The following steps allow you to configure your build tool for accessing the repository:

1. Navigate to Artifact Registry and select Repositories in the left hand navigation under the Artifact Registry label.
2. Click the java-all repository name in the list of repositories.
3. Click Setup instructions and follow the documentation. Note that you must add the extension com.google.cloud.artifactregistry:artifactregistry-maven-wagon to each project.

In a working setup, the chainguard remote repository contains all artifacts retrieved from Chainguard.

JFrog Artifactory

JFrog Artifactory supports Maven repositories for proxying and hosting, and virtual repositories to combine them. Refer to the Maven Repository documentation for Artifactory for more information.

Initial configuration

Use the following steps to set up a repository in Artifactory to access Chainguard Java Libraries via the Chainguard Repository.

1. Log in as a user with administrator privileges.
2. Click Administration in the top navigation bar.
3. Select Repositories in the left hand navigation.

Configure a remote repository for the Chainguard Libraries for Java repository:

1. Click Create a Repository and choose the Remote option.
2. Configure the repository:
   • Package type: Maven
   • Repository Key: java-chainguard
   • URL: https://libraries.cgr.dev/java/
   • User Name and Password / Access Token: Set to the values as retrieved with chainctl.
   • Deactivate Maven Settings - Handle Snapshots.
3. Optionally click Test to verify connection and authentication.
4. Click the Advanced configuration tab. In the Others section, check the box next to Disable URL Normalization and uncheck the box next to Block Mismatching Mime Types.
5. Click Create Remote Repository.
6. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named java-chainguard-remediated with a URL set to https://libraries.cgr.dev/java-remediated/. Use the same authentication details.

If you are manually managing fallback, you can configure an additional remote repository for Maven Central with lower priority. Make sure to deactivate Maven Settings - Handle Snapshots in the remote repository.

Note: If you are running Curation, you must add your Chainguard remote repository to the curation-bypass list.

Combine the repositories in a new virtual repository:

1. Click Create a Repository and choose the Virtual option.
2. Configure the repository:
   • Package type: Maven
   • Repository Key: java-all
3. Scroll down to the Repositories section.
4. Add the java-chainguard repository. If you are using the remediated repository, add the java-chainguard-remediated repository and ensure it is the first in the displayed list.
5. Click Create Virtual Repository.

Use this setup for initial testing with Chainguard Libraries for Java. For production usage add the java-chainguard repository to your production virtual repository.

Validate the remote repository

After creating the java-chainguard remote repository, validate that Artifactory is successfully proxying through to Chainguard before proceeding. Because Artifactory falls back to Maven Central when a connection to a remote repository fails, a misconfigured repository may silently resolve packages from Maven Central rather than Chainguard — and the build will succeed without any visible error.

Common sources of misconfiguration include invalid or expired credentials, or an incorrect or incomplete repository URL. The Artifactory Test button on the repository configuration screen is not a reliable indicator; it may fail for a correctly configured repository, and may pass for an incorrectly configured one. Instead, use the following steps to verify that fetching an artifact through Artifactory produces the same checksum as fetching it directly from libraries.cgr.dev.

1. Compute the artifact’s checksum

Fetch the artifact directly from Chainguard and compute its checksum. This example uses junit-4.13.2.jar. You can substitute any artifact you know to be available.

curl -sSf -L \
  -u "${CHAINGUARD_JAVA_IDENTITY_ID}:${CHAINGUARD_JAVA_TOKEN}" \
  https://libraries.cgr.dev/java/junit/junit/4.13.2/junit-4.13.2.jar \
  | sha256sum

2. Compute the same artifact’s checksum from Artifactory

Fetch the same artifact through the Artifactory remote repository and compute its checksum:

curl -sSf -L \
  -u "${ARTIFACTORY_USER}:${ARTIFACTORY_TOKEN}" \
  https://<artifactory-host>/artifactory/java-chainguard/junit/junit/4.13.2/junit-4.13.2.jar \
  | sha256sum

Replace artifactory-host with your Artifactory instance hostname.

The checksums returned by the commands must match.

If the checksum from the Artifactory remote repository differs from the direct fetch, or if the Artifactory fetch fails entirely, review the following before proceeding:

• URL: The remote repository URL must be set to https://libraries.cgr.dev/java/.
• Credentials: You may need to regenerate your pull token with chainctl auth pull-token --repository=java and update the Artifactory repository credentials. Expired tokens fail silently.
• Advanced configuration: Ensure all recommended Advanced settings from the remote repository configuration steps have been applied.

Do not proceed to virtual repository setup or build configuration until the checksums match.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Click Administration in the top navigation bar.
2. Select Repositories in the left hand navigation.
3. Select the Virtual tab in the repositories view.
4. Locate the chainguard-maven repository.
5. Hover over the row and click the … in the last column on the right.
6. Select Set Me Up in the dialog.
7. Click Generate Token & Create Instructions.
8. Copy the generated token value to use as the password for authentication.
9. Click Generate Settings.
10. Copy the value from a url field. They are all identical. For example, https://exampleorg.jfrog.io/artifactory/java-all/ with exampleorg replaced with the name of your organization.

Use the URL of the virtual repository in the build configuration and build a first test project. In a working setup the chainguard remote repository contains all libraries retrieved from Chainguard.

Sonatype Nexus Repository

Sonatype Nexus Repository includes a maven-public repository group out of the box. It groups access to the Maven Central Repository from the maven-central repository with the internal maven-releases and maven-snapshot repositories. Refer to the Maven Repositories documentation for Nexus for more information.

If you are using this group, you can add a proxy repository for Chainguard Libraries for Java repository for production use.

Initial configuration

Use the following steps to set up a repository in Sonatype Nexus to access Chainguard Java Libraries via the Chainguard Repository.

If you are configuring your own fallback in your repo manager, for initial testing it is advised to create a separate proxy repository for the Maven Central Repository, a separate proxy repository Chainguard Libraries for Java repository, and a separate repository group.

1. Log in as a user with administrator privileges.
2. Click the gear icon in the top navigation bar to access Server administration.

Configure a remote repository for the Chainguard Libraries for Java repository:

1. Select Repository - Repositories in the left hand navigation.
2. Click Create repository, then select the maven2 (proxy) recipe.
3. Configure the repository:
   • Name: java-chainguard
   • Maven 2 - Version policy: Release.
   • Proxy - Remote storage: Add the URL https://libraries.cgr.dev/java/
   • HTTP - Authentication Select the username Authentication type, and provide the username and password values as retrieved with chainctl.
4. Click Create repository.
5. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named java-chainguard-remediated with a URL set to https://libraries.cgr.dev/java-remediated/. Use the same authentication details.

If you are manually managing fallback, you can configure an additional java-public remote repository for Maven Central with lower priority.

Combine a new repository group and add the repositories:

1. Select Repository - Repositories in the left hand navigation.
2. Click Create repository, then select the maven2 (group) recipe.
3. Configure the repository:
   • Name: java-all
   • Under Group - Member repositories, move the new repository java-chainguard to the right. If you are using the remediated repository, move the java-chainguard-remediated repository to the right, above the java-chainguard repository.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Click Browse in the Welcome view or the browse icon (cube) in the top navigation bar.
2. Locate the URL column for the java-all repository group and click Copy.
   • For example, https://repo.example.com/repository/java-all/ (with repo.example.com replaced with the hostname of your repository manager).
3. Use your configured username and password, unless Security > Anonymous Access > Access > Allow anonymous users to access the server is activated. Details vary based on your configured authentication system.

Use the URL of the repository group, such as https://repo.example.com/repository/java-all/ or https://repo.example.com/repository/maven-public/ in the build configuration and build a first test project. In a working setup the java-chainguard proxy repository contains all libraries retrieved from Chainguard.