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

@ -25,7 +25,7 @@ import {
NPM_COMPROMISED, PIP_COMPROMISED, CARGO_COMPROMISED, GEM_COMPROMISED,
DOCKER_SUSPICIOUS, POPULAR_PIP,
isCompromised, parseSpec, parsePipSpec, execSafe,
queryOSV, extractOSVSeverity,
queryOSV, extractOSVSeverity, checkScopeHop,
} from '../../scanners/lib/supply-chain-data.mjs';
import { normalizeBashExpansion } from '../../scanners/lib/bash-normalize.mjs';
import { getPolicyValue } from '../../scanners/lib/policy-loader.mjs';
@ -123,6 +123,21 @@ async function checkNpm() {
for (const spec of packages) {
const { name, version } = parseSpec(spec);
// E13: scope-hopping advisory — '@evilcorp/lodash' where '@evilcorp'
// is not on the official-scopes allowlist and 'lodash' matches a top
// npm package. MEDIUM advisory only, never blocks.
const allowedScopes = getPolicyValue('supply_chain', 'allowed_scopes', []);
const scopeHop = checkScopeHop(name, allowedScopes);
if (scopeHop) {
warnings.push(
`SCOPE-HOPPING SUSPECTED: "${scopeHop.spec}"\n` +
` Unscoped name "${scopeHop.unscoped}" matches a top-100 npm package, but\n` +
` scope "${scopeHop.scope}" is not on the official-scopes allowlist.\n` +
` Verify the publisher before installing. Add "${scopeHop.scope}" to\n` +
` policy.json supply_chain.allowed_scopes to silence this advisory.`
);
}
if (isCompromised(NPM_COMPROMISED, name, version) || POLICY_BLOCKED.has(name)) {
blocks.push(
`COMPROMISED: ${name}${version ? '@' + version : ''}\n` +