feat(pre-install-supply-chain): E13 — npm scope-hopping MEDIUM advisory with allowlist

Adds a scope-hopping detector to the npm install gate. When a user
installs `@<scope>/<unscoped>`, the hook now emits a MEDIUM warning
on stderr (exit 0, never blocks) if:
  - `<unscoped>` matches a popular npm package (POPULAR_NPM, ~80
    names from knowledge/top-packages.json), AND
  - `<scope>` is not on NPM_OFFICIAL_SCOPES (built-in 22 entries) or
    on policy.json `supply_chain.allowed_scopes`.

Why: an attacker publishing `@evilcorp/lodash` cannot squat the bare
`lodash` name, but they can register an unrelated scope and rely on
typo or copy-paste to trick installs. NPM_OFFICIAL_SCOPES anchors the
known-good scopes (@types, @reduxjs, @nestjs, …) so legitimate
installs stay silent.

Implementation:
- `scanners/lib/supply-chain-data.mjs`: exports POPULAR_NPM,
  NPM_OFFICIAL_SCOPES, and `checkScopeHop(name, extraAllowedScopes)` —
  pure function, no policy/network dependency, fully unit-testable.
- `knowledge/typosquat-allowlist.json`: mirrors NPM_OFFICIAL_SCOPES as
  `npm_official_scopes`. A doc-consistency assertion ensures the two
  lists never drift.
- `hooks/scripts/pre-install-supply-chain.mjs`: imports checkScopeHop,
  reads `supply_chain.allowed_scopes` from policy, and pushes a
  warning before existing compromised/audit checks.

Tests:
- 9 new cases in tests/hooks/pre-install-supply-chain.test.mjs:
  TP @evilcorp/lodash, TP @attacker/express, allowlist @types,
  allowlist @reduxjs, allowlist @modelcontextprotocol, FP unscoped
  name not in top-100, bare unscoped name, policy override, defensive
  non-string input, NPM_OFFICIAL_SCOPES <-> typosquat-allowlist.json
  consistency.
This commit is contained in:
Kjell Tore Guttormsen 2026-04-30 15:38:28 +02:00
commit ad86f5031a
4 changed files with 173 additions and 2 deletions

View file

@ -1,5 +1,5 @@
{
"_comment": "Known legitimate packages that trigger false positive typosquatting alerts due to short names or Levenshtein proximity to top packages. Normalized: lowercase, hyphens. Extended in v7.0.0 with short-named legit packages observed flagged against top-200 (knip vs knex, oxlint vs eslint, tsx vs nx, etc.).",
"_comment": "Known legitimate packages that trigger false positive typosquatting alerts due to short names or Levenshtein proximity to top packages. Normalized: lowercase, hyphens. Extended in v7.0.0 with short-named legit packages observed flagged against top-200 (knip vs knex, oxlint vs eslint, tsx vs nx, etc.). v7.3.0 adds npm_official_scopes — list of scopes whose scoped packages should NOT trigger E13 scope-hopping advisory. Kept in sync with NPM_OFFICIAL_SCOPES in scanners/lib/supply-chain-data.mjs (doc-consistency drift-guard).",
"npm": [
"ms",
"acorn",
@ -58,5 +58,29 @@
"rich",
"typer",
"anyio"
],
"npm_official_scopes": [
"@types",
"@reduxjs",
"@nestjs",
"@angular",
"@nrwl",
"@modelcontextprotocol",
"@babel",
"@testing-library",
"@aws-sdk",
"@azure",
"@google-cloud",
"@vue",
"@svelte",
"@nuxt",
"@sveltejs",
"@vitejs",
"@playwright",
"@storybook",
"@radix-ui",
"@reach",
"@emotion",
"@mui"
]
}