Typosquatted npm packages: keep impostors out of your build
Short answer: Most web apps and websites built with JavaScript install hundreds of open-source packages from the npm registry, and attackers exploit that by publishing packages with names one letter away from popular ones, or with the same name as a company's private package. One mistyped install command can run someone else's code on a developer laptop or in your build pipeline. Protect yourself with scoped names for private packages, a configured private registry, careful review of new dependencies, lockfiles with npm ci in builds, and limits on install scripts.
How the attacks work
npm's own documentation on threats and mitigations describes the two related tricks:
- Typosquatting. Attackers register a package with a name similar to a popular one, hoping people mistype or confuse the two. Think of a missing hyphen, a swapped letter or a plural.
- Dependency confusion. A public package is registered with the same name as a private package an organisation uses internally, so a misconfigured build fetches the public impostor instead of the internal one.
The documentation says npm can detect typosquat attacks and block publication of those packages, but that it is not able to detect dependency confusion attacks, which is why it strongly encourages scoped packages for private code. It also describes a third route, adding malicious behaviour to an existing popular package, and mentions scanning and removing malicious content. No registry catches everything, so your own habits matter.
Why small teams are exposed
A typical small-business web app depends on far more packages than anyone chose directly, because each dependency brings its own. Agencies and freelancers often add packages quickly to meet a deadline. Build servers run installs automatically with access to deployment keys. A malicious package that runs during installation can read environment variables, steal tokens or tamper with the build output.
Protect private packages with scopes
If your business publishes internal packages, such as a shared design system or API client, name them under a scope that you own, for example @yourcompany/ui. Then:
- Register the scope as an organisation on the public registry, so nobody else can publish under it.
- Configure your project's npm settings so that the scope always resolves to your private registry.
- Never use unscoped names for private packages; an unscoped internal name is exactly what dependency confusion targets.
Check before you add a dependency
Make adding a package a small, deliberate step:
- Copy names from the official documentation or the project's repository rather than typing them.
- Check the package page: weekly downloads, repository link, maintainers, publish history. A brand-new package with a familiar-looking name and few downloads is a warning sign.
- Ask whether you need it. A ten-line helper may be better written in-house than pulled in as a dependency with its own dependencies.
- Review pull requests that change package.json with the same care as code, looking at new names letter by letter.
Lock and reproduce installs
The lockfile records exactly which versions and sources were installed. In builds and deployments, use npm ci rather than npm install. npm's documentation explains that npm ci requires an existing package-lock.json, and if the dependencies in the lockfile do not match package.json, it exits with an error instead of updating the lockfile. That stops a build from quietly picking up something new.
Commit the lockfile, review changes to it, and use automated update tools so upgrades arrive as visible pull requests rather than surprise changes.
Limit install scripts
Packages can run scripts automatically during installation, which is how many malicious packages act. npm's configuration reference documents an ignore-scripts setting: when true, npm does not run scripts specified in package.json files. Some legitimate packages need install scripts, for example to download native binaries, so test before enabling it everywhere. A practical approach is to disable scripts by default in CI and allow them only for the specific packages that need them, or use a package manager that supports an allowlist of packages permitted to run scripts.
Reduce what a bad package can reach
- Give build pipelines only the secrets they need for that job, and not production database credentials during dependency installation.
- Run installs in isolated containers.
- Use short-lived deployment credentials.
- Turn on two-factor authentication for anyone who publishes packages from your organisation.
What to do if you installed one
If you suspect a malicious package ran on a laptop or build server, treat it as a security incident. Remove the package, but assume anything the machine could reach may be exposed: rotate tokens, deployment keys and passwords that were available as environment variables or files, check recent deployments for unexpected changes, and rebuild the affected machine or container from a clean image. Report the package to the registry so others are protected.
Monitor
Use a dependency scanning tool, many of which are built into code hosting platforms, to flag known malicious or vulnerable packages. Re-check after a security announcement about a package you use. Keep an inventory of what your apps depend on so you can answer "are we affected?" quickly.
A worked example
Picture a hypothetical Hamilton software agency that maintained an unscoped internal package called company-forms, used across client sites. A developer noticed that a package with the same name had appeared on the public registry, and a fresh build server had briefly installed it.
The agency rotated the build server's credentials, renamed its internal packages under its own registered scope, configured the scope to resolve only from its private registry, and switched all builds to npm ci with committed lockfiles. Install scripts are now disabled in CI apart from two allowed packages, and new dependencies need a second reviewer. Later reviews caught a mistyped package name in a pull request before it was merged.
FAQ
Do these risks apply outside npm?
Yes. Similar attacks target other package registries; the same principles apply.
Is a popular package always safe?
No. Popular packages can be compromised too, which is why lockfiles and monitoring matter.
Will ignore-scripts break my build?
It can, if a dependency needs an install step. Test it first and allow the packages that require it.
If your web app pulls in hundreds of packages and nobody checks what's added, tell us how your builds are set up.