Your app runs every line of code in node_modules with full access to your files, env vars, and network. This repo collects practical defenses against malicious or compromised npm packages, as config you can copy and small tools you can run.
npm test # tests for the scanner and the permission model
npm run scan # list packages in ./node_modules that run install scripts
npm run demo:open # app with normal Node permissions
npm run demo:locked # same app under the Node permission modelLive preview: nodejs-supply-chain-security.netlify.app. It replays recorded runs, so nothing executes on that server. Run it locally to try your own payloads.
A local web page that runs each attack for real, against the unsafe setup and the safe one side by side. Everything runs offline in temp folders with fake tokens.
npm run demo # then open http://127.0.0.1:4103The hosted preview is a static build of demo/recordings.json (npm run build). Refresh the recordings with npm run demo:record (needs Google Chrome).
A fake package's postinstall script collects tokens during a real npm install. Plain install hands them over; --ignore-scripts never runs the script.
The real scripts/find-install-scripts.js lists every package that would run code on install, and fails CI until you've reviewed them.
The same script runs with and without node --permission. Tick a grant to see it open exactly one door.
.npmrc safe npm defaults (copy into your project)
.github/workflows/security.yml CI: npm ci, audit, signatures, install-script scan
.github/dependabot.yml weekly updates with a 7-day cooldown
scripts/find-install-scripts.js lists dependencies that run code on install
permission-demo/app.mjs same app with and without --permission
demo/server.js, demo/index.html interactive demo (npm run demo)
docs/ demo screenshots
test/supply-chain.test.js tests for the scanner and the permission model
test/demo.test.js tests for the demo server and its local-only guards
In September 2025, phishing of maintainer accounts led to malicious versions of very popular packages (including chalk and debug) being published, and the self-spreading Shai-Hulud worm stole npm and GitHub tokens through postinstall scripts and used them to publish infected versions of other packages. Both attacks needed nothing more than a normal npm install.
| File | What it does |
|---|---|
| .npmrc | ignore-scripts, save-exact, audit-level, engine-strict |
| scripts/find-install-scripts.js | Lists every dependency with preinstall/install/postinstall or binding.gyp. Exits 1 unless each one is on your --allow list |
| .github/workflows/security.yml | CI: npm ci, npm audit, npm audit signatures, install-script scan, least-privilege token |
| .github/dependabot.yml | Weekly updates with a 7-day cooldown on new releases |
| permission-demo/ | Shows the Node permission model blocking file, process, and write access |
| demo/ | Interactive web demo of all of the above (npm run demo). Only listens on 127.0.0.1 and rejects requests from other sites |
| docs/ | Screenshots of the demo |
- Commit
package-lock.json. Usenpm ci(notnpm install) in CI and Docker builds. It installs exactly the lockfile and fails if it doesn't matchpackage.json. save-exact=trueso upgrades are a deliberate diff you can review.- Review lockfile changes in PRs. A new transitive dependency or a
resolvedURL pointing somewhere other thanregistry.npmjs.orgis a red flag.
ignore-scripts=truein.npmrcblocks lifecycle scripts from dependencies. Your ownnpm test/npm run xstill work.- Some packages genuinely need them (native addons like
sharp,bcrypt, oresbuild's binary). Review them withnpm run scan, then runnpm rebuild <pkg>for just those. - pnpm (v10+) and Bun block dependency install scripts by default and use an explicit allowlist (
onlyBuiltDependencies/trustedDependencies).
npm audit --audit-level=highin CI, plus a weekly scheduled run so new advisories surface even without code changes.npm audit signaturesverifies registry signatures and provenance attestations of what you installed.- Extra scanners worth considering: OSV-Scanner, Socket, Snyk, GitHub Dependency Review.
- Most malicious versions are found within hours or days. A cooldown means you are rarely the first to install one.
- Dependabot
cooldown, RenovateminimumReleaseAge, pnpmminimumReleaseAge. - For a one-off install,
npm install --before=2025-01-01resolves versions as of that date.
- Every package is code you trust plus everyone who can publish it. Before adding one, check whether Node already does it:
fetch,node:test,node:sqlite,util.parseArgs,util.styleText,crypto.randomUUID,--env-file,--watch. - Watch for typosquats (
expresss,cross-env.js) and dependency confusion (a public package with the same name as your private one; scope private packages, e.g.@yourco/, and map the scope to your registry in.npmrc).
- Enable 2FA on npm, and require it for publishing.
- Publish from CI with npm trusted publishing (OIDC) instead of long-lived tokens. This also adds provenance automatically. Otherwise use
npm publish --provenanceand short-lived granular tokens. - Use the
filesfield inpackage.jsonso you never publish.env, tests, or keys.
permissions: contents: readby default. Grantid-token: writeorpackages: writeonly to the job that publishes.- Pin third-party actions to a full commit SHA (
uses: owner/action@<sha> # v4). Tags can be moved, as in the 2025tj-actions/changed-filescompromise. persist-credentials: falseon checkout so later steps (and dependency scripts) can't reuse the git token.- Don't use
pull_request_targetwith a checkout of PR code.
The Node permission model (stable since Node 22.13 / 23.5) restricts the whole process, including every dependency:
node --permission \
--allow-fs-read=./src --allow-fs-read=./node_modules \
--allow-fs-write=./tmp \
server.jsWithout explicit --allow-* flags, the process can't read or write files, spawn child processes (--allow-child-process), start workers (--allow-worker), or load native addons (--allow-addons). Check at runtime with process.permission.has('fs.write', path).
Caveats: on Node 24 it does not restrict network access (check node --help | grep allow-net on newer versions), and it is a seatbelt, not a sandbox for hostile code. Pair it with containers: non-root user, read-only filesystem, no secrets the service doesn't need.
| Repo | Covers |
|---|---|
| nodejs-injection-defense | Command, SQL, path traversal, prototype pollution, ReDoS |
| nodejs-http-hardening | Headers, body limits, timeouts, rate limiting, CORS, safe errors |
| nodejs-supply-chain-security (you are here) | npm config, CI auditing, install-script scanning, permission model |
| nodejs-crypto-secrets | Password hashing, tokens, JWTs, encryption, secrets |
Requires Node.js 22.13 or newer. No npm install needed.
git clone https://github.com/msanvarov/nodejs-supply-chain-security.git
cd nodejs-supply-chain-security
npm testFound a mistake or want to add an example? Issues and pull requests are welcome.


