From 669e9609307bf56be909e678533873a6fd6b02e4 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Fri, 8 May 2026 13:39:26 -0400 Subject: [PATCH] Add global cooldown info to Library docs Signed-off-by: s-stumbo --- content/chainguard/chainguard-repository/overview.md | 2 +- content/chainguard/libraries/javascript/overview.md | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/content/chainguard/chainguard-repository/overview.md b/content/chainguard/chainguard-repository/overview.md index b9f20ba277..31d2383a9b 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. +* **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. It is applied globally across all packages to prevent dependency resolution errors. > **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 1055ff554f..e9b2e6d460 100644 --- a/content/chainguard/libraries/javascript/overview.md +++ b/content/chainguard/libraries/javascript/overview.md @@ -243,9 +243,10 @@ 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. +* **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 @@ -270,6 +271,8 @@ Malware detection is continuous. If a version that was previously cached is late 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