From 0444a3c531daa7133cd19f28795e069b3e5f35c0 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Tue, 12 May 2026 13:53:47 -0400 Subject: [PATCH 1/2] Chainguard Repository for Java Signed-off-by: s-stumbo --- content/chainguard/chainguard-repository/overview.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/chainguard/chainguard-repository/overview.md b/content/chainguard/chainguard-repository/overview.md index 31d2383a9b..2ae87c9ad2 100644 --- a/content/chainguard/chainguard-repository/overview.md +++ b/content/chainguard/chainguard-repository/overview.md @@ -21,6 +21,7 @@ As of this writing, the Chainguard Repository contains the following artifact ty | Artifact type | Description | | ----- | ----- | | [Chainguard Libraries for JavaScript](/chainguard/libraries/javascript/overview/) | Open source language dependencies rebuilt from source for JavaScript (npm). | +| [Chainguard Libraries for Java](/chainguard/libraries/java/overview/) | Open source language dependencies rebuilt from source for Java (Maven). | ## Endpoints @@ -28,7 +29,8 @@ Each artifact type is accessible via its own endpoint: | Artifact type | Endpoint | | ----- | ----- | -| Libraries for JavaScript | `libraries.cgr.dev/javascript` | +| Libraries for JavaScript | `https://libraries.cgr.dev/javascript/` | +| Libraries for Java | `https://libraries.cgr.dev/java/` | See each artifact type's documentation for authentication and configuration details. @@ -56,5 +58,6 @@ Access the Console at [console.chainguard.dev](https://console.chainguard.dev). ## **Learn more** -* [Chainguard Repository for JavaScript Libraries](/chainguard/libraries/chainguard-repository/) +* [Chainguard Libraries for JavaScript](/chainguard/libraries/javascript/overview/) +* [Chainguard Libraries for Java](/chainguard/libraries/java/overview/) From 2a5c2be4e2199d98775549f892391865b4f292a0 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Mon, 18 May 2026 13:31:51 -0400 Subject: [PATCH 2/2] Updates Signed-off-by: s-stumbo --- content/chainguard/libraries/java/overview.md | 34 +++++++++ .../libraries/javascript/overview.md | 57 +-------------- content/chainguard/libraries/overview.md | 73 +++++++++++++++++++ content/chainguard/libraries/quickstart.md | 4 +- 4 files changed, 110 insertions(+), 58 deletions(-) diff --git a/content/chainguard/libraries/java/overview.md b/content/chainguard/libraries/java/overview.md index 0f306130d8..2dab164544 100644 --- a/content/chainguard/libraries/java/overview.md +++ b/content/chainguard/libraries/java/overview.md @@ -115,6 +115,40 @@ Alternatively, you can use the token for direct access from a build tool as discussed in [Build configuration](/chainguard/libraries/java/build-configuration/). +## CVE remediation + +Chainguard Libraries for Java includes the [CVE +Remediation](/chainguard/libraries/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. + +Learn how to opt in to remediated versions in the [Java build configuration docs](/chainguard/libraries/java/build-configuration/#selecting-remediated-library-versions). + +### Troubleshooting resolution issues + +Enabling the remediated repository does not typically require clearing caches. However, clearing the cache may help when troubleshooting resolution issues. + +Maven: + +```bash +rm -rf ~/.m2/repository +``` + +Gradle: + +```bash +rm -rf ~/.gradle/caches/ +``` + +Bazel: + +```bash +bazel clean --expunge +``` + ## Manual access diff --git a/content/chainguard/libraries/javascript/overview.md b/content/chainguard/libraries/javascript/overview.md index e9b2e6d460..3ffb440029 100644 --- a/content/chainguard/libraries/javascript/overview.md +++ b/content/chainguard/libraries/javascript/overview.md @@ -229,60 +229,5 @@ Repository](/chainguard/chainguard-repository/overview/). By default, the endpoi only Chainguard-built packages. When the upstream fallback is enabled, upstream packages are subject to additional security controls before being served. -### Enable the upstream repository +Learn about managing fallback and cooldown controls in the [Chainguard Libraries Overview](/chainguard/libraries/overview/). -To enable or change upstream fallback configuration, use the [`chainctl -libraries entitlements` -command](/chainguard/chainctl/chainctl-docs/chainctl_libraries_entitlements_create/). - -The following command creates or updates an entitlement to Chainguard Libraries -for JavaScript, adds the npm upstream fallback policy, and configures a 7-day cooldown: - -```bash -chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM --cooldown-days=7 -``` - -### Fallback options - -The following options are available: -* **No upstream fallback (default)**: Only Chainguard-built packages are served. -* **Upstream fallback enabled with cooldown**: Upstream packages are available after passing a cooldown period and malware scan. The same cooldown period is also enforced for Chainguard-built packages when the upstream repository is enabled, so dependency trees resolve consistently across both sources. - -#### Configuring the cooldown period - -When upstream fallback is enabled, users with the Owner role can configure the cooldown with `chainctl`: - -```bash -chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM --cooldown-days=3 -``` -The default cooldown period is 7 days. Note that shorter cooldown periods increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. - -> **Upstream fallback best practices** -> Upstream packages are proxied directly from npm and are not rebuilt or authored by Chainguard as part of our Libraries product. The cooldown period and malware scanning provide a supplemental baseline of protection to your own security practices, but you are solely responsible for independently evaluating and validating all upstream artifacts before use in your environment. - -### Security controls - -#### Malware scanning -All packages served from the upstream fallback are scanned for malware before being made available. Any package version with a detected malware identifier (MAL ID) from the public OSV feed is blocked and will not be served. - -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. - -#### Cooldown period - -When fallback is enabled, upstream npm 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 npm 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 package version is requested and 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. - -### How package resolution works - -When you request a JavaScript 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 npm registry, serves it to the client, and caches it in the upstream mirror for future requests. -* **Malware detected**: Any package version with a known malware identifier (MAL ID) is blocked and never served, whether it originates from Chainguard builds or the npm upstream. Malware scanning runs on all packages, including those proxied from npm. - * 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 for JavaScript is not a full mirror of npm by design. 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. diff --git a/content/chainguard/libraries/overview.md b/content/chainguard/libraries/overview.md index 357dc2510d..90382eab78 100644 --- a/content/chainguard/libraries/overview.md +++ b/content/chainguard/libraries/overview.md @@ -133,6 +133,79 @@ After that six-month window closes, Chainguard Libraries will: - 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 built-in fallback managed through the [Chainguard +Repository](/chainguard/chainguard-repository/overview/): + +- Chainguard Libraries for JavaScript supports fallback to +the upstream npm Registry +- Chainguard Libraries for Java supports fallback to Maven Central + +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. + +### Enable the upstream repository + +To enable or change upstream fallback configuration, use the [`chainctl +libraries entitlements` +command](/chainguard/chainctl/chainctl-docs/chainctl_libraries_entitlements_create/). + +The following command creates or updates an entitlement to Chainguard Libraries +for JavaScript, adds the npm upstream fallback policy, and configures a 7-day cooldown: + +```bash +chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM --cooldown-days=7 +``` + +### Fallback options + +The following options are available: +* **No upstream fallback (default)**: Only Chainguard-built packages are served. +* **Upstream fallback enabled with cooldown**: Upstream packages are available after passing a cooldown period and malware scan. The same cooldown period is also enforced for Chainguard-built packages when the upstream repository is enabled, so dependency trees resolve consistently across both sources. + +#### Configuring the cooldown period + +When upstream fallback is enabled, users with the Owner role can configure the cooldown with `chainctl`: + +```bash +chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM --cooldown-days=3 +``` +The default cooldown period is 7 days. Note that shorter cooldown periods increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. + +> **Upstream fallback best practices** +> Upstream packages are proxied directly from npm or Maven Central, and are not rebuilt or authored by Chainguard as part of our Libraries product. The cooldown period and malware scanning provide a supplemental baseline of protection to your own security practices, but you are solely responsible for independently evaluating and validating all upstream artifacts before use in your environment. + +### Security controls + +#### Malware scanning +All packages served from the upstream fallback are scanned for malware before being made available. Any package version with a detected malware identifier (MAL ID) from the public OSV feed is blocked and will not be served. + +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. + +#### 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 npm or Maven Central 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 package version is requested and 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. + +### How package resolution works + +When you request a JavaScript or Java 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 detected**: Any package version with a known malware identifier (MAL ID) is blocked and never served, whether it originates from Chainguard builds or the npm upstream. Malware scanning runs on all packages, including those proxied from npm. + * 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 for JavaScript is not a full mirror of npm by design. Similarly, Chainguard Repository for Java is not a full mirror of Maven Central. 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) diff --git a/content/chainguard/libraries/quickstart.md b/content/chainguard/libraries/quickstart.md index f274d5b719..a51d56e936 100644 --- a/content/chainguard/libraries/quickstart.md +++ b/content/chainguard/libraries/quickstart.md @@ -195,8 +195,8 @@ Check out minimal example projects for > are solely responsible for independently evaluating and validating all > upstream artifacts before use in your environment. >
Learn more about upstream -> fallback policy and controls in the [JavaScript -> overview](/chainguard/libraries/javascript/overview/#upstream-fallback-policy-and-controls). +> fallback policy and controls in the [Libraries +> overview](/chainguard/libraries/overview/#upstream-fallback-and-controls). Check out minimal example projects for [npm](/chainguard/libraries/javascript/build-configuration/#minimal-example-project),