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>

config/config.go

@@ -148,6 +148,17 @@ type SandboxConfig struct {
 type DependencyCooldownConfig struct {
 	Enabled bool `mapstructure:"enabled"`
 	Days    int  `mapstructure:"days"`
+
+	// Skip is a per-control skip list of packages exempt from the cooldown
+	// window. It is independent of the top-level trusted_packages: it waives ONLY
+	// the cooldown wait, never malware analysis, so a fast-tracked package is
+	// still scanned. Intended for first-party / internal packages that must be
+	// installed immediately on release.
+	//
+	// Matching: a PURL without a version skips cooldown for ALL versions of the
+	// package (package-level); a PURL with a version skips cooldown for that
+	// version only (version-level).
+	Skip []TrustedPackage `mapstructure:"skip"`
 }
 
 // legacyProfileAliases maps old default profile names, keyed by package

config/config.template.yml

@@ -167,6 +167,21 @@ dependency_cooldown:
   enabled: true
   days: 5
 
+  # Per-control skip list of packages exempt from the cooldown window. This is
+  # independent of the top-level trusted_packages above (which waives malware
+  # analysis): packages here are STILL malware-scanned — only the cooldown wait
+  # is waived. Use it for first-party / internal packages that must be installed
+  # immediately on release (e.g. to sanity-test a freshly published version).
+  #
+  # A PURL without a version skips cooldown for ALL versions of the package; a
+  # PURL with a version skips cooldown for that version only. Example:
+  #   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 1.2.3
+  #       reason: "Pin a specific just-published build"
+  skip: []
+
 # Cloud sync configuration.
 # When enabled, PMG audit events are synced to SafeDep Cloud for centralized visibility.
 # Requires SAFEDEP_API_KEY and SAFEDEP_TENANT_ID environment variables for authentication.

config/cooldown_skip_test.go

@@ -0,0 +1,158 @@
+package config
+
+import (
+	"testing"
+
+	packagev1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/messages/package/v1"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCooldownSkip(t *testing.T) {
+	tests := []struct {
+		name        string
+		skip        []TrustedPackage
+		ecosystem   packagev1.Ecosystem
+		pkgName     string
+		wantSkipAll bool
+		wantVers    map[string]bool
+	}{
+		{
+			name:      "empty skip list",
+			skip:      []TrustedPackage{},
+			ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:   "internal-sdk",
+		},
+		{
+			name:      "empty package name",
+			skip:      []TrustedPackage{{Purl: "pkg:npm/internal-sdk"}},
+			ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:   "",
+		},
+		{
+			name:        "version-less entry skips all versions",
+			skip:        []TrustedPackage{{Purl: "pkg:npm/internal-sdk", Reason: "first-party"}},
+			ecosystem:   packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:     "internal-sdk",
+			wantSkipAll: true,
+		},
+		{
+			name:      "version-pinned entry skips only that version",
+			skip:      []TrustedPackage{{Purl: "pkg:npm/internal-sdk@1.2.3", Reason: "first-party"}},
+			ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:   "internal-sdk",
+			wantVers:  map[string]bool{"1.2.3": true},
+		},
+		{
+			name: "multiple version-pinned entries",
+			skip: []TrustedPackage{
+				{Purl: "pkg:npm/internal-sdk@1.2.3"},
+				{Purl: "pkg:npm/internal-sdk@1.3.0"},
+			},
+			ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:   "internal-sdk",
+			wantVers:  map[string]bool{"1.2.3": true, "1.3.0": true},
+		},
+		{
+			name: "version-less wins over version-pinned for same package",
+			skip: []TrustedPackage{
+				{Purl: "pkg:npm/internal-sdk@1.2.3"},
+				{Purl: "pkg:npm/internal-sdk"},
+			},
+			ecosystem:   packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:     "internal-sdk",
+			wantSkipAll: true,
+		},
+		{
+			name:      "name mismatch",
+			skip:      []TrustedPackage{{Purl: "pkg:npm/internal-sdk"}},
+			ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:   "express",
+		},
+		{
+			name:      "ecosystem mismatch",
+			skip:      []TrustedPackage{{Purl: "pkg:pypi/internal-tool"}},
+			ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:   "internal-tool",
+		},
+		{
+			name:        "pypi version-less entry",
+			skip:        []TrustedPackage{{Purl: "pkg:pypi/internal-tool"}},
+			ecosystem:   packagev1.Ecosystem_ECOSYSTEM_PYPI,
+			pkgName:     "internal-tool",
+			wantSkipAll: true,
+		},
+		{
+			name: "invalid purl skipped, valid match still found",
+			skip: []TrustedPackage{
+				{Purl: "invalid-purl"},
+				{Purl: "pkg:npm/internal-sdk"},
+			},
+			ecosystem:   packagev1.Ecosystem_ECOSYSTEM_NPM,
+			pkgName:     "internal-sdk",
+			wantSkipAll: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &Config{DependencyCooldown: DependencyCooldownConfig{Skip: tt.skip}}
+			_ = preprocessTrustedPackages(cfg)
+
+			got := cooldownSkip(cfg.DependencyCooldown.Skip, tt.ecosystem, tt.pkgName)
+			assert.Equal(t, tt.wantSkipAll, got.SkipAll)
+			assert.Equal(t, tt.wantVers, got.Versions)
+		})
+	}
+}
+
+func TestCooldownSkipInfo_ExemptsVersion(t *testing.T) {
+	skipAll := CooldownSkipInfo{SkipAll: true}
+	assert.True(t, skipAll.ExemptsVersion("9.9.9"), "skip-all exempts any version")
+
+	pinned := CooldownSkipInfo{Versions: map[string]bool{"1.2.3": true}}
+	assert.True(t, pinned.ExemptsVersion("1.2.3"))
+	assert.False(t, pinned.ExemptsVersion("1.2.4"))
+
+	none := CooldownSkipInfo{}
+	assert.False(t, none.ExemptsVersion("1.0.0"))
+}
+
+// TestCooldownSkipAndTrustedPackagesAreIndependent verifies the cooldown skip
+// list and the top-level trusted_packages do not leak into each other: a
+// cooldown-skipped package is NOT trusted for malware analysis, and a
+// malware-trusted package is NOT cooldown-skipped.
+func TestCooldownSkipAndTrustedPackagesAreIndependent(t *testing.T) {
+	cfg := &Config{
+		TrustedPackages: []TrustedPackage{
+			{Purl: "pkg:npm/malware-trusted", Reason: "waives analysis only"},
+		},
+		DependencyCooldown: DependencyCooldownConfig{
+			Skip: []TrustedPackage{
+				{Purl: "pkg:npm/cooldown-skipped", Reason: "waives cooldown only"},
+			},
+		},
+	}
+	_ = preprocessTrustedPackages(cfg)
+
+	cooldownSkipped := &packagev1.PackageVersion{
+		Package: &packagev1.Package{Name: "cooldown-skipped", Ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM},
+		Version: "1.0.0",
+	}
+	malwareTrusted := &packagev1.PackageVersion{
+		Package: &packagev1.Package{Name: "malware-trusted", Ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM},
+		Version: "1.0.0",
+	}
+
+	// Cooldown-skipped package is still malware-analyzed (not in trusted_packages).
+	assert.False(t, isTrustedPackageVersion(cfg.TrustedPackages, cooldownSkipped),
+		"cooldown-skipped package must NOT waive malware analysis")
+	assert.True(t, cooldownSkip(cfg.DependencyCooldown.Skip, packagev1.Ecosystem_ECOSYSTEM_NPM, "cooldown-skipped").SkipAll,
+		"cooldown-skipped package must skip the cooldown window")
+
+	// Malware-trusted package is still subject to cooldown (not in the skip list).
+	assert.True(t, isTrustedPackageVersion(cfg.TrustedPackages, malwareTrusted),
+		"malware-trusted package must waive malware analysis")
+	skip := cooldownSkip(cfg.DependencyCooldown.Skip, packagev1.Ecosystem_ECOSYSTEM_NPM, "malware-trusted")
+	assert.False(t, skip.SkipAll, "malware-trusted package must NOT skip cooldown")
+	assert.Nil(t, skip.Versions)
+}

config/trusted.go

@@ -13,12 +13,82 @@ func IsTrustedPackage(pkgVersion *packagev1.PackageVersion) bool {
 	return isTrustedPackageVersion(Get().Config.TrustedPackages, pkgVersion)
 }
 
-// preprocessTrustedPackages pre-parses all PURL strings in trusted packages.
+// CooldownSkipInfo describes how a package is exempted from the dependency
+// cooldown window by the dependency_cooldown.skip list.
+type CooldownSkipInfo struct {
+	// SkipAll is true when a version-less skip entry matches: every version of
+	// the package is exempt from the cooldown window.
+	SkipAll bool
+
+	// Versions holds the specific versions exempted by version-pinned skip
+	// entries. Only meaningful when SkipAll is false; nil when there are none.
+	Versions map[string]bool
+}
+
+// ExemptsVersion reports whether the given version is exempt from cooldown,
+// either because the whole package is skipped or because that specific version
+// is listed.
+func (s CooldownSkipInfo) ExemptsVersion(version string) bool {
+	return s.SkipAll || s.Versions[version]
+}
+
+// CooldownSkip returns how a package (by ecosystem and name) is exempted from
+// the dependency cooldown window via dependency_cooldown.skip.
+//
+// The skip list waives ONLY the cooldown wait — exempt packages are still
+// subject to malware analysis. A skip entry without a version exempts every
+// version of the package; an entry with a version exempts only that version.
+func CooldownSkip(ecosystem packagev1.Ecosystem, name string) CooldownSkipInfo {
+	return cooldownSkip(Get().Config.DependencyCooldown.Skip, ecosystem, name)
+}
+
+func cooldownSkip(skip []TrustedPackage, ecosystem packagev1.Ecosystem, name string) CooldownSkipInfo {
+	info := CooldownSkipInfo{}
+	if name == "" {
+		return info
+	}
+
+	for _, v := range skip {
+		if !v.parsed || v.ecosystem != ecosystem || v.name != name {
+			continue
+		}
+
+		if v.version == "" {
+			info.SkipAll = true
+			continue
+		}
+
+		if info.Versions == nil {
+			info.Versions = make(map[string]bool)
+		}
+		info.Versions[v.version] = true
+	}
+
+	// A version-less entry skips every version, so per-version entries are
+	// redundant — drop them so SkipAll is the single source of truth.
+	if info.SkipAll {
+		info.Versions = nil
+	}
+
+	return info
+}
+
+// preprocessTrustedPackages pre-parses all PURL strings in the trusted package
+// lists (both the top-level guardrail list and the cooldown-exemption list).
 // This is called once during config load to avoid repeated parsing during
 // trusted package checks. Invalid PURLs are logged but not fatal.
 func preprocessTrustedPackages(cfg *Config) error {
-	for i := range cfg.TrustedPackages {
-		tp := &cfg.TrustedPackages[i]
+	preprocessTrustedPackageList(cfg.TrustedPackages)
+	preprocessTrustedPackageList(cfg.DependencyCooldown.Skip)
+	return nil
+}
+
+// preprocessTrustedPackageList parses the PURL of each entry in place, populating
+// the pre-parsed ecosystem/name/version fields. Entries with an invalid PURL are
+// marked unparsed (and skipped at match time) rather than failing the load.
+func preprocessTrustedPackageList(packages []TrustedPackage) {
+	for i := range packages {
+		tp := &packages[i]
 
 		parsedPurl, err := pb.NewPurlPackageVersion(tp.Purl)
 		if err != nil {
@@ -32,8 +102,6 @@ func preprocessTrustedPackages(cfg *Config) error {
 		tp.name = parsedPurl.Name()
 		tp.version = parsedPurl.Version()
 	}
-
-	return nil
 }
 
 // isTrustedPackageVersion checks if a package version is in the trusted packages list.

docs/dependency-cooldown.md

@@ -18,6 +18,46 @@ dependency_cooldown:
   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:
+
+```yaml
+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`](trusted-packages.md), 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:

proxy/interceptors/npm_cooldown.go

@@ -33,7 +33,7 @@ func newNpmCooldownHandler(statsCollector *AnalysisStatsCollector) *npmCooldownH
 // HandleMetadataRequest overrides the Accept header to force the registry to return
 // a full packument (which includes publish dates in the "time" field), then registers
 // a response modifier that strips versions within the cooldown window.
-func (h *npmCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, packageName string, cooldownDays int, pinnedVersion string) (*proxy.InterceptorResponse, error) {
+func (h *npmCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, packageName string, cooldownDays int, pinnedVersion string, exemptVersions map[string]bool) (*proxy.InterceptorResponse, error) {
 	log.Debugf("[%s] Cooldown: registering metadata modifier for %s", ctx.RequestID, packageName)
 
 	// Force full packument so the response always contains the "time" field.
@@ -62,7 +62,7 @@ func (h *npmCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, pa
 
 		log.Debugf("[%s] Cooldown: parsed %d publish dates for %s", ctx.RequestID, len(dates), packageName)
 
-		strippedBody, stripped, remaining := h.stripCooldownVersions(body, dates, cooldownDays)
+		strippedBody, stripped, remaining := h.stripCooldownVersions(body, dates, cooldownDays, exemptVersions)
 		if stripped > 0 {
 			log.Infof("[%s] Cooldown: stripped %d version(s) from %s metadata (%d days, %d eligible remain)",
 				ctx.RequestID, stripped, packageName, cooldownDays, remaining)
@@ -123,9 +123,13 @@ func (h *npmCooldownHandler) parseMetadataTime(body []byte) (map[string]time.Tim
 
 // stripCooldownVersions removes versions published within the cooldown window from the
 // NPM metadata response. It strips entries from "versions", "time", and updates "dist-tags".
-func (h *npmCooldownHandler) stripCooldownVersions(body []byte, dates map[string]time.Time, cooldownDays int) ([]byte, int, int) {
+func (h *npmCooldownHandler) stripCooldownVersions(body []byte, dates map[string]time.Time, cooldownDays int, exemptVersions map[string]bool) ([]byte, int, int) {
 	tooNew := make(map[string]bool)
 	for version, publishDate := range dates {
+		// Version-pinned skip entries are never stripped, even inside the window.
+		if exemptVersions[version] {
+			continue
+		}
 		if withinCooldown, _, _ := cooldownIsWithinWindow(publishDate, cooldownDays); withinCooldown {
 			tooNew[version] = true
 		}

proxy/interceptors/npm_cooldown_test.go

@@ -183,7 +183,7 @@ func TestStripCooldownVersions_MixedVersions(t *testing.T) {
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5, nil)
 	assert.Equal(t, 1, stripped)
 	assert.Equal(t, 2, remaining)
 
@@ -223,7 +223,7 @@ func TestStripCooldownVersions_AllVersionsTooNew(t *testing.T) {
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5, nil)
 	assert.Equal(t, 2, stripped)
 	assert.Equal(t, 0, remaining)
 
@@ -249,7 +249,7 @@ func TestStripCooldownVersions_NoVersionsTooNew(t *testing.T) {
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5, nil)
 	assert.Equal(t, 0, stripped)
 	assert.Equal(t, 2, remaining)
 	assert.Equal(t, body, newBody) // body unchanged
@@ -267,7 +267,7 @@ func TestStripCooldownVersions_SingleVersionInCooldown(t *testing.T) {
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	_, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	_, stripped, remaining := handler.stripCooldownVersions(body, dates, 5, nil)
 	assert.Equal(t, 1, stripped)
 	assert.Equal(t, 0, remaining)
 }
@@ -277,7 +277,7 @@ func TestStripCooldownVersions_MalformedJSON(t *testing.T) {
 	body := []byte(`not-json`)
 	dates := map[string]time.Time{"1.0.0": time.Now().Add(-1 * time.Hour)}
 
-	newBody, stripped, _ := handler.stripCooldownVersions(body, dates, 5)
+	newBody, stripped, _ := handler.stripCooldownVersions(body, dates, 5, nil)
 	assert.Equal(t, 0, stripped)
 	assert.Equal(t, body, newBody)
 }
@@ -302,7 +302,7 @@ func TestStripCooldownVersions_LatestRepairedToStableNotPlatform(t *testing.T) {
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5)
+	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5, nil)
 
 	var result map[string]json.RawMessage
 	require.NoError(t, json.Unmarshal(newBody, &result))
@@ -329,7 +329,7 @@ func TestStripCooldownVersions_NonLatestTagRemovedWhenStripped(t *testing.T) {
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5)
+	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5, nil)
 
 	var result map[string]json.RawMessage
 	require.NoError(t, json.Unmarshal(newBody, &result))
@@ -368,7 +368,7 @@ func TestStripCooldownVersions_LatestRepairSkipsVersionsMissingFromPackument(t *
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5)
+	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5, nil)
 
 	var result map[string]json.RawMessage
 	require.NoError(t, json.Unmarshal(newBody, &result))
@@ -398,7 +398,7 @@ func TestStripCooldownVersions_LatestRepairStaysWithinBlessedLineage(t *testing.
 	dates, err := handler.parseMetadataTime(body)
 	require.NoError(t, err)
 
-	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5)
+	newBody, _, _ := handler.stripCooldownVersions(body, dates, 5, nil)
 
 	var result map[string]json.RawMessage
 	require.NoError(t, json.Unmarshal(newBody, &result))
@@ -432,7 +432,7 @@ func TestNpmCooldown_HandleMetadataRequest_OverridesHeaders(t *testing.T) {
 	ctx.Headers.Set("If-None-Match", `"abc123"`)
 	ctx.Headers.Set("If-Modified-Since", "Wed, 01 Jan 2025 00:00:00 GMT")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "lodash", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "lodash", 5, "", nil)
 	require.NoError(t, err)
 	assert.Equal(t, proxy.ActionModifyResponse, resp.Action)
 	assert.Equal(t, "application/json", ctx.Headers.Get("Accept"))
@@ -454,7 +454,7 @@ func TestNpmCooldown_HandleMetadataRequest_StripsRecentVersions(t *testing.T) {
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -489,7 +489,7 @@ func TestNpmCooldown_HandleMetadataRequest_NoVersionsInCooldown(t *testing.T) {
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -510,7 +510,7 @@ func TestNpmCooldown_HandleMetadataRequest_AllVersionsInCooldown_RecordsStats(t
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/newpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "newpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "newpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -542,7 +542,7 @@ func TestNpmCooldown_HandleMetadataRequest_AllVersionsInCooldown_ReportsOldestVe
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/multipkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "multipkg", 100, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "multipkg", 100, "", nil)
 	require.NoError(t, err)
 
 	_, _, _, err = resp.ResponseModifier(200, http.Header{}, body)
@@ -559,7 +559,7 @@ func TestNpmCooldown_HandleMetadataRequest_MalformedJSON_FailOpen(t *testing.T)
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/badpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "badpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "badpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -581,7 +581,7 @@ func TestNpmCooldown_HandleMetadataRequest_PinnedVersionInCooldown_RecordsStats(
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "2.0.0")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "2.0.0", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -612,7 +612,7 @@ func TestNpmCooldown_HandleMetadataRequest_PinnedVersionNotInCooldown_NoBlock(t
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "1.0.0")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "1.0.0", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -636,7 +636,7 @@ func TestNpmCooldown_HandleMetadataRequest_UnpinnedWithRemainingVersions_NoBlock
 	handler := newNpmCooldownHandler(collector)
 	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 

proxy/interceptors/npm_registry.go

@@ -113,7 +113,17 @@ func (i *NpmRegistryInterceptor) HandleRequest(ctx *proxy.RequestContext) (*prox
 
 	if !pkgInfo.IsFileDownload() {
 		if depCooldownConfig.Enabled {
-			return i.cooldownHandler.HandleMetadataRequest(ctx, pkgInfo.GetName(), depCooldownConfig.Days, i.execContext.PinnedVersions[pkgInfo.GetName()])
+			skip := pmgconfig.CooldownSkip(packagev1.Ecosystem_ECOSYSTEM_NPM, pkgInfo.GetName())
+			if skip.SkipAll {
+				// Whole package is on the cooldown skip list: let the metadata pass
+				// through unmodified. The tarball download still hits analyzePackage,
+				// so malware analysis is preserved.
+				log.Infof("[%s] Cooldown: package %s is on the skip list (dependency_cooldown.skip); malware analysis still applies", ctx.RequestID, pkgInfo.GetName())
+				return &proxy.InterceptorResponse{Action: proxy.ActionAllow}, nil
+			}
+
+			// Version-pinned skip entries (if any) are preserved during stripping.
+			return i.cooldownHandler.HandleMetadataRequest(ctx, pkgInfo.GetName(), depCooldownConfig.Days, i.execContext.PinnedVersions[pkgInfo.GetName()], skip.Versions)
 		}
 
 		log.Debugf("[%s] Skipping analysis for metadata request: %s", ctx.RequestID, pkgInfo.GetName())

proxy/interceptors/pypi_cooldown.go

@@ -29,7 +29,7 @@ func newPypiCooldownHandler(statsCollector *AnalysisStatsCollector) *pypiCooldow
 // then registers a response modifier that strips files for versions within the cooldown window.
 // If the client does not support PEP 691 (pip < 22.3), cooldown is skipped to avoid
 // returning a content type the client cannot parse.
-func (h *pypiCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, packageName string, cooldownDays int, pinnedVersion string) (*proxy.InterceptorResponse, error) {
+func (h *pypiCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, packageName string, cooldownDays int, pinnedVersion string, exemptVersions map[string]bool) (*proxy.InterceptorResponse, error) {
 	log.Debugf("[%s] Cooldown: registering metadata modifier for %s", ctx.RequestID, packageName)
 
 	originalAccept := ctx.Headers.Get("Accept")
@@ -62,7 +62,7 @@ func (h *pypiCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, p
 
 		log.Debugf("[%s] Cooldown: parsed %d versions for %s", ctx.RequestID, len(dates), packageName)
 
-		strippedBody, stripped, remaining := h.stripCooldownFiles(body, dates, cooldownDays)
+		strippedBody, stripped, remaining := h.stripCooldownFiles(body, dates, cooldownDays, exemptVersions)
 		if stripped > 0 {
 			log.Infof("[%s] Cooldown: stripped %d version(s) from %s metadata (%d days, %d eligible remain)",
 				ctx.RequestID, stripped, packageName, cooldownDays, remaining)
@@ -133,9 +133,13 @@ func (h *pypiCooldownHandler) parsePEP691Files(body []byte) (map[string]time.Tim
 // stripCooldownFiles removes all file entries for versions within the cooldown window
 // from a PEP 691 JSON body. Returns the modified body, number of versions stripped,
 // and number of versions remaining.
-func (h *pypiCooldownHandler) stripCooldownFiles(body []byte, dates map[string]time.Time, cooldownDays int) ([]byte, int, int) {
+func (h *pypiCooldownHandler) stripCooldownFiles(body []byte, dates map[string]time.Time, cooldownDays int, exemptVersions map[string]bool) ([]byte, int, int) {
 	tooNew := make(map[string]bool)
 	for version, uploadDate := range dates {
+		// Version-pinned skip entries are never stripped, even inside the window.
+		if exemptVersions[version] {
+			continue
+		}
 		if within, _, _ := cooldownIsWithinWindow(uploadDate, cooldownDays); within {
 			tooNew[version] = true
 		}

proxy/interceptors/pypi_cooldown_test.go

@@ -180,7 +180,7 @@ func TestStripCooldownFiles_MixedVersions(t *testing.T) {
 	dates, err := handler.parsePEP691Files(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5)
+	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5, nil)
 	assert.Equal(t, 1, stripped)
 	assert.Equal(t, 1, remaining)
 
@@ -213,7 +213,7 @@ func TestStripCooldownFiles_AllVersionsTooNew(t *testing.T) {
 	dates, err := handler.parsePEP691Files(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5)
+	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5, nil)
 	assert.Equal(t, 2, stripped)
 	assert.Equal(t, 0, remaining)
 
@@ -238,7 +238,7 @@ func TestStripCooldownFiles_NoVersionsTooNew(t *testing.T) {
 	dates, err := handler.parsePEP691Files(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5)
+	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5, nil)
 	assert.Equal(t, 0, stripped)
 	assert.Equal(t, 2, remaining)
 	assert.Equal(t, body, newBody)
@@ -256,7 +256,7 @@ func TestStripCooldownFiles_SingleVersionInCooldown(t *testing.T) {
 	dates, err := handler.parsePEP691Files(body)
 	require.NoError(t, err)
 
-	_, stripped, remaining := handler.stripCooldownFiles(body, dates, 5)
+	_, stripped, remaining := handler.stripCooldownFiles(body, dates, 5, nil)
 	assert.Equal(t, 1, stripped)
 	assert.Equal(t, 0, remaining)
 }
@@ -287,8 +287,8 @@ func TestStripCooldownFiles_MultipleFilesPerVersion_AllStripped(t *testing.T) {
 	dates, err := handler.parsePEP691Files(body)
 	require.NoError(t, err)
 
-	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5)
-	assert.Equal(t, 1, stripped)  // 1 version stripped
+	newBody, stripped, remaining := handler.stripCooldownFiles(body, dates, 5, nil)
+	assert.Equal(t, 1, stripped) // 1 version stripped
 	assert.Equal(t, 0, remaining)
 
 	var result struct {
@@ -303,7 +303,7 @@ func TestStripCooldownFiles_MalformedJSON(t *testing.T) {
 	body := []byte(`not-json`)
 	dates := map[string]time.Time{"1.0.0": time.Now().Add(-1 * time.Hour)}
 
-	newBody, stripped, _ := handler.stripCooldownFiles(body, dates, 5)
+	newBody, stripped, _ := handler.stripCooldownFiles(body, dates, 5, nil)
 	assert.Equal(t, 0, stripped)
 	assert.Equal(t, body, newBody)
 }
@@ -338,7 +338,7 @@ func TestStripCooldownFiles_UnparseableFilename_KeepFile(t *testing.T) {
 	forcedDates := map[string]time.Time{
 		"1.0.0": now.Add(-1 * 24 * time.Hour),
 	}
-	newBody, stripped, _ := handler.stripCooldownFiles(body, forcedDates, 5)
+	newBody, stripped, _ := handler.stripCooldownFiles(body, forcedDates, 5, nil)
 	assert.Equal(t, 1, stripped) // version is "stripped" from the date map perspective
 
 	var result struct {
@@ -357,7 +357,7 @@ func TestPyPICooldown_HandleMetadataRequest_OverridesHeaders(t *testing.T) {
 	ctx.Headers.Set("If-None-Match", `"abc123"`)
 	ctx.Headers.Set("If-Modified-Since", "Wed, 01 Jan 2025 00:00:00 GMT")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "requests", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "requests", 5, "", nil)
 	require.NoError(t, err)
 	assert.Equal(t, proxy.ActionModifyResponse, resp.Action)
 	assert.Equal(t, "application/vnd.pypi.simple.v1+json", ctx.Headers.Get("Accept"))
@@ -371,7 +371,7 @@ func TestPyPICooldown_HandleMetadataRequest_ClientWithoutPEP691_SkipsCooldown(t
 	ctx := makeTestRequestContext("https://pypi.org/simple/requests/")
 	ctx.Headers.Set("Accept", "text/html")
 
-	resp, err := handler.HandleMetadataRequest(ctx, "requests", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "requests", 5, "", nil)
 	require.NoError(t, err)
 	assert.Equal(t, proxy.ActionAllow, resp.Action)
 	assert.Nil(t, resp.ResponseModifier)
@@ -383,7 +383,7 @@ func TestPyPICooldown_HandleMetadataRequest_NonJSONResponse_FailOpen(t *testing.
 	ctx := makeTestRequestContext("https://pypi.org/simple/requests/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "requests", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "requests", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -410,7 +410,7 @@ func TestPyPICooldown_HandleMetadataRequest_StripsRecentVersions(t *testing.T) {
 	ctx := makeTestRequestContext("https://pypi.org/simple/testpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -448,7 +448,7 @@ func TestPyPICooldown_HandleMetadataRequest_AllVersionsInCooldown_RecordsStats(t
 	ctx := makeTestRequestContext("https://pypi.org/simple/newpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "newpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "newpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -482,7 +482,7 @@ func TestPyPICooldown_HandleMetadataRequest_NoVersionsInCooldown_BodyUnchanged(t
 	ctx := makeTestRequestContext("https://pypi.org/simple/testpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -499,7 +499,7 @@ func TestPyPICooldown_HandleMetadataRequest_MalformedJSON_FailOpen(t *testing.T)
 	ctx := makeTestRequestContext("https://pypi.org/simple/badpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "badpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "badpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -526,7 +526,7 @@ func TestPyPICooldown_HandleMetadataRequest_PinnedVersionInCooldown_RecordsStats
 	ctx := makeTestRequestContext("https://pypi.org/simple/testpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "2.0.0")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "2.0.0", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -561,7 +561,7 @@ func TestPyPICooldown_HandleMetadataRequest_PinnedVersionNotInCooldown_NoBlock(t
 	ctx := makeTestRequestContext("https://pypi.org/simple/testpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "1.0.0")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "1.0.0", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 
@@ -589,7 +589,7 @@ func TestPyPICooldown_HandleMetadataRequest_UnpinnedWithRemainingVersions_NoBloc
 	ctx := makeTestRequestContext("https://pypi.org/simple/testpkg/")
 	ctx.Headers.Set("Accept", pypiSimpleAPIContentType)
 
-	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "")
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5, "", nil)
 	require.NoError(t, err)
 	require.NotNil(t, resp.ResponseModifier)
 

proxy/interceptors/pypi_registry.go

@@ -126,7 +126,20 @@ func (i *PypiRegistryInterceptor) HandleRequest(ctx *proxy.RequestContext) (*pro
 		// for version resolution. JSON API requests (/pypi/{pkg}/json) are allowed through;
 		// they have a different response structure and pip does not use them for installs.
 		if depCooldownConfig.Enabled && strings.HasPrefix(ctx.URL.Path, "/simple/") {
-			return i.cooldownHandler.HandleMetadataRequest(ctx, pkgInfo.GetName(), depCooldownConfig.Days, i.execContext.PinnedVersions[pkgInfo.GetName()])
+			// Match the skip list against the normalized name (lowercase, _/. → -),
+			// the same canonical form used for pinned-version lookups, so a PURL
+			// like pkg:pypi/My_Pkg reliably matches the resolved request name.
+			skip := pmgconfig.CooldownSkip(packagev1.Ecosystem_ECOSYSTEM_PYPI, denormalizePyPIPackageName(pkgInfo.GetName()))
+			if skip.SkipAll {
+				// Whole package is on the cooldown skip list: pass metadata through
+				// unmodified. The tarball download still hits analyzePackage, so
+				// malware analysis is preserved.
+				log.Infof("[%s] Cooldown: package %s is on the skip list (dependency_cooldown.skip); malware analysis still applies", ctx.RequestID, pkgInfo.GetName())
+				return &proxy.InterceptorResponse{Action: proxy.ActionAllow}, nil
+			}
+
+			// Version-pinned skip entries (if any) are preserved during stripping.
+			return i.cooldownHandler.HandleMetadataRequest(ctx, pkgInfo.GetName(), depCooldownConfig.Days, i.execContext.PinnedVersions[pkgInfo.GetName()], skip.Versions)
 		}
 
 		log.Debugf("[%s] Skipping analysis for metadata request: %s", ctx.RequestID, pkgInfo.GetName())