AI Docs Bundle
Join Our Community Slack Contact
Chainguard Libraries troubleshooting and FAQ

Chainguard Libraries FAQ

Frequently asked questions about Chainguard Libraries, including security benefits, supported ecosystems, and how automated patching protects against supply chain attacks
  12 min read
Chainguard Libraries Overview

How does Chainguard Libraries help developers?

Watch: How Chainguard Libraries helps developers

The following video focuses on Chainguard’s built-from-source model: when a rebuilt package is available, Chainguard serves it with verifiable provenance and SBOMs. Not every package or version can be built immediately, so the Chainguard Repository also supports an optional, policy-governed upstream fallback. When enabled, Chainguard-built packages are preferred, while eligible upstream packages are subject to configurable controls such as a cooldown period and malware and greyware scanning. Packages identified as malicious are blocked.

Transcript

Interviewer: So how does Chainguard Libraries help developers?

Dustin Kirkland: Yeah, so building off of that Chainguard Factory, we’ve actually repurposed all of that automation to not just build packages and containers, but actually fetch libraries directly from their upstream source and recompile those Java binaries—JARs—and those Python binaries—wheels—in a new format, or in the same format rather, but totally bootstrapped from source. The fact that we can rebuild those libraries means that we can actually patch them if necessary.

Now, in doing so, we’ve created an entire repository of Python wheels and Java JARs that we can publish and hydrate into a customer’s environment, so that their developers can retrieve their libraries from a secure source, from a trusted source, and avoid malicious packages—deliberately modified or intentionally compromised packages—which, you know, we find in PyPI.org or in Maven Central from time to time. But Chainguard building those from source ensures that that entire open source ecosystem is secured in the same way that we’re securing the packages and the container ecosystems.

How does Chainguard Libraries plug into a developer’s workflow?

Watch: How Chainguard Libraries plugs into a developer's workflow

Transcript

Interviewer: So Dustin, how does Libraries actually plug into a developer workflow?

Dustin Kirkland: Yeah, so I used the word “hydrate” earlier. We hydrate typically a JFrog Artifactory or a Cloudsmith—we hydrate that registry of artifacts with Chainguard securely built artifacts. And we produce this constant flow of tens of thousands of those library version tuples into that environment. And our customers can come to us and get a license for our entire Java ecosystem or our entire Python ecosystem.

So from that sense, we’re certainly not an artifact registry. You use the artifact registry that’s typically used inside of your organization. We help populate that with secure artifacts. This is fairly similar to our approach with containers, where we’re not a scanner, but what we’re trying to do is complement the scanners that you have with better containers that have fewer CVEs, and you end up with cleaner scan results. So in this artifact sense, we’re not an artifact registry, but we’re putting better binaries into that artifact destination.

Interviewer: So once the artifact registry is set up, is there any changes to actual developers’ workflow, or will it just work?

Dustin Kirkland: Typically not. I mean, if inside of your organization you already have an artifact registry and your developers are pip installing or maybe even importing those classes and libraries from that artifact repository, we’re just replacing the artifacts that may have additional vulnerabilities or potentially malicious code with artifacts that have fewer vulnerabilities and are immune to that malicious code.

What security issues can Chainguard Libraries prevent?

As detailed on the background and introduction pages, Chainguard Libraries are built directly from source in the Chainguard Factory and the resulting binaries are directly provided to you by Chainguard. Chainguard operates the whole supply chain for the package lifecycle as one reliable, secure partner. You can therefore avoid issues from the following software supply chain attack surface points:

  • Build pipeline
  • Build system
  • Dependency injection
  • Bypass of CI/CD systems
  • Library distribution
  • Library consumption

More information about these stages in the software supply chain is available on the Supply chain Levels for Software Artifacts (SLSA) website.

The following examples are issues, attacks, and compromises that affect stages of the software supply chain for libraries across different language ecosystems:

Malicious GlueStack packages
  • This May 2025 attack uploaded compromised packages to PyPI and npm that enable remote shell access and uploading files to compromised machines
  • Chainguard Libraries would have protected against this attack. First, the packages have invalid upstream source URLs so there was no source repository. In the case of the lone exception (a package with a valid source repository link), no code was present for Chainguard to build a valid package.
  • The Hacker News blog post on the attack
Ultralytics Python project
  • Attackers compromised the GitHub Actions workflows for the Ultralytics repository, injecting malware into PyPI package releases.
  • Attackers pushed out four malicious versions of the Ultralytics YOLO project over the course of a week (8.3.41, 8.3.42, 8.3.45, 8.3.46).
  • Ultralytics YOLO is a widely-used fast object detection neural network library downloaded about five million times per month. Users affected during this period were infected with cryptomining malware.
  • Chainguard Libraries would have prevented this attack by building the project from clean source. No source code was modified by attackers during this incident.
  • Refer also to PyPI attack analysis and bleepingcomputer blog post.
Lottie Player
  • Hackers gained access to the NPM registry by compromising a developer authentication token.
  • Token used to upload a compromised version of Lottie Player.
  • The malicious package drained crypto wallet funds.
  • Chainguard Libraries would have prevented this attack by building the project from clean source. No source code was modified by attackers during this incident.
  • Refer also to npm package Lottie-Player compromised in supply chain attack, Nov 2024.
MavenGate
  • MavenGate is a proof of concept for exploiting abandoned Java library domains.
  • Vulnerabilities in Maven dependency management allow unauthorized package replacements.
  • All Java build tools using Maven repositories, including Maven, Gradle, and Ant, could be affected.
  • MavenGate relied on the use of multiple repositories and any attack with the proposed mechanism would not publish source code. Chainguard Libraries replace other repositories and the use of Chainguard Libraries, based on building from the original source, would have prevented an attack using this approach
  • Refer also to The Hacker News article, Oversecured blog post, and Sonatype’s take as Maven Central operator.
XZ Utils backdoor
  • Example of a supply chain attack leveraging social engineering by a patient actor
  • Sophisticated backdoor that had remote code execution capability and the potential to affect many systems
  • Vulnerability was patched within hours of disclosure by reverting to a previous version known to be safe.
  • Malicious source tarball and binaries were distributed successfully, but source code repository was not compromised.
  • Since no source code was compromised, a similar attack on a protected library ecosystem would be prevented by Chainguard Libraries
  • XZ Utils is written in C and therefore not available as an ecosystem protected by Chainguard Libraries. However, Chainguard Containers include XZ Utils packages. These are also built from source and are not affected.
  • Refer also to Wikipedia article and official page from the XZ data compression.
Other examples and resources

The following links provide details for other software supply chain attacks. Depending on the exact details some of these attacks and approaches are prevented by use of Chainguard Libraries.

Find pointers to further resources in the Software supply chain reading list.

Why do the Chainguard library checksums differ from those published by upstream repositories?

Chainguard rebuilds libraries from source in a controlled environment to improve supply-chain security. As a result, while functionality remains the same, build metadata and generated content, such as SBOMs, differs from upstream distributions. Whether Chainguard library checksums match upstream depends on the ecosystem and build process.

During initial migration to Chainguard Libraries, some common causes of checksum errors include:

  • Artifacts were previously cached from upstream repositories
    • Example: Maven’s .m2 or Gradle’s cache.
  • Dependencies are pinned to upstream checksums or hashes
    • Example: JavaScript’s package-lock.json or yarn.lock.
  • Repository managers or build tools enforce strict verification
    • Example: Artifactory validating against Maven Central.

After you migrate, build pinning keeps a version you pulled from the upstream fallback stable when Chainguard later publishes its own build, so checksums don’t change unexpectedly across rebuilds.

What’s the difference between malware‑hardened libraries and CVE remediation?

Malware‑hardened libraries are the baseline Chainguard Libraries experience: Chainguard rebuilds open source Java, JavaScript, and Python dependencies from upstream source in the Chainguard Factory, a controlled, SLSA‑aligned build environment, and publishes them to hardened registries for customers to consume. This closes off most supply chain malware vectors compared to pulling directly from public registries like Maven Central, npm, and PyPI.

CVE remediation is an additional feature where Chainguard backports High and Critical vulnerability fixes from newer upstream releases to older versions that customers are still using, particularly when upstream maintainers no longer ship patches for those older versions. Remediated versions are:

  • Published in a separate repository: https://libraries.cgr.dev/python-remediated/simple/ for Python and https://libraries.cgr.dev/java-remediated/ for Java.
  • Given a local version suffix – like +cgr.N for Python (for example, 2.0.0+cgr.1) and -0.cgr.N for Java – so dependency resolvers can distinguish them from non‑remediated upstream versions while still preferring the remediated build during resolution.

Why might I still see errors with the upstream fallback enabled through the Chainguard Repository?

Chainguard offers an upstream fallback through the Chainguard Repository as a single, managed endpoint for each ecosystem. This endpoint:

  • Serves Chainguard‑built packages first, rebuilt from source.
  • Serves upstream packages for versions that are not yet available from Chainguard. Chainguard scans these packages for malware and greyware before serving them, and subjects them to configurable policies such as a cooldown period.

Because of those controls, you may still see failed pulls when the upstream fallback is enabled, for example when:

  • A package or version is blocked by malware detection and therefore intentionally not served from upstream.
  • A recently published version is still in the cooldown period, so the repository will not yet serve it.
  • The requested package/version truly does not exist in either Chainguard’s catalog or upstream.

For customers, this can surface as an error from the Chainguard endpoint even though a version appears in the public registry.

For more details on the errors you may see when a package is blocked for these reasons, see the Error messages documentation.

What are Chibbies?

Chibbies is the internal codename for the Chainguard Libraries. It evolved from Chainguard Libraries being shortened to Chainguard Libbies, and then finally to Chibbies.

JFrog Artifactory troubleshooting

The following questions apply to repo manager configurations for Chainguard Libraries, using JFrog Artifactory. Learn more about using a repo manager in the global configuration pages for each ecosystem: Java, JavaScript, Python.

What are the most common setup mistakes when using Artifactory with Chainguard Libraries?

Follow these steps for general troubleshooting:

  • Verify the token and repository settings.
    • Confirm that the token is scoped correctly, not expired, and copied correctly. Also confirm that the repository URL is the correct language-specific endpoint and that the expected remote repository settings are in place.
  • Validate pulling packages with direct access.
    • Attempt to pull a package directly from the Chainguard endpoint from a controlled environment. This helps you confirm that the token works and that the package is available independently of Artifactory.
    • Attempt to pull the same package through the Artifactory remote or virtual repository and compare the result.
    • If direct access works but the Artifactory path fails, check the network path between Artifactory and the Chainguard endpoint. This is where firewall restrictions, proxy behavior, TLS inspection, or object-storage allowlisting issues may have an impact.
  • Test with a real package fetch.
    • The Test button in Artifactory is not a reliable way to confirm that your integration is working as expected. Instead, use a real package fetch, install, or checksum comparison.
  • If results aren’t as expected, clear one cache layer at a time and rerun the same test.

Why might I see TLS or SSL handshake errors and authentication failures after configuring Artifactory with Chainguard Libraries?

In some cases, authentication failures or malformed token behavior are caused by traffic inspection or proxy-layer handling. When troubleshooting, check the following:

  • Whether a proxy, TLS inspection layer, or MITM device is in path
  • Whether the full certificate chain is installed correctly
  • Whether the environment uses an internal CA
  • Whether the runtime, package manager, and repository manager trust the same CA bundle
  • Whether the proxy is modifying or normalizing headers, tokens, or request format

Why might I experience timeouts or “connection refused” errors after configuring Artifactory with Chainguard Libraries?

Firewall rules can prevent dependency resolution or break integration behavior. This is often observed when the repository manager can reach one destination but not another required upstream host or storage host. When troubleshooting, check the following:

  • Allowed outbound destinations
  • DNS resolution
  • Port restrictions
  • Whether the repository manager can reach all required upstream hosts
  • Whether object-storage or redirect targets also need to be allowlisted

Why might I experience authentication loops, 4xx or 5xx responses, incorrect endpoint routing, stale artifacts, or behavior that differs between direct and proxied paths after configuring Artifactory with Chainguard Libraries?

Proxy layers can change headers, certificate handling, path routing, protocol support, and cache behavior. When troubleshooting, check the following:

  • Whether a forward proxy, reverse proxy, or both are present
  • Header rewriting
  • Path rewriting
  • Auth forwarding
  • TLS termination point
  • HTTP/2 support where required
  • Cache behavior at each layer

Why might I experience inconsistent fallback behavior, outdated package metadata, or inconsistent experience between users after configuring Artifactory with Chainguard Libraries?

Caching is a common cause of unexpected behavior during onboarding and testing. Builds can continue using previously cached public-registry artifacts or stale metadata even after you switch a repository over to Chainguard. When troubleshooting, check the following:

  • Local package manager cache
  • Artifact repository cache
  • Proxy cache
  • CI/CD runner cache

Clear one cache layer at a time and rerun the same test after each change. Avoid clearing multiple cache layers simultaneously unless the steps are documented. If you are switching an existing Artifactory repository to Chainguard, invalidate or zap the remote cache before concluding that the configuration is broken.

Related Articles

Chainguard Libraries overview

Learn about Chainguard Libraries, providing enhanced security for Java, JavaScript, and Python dependencies through …

  11 min read

Last updated: 2026-09-10 14:55

Error messages Prev   Overview of Chainguard OS   Next