Skip to content

Commit 9647e48

Browse files
authored
Add global cooldown info to Library docs (#3307)
[ ] Check if this is a typo or other quick fix and ignore the rest :) ## Type of change Update to existing pages ### What should this PR do? Add that the cooldown applies globally to chainguard-built and upstream packages for JS libraries ### Why are we making this change? New functionality released ### What are the acceptance criteria? Content should be clear and accurate, and appear in the expected location ### How should this PR be tested? Review the deploy preview Signed-off-by: s-stumbo <sally.stumbo@chainguard.dev>
1 parent 39e3ea1 commit 9647e48

2 files changed

Lines changed: 5 additions & 2 deletions

File tree

content/chainguard/chainguard-repository/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ The Chainguard Repository includes a policy engine that lets you define rules go
4040
For language dependencies, policies apply to both Chainguard-built packages and upstream packages served via the optional fallback to public registries. Available policies include:
4141

4242
* **Upstream fallback**: Control whether packages not yet built by Chainguard can be sourced from the upstream public registry.
43-
* **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.
43+
* **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.
4444

4545
> **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.
4646

content/chainguard/libraries/javascript/overview.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -243,9 +243,10 @@ chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUA
243243
```
244244

245245
### Fallback options
246+
246247
The following options are available:
247248
* **No upstream fallback (default)**: Only Chainguard-built packages are served.
248-
* **Upstream fallback enabled with cooldown**: Upstream packages are available after passing a cooldown period and malware scan.
249+
* **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.
249250

250251
#### Configuring the cooldown period
251252

@@ -270,6 +271,8 @@ Malware detection is continuous. If a version that was previously cached is late
270271

271272
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.
272273

274+
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.
275+
273276
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.
274277

275278
### How package resolution works

0 commit comments

Comments
 (0)