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-08-03 07:24:09 +02:00 · 2026-06-15 19:44:55 +05:30
parent 26d5c0ad71
commit 61230fbcd7
11 changed files with 372 additions and 49 deletions
@@ -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
@@ -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.
@@ -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)
+}
@@ -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.