How npm Supply-Chain Attacks Fit Reach Your Server
See how malicious npm patch releases, postinstall scripts, and typosquats fit reach your Node app on a VPS, plus the deploy practice wey stops them.
Wetin npm supply-chain attack mean for your server
npm supply-chain attack fit reach your server through package wey you choose install. No open port dey involved, and no exploit step dey. npm dey install code, and when you install code, code go run. So, small Node application fit pull several hundred packages wey you never read, and any one of dem fit publish new version one hour from now.
Your deploy fetch malicious version because your install command ask for the newest version wey match. That code go then run with the privileges of whoever run the install. Everything below come from those two sentences.
The forms dey arranged according to how often dem affect one person wey dey deploy one Node app to one VPS. Big company no go use this order, because big company get internal registry, review team, and mirror of the public registry. You get deploy script.
Shape 1: maintainer account breach go publish patch
The npm registry no dey allow anybody change the content of version wey don already exist. So, if attacker phish maintainer or steal publish token, e no fit rewrite 4.18.2. Instead, dem publish 4.18.3.
Look your package.json. Line like "express": "^4.18.2" no mean version 4.18.2. The caret mean “any 4.x version wey be this one or newer”, while ~4.18.2 mean “any 4.18.x”. npm install go resolve that range when e run, so the same git commit wey you deploy twice for the same afternoon fit install two different sets of code. Na that gap be the attack surface. Nothing for your machine need to get breached before the gap open.
People dey usually report malicious releases and pull dem, but dem go pull am only after people don install am. Anybody wey deploy during that window don get the code for disk. Pipeline wey resolve ranges for every run go enter that window automatically, several times every week, without anybody deciding to.
Shape 2: install script dey run as the user wey dey do the deploy
A package’s package.json fit declare preinstall, install, postinstall and prepare inside im scripts block. npm dey run dem during installation. Dem no dey sandbox, and nobody dey review dem. Na shell commands wey dey run as the user wey type the install command, inside that user’s home directory, with that user’s network access and the complete environment of that shell.
npm 12, wey release on 8 July 2026, change that default: e dey block dependency install scripts unless the project’s allowScripts field for package.json approve dem. As of 12 October 2026, no Node.js release bundle npm 12 (Node.js 26.11.1 ships npm 11.20.0). So unless you upgrade npm by yourself, the npm for your server still dey run every one of dem.
So the useful question no be wetin the package fit do. Na wetin that user fit read. For normal deploy box, the answer include ~/.npmrc wey hold registry token, ~/.ssh/id_ed25519 wey dem use as deploy key for SSH (secure shell), ~/.aws/credentials, ~/.docker/config.json, and every exported variable for the shell. Na for there DATABASE_URL dey usually live.
Payload like this no need persistence or privilege escalation. E dey read some files, send dem go host through HTTPS, then exit with status 0. You no go see anything because npm dey hide install-script output by default. Turn that off and monitor wetin actually dey run:
npm ci --foreground-scriptsforeground-scripts share standard input, output and error with the npm process. So build scripts print for your terminal instead of entering buffer wey npm discard when installation succeed.
Shape 3: typosquat, na di name wey you no type well
Typosquat na package wey dem publish with name wey resemble popular package, dey wait for person to type or paste install command wrongly. Na the command cause the problem, no be the code, so lockfile no fit help you here: you add the wrong name once, then lockfile go faithfully pin am from that time onward.
The variant wey dey catch teams instead of individual users na dependency confusion. Your internal package name na billing-utils, and e dey for private registry. If nobody create package wey name billing-utils for public registry, anybody fit publish one. npm dey resolve unscoped names against the default public registry, so the public copy fit win. The fix na scope wey you own plus registry mapping for that scope, inside .npmrc:
@yourorg:registry=https://npm.yourorg.example/
//npm.yourorg.example/:_authToken=${NPM_TOKEN}Now @yourorg/billing-utils go only ever fetch from that host, because system go check the scope-to-registry mapping before the default registry. Unscoped internal name no get mapping, so e no get this protection.
Before you add any new dependency, inspect am instead of only checking the download badge:
npm view some-lib repository.url maintainers time.created time.modifiedPackage wey dem create last month and publish by account wey you no fit link to public repository get different risk from package wey get six years of history. None of these facts prove anything by themselves. But both checks cheap to do.
Shape 4: dependency wey the owner change quietly
Maintainers dey hand packages over. Person fit tire, another person offer to help, publishing rights move, and no notification reach the projects wey depend on am. Nothing don breach. The trust wey you give for 2021 now dey with another person.
This na the slowest shape and the hardest one to detect, and no command fit answer am directly. Two things fit narrow am. Check who fit publish before you adopt a package, with the npm view line above. Then read the diff when package wey you really depend on change:
npm diff --diff-name-only --diff=some-lib@1.4.2 --diff=some-lib@1.4.3
npm diff --diff=some-lib@1.4.2 --diff=some-lib@1.4.3The first form dey print only the filenames wey change. E fast enough to run am for every upgrade of package wey matter to you. If patch release touch build script, add file for package root, or edit the scripts block, read am fully before e reach your server.
Build from committed lockfile with npm ci
package-lock.json dey record the exact version of every package for the tree, the URL wey each one come from, a sha512 integrity hash for each tarball, and which package require am. Commit am. Na the only file wey talk wetin una actually test.
Then install with npm ci, never npm install, for any machine wey no be developer laptop:
npm ci --omit=dev --ignore-scriptsnpm ci different from npm install for ways wey all matter here. E require make lockfile dey exist. E remove any existing node_modules before e start, so leftovers from earlier deploy no fit survive enter this one. E no ever write to package.json or to the lockfile, so install no fit quietly move you forward to another version. If lockfile and package.json no agree, e go exit with error instead of resolving the difference.
That error na the feature, no be annoyance. E mean say dependency change must come as commit wey person review, no be side effect of deploy for 02:00.
Dem dey check the integrity hash for every fetch. If tarball bytes no match the recorded hash, install go fail with code EINTEGRITY instead of unpacking am. Make you understand exactly wetin this one give you: e prove say the file wey you receive na the same file wey lockfile pin, and na the same guarantee verifying downloads with checksums dey give you. E get the same limitation too. E no talk anything about whether the pinned version malicious when dem publish am.
One detail about --omit=dev: dem packages still dey resolve and still dey write inside lockfile. Na only say dem no dey place am for disk. Fewer packages for disk mean fewer install scripts and less code wey load for runtime, so e worth doing. E no remove dependency from your tree.
Treat install scripts as code, and know how to refuse dem
You fit disable install scripts. Put this for the project .npmrc and commit am beside the lockfile:
ignore-scripts=true
save-exact=trueignore-scripts=true dey stop npm from running the scripts wey dependencies declare. save-exact=true dey make npm install some-lib write 1.4.2 inside package.json instead of ^1.4.2, so a resolving range no go enter your manifest by mistake.
This fit break things, and you suppose know how before you enable am. Packages wey dey compile native addon or download prebuilt binary dey do that work inside install script. When scripts dey off, the install go succeed, but the failure go show later for runtime, as a module wey no fit load its binding file. The answer na allowlist:
npm ci --ignore-scripts
npm rebuild better-sqlite3 --ignore-scripts=falsenpm rebuild <package> dey run the build scripts for that one package. The --ignore-scripts=false no be optional: npm rebuild dey respect the ignore-scripts=true wey you just commit to .npmrc, and without the override e go link the package binaries and run none of its scripts. You don now make decision for each package, instead of giving blanket execute permission to some hundred strangers wey you no go ever meet.
If you dey run npm 12, this allowlist dey built in. npm approve-scripts better-sqlite3 dey record the approval for the allowScripts field of package.json, unapproved dependency scripts dey skip with warning, and npm rebuild dey check the same list, so for npm 12 the rebuild above still need that approval. A committed ignore-scripts=true dey override the allowScripts policy completely.
To see how big that grant be now, ask npm:
npm query ":attr(scripts, [postinstall])"That one go print every package for the installed tree wey get a postinstall script. For a normal application, the list short pass wetin people dey expect, and na exactly this one make the allowlist practical.
Separate the build from the process wey dey serve traffic
Deploy user need write access to node_modules. The process wey dey answer HTTP requests no need am. If na the same account, code wey run during install fit rewrite the code wey dey serve your users, and code wey run at runtime fit rewrite am too.
Separate dem. Build as one user, serve as another, then make the served directory read-only for the serving account:
sudo useradd --system --home-dir /srv/nodeapp --shell /usr/sbin/nologin nodeapp
sudo chown -R deploy:nodeapp /srv/nodeapp
sudo chmod -R o-rwx /srv/nodeappThen make systemd enforce am. Write /etc/systemd/system/nodeapp.service:
[Unit]
Description=Node application
After=network-online.target
[Service]
User=nodeapp
Group=nodeapp
WorkingDirectory=/srv/nodeapp/current
EnvironmentFile=/etc/nodeapp/env
ExecStart=/usr/bin/node server.js
Restart=on-failure
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/srv/nodeapp/shared
NoExecPaths=/srv/nodeapp/shared
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
[Install]
WantedBy=multi-user.targetProtectSystem=strict mounts the whole file system as read-only for this service, except /dev, /proc, /sys and anything wey you list for ReadWritePaths. So if the application try write inside node_modules, the attempt go fail with EROFS: read-only file system. You fit reproduce this for your own logs in about one minute. NoExecPaths covers the writable upload directory: the service fit write files there, but the kernel no go allow am execute those files. This option need systemd 248 or newer, and Ubuntu 24.04 ships with 255.
Two things fit cause problem for this unit file. First, no add MemoryDenyWriteExecute=yes. E dey inside most systemd hardening lists, but e stops Node from starting because V8 dey compile JavaScript to machine code at runtime and need pages wey writable and executable at the same time. Second, take the ExecStart path from command -v node. If you install Node with a version manager, e dey under deploy user's home directory. ProtectHome=yes go then hide that directory from the service, and the unit go fail immediately with status=203/EXEC plus one log line wey say e no fit locate the executable.
Check the result instead of just trusting the file:
sudo systemctl daemon-reload
sudo systemctl enable --now nodeapp
sudo systemd-analyze security nodeapp.service
sudo -u nodeapp touch /srv/nodeapp/current/probesystemd-analyze security lists every hardening setting together with the exposure level, so you fit see the ones wey still dey use default. The touch suppose fail with Permission denied because nodeapp no own anything under current. If e succeeds, your file ownership no correct, and the systemd settings dey quietly cover the problem.
One thing about EnvironmentFile: systemd reads am as root before e drops privileges to User=nodeapp, so that file fit be root:root with mode 600. The application still receives the variables. Anybody wey get shell as nodeapp fit still read dem from /proc/<pid>/environ, so this protects the secret while e dey stored, but e no protect am from the running process.
Credentials for deploy dey outside build environment
Install scripts inherit environment. Na this fact suppose decide where you go build.
The strongest option na to build for somewhere wey no be production server, then copy the finished directory go there. Build machine go then hold one read-only registry token and nothing else. No SSH deploy key, no cloud access key, no database password, no container registry login.
npm token create --name=build-readonly --packages-and-scopes-permission=read-only --packages-all --expires=30Read-only token fit fetch packages but e no fit publish. npm revoke every classic token on 9 December 2025, so this one na granular access token, and na the permission flag make am read-only: current npm still accept the old --read-only flag, but npm token create no send am go registry. If person steal the token from build environment, the loss na read access to the packages wey e cover.
If you must build for the server, build as the deploy user with environment wey you narrow deliberately, and keep runtime secrets inside /etc/nodeapp/env, wey deploy no fit read. The same reasoning apply to build automation wey you host by yourself: self-hosted GitHub Actions runner dey hold tokens and execute any published code for every job, so e become the machine with the highest value for small deployment. Any program wey you no write wey receive your complete environment belong to the same category. Na why keeping secrets outside AI agent environment be this same problem with another program for the middle.
Pin or vendor wetin you no fit audit
Pinned dependency na dependency wey version no fit change unless commit happen. The committed lockfile don already do this for the whole dependency tree. Two cases need extra protection.
Transitive dependencies na the first one. You no control wetin your dependencies depend on. overrides for package.json go force one version anywhere for the tree:
{
"overrides": {
"some-transitive-lib": "1.4.2"
}
}Run npm install once after you add am, so lockfile fit record the result. Then commit both files.
The second case na package wey you no fit audit and you no fit remove. Vendor am. npm pack downloads the exact tarball wey registry for serve, and file: dependency installs from your own copy:
npm pack some-lib@1.4.2
mkdir -p vendor && mv some-lib-1.4.2.tgz vendor/{
"dependencies": {
"some-lib": "file:vendor/some-lib-1.4.2.tgz"
}
}The tarball don dey your repository now, and e no fit change without your action. But you don also accept responsibility for all its updates forever. So use this for small abandoned package wey you stuck with, not for your web framework.
Cooling-off period dey too, and e no cost anything:
npm install --before=2026-08-01The before option rebuilds the tree using only versions wey dem publish on or before that date. Set am one or two weeks back when you refresh dependencies. This go make you skip the period when bad release dey live but nobody don report am yet. Na blunt tool, because e also delay genuine security fixes. Use am to resolve the ranges, read wetin change, then commit the lockfile. Recent npm releases also accept min-release-age, na rolling window in days (min-release-age=7 for .npmrc), wey do the same work without date wey you need keep changing. This same approach make sense for command-line tools wey you install from npm instead of depend on. An unpinned npx call fit fetch anything wey ship that morning, while pin exact dsh version na wetin make two machines run the same code.
How you fit know which version you actually release?
The lockfile for git dey talk wetin suppose install. The disk dey talk wetin dey installed. Na only the second one be evidence.
npm ls some-lib
node -e "console.log(require('./node_modules/some-lib/package.json').version)"npm ls dey read node_modules, so e dey report wetin physically dey present instead of wetin the lockfile intend. The node -e line dey read the installed manifest by path. E still work for packages wey their exports field dey block subpath imports, and e print one version without tree drawing around am.
For the other side of the comparison, read git:
git log --oneline -- package-lock.json
git show <commit>:package-lock.json | grep -A3 '"node_modules/some-lib"'Make the connection between both ones permanent by putting the commit inside the deploy layout. Release go /srv/nodeapp/releases/<short commit sha> and point /srv/nodeapp/current to am with a symlink. The answer to “wetin dey run right now” become readlink /srv/nodeapp/current, and e dey available for 03:00 to person wey no be the person wey deploy am.
Finally, check wetin the registry fit vouch for:
npm audit signaturesThis one verify registry signatures for the packages inside your installed tree, and e verify provenance attestations for packages wey get dem. Provenance connect published tarball to the public continuous integration (CI) build wey produce am, so verified attestation mean say you fit trace the code back to a commit instead of an unknown laptop. Coverage no universal, so treat missing attestation as “no information”, not as “bad package”.
Wetin to do after bad release reach your server
Start from wetin run, and which user run am.
If the code run during install, assume say everything wey build user fit read don comot. Rotate the registry token, the SSH keys for that home directory, the cloud credentials, and every secret wey shell export. Rotation na the only honest response, because you no fit prove say nobody read the file.
If the code run during runtime under locked-down service account, the things e fit reach dey much smaller: the application's own environment variables and anything wey e network access fit reach. Na this be the whole reason for running services as unprivileged users on a VPS. E no prevent the compromise. E decide how much of the machine the compromise go get, and whether e go survive restart.
Then rebuild instead of cleaning. Delete node_modules, pin the affected package below the bad version for package.json, run npm install once to update the lockfile, commit am, then deploy with npm ci. No repair tree in place. You no fit list everything wey install script touch.
Write down the window too: the first deploy wey fit don pull the version, and the deploy wey remove am. That range go tell you which of your own logs to read, and you fit only answer am if your releases get commit names.
Wetin all dis no fit fix
A lockfile no make dependency safe. E just turn the time wey you accept that dependency into a dated, reviewed decision, instead of making am happen as side effect of deploy. Every practice wey dey above perform the same conversion, from accident to choice.
npm audit no be defence for here. E compare your tree with database of reported vulnerabilities, so e dey find problems wey dem don already publish and name. Supply-chain attack no get name for the whole useful period wey e dey operate. Run npm audit for old known bugs, and no expect am to tell you anything about release wey ship four hours ago.
To reduce the number of your dependencies help pass any tool for this guide, but na the advice wey people like least. Every package wey you no add na another publisher wey no fit get phished through you, and another install script wey no go ever run as your deploy user.
All dis no concern npm alone. The same four patterns apply to PyPI, RubyGems, container images, and your distribution package manager. Na for npm e dey show most because the trees deep pass, and the npm wey most servers run still execute install scripts by default. Anything wey extend tool wey you already dey run inherit the same problem. Na why to work out wetin dsh plugin fit reach before you install am na the same exercise as reading postinstall script, with your agent permissions standing in for your deploy user's permissions. How much of the machine around am you get responsibility to defend depend on where e dey run. Dis na part of the bigger question of whether VPS hosting safe.
FAQ
npm ci fit protect me from a breached npm package?
E protect you from version changing without your knowledge. npm ci installs exactly wetin package-lock.json records, checks each tarball against im sha512 integrity hash, and stops with error if package.json and the lockfile no agree, instead make e resolve the difference. E no talk whether the pinned version safe. If you commit lockfile wey pins malicious version, npm ci go faithfully install that version for every server wey you own, every time.
I suppose set ignore-scripts=true for everything?
Set am, then allowlist. ignore-scripts=true for the project .npmrc stops dependency install scripts from running. This removes the most direct path from bad package to your deploy user credentials. Packages wey compile native addon or fetch prebuilt binary genuinely need their own scripts. If scripts dey off, dem go fail later for runtime with missing binding file instead of failing during install. Run npm ci --ignore-scripts, then npm rebuild <package> --ignore-scripts=false for the few packages wey you decide to trust, because npm rebuild otherwise honours the .npmrc setting and runs nothing. npm query ":attr(scripts, [postinstall])" shows how many packages really dey there.
How I fit know which package version my server actually install?
Read the disk, no be the lockfile. npm ls <package> reports wetin dey present for node_modules, and node -e "console.log(require('./node_modules/<package>/package.json').version)" prints only the version string. The lockfile for git answers another question: wetin suppose get installed. Na to compare both answers be the point. If you deploy into directory wey carry the git commit name, both answers go still dey available months later when you need dem.
npm audit fit find supply-chain attacks?
No. npm audit matches your tree against database of reported vulnerabilities, so e only finds issues wey people don publish and give identifier. Malicious release fit remain unreported during the hours or days when installing am matters. npm audit signatures na the more useful command: e verifies registry signatures across your installed tree and checks provenance attestations where the publisher provide dem. This tells you whether tarball come from public build instead of unknown machine.
Why e matter to run the app as unprivileged user if the attack happen during install?
Because both failures get different reach, and you dey defend against both. Install-time code runs as the deploy user and fit read that user SSH keys, registry tokens, and cloud credentials. Runtime code runs as the service account. With User=nodeapp, ProtectSystem=strict, and no credentials on disk wey e fit read, im reach stops for the application own environment and database. Separating the accounts also mean say the process wey dey serve traffic no fit rewrite node_modules. So runtime breach go disappear at the next restart instead of becoming permanent.