|
| 1 | +"""Provenance Regression Detector |
| 2 | +
|
| 3 | +npm records a `dist.attestations` field on a version when it was published with |
| 4 | +provenance (`npm publish --provenance` from a trusted CI flow). When a version |
| 5 | +that previously carried attestations is followed by one that lacks them, the |
| 6 | +publish likely happened outside the normal attested flow. That regression is the |
| 7 | +signal this detector flags, mirroring the pattern seen in the nx compromise where |
| 8 | +malicious versions were pushed with stolen credentials. |
| 9 | +
|
| 10 | +A package that never adopted provenance is not flagged. Absence alone is common |
| 11 | +and legitimate; only a regression (had it, then lost it) counts. |
| 12 | +
|
| 13 | +Evidence of prior provenance must come from a version that precedes the scanned one |
| 14 | +in semver order, not merely in publish time. Projects routinely publish a modernized |
| 15 | +release line from an attested CI workflow while still cutting maintenance releases of |
| 16 | +an older line the old way, so a later-published patch of an older line is not a |
| 17 | +regression against it. |
| 18 | +""" |
| 19 | + |
| 20 | +import logging |
| 21 | +from typing import Optional |
| 22 | + |
| 23 | +from semantic_version import Version # type: ignore |
| 24 | + |
| 25 | +from guarddog.analyzer.metadata.detector import Detector |
| 26 | +from guarddog.utils.npm import published_versions_before |
| 27 | + |
| 28 | +log = logging.getLogger("guarddog") |
| 29 | + |
| 30 | + |
| 31 | +def _parse_semver(version: str) -> Optional[Version]: |
| 32 | + try: |
| 33 | + return Version(version) |
| 34 | + except ValueError: |
| 35 | + return None |
| 36 | + |
| 37 | + |
| 38 | +class NPMProvenanceRegressionDetector(Detector): |
| 39 | + """Detects a version that dropped npm provenance attestations earlier versions had. |
| 40 | +
|
| 41 | + The scanned version's `dist.attestations` is checked first: if present, there is |
| 42 | + no regression. If absent, the package's publish history (ordered by the registry |
| 43 | + `time` map) is walked backward. Finding an earlier version that did carry |
| 44 | + attestations flags the package; running out of earlier versions without finding |
| 45 | + one means the package never used provenance, which is not a regression. |
| 46 | +
|
| 47 | + Only versions that also precede the scanned one in semver order count as evidence, |
| 48 | + and prereleases only count when the scanned version is itself a prerelease.""" |
| 49 | + |
| 50 | + def __init__(self): |
| 51 | + super().__init__( |
| 52 | + name="provenance_regression", |
| 53 | + description="Identify a version that lost npm provenance attestations that " |
| 54 | + "earlier versions had. A version dropping provenance after prior versions " |
| 55 | + "carried it can indicate a publish made outside the normal CI-attested flow.", |
| 56 | + identifies="threat.metadata.provenance-regression", |
| 57 | + severity="medium", |
| 58 | + mitre_tactics="initial-access", |
| 59 | + specificity="medium", |
| 60 | + sophistication="low", |
| 61 | + ) |
| 62 | + |
| 63 | + def detect( |
| 64 | + self, |
| 65 | + package_info, |
| 66 | + path: Optional[str] = None, |
| 67 | + name: Optional[str] = None, |
| 68 | + version: Optional[str] = None, |
| 69 | + ) -> tuple[bool, Optional[str]]: |
| 70 | + package_name = name or package_info.get("name", "") |
| 71 | + versions = package_info.get("versions", {}) |
| 72 | + current_version = version or package_info.get("dist-tags", {}).get("latest") |
| 73 | + if not current_version or current_version not in versions: |
| 74 | + log.debug( |
| 75 | + f"[{self.name}] No usable version for '{package_name}' " |
| 76 | + f"(resolved '{current_version}'); skipping" |
| 77 | + ) |
| 78 | + return False, None |
| 79 | + |
| 80 | + if self._has_attestations(versions.get(current_version, {})): |
| 81 | + log.debug( |
| 82 | + f"[{self.name}] '{package_name}@{current_version}' has provenance " |
| 83 | + f"attestations; no regression" |
| 84 | + ) |
| 85 | + return False, None |
| 86 | + |
| 87 | + last_attested = self._most_recent_attested_before(package_info, current_version) |
| 88 | + if last_attested is None: |
| 89 | + log.debug( |
| 90 | + f"[{self.name}] '{package_name}@{current_version}' lacks attestations " |
| 91 | + f"and no earlier version had them; not a regression" |
| 92 | + ) |
| 93 | + return False, None |
| 94 | + |
| 95 | + log.debug( |
| 96 | + f"[{self.name}] '{package_name}@{current_version}' lost provenance " |
| 97 | + f"attestations last seen on '{last_attested}'; flagging" |
| 98 | + ) |
| 99 | + return True, ( |
| 100 | + f"Version {current_version} was published without npm provenance " |
| 101 | + f"attestations, but the earlier version {last_attested} had them. Losing " |
| 102 | + f"provenance after previous versions carried it can indicate a publish made " |
| 103 | + f"outside the normal CI-attested flow, as seen in the nx compromise." |
| 104 | + ) |
| 105 | + |
| 106 | + @staticmethod |
| 107 | + def _has_attestations(version_info: dict) -> bool: |
| 108 | + """Whether a version was published with npm provenance attestations.""" |
| 109 | + return "attestations" in (version_info.get("dist") or {}) |
| 110 | + |
| 111 | + def _most_recent_attested_before( |
| 112 | + self, package_info, current_version: str |
| 113 | + ) -> Optional[str]: |
| 114 | + """Walk earlier versions newest-first and return the first with attestations. |
| 115 | +
|
| 116 | + The walk does not stop at the immediately preceding version: a compromise may |
| 117 | + push several unsigned releases in a row, so the search continues back until a |
| 118 | + version with attestations is found or the history is exhausted. |
| 119 | + """ |
| 120 | + versions = package_info.get("versions", {}) |
| 121 | + for earlier_version in published_versions_before(package_info, current_version): |
| 122 | + if not self._precedes_in_release_order(earlier_version, current_version): |
| 123 | + continue |
| 124 | + if self._has_attestations(versions.get(earlier_version, {})): |
| 125 | + return earlier_version |
| 126 | + return None |
| 127 | + |
| 128 | + @staticmethod |
| 129 | + def _precedes_in_release_order(candidate: str, current_version: str) -> bool: |
| 130 | + """Whether `candidate` can be evidence of provenance the current version lost. |
| 131 | +
|
| 132 | + A version published earlier in time still belongs to a later release line when |
| 133 | + it is semver-greater, e.g. an attested `8.0.0-alpha` published before an |
| 134 | + unattested `7.8.2` maintenance patch. Such a version is not something the |
| 135 | + current one regressed from. |
| 136 | +
|
| 137 | + Prereleases only count as evidence for another prerelease: a project commonly |
| 138 | + pipes its `next` line through attested CI before its stable line, and a stable |
| 139 | + release that lacks what only an alpha had has not lost anything. |
| 140 | + """ |
| 141 | + current_semver = _parse_semver(current_version) |
| 142 | + candidate_semver = _parse_semver(candidate) |
| 143 | + if current_semver is None or candidate_semver is None: |
| 144 | + # npm requires valid semver, so this is unreachable in practice; fall back |
| 145 | + # to publish order rather than silently dropping the version from the walk. |
| 146 | + return True |
| 147 | + if candidate_semver.prerelease and not current_semver.prerelease: |
| 148 | + return False |
| 149 | + return candidate_semver < current_semver |
0 commit comments