npm-sentinel

npm-sentinel is built for the gap after “nothing matched CVE/NVD/OSV today.” Most scanners answer: is this version on a list? This tool asks: did the dependency graph or install behavior change in a way that should make me stop and think?

Think of it a little like macOS asking for consent when something new wants access: you still install packages with npm, but npm-sentinel surfaces differentials—what showed up that was not there before, or what the install tried to talk to—so you can react before “unknown” becomes “incident write-up.”

What you get:

• Baseline drift — for packages you already trust (your direct deps), flag new transitive dependencies, new lifecycle scripts, and version jumps—the same class of signal as when a widely used client suddenly pulls in an unrelated helper package you did not expect.
• Optional Docker sandbox — run npm ci with scripts inside a container and watch DNS against an allowlist, so you can see unexpected outbound hosts during install without running that install on your host.
• Lockfile intelligence — optional OSV and offline IOC-style checks for known bad versions (useful, but explicitly not the whole story).

Why this is different from “CVE-only” tooling

OSV and similar feeds are one layer here. The baseline and sandbox layers are for when the threat is not yet in any database—or never will be, because the issue is “wrong package, wrong script, wrong phone home,” not a scored CVE.

Example outcomes (the mental model)

• Static / baseline: “axios’s resolved tree now includes plain-crypto-js (or another dependency you do not recognize). Nothing is ‘CVE-critical’ yet—but **why is it there suddenly?**”
• Sandbox: “During npm ci, something resolved from your lockfile tried to reach example-malicious-host[.]com (or any host not on your allowlist).” You configure what “normal” looks like; anything else is surfaced for review.

Those are differential signals: compare to what you accepted before and what the install actually did in isolation.

Simple guide: two jobs, five commands

Think of it as two layers:

Cheat sheet (what to run)

Most teams: use check (and check --baseline once baselines exist) on every PR; add sandbox where you need install-time behavior proof (DNS, scripts) without trusting the host.

Commands in plain English

• check — “Does this lockfile match known bad versions (OSV/IOCs)?” 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

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:

{
  "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

npx npm-sentinel baseline save
git add .npm-sentinel-baseline.json
git commit -m "chore: npm-sentinel baseline"

Later:

npx npm-sentinel check --baseline

4. Optional: Docker sandbox (git+ssh private deps)

npx npm-sentinel sandbox --mount-ssh

Or a folder with only deploy keys:

npx npm-sentinel sandbox --ssh-dir /path/to/keys

See Docker & SSH below for macOS vs Linux caveats.

Install

npm install -D npm-sentinel

npm install -g npm-sentinel

From a local clone of this repo:

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)

Flags

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.

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:

{
  "watchPackagesExtra": ["some-transitive-parent"],
  "watchPackagesOverride": null,
  "dnsAllowlist": {
    "mode": "merge",
    "suffixes": ["my-registry.example.com"],
    "exactHosts": []
  },
  "sandbox": {
    "mountSsh": true
  }
}

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)

Real-world context: the Axios supply-chain write-up is exactly the kind of change a baseline diff is meant to make obvious early.

Development (this repo)

Command details and testing: docs/ (per-command guides under docs/commands/). Security reports: SECURITY.md.

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 to match.

Related reading

• pakrat — behavioral npm monitoring (inspiration)
• Elastic — Axios supply chain
• Microsoft — Axios mitigation

License

MIT