@kushankurdas/npm-sentinel 0.1.0

package/lib/sandbox/docker-runner.js

@@ -0,0 +1,211 @@
+import {
+  readFileSync,
+  mkdtempSync,
+  rmSync,
+  existsSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import {
+  extractHostsFromTcpdump,
+  filterDisallowedHosts,
+} from "./dns-parse.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..", "..");
+const DOCKER_DIR = join(PACKAGE_ROOT, "docker");
+const IMAGE_TAG = "npm-sentinel-sandbox:local";
+
+/**
+ * Skip mounted ~/.ssh/config: macOS often sets UseKeychain, which Linux OpenSSH rejects.
+ * With -F /dev/null, ssh still tries default identity files under /root/.ssh (id_ed25519, id_rsa, …).
+ */
+const GIT_SSH_COMMAND =
+  "ssh -F /dev/null -o BatchMode=yes -o IdentityAgent=none -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/tmp/npm-sentinel-known_hosts";
+
+function loadDefaultAllowlist() {
+  const p = join(PACKAGE_ROOT, "lib", "dns-allowlist-default.json");
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+/**
+ * DNS allowlist for sandbox: built-in defaults plus optional project config.
+ *
+ * - **merge** (default): `lib/dns-allowlist-default.json` + `dnsAllowlist.suffixes` / `exactHosts`.
+ * - **replace**: only `suffixes` / `exactHosts` from config (full list is your responsibility).
+ *
+ * @param {object | null | undefined} userAllow - from `dnsAllowlist` in npm-sentinel.config.json
+ * @returns {{ suffixes: string[], exactHosts: string[] }}
+ */
+export function resolveDnsAllowlist(userAllow) {
+  const modeRaw =
+    userAllow && typeof userAllow.mode === "string"
+      ? String(userAllow.mode).toLowerCase()
+      : "merge";
+  const mode = modeRaw === "replace" ? "replace" : "merge";
+
+  const userSuffixes = (userAllow && userAllow.suffixes) || [];
+  const userExact = (userAllow && userAllow.exactHosts) || [];
+
+  if (mode === "replace") {
+    return {
+      suffixes: [...userSuffixes],
+      exactHosts: [...userExact],
+    };
+  }
+
+  const base = loadDefaultAllowlist();
+  return {
+    suffixes: [...(base.suffixes || []), ...userSuffixes],
+    exactHosts: [...(base.exactHosts || []), ...userExact],
+  };
+}
+
+/**
+ * Resolve directory to mount at /root/.ssh in the container.
+ * @param {{ sshMountPath?: string | null, mountSsh?: boolean }} opts
+ * @returns {{ path: string } | { error: string }}
+ */
+export function resolveSshMountPath(opts) {
+  let dir = opts.sshMountPath;
+  if (!dir && opts.mountSsh) {
+    dir = join(homedir(), ".ssh");
+  }
+  if (!dir) return { path: "" };
+  if (!existsSync(dir)) {
+    return {
+      error: `SSH mount path does not exist: ${dir}`,
+    };
+  }
+  try {
+    return { path: realpathSync(dir) };
+  } catch {
+    return { error: `Could not resolve SSH mount path: ${dir}` };
+  }
+}
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   skipBuild?: boolean,
+ *   userAllowlist?: object,
+ *   dockerPath?: string,
+ *   mountSsh?: boolean,
+ *   sshMountPath?: string | null,
+ * }} opts
+ */
+export function runSandbox(opts) {
+  const cwd = opts.cwd || process.cwd();
+  if (!existsSync(join(cwd, "package-lock.json"))) {
+    return {
+      ok: false,
+      error: "package-lock.json required for sandbox (npm ci)",
+    };
+  }
+
+  const sshResolved = resolveSshMountPath({
+    sshMountPath: opts.sshMountPath || null,
+    mountSsh: !!opts.mountSsh,
+  });
+  if (sshResolved.error) {
+    return { ok: false, error: sshResolved.error };
+  }
+  const sshHostPath = sshResolved.path || null;
+
+  const dockerBin = opts.dockerPath || "docker";
+  const checkDocker = spawnSync(dockerBin, ["info"], { encoding: "utf8" });
+  if (checkDocker.status !== 0) {
+    return {
+      ok: false,
+      error: `Docker not available: ${checkDocker.stderr || checkDocker.stdout || "docker info failed"}`,
+    };
+  }
+
+  if (!opts.skipBuild) {
+    const build = spawnSync(
+      dockerBin,
+      [
+        "build",
+        "-t",
+        IMAGE_TAG,
+        "-f",
+        join(DOCKER_DIR, "Dockerfile.sandbox"),
+        DOCKER_DIR,
+      ],
+      { encoding: "utf8" }
+    );
+    if (build.status !== 0) {
+      return {
+        ok: false,
+        error: `docker build failed:\n${build.stderr || build.stdout}`,
+      };
+    }
+  }
+
+  const outDir = mkdtempSync(join(tmpdir(), "npm-sentinel-"));
+  try {
+    const dockerArgs = [
+      "run",
+      "--rm",
+      "--cap-add=NET_RAW",
+      "--cap-add=NET_ADMIN",
+    ];
+
+    if (sshHostPath) {
+      dockerArgs.push("-e", `GIT_SSH_COMMAND=${GIT_SSH_COMMAND}`);
+      dockerArgs.push("-v", `${sshHostPath}:/root/.ssh:ro`);
+    }
+
+    dockerArgs.push("-v", `${cwd}:/src:ro`, "-v", `${outDir}:/out`, IMAGE_TAG);
+
+    const run = spawnSync(dockerBin, dockerArgs, {
+      encoding: "utf8",
+      maxBuffer: 50 * 1024 * 1024,
+    });
+
+    const dnsLogPath = join(outDir, "dns.log");
+    const npmLogPath = join(outDir, "npm.log");
+    const exitPath = join(outDir, "npm-exit.code");
+
+    let dnsText = "";
+    if (existsSync(dnsLogPath)) {
+      dnsText = readFileSync(dnsLogPath, "utf8");
+    }
+    let npmLog = "";
+    if (existsSync(npmLogPath)) {
+      npmLog = readFileSync(npmLogPath, "utf8");
+    }
+    let npmExit = 1;
+    if (existsSync(exitPath)) {
+      npmExit = parseInt(readFileSync(exitPath, "utf8").trim(), 10);
+      if (Number.isNaN(npmExit)) npmExit = 1;
+    }
+
+    const hosts = extractHostsFromTcpdump(dnsText);
+    const allow = resolveDnsAllowlist(opts.userAllowlist);
+    const disallowed = filterDisallowedHosts(hosts, allow);
+
+    const dnsViolation = disallowed.length > 0;
+    const npmFailed = npmExit !== 0;
+
+    return {
+      ok: !dnsViolation && !npmFailed,
+      npmExit,
+      npmLogTail: npmLog.slice(-8000),
+      dnsHostsSample: [...hosts].slice(0, 50),
+      disallowedDns: disallowed,
+      dockerStderr: run.stderr,
+      dockerStdout: run.stdout,
+      sshMounted: !!sshHostPath,
+    };
+  } finally {
+    try {
+      rmSync(outDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/lib/scan.js

@@ -0,0 +1,156 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import {
+  parseNpmLockfile,
+  getAllNameVersionPairs,
+} from "./parse-npm-lockfile.js";
+import { queryOsvBatch } from "./osv-client.js";
+import {
+  flattenOsvFindings,
+  matchOfflineIocs,
+  filterByMinSeverity,
+} from "./merge-findings.js";
+import { loadBaseline, buildBaselineSnapshot } from "./baseline.js";
+import { diffAgainstBaseline } from "./diff-signals.js";
+import { loadConfig, getWatchPackageNames } from "./config.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @param {string} cwd
+ */
+function readPackageJson(cwd) {
+  const p = join(cwd, "package.json");
+  if (!existsSync(p)) throw new Error(`Missing package.json in ${cwd}`);
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+/**
+ * @param {string} cwd
+ */
+function readLockfile(cwd) {
+  const p = join(cwd, "package-lock.json");
+  if (!existsSync(p)) throw new Error(`Missing package-lock.json in ${cwd}`);
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} [opts.minSeverity]
+ * @param {boolean} [opts.noOsv]
+ * @param {boolean} [opts.offline] - skip OSV, IOCs only
+ * @param {boolean} [opts.withBaselineDiff]
+ * @param {boolean} [opts.npmAudit]
+ * @param {typeof fetch} [opts.fetchImpl]
+ */
+export async function runCheck(opts) {
+  const cwd = opts.cwd || process.cwd();
+  const minSeverity = opts.minSeverity || "low";
+  const pkg = readPackageJson(cwd);
+  const lockRaw = readLockfile(cwd);
+  const parsed = parseNpmLockfile(lockRaw);
+  const pairs = getAllNameVersionPairs(parsed);
+  const config = loadConfig(cwd);
+  const watchNames = getWatchPackageNames(pkg, config);
+
+  /** @type {Array<{name: string, version: string, source: string, severity: string, ids: string[], summary?: string}>} */
+  let findings = [];
+
+  if (!opts.offline) {
+    if (!opts.noOsv) {
+      const osv = await queryOsvBatch(pairs, opts.fetchImpl || fetch);
+      findings = findings.concat(flattenOsvFindings(osv));
+    }
+  }
+
+  findings = findings.concat(matchOfflineIocs(pairs));
+  findings = filterByMinSeverity(minSeverity, findings);
+
+  /** @type {import('./diff-signals.js').Signal[]} */
+  let signals = [];
+  if (opts.withBaselineDiff) {
+    const baseline = loadBaseline(cwd);
+    if (baseline) {
+      signals = await diffAgainstBaseline(
+        baseline,
+        parsed,
+        watchNames,
+        opts.fetchImpl || fetch
+      );
+    }
+  }
+
+  let npmAuditFindings = [];
+  if (opts.npmAudit) {
+    npmAuditFindings = await runNpmAuditJson(cwd);
+  }
+
+  return {
+    cwd,
+    packagesScanned: pairs.length,
+    findings,
+    signals,
+    npmAuditFindings,
+    watchNames,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<object[]>}
+ */
+async function runNpmAuditJson(cwd) {
+  try {
+    const { stdout } = await execFileAsync(
+      "npm",
+      ["audit", "--json"],
+      { cwd, maxBuffer: 20 * 1024 * 1024 }
+    );
+    const j = JSON.parse(stdout);
+    const vulns = j.vulnerabilities || {};
+    const out = [];
+    for (const [name, v] of Object.entries(vulns)) {
+      if (!v.via || !v.effects) continue;
+      const sev = String(v.severity || "moderate").toLowerCase();
+      out.push({
+        name,
+        severity: sev,
+        source: "npm-audit",
+        via: v.via,
+        range: v.range,
+      });
+    }
+    return out;
+  } catch (e) {
+    const out = e.stdout?.toString?.() || e.stdout;
+    if (out) {
+      try {
+        const j = JSON.parse(out);
+        if (j.error?.code === "ENOLOCK") return [];
+        const vulns = j.vulnerabilities || {};
+        const arr = [];
+        for (const [name, v] of Object.entries(vulns)) {
+          if (!v.via) continue;
+          arr.push({
+            name,
+            severity: String(v.severity || "moderate").toLowerCase(),
+            source: "npm-audit",
+            via: v.via,
+            range: v.range,
+          });
+        }
+        return arr;
+      } catch {
+        /* fallthrough */
+      }
+    }
+    return [
+      { name: "(npm-audit)", source: "npm-audit", error: String(e.message) },
+    ];
+  }
+}
+
+export { readPackageJson, readLockfile, parseNpmLockfile };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kushankurdas/npm-sentinel",
+  "version": "0.1.0",
+  "description": "Static gate (lockfile + OSV) and isolated Docker npm install with DNS allowlisting",
+  "license": "MIT",
+  "author": {
+    "name": "kushankurdas",
+    "url": "https://github.com/kushankurdas"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kushankurdas/npm-sentinel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kushankurdas/npm-sentinel/issues"
+  },
+  "homepage": "https://github.com/kushankurdas/npm-sentinel#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "npm-sentinel": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "docker",
+    "docs",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "npm",
+    "security",
+    "supply-chain",
+    "docker",
+    "osv"
+  ]
+}