postinstall-guardian 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SNR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# postinstall-guardian
+
+Scan `node_modules` for `preinstall`/`install`/`postinstall` scripts — the
+most common npm supply-chain attack vector (a compromised or typosquatted
+package runs arbitrary code the moment someone runs `npm install`) — and gate
+CI on any that aren't explicitly approved.
+
+## Why not just `npm audit`?
+
+`npm audit` only flags packages with a *reported* CVE. A malicious install
+script in a brand-new or typosquatted package has no CVE yet — that's exactly
+how the recent high-profile npm supply-chain compromises worked. This tool
+doesn't judge whether a script is malicious (it can't); it makes sure a human
+looks at every install script before it's allowed to run unreviewed in CI.
+
+## How it works
+
+1. `postinstall-guardian scan` walks `node_modules` (including nested/hoisted
+   copies) and lists every package with an install-type script.
+2. Compare that list against a baseline file (`.postinstall-guardian.json`,
+   committed to your repo) of package versions you've already reviewed and
+   approved.
+3. `postinstall-guardian ci` exits non-zero if anything isn't in the
+   baseline — so a new or bumped dependency with a new install script fails
+   the build until someone reviews and approves it.
+
+A version bump automatically drops out of the baseline and gets re-flagged,
+since a new version can ship a different script than the one you approved.
+
+## Install
+
+```bash
+npm install --save-dev postinstall-guardian
+```
+
+## CLI
+
+### `postinstall-guardian scan`
+
+```bash
+postinstall-guardian scan --dir . --report report.md
+```
+
+Lists every install-type script found and marks which ones aren't yet
+approved. Exit code is always 0 — use `ci` for a gating exit code.
+
+### `postinstall-guardian approve`
+
+```bash
+postinstall-guardian approve
+```
+
+Adds every currently-found install script to `.postinstall-guardian.json`.
+**Review the `scan` output before running this** — approving is how you tell
+the tool "I looked at this command and it's fine."
+
+### `postinstall-guardian ci`
+
+```bash
+postinstall-guardian ci --report postinstall-guardian-report.md
+```
+
+Scans, writes a report, and exits 1 if any install script isn't in the
+baseline. This is the command to run in CI.
+
+### `postinstall-guardian init-workflow`
+
+```bash
+postinstall-guardian init-workflow
+# writes .github/workflows/postinstall-guardian.yml
+```
+
+Writes a workflow that runs on every push/PR to `main` (new install scripts
+arrive with dependency changes, not on a calendar) plus a daily cron as a
+backstop for unpinned version ranges resolving to a new version between
+deploys. It installs with `npm ci --ignore-scripts` so CI never executes the
+scripts it's auditing.
+
+## Library API
+
+```ts
+import { scan, mergeIntoBaseline, writeBaseline, readBaseline } from 'postinstall-guardian';
+
+const result = await scan('./my-project');
+if (result.unapproved.length > 0) {
+  console.log(`${result.unapproved.length} unreviewed install script(s)`);
+}
+```
+
+## Baseline file format
+
+```json
+{
+  "approved": ["esbuild@0.21.5", "sharp@0.33.4"]
+}
+```
+
+Commit `.postinstall-guardian.json` to version control — reviewing and
+approving a new script is meant to happen in a PR, same as any other code
+change.
+
+## Limitations
+
+- Only npm's `node_modules` layout is supported (pnpm's symlink layout is
+  deduped via realpath, but scoped/aliased pnpm structures aren't specially
+  handled).
+- This tool surfaces scripts for human review — it does not analyze whether
+  a script is actually malicious.

package/dist/baseline.d.ts

@@ -0,0 +1,6 @@
+import type { Baseline, ScriptEntry } from './types';
+export declare const DEFAULT_BASELINE_FILE = ".postinstall-guardian.json";
+export declare function readBaseline(root: string, filename?: string): Promise<Baseline>;
+export declare function writeBaseline(root: string, baseline: Baseline, filename?: string): Promise<void>;
+export declare function diffAgainstBaseline(entries: ScriptEntry[], baseline: Baseline): ScriptEntry[];
+export declare function mergeIntoBaseline(baseline: Baseline, entries: ScriptEntry[]): Baseline;

package/dist/baseline.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BASELINE_FILE = void 0;
+exports.readBaseline = readBaseline;
+exports.writeBaseline = writeBaseline;
+exports.diffAgainstBaseline = diffAgainstBaseline;
+exports.mergeIntoBaseline = mergeIntoBaseline;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const types_1 = require("./types");
+exports.DEFAULT_BASELINE_FILE = '.postinstall-guardian.json';
+async function readBaseline(root, filename = exports.DEFAULT_BASELINE_FILE) {
+    try {
+        const raw = await node_fs_1.promises.readFile((0, node_path_1.join)(root, filename), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.approved))
+            throw new Error('malformed baseline');
+        return { approved: parsed.approved };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { approved: [] };
+        throw new Error(`Could not read ${filename}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+async function writeBaseline(root, baseline, filename = exports.DEFAULT_BASELINE_FILE) {
+    const sorted = { approved: [...new Set(baseline.approved)].sort() };
+    await node_fs_1.promises.writeFile((0, node_path_1.join)(root, filename), JSON.stringify(sorted, null, 2) + '\n', 'utf8');
+}
+function diffAgainstBaseline(entries, baseline) {
+    const approved = new Set(baseline.approved);
+    return entries.filter((entry) => !approved.has((0, types_1.baselineKey)(entry)));
+}
+function mergeIntoBaseline(baseline, entries) {
+    const approved = new Set(baseline.approved);
+    for (const entry of entries)
+        approved.add((0, types_1.baselineKey)(entry));
+    return { approved: [...approved] };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const scan_1 = require("./scan");
+const report_1 = require("./report");
+const baseline_1 = require("./baseline");
+const workflowTemplate_1 = require("./workflowTemplate");
+const program = new commander_1.Command();
+program
+    .name('postinstall-guardian')
+    .description('Scan node_modules for preinstall/install/postinstall scripts and gate CI on unapproved ones.')
+    .version('0.1.0');
+function writeReport(path, contents) {
+    if (!path)
+        return;
+    const full = (0, node_path_1.resolve)(process.cwd(), path);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(full), { recursive: true });
+    (0, node_fs_1.writeFileSync)(full, contents, 'utf8');
+}
+program
+    .command('scan')
+    .description('List install-type scripts in node_modules and flag any not in the baseline.')
+    .option('-d, --dir <path>', 'project directory', '.')
+    .option('-r, --report <path>', 'write a Markdown report to this path')
+    .action(async (opts) => {
+    const cwd = (0, node_path_1.resolve)(process.cwd(), opts.dir);
+    const result = await (0, scan_1.scan)(cwd);
+    const md = (0, report_1.scanToMarkdown)(result);
+    console.log(md);
+    writeReport(opts.report, md);
+});
+program
+    .command('approve')
+    .description('Add all currently-found install scripts to the baseline (review them first!).')
+    .option('-d, --dir <path>', 'project directory', '.')
+    .action(async (opts) => {
+    const cwd = (0, node_path_1.resolve)(process.cwd(), opts.dir);
+    const result = await (0, scan_1.scan)(cwd);
+    const baseline = await (0, baseline_1.readBaseline)(cwd);
+    const updated = (0, baseline_1.mergeIntoBaseline)(baseline, result.entries);
+    await (0, baseline_1.writeBaseline)(cwd, updated);
+    console.log(`Approved ${result.unapproved.length} new script(s). ${baseline_1.DEFAULT_BASELINE_FILE} now tracks ${updated.approved.length} package version(s).`);
+});
+program
+    .command('ci')
+    .description('Scan and exit non-zero if any install script is not in the baseline.')
+    .option('-d, --dir <path>', 'project directory', '.')
+    .option('-r, --report <path>', 'write a Markdown report to this path', 'postinstall-guardian-report.md')
+    .action(async (opts) => {
+    const cwd = (0, node_path_1.resolve)(process.cwd(), opts.dir);
+    const result = await (0, scan_1.scan)(cwd);
+    const md = (0, report_1.scanToMarkdown)(result);
+    console.log(md);
+    writeReport(opts.report, md);
+    if (result.unapproved.length > 0) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command('init-workflow')
+    .description('Write a GitHub Actions workflow that runs postinstall-guardian on every push/PR (plus a daily backstop).')
+    .option('-o, --out <path>', 'workflow file path', '.github/workflows/postinstall-guardian.yml')
+    .option('--cron <expr>', 'backstop cron schedule (UTC)', '0 6 * * *')
+    .option('--node-version <version>', 'Node.js version to run under', '20')
+    .action((opts) => {
+    const yaml = (0, workflowTemplate_1.workflowYaml)({ cron: opts.cron, nodeVersion: opts.nodeVersion });
+    const full = (0, node_path_1.resolve)(process.cwd(), opts.out);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(full), { recursive: true });
+    (0, node_fs_1.writeFileSync)(full, yaml, 'utf8');
+    console.log(`Wrote ${opts.out}`);
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export { scan } from './scan';
+export { scanNodeModules } from './scanner';
+export { readBaseline, writeBaseline, diffAgainstBaseline, mergeIntoBaseline, DEFAULT_BASELINE_FILE } from './baseline';
+export { scanToMarkdown } from './report';
+export { workflowYaml } from './workflowTemplate';

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowYaml = exports.scanToMarkdown = exports.DEFAULT_BASELINE_FILE = exports.mergeIntoBaseline = exports.diffAgainstBaseline = exports.writeBaseline = exports.readBaseline = exports.scanNodeModules = exports.scan = void 0;
+__exportStar(require("./types"), exports);
+var scan_1 = require("./scan");
+Object.defineProperty(exports, "scan", { enumerable: true, get: function () { return scan_1.scan; } });
+var scanner_1 = require("./scanner");
+Object.defineProperty(exports, "scanNodeModules", { enumerable: true, get: function () { return scanner_1.scanNodeModules; } });
+var baseline_1 = require("./baseline");
+Object.defineProperty(exports, "readBaseline", { enumerable: true, get: function () { return baseline_1.readBaseline; } });
+Object.defineProperty(exports, "writeBaseline", { enumerable: true, get: function () { return baseline_1.writeBaseline; } });
+Object.defineProperty(exports, "diffAgainstBaseline", { enumerable: true, get: function () { return baseline_1.diffAgainstBaseline; } });
+Object.defineProperty(exports, "mergeIntoBaseline", { enumerable: true, get: function () { return baseline_1.mergeIntoBaseline; } });
+Object.defineProperty(exports, "DEFAULT_BASELINE_FILE", { enumerable: true, get: function () { return baseline_1.DEFAULT_BASELINE_FILE; } });
+var report_1 = require("./report");
+Object.defineProperty(exports, "scanToMarkdown", { enumerable: true, get: function () { return report_1.scanToMarkdown; } });
+var workflowTemplate_1 = require("./workflowTemplate");
+Object.defineProperty(exports, "workflowYaml", { enumerable: true, get: function () { return workflowTemplate_1.workflowYaml; } });

package/dist/report.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from './types';
+export declare function scanToMarkdown(result: ScanResult): string;

package/dist/report.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanToMarkdown = scanToMarkdown;
+function line(entry) {
+    const cmd = entry.command.length > 100 ? entry.command.slice(0, 97) + '...' : entry.command;
+    return `- **${entry.name}@${entry.version}** \`${entry.hook}\`: \`${cmd}\``;
+}
+function scanToMarkdown(result) {
+    const lines = [
+        '# postinstall-guardian scan report',
+        '',
+        `Generated: ${new Date().toISOString()}`,
+        '',
+        `Total install-type scripts found: ${result.entries.length}`,
+        `Unapproved: ${result.unapproved.length}`,
+        '',
+    ];
+    if (result.unapproved.length === 0) {
+        lines.push('All install-type scripts are approved in the baseline.');
+        return lines.join('\n');
+    }
+    lines.push('## Unapproved scripts', '', 'These packages run a script during `npm install` and are not yet in your baseline.', 'Review each command below. If it is expected (native module builds, binary', 'downloads, etc.), run `postinstall-guardian approve` to add it to the baseline.', '', ...result.unapproved.map(line));
+    return lines.join('\n');
+}

package/dist/scan.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from './types';
+export declare function scan(root: string, baselineFile?: string): Promise<ScanResult>;

package/dist/scan.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scan = scan;
+const baseline_1 = require("./baseline");
+const scanner_1 = require("./scanner");
+async function scan(root, baselineFile = baseline_1.DEFAULT_BASELINE_FILE) {
+    const [entries, baseline] = await Promise.all([(0, scanner_1.scanNodeModules)(root), (0, baseline_1.readBaseline)(root, baselineFile)]);
+    return { entries, unapproved: (0, baseline_1.diffAgainstBaseline)(entries, baseline) };
+}

package/dist/scanner.d.ts

@@ -0,0 +1,9 @@
+import type { ScriptEntry } from './types';
+/**
+ * Walks every node_modules directory under `root` (including nested ones from
+ * hoisting/version conflicts) and collects packages that declare a
+ * preinstall/install/postinstall script. Dedupes on realpath to avoid
+ * re-scanning symlinked packages (pnpm) or looping on symlink cycles.
+ */
+export declare function scanNodeModules(root: string): Promise<ScriptEntry[]>;
+export declare function toRelative(root: string, entry: ScriptEntry): string;

package/dist/scanner.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanNodeModules = scanNodeModules;
+exports.toRelative = toRelative;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const HOOKS = ['preinstall', 'install', 'postinstall'];
+/**
+ * Walks every node_modules directory under `root` (including nested ones from
+ * hoisting/version conflicts) and collects packages that declare a
+ * preinstall/install/postinstall script. Dedupes on realpath to avoid
+ * re-scanning symlinked packages (pnpm) or looping on symlink cycles.
+ */
+async function scanNodeModules(root) {
+    const entries = [];
+    const visited = new Set();
+    await walk((0, node_path_1.join)(root, 'node_modules'), entries, visited);
+    return entries;
+}
+async function walk(dir, entries, visited) {
+    let real;
+    try {
+        real = await node_fs_1.promises.realpath(dir);
+    }
+    catch {
+        return;
+    }
+    if (visited.has(real))
+        return;
+    visited.add(real);
+    let children;
+    try {
+        children = await node_fs_1.promises.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const child of children) {
+        if (child === '.bin')
+            continue;
+        const childPath = (0, node_path_1.join)(dir, child);
+        if (child.startsWith('@')) {
+            // Scoped packages are a directory of packages, not a package itself.
+            let scopedChildren;
+            try {
+                scopedChildren = await node_fs_1.promises.readdir(childPath);
+            }
+            catch {
+                continue;
+            }
+            for (const scopedChild of scopedChildren) {
+                await readPackage((0, node_path_1.join)(childPath, scopedChild), entries);
+                await descendNested((0, node_path_1.join)(childPath, scopedChild), entries, visited);
+            }
+            continue;
+        }
+        await readPackage(childPath, entries);
+        await descendNested(childPath, entries, visited);
+    }
+}
+async function descendNested(packageDir, entries, visited) {
+    const nested = (0, node_path_1.join)(packageDir, 'node_modules');
+    const stat = await safeStat(nested);
+    if (stat?.isDirectory()) {
+        await walk(nested, entries, visited);
+    }
+}
+async function readPackage(packageDir, entries) {
+    const pkgJsonPath = (0, node_path_1.join)(packageDir, 'package.json');
+    const stat = await safeStat(pkgJsonPath);
+    if (!stat?.isFile())
+        return;
+    let pkg;
+    try {
+        pkg = JSON.parse(await node_fs_1.promises.readFile(pkgJsonPath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    if (!pkg.name || !pkg.version || !pkg.scripts)
+        return;
+    for (const hook of HOOKS) {
+        const command = pkg.scripts[hook];
+        if (command) {
+            entries.push({ name: pkg.name, version: pkg.version, hook, command, path: packageDir });
+        }
+    }
+}
+async function safeStat(path) {
+    try {
+        return await node_fs_1.promises.stat(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+function toRelative(root, entry) {
+    return (0, node_path_1.relative)(root, entry.path) || '.';
+}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type InstallHook = 'preinstall' | 'install' | 'postinstall';
+export interface ScriptEntry {
+    name: string;
+    version: string;
+    hook: InstallHook;
+    command: string;
+    /** Path to the package directory, relative to the scan root. */
+    path: string;
+}
+export interface ScanResult {
+    /** Every install-type script found in node_modules. */
+    entries: ScriptEntry[];
+    /** Entries not present in the baseline (i.e. never approved). */
+    unapproved: ScriptEntry[];
+}
+/** Baseline key uniquely identifying an approved package version's script set. */
+export declare function baselineKey(entry: Pick<ScriptEntry, 'name' | 'version'>): string;
+export interface Baseline {
+    /** Set of "name@version" strings whose install scripts have been reviewed and approved. */
+    approved: string[];
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baselineKey = baselineKey;
+/** Baseline key uniquely identifying an approved package version's script set. */
+function baselineKey(entry) {
+    return `${entry.name}@${entry.version}`;
+}

package/dist/workflowTemplate.d.ts

@@ -0,0 +1,12 @@
+export interface WorkflowOptions {
+    /** Daily cron in UTC, as a backstop for drift outside of PRs (e.g. floating ranges resolving differently). */
+    cron?: string;
+    nodeVersion?: string;
+}
+/**
+ * Unlike vuln-guardian's daily-only schedule, new install scripts arrive
+ * whenever dependencies change — so this runs on every push/PR (the moment
+ * that matters) plus a daily cron as a backstop for drift from unpinned
+ * version ranges resolving to a new version between deploys.
+ */
+export declare function workflowYaml(options?: WorkflowOptions): string;

package/dist/workflowTemplate.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowYaml = workflowYaml;
+/**
+ * Unlike vuln-guardian's daily-only schedule, new install scripts arrive
+ * whenever dependencies change — so this runs on every push/PR (the moment
+ * that matters) plus a daily cron as a backstop for drift from unpinned
+ * version ranges resolving to a new version between deploys.
+ */
+function workflowYaml(options = {}) {
+    const cron = options.cron ?? '0 6 * * *';
+    const nodeVersion = options.nodeVersion ?? '20';
+    return `name: postinstall-guardian
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '${cron}'
+  workflow_dispatch: {}
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '${nodeVersion}'
+
+      # --ignore-scripts: don't execute the very scripts we're about to audit.
+      - run: npm ci --ignore-scripts
+
+      - name: Scan for unapproved install scripts
+        run: npx postinstall-guardian ci
+`;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "postinstall-guardian",
+  "version": "0.1.0",
+  "description": "Scan node_modules for preinstall/install/postinstall scripts (the #1 npm supply-chain attack vector) and gate CI on any that aren't explicitly approved.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "postinstall-guardian": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test .test-build/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "npm",
+    "security",
+    "supply-chain",
+    "postinstall",
+    "preinstall",
+    "install-scripts",
+    "cli",
+    "ci"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0"
+  }
+}