feat(vet): review dormant npm publisher handovers (#37)

Author: duriantaco

CHANGELOG.md

@@ -51,6 +51,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `ca9 vet --scan-publisher-changes` optionally reviews direct npm lockfile
+  dependencies for recent publisher handovers after long release gaps using
+  public npm metadata. It emits review warnings tied to the locked version.
 - `ca9 review --base FILE --head FILE` compares npm v2/v3 dependency updates
   using lockfile occurrence identity, verified release artifacts, lifecycle and
   entry-point declarations, and stable static observations. Markdown and JSON

README.md

@@ -280,6 +280,7 @@ scope. See the [dependency review guide](docs/guide/dependency-review.md).
 ```bash
 ca9 vet --repo .
 ca9 vet --repo . --malware-query
+ca9 vet --repo . --scan-publisher-changes
 ca9 vet --repo . --scan-artifacts
 ca9 vet --repo . --scan-workflows
 ca9 vet --repo . --internal-package 'acme-*' --private-index https://packages.acme.internal/simple
@@ -300,6 +301,14 @@ untrusted indexes, known malicious packages, too-new package versions, and
 high-risk workflow patterns are blocking findings; weaker local signals are
 warnings or investigation items.
 
+With `--scan-publisher-changes`, ca9 queries public npm registry metadata for
+direct, locked npm dependencies. It warns when a new publisher released a stable
+version after at least 180 days without a release, within the last 365 days, and
+the locked version belongs to that publisher's later releases. Verified npm
+trusted publishing and publishers who maintain another package with at least
+100,000 weekly downloads are exempt. This is a review signal, not a malware
+verdict. The check requires network access and cannot be combined with `--offline`.
+
 With `--scan-artifacts`, ca9 downloads only lockfile artifacts with hashes by
 default, verifies the hash, safely unpacks Python wheels/sdists and npm tarballs
 without executing code, and runs GuardDog-style static heuristics for suspicious
@@ -687,13 +696,14 @@ Vet-only options:
   --private-index URL               Private index allowed for internal packages
   --internal-package PATTERN        Internal package glob, e.g. acme-*; repeatable
   --malware-query                   Query OSV for known malicious packages
+  --scan-publisher-changes          Query npm for recent publisher handovers after dormancy
   --scan-artifacts                  Hash-verify, unpack, and statically inspect artifacts
   --scan-workflows                  Scan GitHub Actions workflow risk patterns
   --allow-unhashed-downloads        Allow artifact downloads without lockfile hashes
   --max-artifact-mb N               Max artifact download size  [default: 100]
   --deny-license ID                 Denied license identifier; repeatable
   --require-known-license           Warn when artifact metadata has no known license
-  --offline                         Use cached OSV data only for malware query
+  --offline                         Use cached OSV data for malware query; incompatible with publisher checks
 
 Policy-only options:
   --policy PATH                   ca9 package policy TOML

docs/guide/cli.md

@@ -214,13 +214,14 @@ Options:
 | `--private-index URL` | Private package index allowed for internal package names. Can be repeated. |
 | `--internal-package PATTERN` | Internal package name or glob pattern, e.g. `acme-*`. Can be repeated. |
 | `--malware-query` | Query OSV for known malicious-package advisories. |
+| `--scan-publisher-changes` | Query public npm metadata for recent publisher changes after release dormancy in direct, locked dependencies. |
 | `--scan-artifacts` | Hash-verify, unpack, and statically inspect package artifacts. |
 | `--scan-workflows` | Scan GitHub Actions workflows for risky token, OIDC, and trust-boundary patterns. |
 | `--allow-unhashed-downloads` | Allow artifact scanning when the lockfile has no artifact hash. |
 | `--max-artifact-mb N` | Maximum artifact download size for `--scan-artifacts`. Defaults to `100`. |
 | `--deny-license ID` | Denied license identifier. Can be repeated. |
 | `--require-known-license` | Warn when scanned artifact metadata has no known license. |
-| `--offline` | Use cached OSV data only for `--malware-query`. |
+| `--offline` | Use cached OSV data only for `--malware-query`; incompatible with `--scan-publisher-changes`. |
 | `--refresh-cache` | Clear OSV cache before `--malware-query`. |
 | `--max-osv-workers N` | Maximum concurrent OSV detail fetches. Defaults to `8`. |
 
@@ -229,6 +230,7 @@ Examples:
 ```bash
 ca9 vet --repo .
 ca9 vet --repo . --scan-artifacts
+ca9 vet --repo . --scan-publisher-changes
 ca9 vet --repo . --scan-workflows
 ca9 vet --repo . --malware-query --offline
 ca9 vet --repo . --internal-package 'acme-*' --private-index https://packages.acme.internal/simple

docs/guide/supply-chain.md

@@ -178,6 +178,33 @@ is separate from the installed local feed: the feed path is deterministic and lo
 while `--malware-query` asks OSV or uses the OSV cache. Use `--offline` to restrict the
 query path to cached OSV data.
 
+## Npm Publisher Change Review
+
+Query the public npm registry for recent changes in publishers after a dormant
+release period:
+
+```bash
+ca9 vet --repo . --scan-publisher-changes
+```
+
+This optional check covers direct npm dependencies pinned in `package-lock.json`
+and resolved from `https://registry.npmjs.org`. It reads full package metadata
+and warns when a stable release in the past 365 days followed a gap of at least
+180 days and came from a publisher not seen in earlier releases. The locked
+version must be from that publisher and no older than the handover. Releases
+with npm's verified trusted-publisher identity and publishers with another
+package receiving at least 100,000 weekly downloads are excluded. If the
+publisher lookup is unavailable, ca9 keeps the finding and adds a report
+warning. Metadata fetch failures also appear in report warnings. This signal calls
+for human review; it does not establish malicious behavior. The check can
+download large registry documents, so it is opt-in and cannot run with
+`--offline`.
+
+Some old npm releases have timestamps but no publisher identity. ca9 reports
+that incomplete history and can still warn when the publisher immediately
+before the handover is known. In that case, the new publisher is the first
+*observed* publisher in the available metadata, not necessarily the first ever.
+
 ## GitHub Actions Workflow Scanning
 
 Scan workflow files for risky token and trust-boundary patterns:

src/ca9/cli.py

@@ -947,6 +947,12 @@ def protect_cmd(
     default=False,
     help="Query OSV for known malicious package advisories.",
 )
+@click.option(
+    "--scan-publisher-changes",
+    is_flag=True,
+    default=False,
+    help="Query public npm metadata for recent publisher changes after release dormancy.",
+)
 @click.option(
     "--scan-artifacts",
     is_flag=True,
@@ -988,7 +994,7 @@ def protect_cmd(
     "--offline",
     is_flag=True,
     default=False,
-    help="Use only cached OSV data for --malware-query.",
+    help="Use cached OSV data for --malware-query; cannot scan publisher changes.",
 )
 @click.option(
     "--refresh-cache",
@@ -1014,6 +1020,7 @@ def vet_cmd(
     private_indexes: tuple[str, ...],
     internal_package_patterns: tuple[str, ...],
     malware_query: bool,
+    scan_publisher_changes: bool,
     scan_artifacts: bool,
     scan_workflows: bool,
     allow_unhashed_downloads: bool,
@@ -1050,6 +1057,18 @@ def vet_cmd(
         raise click.ClickException(str(exc)) from None
 
     inventory = build_inventory(repo_path)
+    if offline and scan_publisher_changes:
+        raise click.ClickException(
+            "--scan-publisher-changes requires npm registry access; remove --offline"
+        )
+
+    publisher_findings = []
+    publisher_warnings = []
+    if scan_publisher_changes:
+        from ca9.npm_publisher import scan_npm_publisher_changes
+
+        publisher_findings, publisher_warnings = scan_npm_publisher_changes(inventory.packages)
+
     policy_findings = []
     feed_warnings = []
     if package_policy.package_age.enabled:
@@ -1107,7 +1126,7 @@ def vet_cmd(
                 raise click.ClickException(str(e)) from None
 
     artifact_findings = []
-    artifact_warnings = [*policy_warnings, *feed_warnings]
+    artifact_warnings = [*policy_warnings, *feed_warnings, *publisher_warnings]
     artifact_scans = 0
     skipped_artifacts = 0
     workflow_findings = []
@@ -1132,7 +1151,12 @@ def vet_cmd(
             require_known_license=require_known_license,
         )
         artifact_findings.extend(analyze_license_policy(artifact_result.snapshots, license_policy))
-        artifact_warnings = [*policy_warnings, *feed_warnings, *artifact_result.warnings]
+        artifact_warnings = [
+            *policy_warnings,
+            *feed_warnings,
+            *publisher_warnings,
+            *artifact_result.warnings,
+        ]
         artifact_scans = artifact_result.scanned_artifacts
         skipped_artifacts = artifact_result.skipped_artifacts
 
@@ -1157,7 +1181,12 @@ def vet_cmd(
         inventory,
         policy=policy,
         malware_advisories=malware_advisories,
-        extra_findings=[*policy_findings, *artifact_findings, *workflow_findings],
+        extra_findings=[
+            *policy_findings,
+            *publisher_findings,
+            *artifact_findings,
+            *workflow_findings,
+        ],
         extra_warnings=artifact_warnings,
         artifact_scans=artifact_scans,
         skipped_artifacts=skipped_artifacts,