How to Set Up Release Freshness Guards to Block New Packages

Intermediate 15 minutes Security Engineers Monitoring & Compliance Updated

Configure package age policies to block packages younger than N days, protecting against attacks that exploit freshly published malicious versions.

Overview

Many supply chain attacks involve publishing a malicious package version and getting it installed before the community detects it. By setting a release freshness guard, you can block packages that are younger than a configurable number of days, giving the ecosystem time to detect and report malicious content.

This is especially effective against:

  • Newly published malicious packages
  • Compromised maintainer accounts pushing backdoored releases
  • Dependency confusion attacks using freshly created packages

Prerequisites

  • Admin or Manager role in Chainsaw
  • Understanding of your organization’s update cadence

Step 1: Understand Package Age Tracking

Chainsaw records the package_release_date and version_release_date for every package that flows through the proxy. These dates come from the upstream registry metadata.

The package age policy compares the current date against the release date to determine if a package is “too new.”

Package age timeline diagram
Freshness guards create a quarantine window for newly published packages

Step 2: Create a Release Age Policy

Navigate to Policies and click Create Policy.

Basic Configuration

  1. Name: Block New Packages (< 30 days)
  2. Action: Block (or Quarantine for a softer approach)
  3. Condition: Package Age → less than 30 days
Creating a package age policy
Block packages that have been published within the last 30 days

Choose Your Quarantine Window

WindowProtection LevelImpact on Development
7 daysMinimalLow — most releases are safe after a week
14 daysModerateMedium — some new features delayed
30 daysStrongHigher — developers may need exceptions for new releases
90 daysMaximumHigh — only well-established versions allowed
Start with 7 days and increase if your risk tolerance demands it. The sweet spot for most organizations is 14-30 days.

Step 3: Scope the Policy

Consider applying different age requirements to different contexts:

Production vs Development

Create two policies:

  • Production: Block packages < 30 days (strict)
  • Development: Quarantine packages < 7 days (permissive)

Scope each policy to the appropriate client type:

  • Service tokens → production policy
  • End user credentials → development policy
Age policies scoped by client type
Apply stricter freshness guards to production pipelines

Per-Ecosystem Tuning

Some ecosystems release more frequently than others. You might want:

  • npm: 14 days (high volume, frequent attacks)
  • PyPI: 14 days (growing attack surface)
  • Maven: 7 days (more stable ecosystem)
  • Docker: 7 days (versioned tags are more deliberate)

Step 4: Handle Exceptions

When developers need a new release urgently:

  1. Create a time-bound exception for the specific package and version
  2. Set the exception to expire (e.g., 30 days)
  3. Document the reason for the exception
Creating an exception for a new package
Allow a specific new package through with a time-bound exception
Before granting an exception for a new package, check its trust score and provenance status. A new package with verified provenance and a high trust score is lower risk.

Step 5: Monitor Impact

Navigate to the Overview dashboard to see how many packages are being blocked by the freshness guard.

Dashboard showing freshness guard violations
Monitor how many packages are caught by the freshness guard

If the violation count is very high, consider:

  • Reducing the age threshold
  • Scoping the policy more narrowly
  • Adding exceptions for trusted publishers

Step 6: Trust Score Impact

Package age contributes to the composite trust score:

AgeTrust Score Impact
> 30 days+10 points
<= 30 days+0 points

This means newly published packages automatically start with a lower trust score, even without an explicit age policy.

The Organization-Wide Release Hold

Separate from the age policies above, every organization has a release hold: an org setting, on by default at 48 hours, that applies to every package without a policy. While a version is younger than the hold, the package listings the proxy serves leave it out, so a version range resolves to the newest version that is old enough. A lockfile that pins the young version directly is refused with CHW-2301, which names the newest allowed version.

Docker images: pin by digest

Docker tag lists are not filtered, because a tag points at a new build each time it is pushed. Pulling a tag whose newest build is younger than the hold is refused with CHW-2301. To keep using the build the tag pointed at before, pull it by digest (image@sha256:<digest>) instead of by tag.

Fixes for known vulnerabilities are released automatically

A held version is served before the hold ends when it is the fix for a published vulnerability that affects the version you would otherwise get. Nobody has to do anything. All of these must be true:

  • The version you would otherwise get is affected by the advisory.
  • The advisory names the held version as the version that fixes it, with exactly that version number. On NuGet and PyPI, spellings of the same version count as the same number (1.19 and 1.19.0), because those registries do not allow both. Everywhere else the spelling must match.
  • No part of that advisory affects the held version. One advisory can cover several version ranges, and it must clear the held version in all of them.
  • The held version was published before the advisory was. On PyPI this is checked for each file, so a wheel added to the release after the advisory keeps its hold. An advisory with no publication date releases nothing.
  • Chainsaw has already scanned the held version, and the scan found no warn verdict and no account-takeover sign. A version with no scan result yet, or whose scan result cannot be read in time, keeps its full hold.
  • The held version is held only because it is new. A version also held for a warn risk verdict, an account-takeover sign, a new install script or another flagged change, or an offline feed that is behind keeps its full hold.

Only that one version is released. Any other new version keeps its hold, including one published next to the fix, one above a fix number that was never published, and a lower version on another release line. An advisory that names no fix, for example one that lists affected versions up to the latest, releases nothing.

This works for npm, PyPI, Composer, Cargo, Go, Maven, Gradle, NuGet and RubyGems. It does not apply to Docker images, which have no advisory data in this form.

What this protects against, and what it does not. Chainsaw trusts the advisory’s version data, and the person who controls a package controls which versions exist.

  • Covered: an advisory that names a fix before that version exists. This happens when the maintainers ship a different version from the one the advisory names, or when a version is published and then removed. If an attacker then publishes a version with that number, it was published after the advisory, so it keeps its full hold. The same applies to an attacker who files an advisory naming a version and then publishes it.
  • Not covered: a version published before an advisory that names it as the fix. Someone who controls the package can publish a malicious version, then get an advisory accepted that names it as the fix for a flaw in the version below. If that advisory reaches Chainsaw’s advisory data while the version is still inside its hold, and Chainsaw’s scan of the version comes back clean, the version skips the rest of its hold. The malware feed is then its only check. A file added to a PyPI fix release after the release but before the advisory is in the same position.
  • The cost: a real fix also waits out the full hold when the advisory was first published before the fix and only later updated to name it, or when Chainsaw has not scanned the fix yet.

If your organisation does not accept this trade-off, turn automatic fix releases off. Held fixes then wait out the hold like any other version, and an admin can still release one with an exemption (below):

curl -X PATCH https://chain305.com/chainproxy/api/settings/general \
  -H "Authorization: Bearer $CHAINSAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"release_hold": {"cve_fix_release": false}}'

Send true to turn it back on. It is on by default, and the settings response reports the current value as release_hold.cve_fix_release.

Release one version early (admin pin)

To let one exact version through before the hold ends, an admin adds it to the hold’s exemptions. Each entry is package@version. The list in the request replaces the stored list, so send every entry you want to keep:

curl -X PATCH https://chain305.com/chainproxy/api/settings/general \
  -H "Authorization: Bearer $CHAINSAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"release_hold": {"exemptions": ["left-pad@1.3.1"]}}'
  • Which credential: $CHAINSAW_TOKEN here is a management-API key (c305_pa_…) from a user with settings:update, not a package-manager client credential.
  • Who can set it: any role with settings:update: org owners, org admins and org managers.
  • What is recorded: every change writes a settings.updated event to the audit log, with the hold’s settings before and after the change, and the user who made it.
  • For an org-private scope or name that should never be held (for example @acme), use exempt_scopes in the same object instead.

The chainsaw_release_hold_released_early_total metric counts each download served before its hold ended, by reason: cve_fix, exemption or scope.

Policy exceptions do not lift the release hold. The exceptions in Step 4 apply to policies only. To release a held version early, use the hold’s exemptions list.

Real-World Example

In 2024, a compromised npm maintainer account published a backdoored version of a popular package. The malicious version was live for 3 days before being detected. With a 7-day freshness guard:

  • Day 0: Malicious version published
  • Day 0-7: Chainsaw blocks the new version for all production installs
  • Day 3: Community detects the malware, npm removes the package
  • Day 7: Even without the takedown, Chainsaw would have continued blocking

The freshness guard provided a 3-day safety buffer that would have prevented exploitation.

Next Steps