From 089c3c33168f177eb5a35c8b561d6dafa2398b13 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Tue, 28 Apr 2026 15:26:05 -0400 Subject: [PATCH 1/5] Add Chainguard Repo cooldown and pull-through cache Signed-off-by: s-stumbo --- .../libraries/javascript/overview.md | 27 ++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/content/chainguard/libraries/javascript/overview.md b/content/chainguard/libraries/javascript/overview.md index c4cd96f33e..ec55abdd03 100644 --- a/content/chainguard/libraries/javascript/overview.md +++ b/content/chainguard/libraries/javascript/overview.md @@ -238,16 +238,25 @@ libraries entitlements` command](/chainguard/chainctl/chainctl-docs/chainctl_libraries_entitlements_create/). The following command creates or updates an entitlement to Chainguard Libraries -for JavaScript and adds the npm upstream fallback policy: +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 +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. +* **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. Setting `--cooldown-days=0` disables the cooldown. Note that shorter cooldown periods reduce friction for new versions but 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. @@ -257,19 +266,23 @@ The following options are available: #### 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 default 7-day cooldown from their publication date before the Chainguard Repository will serve them. The cooldown is an additional layer of security on top of malware scanning. It provides a window for the security community to identify and report malicious packages before your builds can pull them. +When fallback is enabled, upstream npm packages are subject to cooldown period from their publication date before the Chainguard Repository will serve them. The cooldown applies to Chainguard-built packages and upstream npm packages served through the fallback. + +This unified cooldown is an additional layer of security on top of malware scanning. It provides a window for the security community to identify and report malicious packages before your builds can pull them, and it prevents installs from failing when a Chainguard-built package depends on an upstream transitive that is still in its 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. +* **Chainguard-built package available and outside cooldown**: 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**: The package is checked against malware scanning. If it passes, it is proxied from the npm Registry. + * **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](https://osv.dev/), which includes the OpenSSF Malicious Packages feed among other sources. Any package version flagged with a known MAL ID is blocked before it can be served. This covers reported malicious packages across the npm ecosystem; packages with unreported or novel malware may not be detected by scanning alone, which is why building from verified source remains the primary defense. -> **Note**: Chainguard Repository for JavaScript is not a full mirror of npm. With fallback enabled, Chainguard does not guarantee that evey package and version on npm will be available. Packages can be delayed by cooldown or permanently blocked by malware policies. \ No newline at end of file +> **Note**: With fallback enabled, the Chainguard Repository acts as a pull-through cache for npm, subject to cooldown and malware policies. Packages and specific versions may still be delayed by cooldown or permanently blocked by malware policies, so Chainguard does not guarantee that every package and version on npm will be available. \ No newline at end of file From 6f17c624e4d8df84014bcedec53da36c82464ef2 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Tue, 28 Apr 2026 15:31:21 -0400 Subject: [PATCH 2/5] updates Signed-off-by: s-stumbo --- content/chainguard/chainguard-repository/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/chainguard/chainguard-repository/overview.md b/content/chainguard/chainguard-repository/overview.md index a8d4fd8eb6..64a860adb7 100644 --- a/content/chainguard/chainguard-repository/overview.md +++ b/content/chainguard/chainguard-repository/overview.md @@ -40,9 +40,9 @@ The Chainguard Repository includes a policy engine that lets you define rules go For language dependencies, policies apply to both Chainguard-built packages and upstream packages served via the optional fallback to public registries (npm). Available policies include: * **Upstream fallback** — Control whether packages not yet built by Chainguard can be sourced from the upstream public registry. -* **Cooldown** — Block newly published upstream packages for a defined period before they can be pulled, giving the security community time to detect threats. A 7-day cooldown blocks 47% of malicious packages. +* **Cooldown** — When upstream fallback is enabled, block newly published package versions (Chainguard-built and upstream) for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default o 7 days. A 7-day cooldown blocks a large share of malicious packages identified shortly after publication. -All packages — whether Chainguard-built or sourced from upstream — are also scanned for malware before being served. Any package with a detected malware identifier is blocked. +All packages — whether Chainguard-built or sourced from upstream — are also scanned for malware before being served. Any package version with a detected malware identifier is blocked, including previously cached upstream versions that are later added to the malware block list. ## **Console** From 7be97f42e104252be056b3268566f89c0d800bfb Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Wed, 29 Apr 2026 09:18:55 -0400 Subject: [PATCH 3/5] updates Signed-off-by: s-stumbo --- content/chainguard/chainguard-repository/overview.md | 4 +++- content/chainguard/libraries/javascript/overview.md | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/chainguard/chainguard-repository/overview.md b/content/chainguard/chainguard-repository/overview.md index 64a860adb7..ae330d2268 100644 --- a/content/chainguard/chainguard-repository/overview.md +++ b/content/chainguard/chainguard-repository/overview.md @@ -40,7 +40,9 @@ The Chainguard Repository includes a policy engine that lets you define rules go For language dependencies, policies apply to both Chainguard-built packages and upstream packages served via the optional fallback to public registries (npm). Available policies include: * **Upstream fallback** — Control whether packages not yet built by Chainguard can be sourced from the upstream public registry. -* **Cooldown** — When upstream fallback is enabled, block newly published package versions (Chainguard-built and upstream) for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default o 7 days. A 7-day cooldown blocks a large share of malicious packages identified shortly after publication. +* **Cooldown** — When upstream fallback is enabled, block newly published package versions (Chainguard-built and upstream) for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default o 7 days. + +> **Note**: A 7-day cooldown blocks a large share of malicious packages identified shortly after publication. Shorter cooldown periods increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. All packages — whether Chainguard-built or sourced from upstream — are also scanned for malware before being served. Any package version with a detected malware identifier is blocked, including previously cached upstream versions that are later added to the malware block list. diff --git a/content/chainguard/libraries/javascript/overview.md b/content/chainguard/libraries/javascript/overview.md index ec55abdd03..fc1ac1ec7d 100644 --- a/content/chainguard/libraries/javascript/overview.md +++ b/content/chainguard/libraries/javascript/overview.md @@ -256,7 +256,7 @@ When upstream fallback is enabled, users with the Owner role can configure the c ```bash chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM --cooldown-days=3 ``` -The default cooldown period is 7 days. Setting `--cooldown-days=0` disables the cooldown. Note that shorter cooldown periods reduce friction for new versions but increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. +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. @@ -271,7 +271,7 @@ Malware detection is continuous. If a version that was previously cached is late #### Cooldown period When fallback is enabled, upstream npm packages are subject to cooldown period from their publication date before the Chainguard Repository will serve them. The cooldown applies to Chainguard-built packages and upstream npm packages served through the fallback. -This unified cooldown is an additional layer of security on top of malware scanning. It provides a window for the security community to identify and report malicious packages before your builds can pull them, and it prevents installs from failing when a Chainguard-built package depends on an upstream transitive that is still in its cooldown window. +This global cooldown is an additional layer of security on top of malware scanning. It provides a window for the security community to identify and report malicious packages before your builds can pull them, and it prevents installs from failing when a Chainguard-built package depends on an upstream transitive that is still in its 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. From da1ae27d857a6949257c01d349444cc0255bd3f0 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Mon, 4 May 2026 09:05:36 -0400 Subject: [PATCH 4/5] apply feedback Signed-off-by: s-stumbo --- content/chainguard/chainguard-repository/overview.md | 8 ++++---- content/chainguard/libraries/javascript/overview.md | 8 +++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/content/chainguard/chainguard-repository/overview.md b/content/chainguard/chainguard-repository/overview.md index ae330d2268..95c48dffbf 100644 --- a/content/chainguard/chainguard-repository/overview.md +++ b/content/chainguard/chainguard-repository/overview.md @@ -40,14 +40,14 @@ The Chainguard Repository includes a policy engine that lets you define rules go For language dependencies, policies apply to both Chainguard-built packages and upstream packages served via the optional fallback to public registries (npm). Available policies include: * **Upstream fallback** — Control whether packages not yet built by Chainguard can be sourced from the upstream public registry. -* **Cooldown** — When upstream fallback is enabled, block newly published package versions (Chainguard-built and upstream) for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default o 7 days. +* **Cooldown** — When upstream fallback is enabled, block newly published package versions for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default of 7 days. The cooldown is applied globally across all packages to prevent dependency resolution errors. -> **Note**: A 7-day cooldown blocks a large share of malicious packages identified shortly after publication. Shorter cooldown periods increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. +> **Note**: Chainguard recommends a 7-day cooldown when enabling upstream fallback, to block a large share of malicious packages identified shortly after publication. Shorter cooldown periods increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. -All packages — whether Chainguard-built or sourced from upstream — are also scanned for malware before being served. Any package version with a detected malware identifier is blocked, including previously cached upstream versions that are later added to the malware block list. +All upstream packages are checked against public malware identifier feeds, and any package with a known malware idenitifier is blocked before being served. -## **Console** +## **Management** The Chainguard Console is the central interface for configuring policies and monitoring artifact activity across your organization. Learn more in [Using the Chainguard Console](/chainguard/chainguard-images/how-to-use/images-directory/). diff --git a/content/chainguard/libraries/javascript/overview.md b/content/chainguard/libraries/javascript/overview.md index fc1ac1ec7d..82b724166a 100644 --- a/content/chainguard/libraries/javascript/overview.md +++ b/content/chainguard/libraries/javascript/overview.md @@ -269,16 +269,18 @@ All packages served from the upstream fallback are scanned for malware before be 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 cooldown period from their publication date before the Chainguard Repository will serve them. The cooldown applies to Chainguard-built packages and upstream npm packages served through the fallback. +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 applies globally across Chainguard-built packages and upstream npm packages served through the fallback. -This global cooldown is an additional layer of security on top of malware scanning. It provides a window for the security community to identify and report malicious packages before your builds can pull them, and it prevents installs from failing when a Chainguard-built package depends on an upstream transitive that is still in its cooldown window. +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 and outside cooldown**: The package is served directly from Chainguard's rebuilt artifact store, complete with SBOM, provenance, and signatures, subject to the configured cooldown. +* **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. From c83d4617bbb0d5aa4d6f12254586578b29398059 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Mon, 4 May 2026 13:21:59 -0400 Subject: [PATCH 5/5] remove global cooldown Signed-off-by: s-stumbo --- content/chainguard/chainguard-repository/overview.md | 2 +- content/chainguard/libraries/javascript/overview.md | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/content/chainguard/chainguard-repository/overview.md b/content/chainguard/chainguard-repository/overview.md index 6a4e242e6c..b9f20ba277 100644 --- a/content/chainguard/chainguard-repository/overview.md +++ b/content/chainguard/chainguard-repository/overview.md @@ -40,7 +40,7 @@ The Chainguard Repository includes a policy engine that lets you define rules go For language dependencies, policies apply to both Chainguard-built packages and upstream packages served via the optional fallback to public registries. Available policies include: * **Upstream fallback**: Control whether packages not yet built by Chainguard can be sourced from the upstream public registry. -* **Cooldown**: When upstream fallback is enabled, block newly published package versions for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default of 7 days. The cooldown is applied globally across all packages to prevent dependency resolution errors. +* **Cooldown**: When upstream fallback is enabled, block newly published package versions for a defined period before they can be pulled, giving the security community time to detect threats. The cooldown is configurable (0 to 3650 days) with a default of 7 days. > **Note**: Chainguard recommends a 7-day cooldown when enabling upstream fallback, to block a large share of malicious packages identified shortly after publication. Shorter cooldown periods increase the risk of pulling malicious or compromised upstream packages before the broader ecosystem can detect and report them. diff --git a/content/chainguard/libraries/javascript/overview.md b/content/chainguard/libraries/javascript/overview.md index 23132cac9b..1055ff554f 100644 --- a/content/chainguard/libraries/javascript/overview.md +++ b/content/chainguard/libraries/javascript/overview.md @@ -245,7 +245,7 @@ chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUA ### 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. +* **Upstream fallback enabled with cooldown**: Upstream packages are available after passing a cooldown period and malware scan. #### Configuring the cooldown period @@ -268,9 +268,7 @@ Malware detection is continuous. If a version that was previously cached is late #### 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 applies globally across Chainguard-built packages and upstream npm packages served through the fallback. 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. +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. 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.