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 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:

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.

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

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)

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