Manage and update dependencies

Chainguard Libraries for Java operates transparently after configuring your repository manager or your build tool, automatically providing security-enhanced versions of your Maven dependencies. After you configure Chainguard Libraries for Java, use this page for recurring maintenance tasks.

Chainguard Libraries serves Chainguard-built artifacts when they are available. When upstream fallback is enabled, an artifact that Chainguard has not yet built may first be served through Chainguard’s upstream tier. With build pinning, the exact package version remains pinned to the artifact tier your organization first received, so a previously downloaded upstream artifact is not immediately replaced when Chainguard publishes a built equivalent.

Existing artifacts may already be present in a developer’s local Maven cache or in a repository manager cache, so a previously downloaded upstream artifact is not automatically replaced just because a Chainguard-built equivalent becomes available.

The following sections detail optional management, maintenance, and auditing steps on the repository manager and the build tool.

Verify dependencies

Use chainctl libraries verify to check whether an artifact comes from Chainguard Libraries:

chainctl libraries verify path/to/artifact.jar

For Java, run verification against the individual JAR files in the local Maven repository cache before assembling a fat JAR or other bundled artifact. The verifier identifies artifacts using their checksums and provenance information; it cannot reliably trace merged classes in a fat JAR back to their source JARs.

For command options, permissions, and supported artifact types, refer to the Verification documentation.

Inspect artifacts in a repository manager

If your organization uses a repository manager, you can inspect the Chainguard proxy or remote repository to audit which artifacts were retrieved through Chainguard Libraries. Use the repository manager’s package or browsing view to locate an artifact and compare its coordinates, file name, size, checksum, and available metadata.

Refer to the Verification page for more information on verifying artifacts in a repository manager.

Refresh cached artifacts

The number of available artifacts in Chainguard Libraries for Java increases over time. If an artifact was already retrieved from the Maven Central Repository and is available in your repository manager or local repository it is not automatically replaced with the equivalent Chainguard Library version.

To adopt a newer Chainguard-built artifact, check out the build pinning documentation for instructions on removing existing pinned versions.

Refreshing cached artifacts may also be necessary to solve other issues, such as stale or corrupted artifacts or metadata, repository configuration changes, and resolution troubleshooting. To refresh the same artifact your organization is already using:

1. Remove the affected artifact from the developer’s local Maven cache.
2. If applicable, remove the affected artifact from the repository manager’s proxy cache, following your organization’s cache-management procedure.
3. Run the build again so Maven requests the artifact from the configured Chainguard Libraries repository.
4. Verify the resulting JARs with chainctl libraries verify.

If an exact package version is pinned, Chainguard continues to serve the pinned artifact after the cache is refreshed.

Prefer removing only the affected artifact or dependency subtree. Avoid broadly deleting production or shared caches unless you understand the operational impact and have a recovery plan.

Prepare for checksum changes

A checksum identifies the exact bytes of a library artifact. Chainguard-built artifacts have different checksums from upstream artifacts with the same Maven coordinates and version because they are rebuilt in a secured environment.

During initial migration if your project records checksums or integrity values, update those values as part of migration or cache refresh, then run your normal tests and verification checks. For a full migration sequence, including cache and project-configuration handling, check out the migration guide for Chainguard Libraries for Java.

For organizations that use Chainguard’s upstream fallback, build pinning keeps the exact artifact previously served for that package version. This prevents a later Chainguard rebuild from unexpectedly changing the checksum. You must remove the pin to adopt a newer Chainguard build. Refer to Build pinning for more information.

Security and policy guidance

Refer to the following pages for topics broader than routine dependency maintenance:

• CVE remediation for Chainguard Libraries for remediated library versions and upgrade guidance.
• Chainguard Libraries policies for upstream fallback, cooldown, and package-serving policy.
• Error messages and the Chainguard Libraries FAQ for troubleshooting and edge cases.