mirror of
https://github.com/safedep/pmg.git
synced 2026-08-03 07:24:09 +02:00
327c9c7068
* feat(cooldown): respect trusted_packages in dependency cooldown Trusted packages are now treated as a superset waiver that bypasses every PMG control (malware analysis, cooldown, and any future controls). A globally trusted package is automatically exempt from the cooldown window and no longer needs a duplicate entry in dependency_cooldown.skip. The skip list remains the narrower, cooldown-only waiver for packages that must bypass the cooldown wait but still be malware-scanned. * refactor(cooldown): tag skip reason and audit-log skipped packages Address review feedback on #342: - Restore cooldownSkip to a pure single-list function (SRP); the merge into trusted_packages now happens in a separate mergeCooldownSkip step, driven by the exported CooldownSkip wrapper. - Extend CooldownSkipInfo with a CooldownSkipReason (TrustedPackage / CooldownSkipList) on both SkipAll and per-version entries, so callers can tell apart the broad waiver from the cooldown-only one. When both lists match the same package, trusted_packages wins. - Add audit.LogCooldownSkipped and emit it from the npm and PyPI interceptors on the SkipAll path, alongside the existing info log, carrying the source list as the reason. * refactor(cooldown): inline list merge, audit per-version exemptions Address further review feedback: - Drop the separate mergeCooldownSkip helper; cooldownSkip now writes into a shared *CooldownSkipInfo and is called twice from CooldownSkip (cooldown skip list first, trusted_packages on top so trusted entries override the reason on overlap). - Audit log every exemption, not just SkipAll: a new auditCooldownSkip helper in proxy/interceptors/cooldown.go emits one event per match (package-wide or per-version), each tagged with its source list. LogCooldownSkipped gains a version argument for the per-version case. - Cover the trusted_packages reason path in TestCooldownSkip. * fix(cooldown): avoid double-auditing trusted package exemptions auditCooldownSkip now only emits EventTypeCooldownSkipped for entries that came from dependency_cooldown.skip. Trusted-package exemptions already get an EventTypeInstallTrustedAllowed event at tarball-download time (proxy/interceptors/base_registry.go), so emitting a cooldown event for them too would double-count the same waiver. * emit trusted and cooldown skip events to cloud * fix tests * refactor(cooldown): return value from collectCooldownSkip, short-circuit on trusted SkipAll Address PR review feedback: - Rename cooldownSkip to collectCooldownSkip and return CooldownSkipInfo instead of mutating an input pointer. - Add mergeCooldownSkip to combine per-list results with trusted_packages taking precedence on overlap. - CooldownSkip now consults trusted_packages first and returns immediately on a package-wide trusted exemption (DC skip list cannot add anything). - Extend tests to cover disjoint pinned entries across both lists and the case where DC version-less subsumes a trusted pinned entry. * fix(audit): address cooldown review feedback * fix(cooldown): audit cooldown skips at download time with concrete version Backend rejects PackageVersion messages without a version, and audit logs should reflect the runtime fact (a specific version was skipped) rather than the config rule. Move the audit emission from metadata-request handling to download-request handling, where the concrete version is known, and require version in LogCooldownSkipped. * chore(audit): drop dead scope assignment in LogCooldownSkipped * refactor(cooldown): move skip-list logic into cooldown handlers Registry interceptors no longer compute CooldownSkip or branch on SkipAll; they just call HandleMetadataRequest. The npm and pypi cooldown handlers own the skip lookup, the package-wide exemption short-circuit, and (for pypi) the canonical-name denormalization. Also align LogCooldownSkipped with other LogXxx signatures by taking *packagev1.PackageVersion. * fix: Simplify audit logging for dependency cooldown skip * refactor: Simplify cooldown handling and maintain separation of concepts for trusted and DC skip packages * fix: Code review fixes * fix: Emit cooldown skipped audit event ONLY when an in-window version is skipped --------- Co-authored-by: Abhisek Datta <abhisek.datta@gmail.com>
84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
# 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](../config/config.template.yml) for the full schema. If you don't have a `config.yml` file, create one by running `pmg setup install`.
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```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.** Use it when you want a
|
|
package to bypass cooldown but still go through every other security control.
|
|
|
|
If you want a package to bypass **every** control PMG enforces — malware
|
|
analysis, dependency cooldown, and any future policies — add it to the
|
|
top-level [`trusted_packages`](trusted-packages.md) list instead. A globally
|
|
trusted package is automatically exempted from the cooldown window without
|
|
needing a separate entry here.
|
|
|
|
| List | Waives malware analysis | Waives cooldown | Waives future controls |
|
|
| --- | --- | --- | --- |
|
|
| `trusted_packages` (top level) | yes | yes | yes |
|
|
| `dependency_cooldown.skip` | no | yes | no |
|
|
|
|
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:
|
|
|
|
```bash
|
|
pmg --skip-dependency-cooldown npm install express
|
|
```
|
|
|
|
## Requirements
|
|
|
|
Dependency cooldown requires [proxy mode](proxy-mode.md) 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](https://peps.python.org/pep-0691/) 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.
|