# Chainguard Libraries overview URL: https://chainguard-docs-preview-git-okta-scim-update.chainguard.app/chainguard/libraries/introduction/overview.md Last Modified: September 28, 2026 Tags: Chainguard Libraries, Overview Learn about Chainguard Libraries, providing enhanced security for Java, JavaScript, and Python dependencies through automated patching and comprehensive supply chain protection. [Chainguard Libraries](https://www.chainguard.dev/libraries) is a secure catalog of language dependencies that replaces your team’s reliance on [npm](https://www.npmjs.com/), [PyPI](https://pypi.org/), and [Maven Central](https://central.sonatype.com/). Every package pulled by your team or AI agents passes through multiple layers of defense, including malicious behavior scanning, building from source, and cooldowns that help prevent malware from entering your environment. As frontier coding models advance, attackers are creating more sophisticated social engineering campaigns and malware injections to exfiltrate enterprise secrets. Chainguard Libraries prevents malware instead of making developers pause work, triage incidents, and respond after compromise. ## Background Open source libraries distributed through public repositories face several security challenges: maintainers may not promptly address vulnerabilities, binary artifacts can be compromised, and the sheer volume of transitive dependencies makes manual security management impractical. While these repositories enable rapid development, they also introduce supply chain risks that traditional security approaches struggle to address. While convenient, these services remove the direct link from your application to the source code of a specific project, and create a potential risk for quality issues with the artifacts, man-in-the-middle attacks, removal or override of libraries with vulnerable or malicious versions, and other issues. The [Supply-chain Levels for Software Artifacts (SLSA)](https://slsa.dev/) specification describes these risks and how to protect your software against them. Although this is a common way of accessing open source binaries, it requires you to put tremendous trust into the following aspects for the dozen or even hundreds of open source libraries you typically use for each application: * Maintainers and especially release managers of the projects * Local workstation or CI setup used for the release build * Release process mechanisms to create the binaries * Transport of the binaries from the build system to the public repositories * Management of access to the repositories * Monitoring of repositories for attacks as well as harmful or malicious binaries * Traffic to public repositories and attacks on the transport to your infrastructure There are no real guarantees as to the actual provenance of the software code. Repositories also vary greatly in quality and there is no guarantee that the upstream source of a project is available in a repository. In addition, these repositories also hold non-open source binaries of libraries. All these factors create uncertainty. Using these public repositories can feel as opaque as picking up a USB drive off of the sidewalk and plugging it into your laptop. ## Introduction Chainguard Libraries rebuilds supported language dependencies from verified upstream source in the Chainguard Factory and distributes the resulting artifacts through Chainguard’s secure repositories. The Chainguard Factory is Chainguard’s dedicated build infrastructure for producing software from source in a hardened, SLSA-certified environment, with verifiable provenance and other metadata for customers. Chainguard Libraries can also serve eligible upstream packages through the [Chainguard Repository](/chainguard/chainguard-repository/overview/), where security controls such as malicious behavior scanning and cooldowns help prevent unsafe packages from reaching your environment. Chainguard Libraries and the use of the Chainguard Factory reduce software supply chain risk by combining trusted source rebuilds with security controls for upstream packages: * Chainguard-built libraries are rebuilt from verified upstream source in the Chainguard Factory and distributed with verifiable provenance and SBOMs. For CVE-remediated libraries, the fix is applied to the artifact itself and accompanied by this metadata, giving auditors evidence they can verify directly rather than requiring them to correlate a separate patch file with a dashboard. See the [vulnerability scanning documentation](/chainguard/libraries/policies-and-security/scanners/) for scanner support details. * When a requested package is not yet available as a Chainguard build, the Chainguard Repository can serve eligible upstream packages through configured fallback policies, subject to malicious behavior scanning and cooldowns before they are served. * If there is no open source code available, no binaries are made available by Chainguard. This eliminates any license-related risks from commercial libraries. The policy and process to have no binaries without source also removes the danger from malicious artifacts, since these artifacts do not provide source code in public code repositories. Chainguard Libraries is available for the following library ecosystems: * Java and the larger Java Virtual Machine (JVM) ecosystem with [Chainguard Libraries for Java](/chainguard/libraries/java/overview/) * JavaScript and the larger ecosystem around JavaScript, TypeScript, npm, React, and others with [Chainguard Libraries for JavaScript](/chainguard/libraries/javascript/overview/) * Python and the larger ecosystem with [Chainguard Libraries for Python](/chainguard/libraries/python/overview/) To move an existing project over, follow the migration guide for [Java](/chainguard/libraries/java/migration/), [JavaScript](/chainguard/libraries/javascript/migration/), or [Python](/chainguard/libraries/python/migration/). ## Chainguard criteria for building a library Chainguard Libraries includes thousands of Java, JavaScript, and Python libraries, and coverage is continuously growing as we add more packages and versions over time. Chainguard aims to build libraries that are relevant to our customers and that support broader software supply chain security goals. However, it is not always feasible or safe to rebuild and redistribute every package from public registries such as Maven Central, npm, or PyPI. ### Licensing and source availability Chainguard Libraries provides a trusted source for Java, JavaScript, and Python dependencies. Our goal is to prevent malware exposure and reduce the security work developers must do after packages enter their environments. For a library to be built and distributed by Chainguard: * Source code must be available and verifiable * The project’s source must be available in a source code manager (such as GitHub or GitLab). Packages that do not provide a valid or verifiable source URL cannot be rebuilt in the Chainguard Factory and are out of scope. * Licensing must allow rebuild and redistribution * The project must be licensed in a way that allows Chainguard to rebuild and redistribute it to customers. ### Library version support Chainguard builds libraries using supported language toolchains in our hardened build environment. We do not aim to replicate all historical runtime environments exactly, but we do attempt to preserve runtime compatibility where it is safe to do so. For older or EOL projects, our ability to build and remediate issues is constrained by runtime compatibility and by upstream maintenance practices. Our current minimum supported toolchains are: * **Python**: Python 3.10 and higher. * **Java**: Java 8 and higher. * **JavaScript**: Any supported, non-EOL version of Node.js. We will attempt to rebuild any libraries that meet the [licensing and source availability criteria](#licensing-and-source-availability) using the supported toolchains. ### EOL version support When a library version reaches end of life (EOL) upstream, Chainguard Libraries continues to build packages and provide security fixes for that version for six months beyond the upstream EOL date. After that six-month window closes, Chainguard Libraries will: * No longer build new packages that require the EOL version * No longer provide security fixes for packages built against the EOL version * Continue to serve previously built packages ## Upstream fallback and controls Chainguard Libraries support an optional protected upstream fallback, managed through the [Chainguard Repository](/chainguard/chainguard-repository/overview/). By default, the Chainguard library endpoints serve only Chainguard-built packages. When the upstream fallback is enabled, upstream packages are subject to additional security controls before being served. > Note: When using `chainctl` to configure upstream fallback or cooldown duration, it can take up to 30 minutes for the repository changes to take effect. ### Enable the upstream repository To enable or change upstream fallback configuration, use the [`chainctl libraries entitlements` command](/platform/chainctl/chainctl-docs/chainctl_libraries_entitlements_create/). For example, the following command creates or updates an entitlement to Chainguard Libraries for JavaScript, and adds the npm upstream fallback policy. Enabling upstream fallback includes a 7-day cooldown by default, which can also be configured: ```bash chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM ``` For JavaScript, you can also enable upstream fallback in the Chainguard Console. For Java and Python, you cannot currently enable fallback or view upstream vs. Chainguard-built packages via the Chainguard Console; you must use `chainctl` to enable fallback for Java and Python. ### Fallback options The following options are available: * **No upstream fallback (default)**: Only Chainguard-built packages are served. * **Upstream fallback enabled with default 7-day cooldown**: Upstream packages are available after passing a configurable cooldown period and malware scan. The same cooldown period is enforced across Chainguard-built packages and upstream packages, so that dependency trees resolve consistently across both sources. When the upstream fallback is enabled, [build pinning](/chainguard/libraries/policies-and-security/build-pinning/) keeps a package version you pulled from upstream stable even after Chainguard publishes its own build of that version. This prevents unexpected checksum changes across rebuilds. ### Malware and greyware detection Chainguard's [source code and maintainer behavior scanning](https://www.chainguard.dev/unchained/the-expanding-threat-landscape-chainguard-now-scans-source-code-for-traditional-malware-and-greyware/) identifies and blocks malicious and greyware packages in Chainguard Libraries via the Chainguard Repository. This includes packages that are publicly reported as malicious (including packages associated with OSV malware IDs) and packages that Chainguard determines are unsafe through its own malware source code scanning, even when no public malware advisory exists yet. Malware detection is continuous. If a version that was previously cached is later identified as malicious, it is added to the block list and will be blocked on subsequent requests. Chainguard's scanning evaluates multiple signal types, including: * **Credential and data theft**: The package harvests secrets (for example, GitHub tokens or SSH keys) and sends sensitive data out of the environment. * **Backdoors and malicious behavior**: The package obfuscates malicious behavior, including backdoor setup, remote access, staged payloads, and more. The code may contact known malicious infrastructure to fetch or run additional payloads. * **Install-time script execution**: The package automatically executes malicious behavior through pre-install and post-install lifecycle scripts. * **Typosquatting and impersonation**: The package is named or brand-engineered to deceive users into downloading the wrong package. * **Compromised or untrusted releases**: The package exhibits signs that a release cannot be trusted. #### View blocked packages You can view blocked packages [in the Chainguard Console](/chainguard/libraries/introduction/browse/#view-malware-information), [using `chainctl` commands](/platform/chainctl/chainctl-docs/chainctl_libraries_packages_malware_list/), or [via the API](#malware-api). For more details on the errors a blocked package surfaces across ecosystems, see the [Error messages documentation](/chainguard/libraries/troubleshooting/errors/). #### Malware API Chainguard's malware API endpoint provides access to Chainguard's malware blocklist. You can use it to retrieve a list of packages that have been identified as malicious and blocked by Chainguard. Learn more about it in the [API documentation](/platform/api/spec-api-v1/#tag/malware). Expand the following section to see examples: **Malware API examples** First, get an access token: ```bash TOKEN=$(chainctl auth token --audience=https://console-api.enforce.dev) ``` Then, use the API to query malware details. List blocked packages for an ecosystem. For example, to see the 10 most recent JavaScript packages blocked: ```bash curl -s \ -H "Authorization: Bearer $TOKEN" \ "https://console-api.enforce.dev/libraries/v1/malware/blocklist?ecosystem=NPM&page_size=10" \ | jq . ``` List packages blocked since a specified date. For example, to see PyPI packages blocked since July 1, 2026: ```bash curl -s \ -H "Authorization: Bearer $TOKEN" \ "https://console-api.enforce.dev/libraries/v1/malware/blocklist?ecosystem=PYPI&since=2026-07-01T00:00:00Z&page_size=10" \ | jq . ``` Check whether a specific package is blocked. For example, to check for blocked `axios` packages: ```bash curl -s \ -H "Authorization: Bearer $TOKEN" \ "https://console-api.enforce.dev/libraries/v1/malware/blocklist?ecosystem=NPM&packageName=axios" \ | jq . ``` ### Cooldown period When fallback is enabled, upstream packages are subject to a cooldown period from their publication date before the Chainguard Repository will serve them. The cooldown is an additional layer of security that provides a window for the security community to identify and report malicious packages before your builds can pull them. The cooldown applies globally across Chainguard-built packages and upstream packages served through the fallback. This prevents installs from failing when a Chainguard-built package depends on an upstream dependency that is still under the cooldown window. If a requested package version falls within the cooldown period, the package manager will output a 404 error. The package becomes available once it has passed the cooldown period and cleared malware scanning. Learn how to create, enforce, disable, and list policies in the [Libraries policies documentation](/chainguard/chainguard-repository/library-policies/) page. ### How package resolution works When you request a package from the Chainguard Repository, the following logic applies: * **Chainguard-built package available**: The package is served directly from Chainguard's rebuilt artifact store, complete with SBOM, provenance, and signatures, subject to the configured cooldown. * **Package not yet built by Chainguard**: If upstream fallback is enabled, the repository checks whether the package has passed the cooldown period and malware scan. * **Within the cooldown period**: The request returns an error. This prevents newly published packages — which carry higher malware risk — from being served immediately. * **After the cooldown period**: If upstream fallback is enabled and the version is outside the cooldown window and passes malware scanning, the repository pulls the version through from the upstream registry, serves it to the client, and caches it in the upstream mirror for future requests. * **Malware or greyware detected**: Any package version that is detected for malware or greyware is blocked, whether it originates from Chainguard's builds or the upstream fallback. * Malware scanning checks all packages against the Open Source Vulnerabilities (OSV) database, which includes the OpenSSF Malicious Packages feed among other sources. Any package version flagged with a malware identifier is blocked. This covers reported malicious packages across the npm ecosystem. > **Note**: Chainguard Repository is not a full mirror of upstream repositories. Packages are screened for malware before being made available. Some packages may be delayed by the cooldown period or permanently blocked if flagged as malicious. ## Other resources * [Chainguard Libraries product page](https://www.chainguard.dev/libraries) * [ Learning Lab for October 2025 on Chainguard Libraries for JavaScript and CVE remediation for Python libraries](/software-security/learning-labs/ll202510/) * [ Learning Lab for June 2025 on Chainguard Libraries for Python](/software-security/learning-labs/ll202506/) * [ Learning Lab for May 2025 about Chainguard Libraries for Java](/software-security/learning-labs/ll202505/) Blog posts * [Mitigating Malware in the npm Ecosystem with Chainguard Libraries](https://www.chainguard.dev/unchained/mitigating-malware-in-the-npm-ecosystem-with-chainguard-libraries ) * [Announcing Chainguard Libraries for JavaScript: Malware-Resistant Dependencies Built Securely from Source](https://www.chainguard.dev/unchained/announcing-chainguard-libraries-for-javascript-malware-resistant-dependencies-built-securely-from-source) * [Registries and the npm Breach: Securing the Weakest Link in the Software Supply Chain](https://www.chainguard.dev/unchained/registries-and-the-npm-breach-securing-the-weakest-link-in-the-software-supply-chain) * [Malware-Resistant Python without the Guesswork](https://www.chainguard.dev/unchained/malware-resistant-python-without-the-guesswork) * [This Shit is Hard: Java Archeology at a Massive Scale](https://www.chainguard.dev/unchained/this-shit-is-hard-java-archeology-at-a-massive-scale) * [Mitigating Malware in the Python Ecosystem with Chainguard Libraries](https://www.chainguard.dev/unchained/mitigating-malware-in-the-python-ecosystem-with-chainguard-libraries) * [Announcing Chainguard Libraries for Python: Malware-Resistant Dependencies Built Securely from Source](https://www.chainguard.dev/unchained/announcing-chainguard-libraries-for-python-malware-resistant-dependencies-built-securely-from-source) * [Announcing Chainguard Libraries: Guarded Java Language Dependencies Built from Source](https://www.chainguard.dev/unchained/announcing-chainguard-libraries-guarded-java-language-dependencies-built-from-source)