Supply chain attacks on open-source packages are a growing concern for platform and security teams. Today, we’re excited to announce the NPM Package Cooldown Check, a new GitHub pull request (PR) check designed to automatically block PRs that introduce new npm package versions. In simple terms, if a PR tries to use an npm package release that came out within the last two days (or within a configurable “cooldown” period), this check will fail the PR. This gives your team a short waiting window before adopting brand-new dependencies, providing a crucial safety net against malicious releases. It’s an accessible, developer-friendly guardrail that integrates directly into your GitHub workflow, helping protect your applications from supply chain attacks without slowing down development.
This feature is part of our broader initiative to bake security into the development lifecycle. Alongside the Cooldown Check, we’re rolling out additional GitHub checks to catch other supply chain threats – from dangerous GitHub Actions workflow vulnerabilities (like “PWN Request” flaws) to script injection issues in CI pipelines. In this post, we’ll explain how the NPM Package Cooldown Check works, walk through an example, discuss the rationale behind it, and provide guidance on adopting it in your environment.
What is the NPM Package Cooldown Check?
The NPM Package Cooldown Check is a lightweight automated verification step that runs on each pull request. Its job is straightforward: detect any npm dependency introduced or updated in the PR that was published within the last 2 days (48 hours) and fail the PR if such a dependency is found.
The “cooldown” period is configurable – by default it’s set to 2 days, but your organization can adjust it to a longer or shorter window based on your risk tolerance. Once the cooldown period has passed for that package version, the check will automatically clear with no manual intervention needed. In practice, this means if you open a PR that updates a library to a version released yesterday, the PR will be blocked; but if you simply wait until that version is 2+ days old, the check will pass and you can merge as normal.
Why Enforce a Cooldown Period?
You might wonder: why delay updates at all? The rationale is rooted in hard lessons from recent software supply chain attacks. Most malicious package releases are discovered within the first 24 hours of being published, often by automated scanners, security researchers, or the package maintainers themselves. The projects that get compromised are typically those that rush to adopt the new version immediately. By introducing a short waiting period before allowing new dependencies, teams can dramatically reduce their exposure to fresh attacks while still keeping their dependencies up to date.
The NX compromise in npm is a stark example of why early adoption of every new release can be risky. Attackers managed to slip a malicious version into the registry, and within hours, developers who immediately pulled the update were at risk of running compromised code. Fortunately, the issue was detected and the package flagged within the first 24 hours. The same pattern has played out with other packages, like es-lint and is, where the compromises were caught quickly but not before exposing early upgraders.
This is exactly the problem that the Cooldown Check addresses. By automatically enforcing a short waiting period before new releases can be adopted, it gives the ecosystem time to react and flag issues. Instead of relying only on vulnerability scanners or CVE announcements after the fact, the Cooldown Check proactively pauses on unvetted code.
The safeguard is especially valuable for teams using automated dependency update tools like Dependabot. With the Cooldown Check enabled, even Dependabot PRs will be flagged if they point to a just-released package, reducing the risk of accidentally merging a compromise. A 48-hour delay is a small trade-off for a significant reduction in exposure.
In the screenshot above, version 20.12.0 was compromised while 20.10.0 was not. However, since Dependabot automatically updated the dependency, the repository ended up using the compromised version. This pattern is something we’ve observed across several npm supply chain attacks: automated dependency upgrade tools like Dependabot and RenovateBot will quickly create pull requests to bump from a safe version to the compromised one shortly after release. Because many developers trust these tools and merge the PRs without much scrutiny, the malicious code often spreads rapidly before the compromise is flagged.
Walkthrough: Blocking a Newly Released Package in a PR
The screenshot below shows how the NPM Package Cooldown Check surfaces a failure on a pull request. In this example, a developer attempted to bump a dependency to a version published just hours earlier. The Cooldown Check ran as part of the PR’s checks and flagged the new version as too recent. In the PR’s status panel, you can see a failed check with details listing the offending package name, the version change (from the previous version to the new one), the file (e.g. package.json or lockfile) where the change occurred, and the new version’s release date/time. The check message even notes when it will pass automatically indicating the exact time the 2-day cooldown will be satisfied. This immediate feedback allows the team to hold off merging the PR until the flagged dependency has aged past the safe threshold, at which point the check will turn green on its own.
To summarize the developer experience with this check:
- A developer (or bot) opens a PR that adds or updates one or more npm package versions.
- The NPM Package Cooldown Check runs during the PR’s CI workflow.
- If any introduced package version was released within the last X days (e.g. 2 days), the check fails and the PR is blocked from merging.
- The PR displays a clear error with information about which package is too new and how long to wait.
- Once the cooldown period elapses, the check automatically re-runs and passes (assuming no other issues), unblocking the PR. The team can then merge the PR knowing the dependency had a little time to “soak” in the community.
Follow this interactive demo to see how it works:
Adopting the Cooldown Check in Your Pipeline
Getting started with the NPM Package Cooldown Check is straightforward. The check can be enabled as part of your GitHub PR workflow using our platform. Platform/ Security engineers can roll it out organization-wide or to specific repositories as a status check on pull requests. To enable this follow the information in our docs
Importantly, the Cooldown Check is not meant to block critical security patches. If an urgent fix is released upstream, developers can still merge it right away. In these cases, the check will initially fail because the new package hasn’t cleared the cooldown period, but a StepSecurity org admin can override the result and approve the PR. This ensures teams maintain agility for emergency updates while still benefiting from a protective default posture against compromised packages.
Part of a Broader Security Initiative
The NPM Package Cooldown Check is one piece of a larger effort to strengthen software supply chain security via GitHub-native checks. As mentioned earlier, we are extending our platform with additional automated PR and CI/CD checks to tackle other classes of vulnerabilities that have been plaguing modern pipelines.
NPM Package Compromised Updates Check
This control ensures that no pull request introduces or updates a dependency that is known to be compromised. StepSecurity continuously monitors the npm ecosystem for emerging threats and maintains an internal database of compromised packages, updated in real time. In many cases, this database is updated before an official CVE is published, meaning developers can block the use of a malicious package faster than traditional vulnerability scanners allow. If a pull request uses a compromised package, the check fails and prevents the merge, eliminating a major attack vector and helping teams respond to incidents at the speed of the ecosystem.
PWN Request Check
This control inspects GitHub Actions workflows for patterns that may allow a PWN Request vulnerability. It detects insecure configurations such as workflows triggered by pull_request_target that can be exploited by malicious forked PRs, and it flags these risks before they can be used to execute unauthorized code in your CI environment.
Script Injection Check
This control scans GitHub Actions workflows for script injection vulnerabilities. It identifies workflows that use overly permissive triggers or unsanitized external inputs and surfaces warnings or blocking checks so issues can be resolved before attackers exploit them
Conclusion and Next Steps
The introduction of the NPM Package Cooldown Check marks an important step toward making supply chain security frictionless and proactive. We believe that security tools work best when they operate in the background of the developer workflow – providing timely alerts and guardrails without overwhelming developers. With this new check, teams can continue to update dependencies confidently, knowing that an extra set of eyes (and a little timer) are watching out for them.
Get started with this feature by starting your free trial
.png)
