mirror of https://github.com/safedep/pmg.git synced 2026-08-03 07:24:09 +02:00

Files

T

61230fbcd7 feat(cooldown): add dependency_cooldown.skip list (per-control exemption) (#328 )

Let dependency cooldown respect an explicit skip list so first-party /
internal packages that must be installed the moment they are published
(e.g. to sanity-test a freshly released version) are not held back by the
cooldown window.

Per review, this is a per-control skip list — NOT a second definition of
"trusted package". There remains a single top-level `trusted_packages`
(which waives malware analysis); `dependency_cooldown.skip` waives ONLY
the cooldown wait, so a fast-tracked package is still malware-scanned.

Matching:
- a PURL without a version skips cooldown for all versions of the package
  (package-level) — the metadata passes through unmodified;
- a PURL with a version skips cooldown for that version only — that
  version is preserved during stripping while other recent versions are
  still held.

- config: DependencyCooldownConfig.Skip + CooldownSkip()/CooldownSkipInfo.
- npm/pypi interceptors: bypass on package-level skip; thread per-version
  exemptions into the cooldown stripper so pinned versions survive.
- docs + config template; unit tests for the matcher (package/version
  level, precedence, mismatches) and the skip-vs-trusted independence.

Signed-off-by: dmdhrumilmistry <56185972+dmdhrumilmistry@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-15 19:44:55 +05:30

3.7 KiB

Raw Blame History

Dependency Cooldown

Dependency cooldown filters package versions published within a configurable time window out of registry metadata responses during version resolution. This reduces exposure to supply chain attacks by ensuring the package manager normally only resolves versions that have been available for a minimum number of days.

How It Works

When cooldown is enabled, PMG intercepts package metadata responses from the registry and strips versions published within the cooldown window. If the requested version range allows an older eligible release, the resolver falls back to it automatically. If no eligible version satisfies the request, the install fails.

Cooldown is enforced through metadata filtering and does not apply to direct tarball installs or workflows that already have a resolved tarball URL (e.g., lockfile or cache scenarios).

Configuration

Dependency cooldown is configured in config.yml. See config template for the full schema. If you don't have a config.yml file, create one by running pmg setup install.

dependency_cooldown:
  enabled: true
  days: 5

Exempting Specific Packages

Some packages — typically first-party or internal — need to be installed as soon as they are published (for example, to sanity-test a freshly released version) and cannot wait out the cooldown window. List them under the dependency_cooldown.skip list:

dependency_cooldown:
  enabled: true
  days: 5
  skip:
    - purl: pkg:npm/my-internal-sdk             # all versions
      reason: "First-party SDK; sanity-tested immediately on release"
    - purl: pkg:npm/another-internal-pkg@1.2.3  # only this version
      reason: "Pin a specific just-published build"

The skip list is a per-control exemption: packages on it skip only the cooldown window — they are still analyzed for malware. It is independent of the top-level trusted_packages, which waives malware analysis. There is a single definition of a trusted package (the top-level list); this is just a cooldown skip list.

List	Waives malware analysis	Waives cooldown
`trusted_packages` (top level)	yes	no
`dependency_cooldown.skip`	no	yes

Matching:

A PURL without a version skips cooldown for all versions of the package.
A PURL with a version skips cooldown for that version only (the version stays installable; other recent versions are still held).

PyPI names are matched in their normalized form (lowercase, _/. → -).

To skip cooldown for a single command instead of configuring a package permanently, use the CLI override below.

CLI Override

Use --skip-dependency-cooldown to disable cooldown enforcement for a single invocation without changing the config file:

pmg --skip-dependency-cooldown npm install express

Requirements

Dependency cooldown requires proxy mode to be enabled. It is supported for npm and PyPI packages.

Limitations

PyPI: requires pip 22.3+ or a PEP 691-capable client

PyPI cooldown is enforced by filtering the PEP 691 JSON Simple API response, which includes a per-file upload-time field needed to determine when each version was published. This JSON format is only supported by pip 22.3+ (released October 2022) and other modern tools such as uv, Poetry, and PDM.

Older pip versions request the HTML Simple API, which carries no publish timestamps. PMG cannot apply cooldown filtering to HTML responses and fails open; the request passes through unchanged and the client receives the full version list. Old pip gets no cooldown protection but does not break.

3.7 KiB Raw Blame History