diff --git a/config/config.go b/config/config.go index 3f37cfe..a27778a 100644 --- a/config/config.go +++ b/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 diff --git a/config/config.template.yml b/config/config.template.yml index 1f52712..3c3d69b 100644 --- a/config/config.template.yml +++ b/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. diff --git a/config/cooldown_skip_test.go b/config/cooldown_skip_test.go new file mode 100644 index 0000000..e64dd6f --- /dev/null +++ b/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) +} diff --git a/config/trusted.go b/config/trusted.go index 7b327c9..d8a6a1c 100644 --- a/config/trusted.go +++ b/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. diff --git a/docs/dependency-cooldown.md b/docs/dependency-cooldown.md index bd40177..bf1a286 100644 --- a/docs/dependency-cooldown.md +++ b/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: diff --git a/proxy/interceptors/npm_cooldown.go b/proxy/interceptors/npm_cooldown.go index fa67c5e..c8772ed 100644 --- a/proxy/interceptors/npm_cooldown.go +++ b/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 } diff --git a/proxy/interceptors/npm_cooldown_test.go b/proxy/interceptors/npm_cooldown_test.go index 4adf77d..4d27fea 100644 --- a/proxy/interceptors/npm_cooldown_test.go +++ b/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) diff --git a/proxy/interceptors/npm_registry.go b/proxy/interceptors/npm_registry.go index 802f406..30ef9a7 100644 --- a/proxy/interceptors/npm_registry.go +++ b/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()) diff --git a/proxy/interceptors/pypi_cooldown.go b/proxy/interceptors/pypi_cooldown.go index 8ce0daa..f1b040d 100644 --- a/proxy/interceptors/pypi_cooldown.go +++ b/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 } diff --git a/proxy/interceptors/pypi_cooldown_test.go b/proxy/interceptors/pypi_cooldown_test.go index 301c48f..c8f2d30 100644 --- a/proxy/interceptors/pypi_cooldown_test.go +++ b/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) diff --git a/proxy/interceptors/pypi_registry.go b/proxy/interceptors/pypi_registry.go index cd00c9f..4324a81 100644 --- a/proxy/interceptors/pypi_registry.go +++ b/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())