@kushankurdas/npm-sentinel 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for helping improve npm-sentinel.
+
+## Development
+
+1. Clone the repo and install dependencies (this package has no runtime deps; tests use Node built-ins).
+2. Run tests: `npm test`
+3. Follow existing style: ES modules, no unnecessary dependencies.
+
+## Pull requests
+
+- Keep changes focused on one concern.
+- Add or update tests when behavior changes.
+- Update `README.md` if user-facing commands or flags change.
+
+## Security
+
+See **[SECURITY.md](SECURITY.md)** for how to report vulnerabilities in this project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 npm-sentinel contributors
+
+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,243 @@
+# npm-sentinel
+
+**npm-sentinel** helps you catch risky dependency changes before or during install:
+
+- **Fast checks** — scan your `package-lock.json` against vulnerability databases and known-bad versions.
+- **Baseline drift** — detect new dependencies or install scripts on packages you trust (similar to how the [Axios supply-chain incident](https://www.elastic.co/security-labs/axios-one-rat-to-rule-them-all) introduced a hidden dependency).
+- **Optional Docker sandbox** — run `npm ci` **inside a container** with DNS monitoring, so malicious `postinstall` scripts do not run on your host during that check.
+
+---
+
+## Simple guide: two jobs, five commands
+
+Think of it as **two layers**:
+
+| Layer | What it does | Needs Docker? |
+|--------|----------------|---------------|
+| **A — Static** | Reads the lockfile, calls [OSV](https://osv.dev/), optional baseline compare | **No** |
+| **B — Sandbox** | Runs a real `npm ci` in Linux + watches DNS | **Yes** |
+
+### Cheat sheet (what to run)
+
+| I want… | Command |
+|--------|---------|
+| **Quick “is my lockfile bad?”** (daily / CI) | `npx npm-sentinel check` |
+| **Same + compare to a saved “good” snapshot** | `npx npm-sentinel check --baseline` |
+| **Save a “good” snapshot** (commit the file afterward) | `npx npm-sentinel baseline save` |
+| **See what changed vs that snapshot** | `npx npm-sentinel baseline diff` |
+| **Heavy: install in Docker + DNS allowlist** | `npx npm-sentinel sandbox` |
+| **CI: static check, then optionally sandbox** | `npx npm-sentinel gate` or `npx npm-sentinel gate --require-sandbox` |
+
+**Most teams:** use **`check`** (and **`check --baseline`** once baselines exist) on every PR; add **`sandbox`** where you need install-time behavior proof.
+
+### Commands in plain English
+
+- **`check`** — “Does this lockfile list any known vulnerable or known-malicious versions?” Optionally: “Did my trusted direct deps drift vs my baseline?”
+- **`baseline save`** — “Remember today’s dependency + script picture for my root `package.json` deps as **trusted**.” Writes `.npm-sentinel-baseline.json`.
+- **`baseline diff`** — “What changed since `baseline save`?” (new child deps, new install scripts, version bumps, etc.)
+- **`sandbox`** — “Copy the project into a container, run **`npm ci` with scripts on**, record DNS. Fail if DNS hits unknown domains or `npm ci` fails.” Use **`--mount-ssh`** if you have private **`git+ssh`** dependencies (see below).
+- **`gate`** — “Run **`check`** with baseline diff enabled **if** a baseline file exists. With **`--require-sandbox`**, run **`sandbox`** after **`check`** passes.”
+
+---
+
+## Quick start
+
+### 1. In any repo that has `package-lock.json`
+
+```bash
+cd your-project
+npx npm-sentinel check
+```
+
+Exit code **0** = no findings at your severity threshold; **1** = findings or baseline errors.
+
+### 2. Optional: block install on bad lockfile (host only runs static check)
+
+Use **npx** or a **global** install so `preinstall` works on a fresh clone:
+
+```json
+{
+  "scripts": {
+    "preinstall": "npx --yes npm-sentinel@latest check --baseline"
+  }
+}
+```
+
+Static `preinstall` does **not** run dependency `postinstall` on the host if npm aborts first. For **install-time** behavior, use **`sandbox`** separately or in CI.
+
+### 3. Optional: baseline workflow
+
+```bash
+npx npm-sentinel baseline save
+git add .npm-sentinel-baseline.json
+git commit -m "chore: npm-sentinel baseline"
+```
+
+Later:
+
+```bash
+npx npm-sentinel check --baseline
+```
+
+### 4. Optional: Docker sandbox (`git+ssh` private deps)
+
+```bash
+npx npm-sentinel sandbox --mount-ssh
+```
+
+Or a folder with only deploy keys:
+
+```bash
+npx npm-sentinel sandbox --ssh-dir /path/to/keys
+```
+
+See **Docker & SSH** below for macOS vs Linux caveats.
+
+---
+
+## Install
+
+```bash
+npm install -D npm-sentinel
+```
+
+```bash
+npm install -g npm-sentinel
+```
+
+From a **local clone** of this repo:
+
+```bash
+cd npm-sentinel
+npm link
+cd /path/to/your-app
+npm link npm-sentinel
+```
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18**
+- **Docker** — only for `sandbox` and `gate --require-sandbox`
+- **`package-lock.json`** at the project root (required for `check`, `baseline`, `sandbox`)
+
+---
+
+## Command reference (detailed)
+
+| Command | Description |
+|--------|-------------|
+| `npm-sentinel check` | Lockfile → OSV + offline IOCs; add `--baseline` if `.npm-sentinel-baseline.json` exists |
+| `npm-sentinel baseline save` | Write baseline from lockfile + registry metadata for watched packages |
+| `npm-sentinel baseline diff` | Print drift vs baseline |
+| `npm-sentinel sandbox` | Docker: copy project, `npm ci`, tcpdump DNS vs allowlist |
+| `npm-sentinel gate` | `check` with baseline diff; `--require-sandbox` runs `sandbox` after |
+| `npm-sentinel help` | Print help |
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--cwd <dir>` | Project root (default: current directory) |
+| `--json` | JSON output |
+| `--min-severity` | `low` \| `moderate` \| `high` \| `critical` (default: `low`) |
+| `--no-osv` | Skip OSV API |
+| `--offline` | Skip OSV (offline IOCs still apply) |
+| `--baseline` | With `check`, run baseline diff when baseline file exists |
+| `--npm-audit` | Also run `npm audit --json` |
+| `--require-sandbox` | With `gate`, run `sandbox` after check |
+| `--no-build` | `sandbox`: reuse existing Docker image |
+| `--mount-ssh` | `sandbox`: mount host `~/.ssh` read-only at `/root/.ssh` |
+| `--ssh-dir <path>` | `sandbox`: mount this directory instead of `~/.ssh` |
+| `--baseline-file <path>` | Alternate baseline file path |
+
+---
+
+## Docker sandbox and your machine
+
+- The sandbox runs **Linux** in Docker. It does **not** always give you a **macOS/Windows–usable** `node_modules` when packages ship **native** binaries built for your host OS.
+- **Recommendation:** run **`sandbox` in CI (Linux)**; locally use **`check`**, or develop inside a **Dev Container** if you want Linux `node_modules` daily.
+
+### Private `git+ssh` dependencies
+
+The image includes **`git`** and **`openssh-client`**.
+
+| Approach | Command / config |
+|----------|-------------------|
+| Mount host keys | `npm-sentinel sandbox --mount-ssh` |
+| Mount a key folder only | `npm-sentinel sandbox --ssh-dir /path/to/keys` |
+| Config file | `npm-sentinel.config.json`: `"sandbox": { "mountSsh": true }` or `"sshDir": "/path"` |
+
+**macOS:** Your `~/.ssh/config` may use **`UseKeychain`**, which **Linux OpenSSH does not support**. The tool sets **`GIT_SSH_COMMAND`** with **`-F /dev/null`** so the **mounted config is ignored**; default key files in the mount still apply (`id_ed25519`, `id_rsa`, …). Keys that exist **only** in the Keychain and not on disk may still fail — use a **deploy key file** or **`git+https`** with a token in CI.
+
+**Security:** Mounting `~/.ssh` gives the container read access to whatever keys are in that directory. Prefer **deploy keys** or **HTTPS + token** for automation.
+
+---
+
+## Configuration
+
+Create **`npm-sentinel.config.json`** or **`.npm-sentinelsrc.json`** in the project root:
+
+```json
+{
+  "watchPackagesExtra": ["some-transitive-parent"],
+  "watchPackagesOverride": null,
+  "dnsAllowlist": {
+    "mode": "merge",
+    "suffixes": ["my-registry.example.com"],
+    "exactHosts": []
+  },
+  "sandbox": {
+    "mountSsh": true
+  }
+}
+```
+
+| Key | Meaning |
+|-----|---------|
+| **Watched packages** | Defaults to root `dependencies` + `devDependencies` (+ optional peers / optionals). `watchPackagesExtra` adds more parent names. |
+| **`watchPackagesOverride`** | If set (array), **only** these names are watched (replaces default list + extras). |
+| **`dnsAllowlist`** | DNS allowlist for `sandbox`: **`mode`** `merge` (default) adds `suffixes` / `exactHosts` to the [built-in list](lib/dns-allowlist-default.json); **`replace`** uses **only** your lists (strict; you must include every host your install needs). |
+| **`sandbox.mountSsh`** | Same as `--mount-ssh`. |
+| **`sandbox.sshDir`** | Same as `--ssh-dir` (wins over `mountSsh` when set). |
+
+---
+
+## Baseline signals
+
+When you compare to a saved baseline, npm-sentinel can report:
+
+- **New direct dependencies** on a watched package (dependency injection)
+- **New lifecycle scripts** on a resolved version (`preinstall` / `install` / `postinstall`)
+- **Version changes** on watched packages
+- **Removed dependencies** (warning; can be noisy; possible account-takeover signal)
+
+---
+
+## Development (this repo)
+
+Command details and testing: **[`docs/`](docs/README.md)** (per-command guides under **`docs/commands/`**). Security reports: **[`SECURITY.md`](SECURITY.md)**.
+
+```bash
+git clone https://github.com/kushankurdas/npm-sentinel.git
+cd npm-sentinel
+npm ci
+npm test
+```
+
+If your GitHub username or repo name differs, update the **`repository`**, **`bugs`**, and **`homepage`** fields in [`package.json`](package.json) to match.
+
+---
+
+## Related reading
+
+- [pakrat](https://github.com/HorseyofCoursey/pakrat) — behavioral npm monitoring (inspiration)
+- [Elastic — Axios supply chain](https://www.elastic.co/security-labs/axios-one-rat-to-rule-them-all)
+- [Microsoft — Axios mitigation](https://www.microsoft.com/en-us/security/blog/2026/04/01/mitigating-the-axios-npm-supply-chain-compromise/)
+
+---
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the **latest** `0.x` release line on the default branch. Use the newest published version when possible.
+
+## Reporting a vulnerability
+
+Report security issues in **this repository or the npm-sentinel CLI** through **[GitHub Security Advisories](https://github.com/kushankurdas/npm-sentinel/security/advisories/new)** (private report, preferred) instead of a public issue.
+
+**Out of scope** for this channel: general discussion of npm ecosystem incidents, vulnerabilities in third-party packages you depend on, or abuse of registries unless they directly involve a flaw in npm-sentinel’s own code.
+
+We will acknowledge receipt as we can and coordinate on fixes and disclosure.
+
+## npm package
+
+After you publish, confirm the **`npm-sentinel`** package on the npm registry lists **`repository`** in `package.json` as this GitHub repo before trusting forks or typosquats.

package/bin/cli.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { runCheck, readPackageJson } from "../lib/scan.js";
+import {
+  buildBaselineSnapshot,
+  saveBaseline,
+  loadBaseline,
+  DEFAULT_BASELINE_PATH,
+} from "../lib/baseline.js";
+import {
+  parseNpmLockfile,
+} from "../lib/parse-npm-lockfile.js";
+import { loadConfig, getWatchPackageNames } from "../lib/config.js";
+import { runSandbox } from "../lib/sandbox/docker-runner.js";
+import { diffAgainstBaseline } from "../lib/diff-signals.js";
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, v] = a.includes("=") ? a.split("=", 2) : [a, null];
+      const key = k.slice(2);
+      if (v !== null) args.flags[key] = v;
+      else if (argv[i + 1] && !argv[i + 1].startsWith("-")) {
+        args.flags[key] = argv[++i];
+      } else {
+        args.flags[key] = true;
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function printFindingsJson(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+function printFindingsHuman(result) {
+  console.log(`Scanned ${result.packagesScanned} unique package versions (lockfile).`);
+  if (result.findings.length === 0) {
+    console.log("No OSV/offline-IOC findings at or above min severity.");
+  } else {
+    console.log("\nFindings:");
+    for (const f of result.findings) {
+      console.log(
+        `  - ${f.name}@${f.version} [${f.source}] severity=${f.severity} ids=${(f.ids || []).join(",")}`
+      );
+      if (f.summary) console.log(`    ${f.summary}`);
+    }
+  }
+  if (result.signals?.length) {
+    console.log("\nBaseline signals:");
+    for (const s of result.signals) {
+      console.log(`  [${s.severity}] ${s.type}: ${s.message}`);
+    }
+  }
+  if (result.npmAuditFindings?.length) {
+    console.log("\nnpm audit (summary):");
+    for (const a of result.npmAuditFindings.slice(0, 20)) {
+      if (a.error) console.log(`  - ${a.error}`);
+      else console.log(`  - ${a.name} [${a.severity}]`);
+    }
+  }
+}
+
+async function cmdCheck(flags) {
+  const cwd = flags.cwd || process.cwd();
+  const json = !!flags.json;
+  const minSeverity = flags["min-severity"] || "low";
+  const result = await runCheck({
+    cwd,
+    minSeverity,
+    noOsv: !!flags["no-osv"],
+    offline: !!flags.offline,
+    withBaselineDiff: !!flags.baseline,
+    npmAudit: !!flags["npm-audit"],
+  });
+
+  const signalErrors = (result.signals || []).filter((s) => s.severity === "error");
+  const failSignals = signalErrors.length > 0;
+
+  if (json) {
+    printFindingsJson({
+      ok: result.findings.length === 0 && !failSignals,
+      ...result,
+    });
+  } else {
+    printFindingsHuman(result);
+  }
+
+  const failFindings = result.findings.length > 0;
+  process.exitCode = failFindings || failSignals ? 1 : 0;
+}
+
+async function cmdBaseline(flags, sub) {
+  const cwd = flags.cwd || process.cwd();
+  const json = !!flags.json;
+  if (sub === "save") {
+    const lockPath = join(cwd, "package-lock.json");
+    if (!existsSync(lockPath)) {
+      console.error("package-lock.json required for baseline save.");
+      process.exitCode = 2;
+      return;
+    }
+    const pkg = readPackageJson(cwd);
+    const config = loadConfig(cwd);
+    const watchNames = getWatchPackageNames(pkg, config);
+    const lockRaw = JSON.parse(readFileSync(lockPath, "utf8"));
+    const parsed = parseNpmLockfile(lockRaw);
+    const snapshot = await buildBaselineSnapshot(pkg, parsed, watchNames);
+    const p = saveBaseline(snapshot, cwd, flags["baseline-file"] || DEFAULT_BASELINE_PATH);
+    if (json) {
+      printFindingsJson({ ok: true, path: p, snapshot });
+    } else {
+      console.log(`Baseline written to ${p} (${watchNames.length} watched packages).`);
+    }
+    process.exitCode = 0;
+    return;
+  }
+  if (sub === "diff") {
+    const baseline = loadBaseline(cwd, flags["baseline-file"] || DEFAULT_BASELINE_PATH);
+    if (!baseline) {
+      console.error("No baseline file. Run: npm-sentinel baseline save");
+      process.exitCode = 2;
+      return;
+    }
+    const lockPath = join(cwd, "package-lock.json");
+    if (!existsSync(lockPath)) {
+      console.error("package-lock.json required.");
+      process.exitCode = 2;
+      return;
+    }
+    const pkg = readPackageJson(cwd);
+    const config = loadConfig(cwd);
+    const watchNames = getWatchPackageNames(pkg, config);
+    const parsed = parseNpmLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
+    const signals = await diffAgainstBaseline(baseline, parsed, watchNames);
+    const errors = signals.filter((s) => s.severity === "error");
+    if (json) {
+      printFindingsJson({ ok: errors.length === 0, signals });
+    } else {
+      if (signals.length === 0) console.log("No baseline drift detected.");
+      else {
+        for (const s of signals) {
+          console.log(`[${s.severity}] ${s.type}: ${s.message}`);
+        }
+      }
+    }
+    process.exitCode = errors.length ? 1 : 0;
+    return;
+  }
+  console.error("Usage: npm-sentinel baseline save|diff");
+  process.exitCode = 2;
+}
+
+function sandboxSshOpts(flags, config) {
+  const explicitDir = flags["ssh-dir"] || config.sandbox?.sshDir;
+  if (explicitDir) {
+    return { mountSsh: false, sshMountPath: explicitDir };
+  }
+  const useDefaultDotSsh =
+    !!flags["mount-ssh"] || !!config.sandbox?.mountSsh;
+  if (useDefaultDotSsh) {
+    return { mountSsh: true, sshMountPath: null };
+  }
+  return { mountSsh: false, sshMountPath: null };
+}
+
+function cmdSandbox(flags) {
+  const cwd = flags.cwd || process.cwd();
+  const json = !!flags.json;
+  let userAllowlist;
+  const config = loadConfig(cwd);
+  if (config.dnsAllowlist) userAllowlist = config.dnsAllowlist;
+
+  const ssh = sandboxSshOpts(flags, config);
+  const res = runSandbox({
+    cwd,
+    skipBuild: !!flags["no-build"],
+    userAllowlist,
+    mountSsh: ssh.mountSsh,
+    sshMountPath: ssh.sshMountPath,
+  });
+
+  if (json) {
+    printFindingsJson({ ok: res.ok, ...res });
+  } else {
+    if (!res.ok && res.error) {
+      console.error(res.error);
+    } else {
+      console.log(`npm ci exit: ${res.npmExit}`);
+      if (res.disallowedDns?.length) {
+        console.error("DNS allowlist violations:");
+        for (const h of res.disallowedDns) console.error(`  - ${h}`);
+      }
+      if (res.npmExit !== 0) {
+        console.error("npm ci failed inside sandbox. Last log lines:");
+        console.error(res.npmLogTail || "(no log)");
+      }
+      if (res.ok) {
+        console.log("Sandbox OK: npm ci succeeded and DNS within allowlist.");
+        if (res.sshMounted) console.log("(SSH keys mounted from host for git+ssh dependencies.)");
+      }
+    }
+  }
+  process.exitCode = res.ok ? 0 : 1;
+}
+
+async function cmdGate(flags) {
+  const cwd = flags.cwd || process.cwd();
+  const json = !!flags.json;
+  const minSeverity = flags["min-severity"] || "low";
+
+  let result;
+  try {
+    result = await runCheck({
+      cwd,
+      minSeverity,
+      noOsv: !!flags["no-osv"],
+      offline: !!flags.offline,
+      withBaselineDiff: true,
+      npmAudit: !!flags["npm-audit"],
+    });
+  } catch (e) {
+    console.error(e.message || e);
+    process.exitCode = 2;
+    return;
+  }
+
+  const signalErrors = (result.signals || []).filter((s) => s.severity === "error");
+  const checkFail = result.findings.length > 0 || signalErrors.length > 0;
+
+  if (checkFail) {
+    if (json) printFindingsJson({ gate: "failed", stage: "check", ...result });
+    else printFindingsHuman(result);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags["require-sandbox"]) {
+    cmdSandbox({ ...flags, cwd, json: false });
+    return;
+  }
+
+  if (json) printFindingsJson({ gate: "ok", stage: "check", packagesScanned: result.packagesScanned });
+  else console.log("Gate OK (check + baseline diff if baseline present).");
+  process.exitCode = 0;
+}
+
+async function main() {
+  const { _, flags } = parseArgs(process.argv);
+  const cmd = _[0] || "check";
+
+  try {
+    if (cmd === "check") await cmdCheck(flags);
+    else if (cmd === "baseline") await cmdBaseline(flags, _[1]);
+    else if (cmd === "sandbox") cmdSandbox(flags);
+    else if (cmd === "gate") await cmdGate(flags);
+    else if (cmd === "help" || cmd === "--help" || flags.help) {
+      console.log(`
+npm-sentinel — static gate + Docker sandbox for npm supply-chain risk
+
+Commands:
+  check              Lockfile + OSV + offline IOCs; optional baseline diff (--baseline)
+  baseline save      Write .npm-sentinel-baseline.json from current lockfile + registry metadata
+  baseline diff      Compare current tree vs baseline (signals only)
+  sandbox            Run npm ci inside Docker with DNS capture + allowlist
+  gate               Run check (with baseline diff) and optionally --require-sandbox
+
+Flags:
+  --cwd <dir>        Project root (default: cwd)
+  --json             JSON output
+  --min-severity     low|moderate|high|critical (default: low)
+  --no-osv           Skip OSV API
+  --offline          Skip OSV (offline IOCs still apply)
+  --baseline         With check: run baseline diff if baseline file exists
+  --npm-audit        Also run npm audit --json
+  --require-sandbox  With gate: run Docker sandbox after check
+  --no-build         sandbox: skip docker build (reuse image)
+  --mount-ssh        sandbox: mount host ~/.ssh read-only at /root/.ssh (git+ssh)
+  --ssh-dir <path>   sandbox: mount this directory instead of ~/.ssh (implies SSH mount)
+  --baseline-file    Alternate baseline path
+
+Config (npm-sentinel.config.json): sandbox.mountSsh, sandbox.sshDir, dnsAllowlist.mode (merge|replace)
+
+preinstall (host, static only):
+  "preinstall": "npx --yes npm-sentinel@latest check --baseline"
+`);
+      process.exitCode = 0;
+    } else {
+      console.error(`Unknown command: ${cmd}`);
+      process.exitCode = 2;
+    }
+  } catch (e) {
+    console.error(e.message || e);
+    process.exitCode = 2;
+  }
+}
+
+main();

package/docker/Dockerfile.sandbox

@@ -0,0 +1,15 @@
+FROM node:20-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    tcpdump \
+    ca-certificates \
+    git \
+    openssh-client \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY entrypoint-sandbox.sh /entrypoint-sandbox.sh
+RUN chmod +x /entrypoint-sandbox.sh
+
+WORKDIR /work
+ENTRYPOINT ["/entrypoint-sandbox.sh"]

package/docker/entrypoint-sandbox.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# /src: read-only project mount, /out: writable output (dns log, npm log)
+rm -rf /work/*
+cp -a /src/. /work/
+cd /work
+
+: "${NPM_CI_FLAGS:=}"
+
+DNS_LOG="${DNS_LOG:-/out/dns.log}"
+NPM_LOG="${NPM_LOG:-/out/npm.log}"
+
+touch "$DNS_LOG" "$NPM_LOG" 2>/dev/null || true
+
+tcpdump -i any -n -l -tttt 'udp port 53' >>"$DNS_LOG" 2>/dev/null &
+TPID=$!
+
+cleanup() {
+  kill "$TPID" 2>/dev/null || true
+  wait "$TPID" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+set +e
+npm ci $NPM_CI_FLAGS >"$NPM_LOG" 2>&1
+NPM_EXIT=$?
+set -e
+
+cleanup
+trap - EXIT
+
+echo "$NPM_EXIT" >/out/npm-exit.code
+exit "$NPM_EXIT"

package/docs/README.md

@@ -0,0 +1,27 @@
+# npm-sentinel documentation
+
+Command references below match the CLI in `bin/cli.js`. The **[main README](../README.md)** is the quick-start and cheat sheet.
+
+## Command reference
+
+| Command | Guide |
+|--------|--------|
+| **`check`** | [commands/check.md](commands/check.md) — lockfile scan (OSV, offline IOCs), optional baseline diff and npm audit |
+| **`baseline`** | [commands/baseline.md](commands/baseline.md) — `save` and `diff` for trusted-tree snapshots |
+| **`sandbox`** | [commands/sandbox.md](commands/sandbox.md) — Docker `npm ci` with DNS capture and allowlist |
+| **`gate`** | [commands/gate.md](commands/gate.md) — CI-friendly check + optional sandbox |
+| **`help`** | [commands/help.md](commands/help.md) — built-in help text |
+
+## Shared configuration
+
+- **Project root:** `--cwd <dir>` (default: current directory).
+- **Config files:** `npm-sentinel.config.json` or `.npm-sentinelsrc.json` — see [reference/config.md](reference/config.md).
+- **Global flags:** [reference/flags.md](reference/flags.md) summarizes all CLI flags by command.
+
+## Testing
+
+See **[testing.md](testing.md)** for links to each command’s testing section and how to run **`npm test`** in this repo.
+
+## Related topics
+
+- Supply-chain background (e.g. lifecycle-based attacks): see the main README’s “Related reading” and [SECURITY.md](../SECURITY.md).