SafeDep Documentation

An attacker who takes over a maintainer account publishes a malicious version. The registry often removes the version within days. The PMG dependency cooldown hides each version that is younger than a set number of days, so the package manager installs an older version. The cooldown is on by default with a window of 2 days. It applies to npm, PyPI, Go, and Cargo packages.

Set the window

pmg config set dependency_cooldown.days 7

To turn the cooldown off, set dependency_cooldown.enabled to false.

Read the result

For npm, PyPI, and Cargo, PMG removes each version inside the window from the version list that the registry sends. When the version range allows an older version, the package manager installs it and PMG shows no message. PMG blocks the install in these cases:

Every version of the package is inside the window.
You asked for an exact version, such as pmg npm install [email protected], and that version is inside the window.

The report starts with Dependency cooldown and names each blocked package. When a dependency asks for an exact version inside the window, the package manager fails, and PMG lists the held-back versions after the error. Add --verbose to see the held-back versions on every install. For npm and PyPI, the cooldown does not apply when the package manager downloads a locked version directly, such as npm ci with a lockfile. For Go and Cargo, PMG also checks each download against the window, so a version from go.mod or Cargo.lock is checked too. PMG does not change the version list for Go. The go command picks the version, and PMG blocks the download when that version is inside the window.

Exempt a package

For a package that you must install as soon as it is published, such as your own SDK, add it to the skip list. Open the config file with pmg config edit and add an entry:

dependency_cooldown:
  enabled: true
  days: 7
  skip:
    - purl: pkg:npm/my-internal-sdk
      reason: "First-party SDK, tested on release"
    - purl: pkg:npm/[email protected]
      reason: "One build we must test now"

A package URL (PURL) without a version exempts all versions. A PURL with a version exempts only that version. PMG still checks an exempt package for malware.

Skip the cooldown for one install

pmg --skip-dependency-cooldown npm install express

With SafeDep Cloud

The cooldown is free in PMG. With SafeDep Cloud, you see every cooldown hold on the endpoints and CI runners of your team. This query lists them:

SELECT endpoints.identifier,
       package_guard_events.package_name,
       package_guard_events.package_version,
       package_guard_events.timestamp
FROM package_guard_events
JOIN endpoints ON endpoints.id = package_guard_events.invocation_id
WHERE package_guard_events.package_action = 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED'
ORDER BY package_guard_events.timestamp DESC

A package that the cooldown holds back on many endpoints can be one of your own packages. To exempt it, see Exempt a package.

This section needs the SafeDep Cloud Team or Enterprise plan, with PMG connected to your tenant. See pricing.

Next steps

For pip version requirements and the trusted_packages list, see the dependency cooldown documentation in the PMG repository.

Alert on PMG blocks

With SafeDep Cloud, send malicious and cooldown blocks to Slack or a webhook.

Use PMG with a Private Registry or Mirror

Check packages from an internal registry.

CI/CD Package Blocking

Hold Back Newly Published Package Versions

Set the window

Read the result

Exempt a package

Skip the cooldown for one install

With SafeDep Cloud

Next steps

Alert on PMG blocks

Use PMG with a Private Registry or Mirror

​Set the window

​Read the result

​Exempt a package

​Skip the cooldown for one install

​With SafeDep Cloud

​Next steps

Alert on PMG blocks

Use PMG with a Private Registry or Mirror

Set the window

Read the result

Exempt a package

Skip the cooldown for one install

With SafeDep Cloud

Next steps