npm Typosquatting: How to Spot and Stop Fake Packages
Learn how npm typosquatting works, spot fake package names before install, and layer controls that reduce developer and CI exposure.
Short answer: npm typosquatting is an attack in which a malicious package uses a name that looks like a legitimate dependency, hoping a developer or tool installs the wrong one. Prevent it by verifying the exact package identity before installation, reviewing lockfile changes, restricting lifecycle scripts, and enforcing package policy in developer and CI environments.
A one-character mistake can cross a security boundary. The npm client resolves the name it receives; it cannot infer that you intended a different package. That makes package identity review especially important when developers copy commands from issue threads, accept AI-generated code, or add dependencies under time pressure.
What is npm typosquatting?
npm typosquatting is a package-confusion technique. An attacker publishes a package whose name resembles a trusted package, then waits for someone to mistype, misread, or copy the deceptive name. Common patterns include a missing character, an added character, a transposition, a different scope, a separator change, or a word that sounds equivalent.
The official npm threats and mitigations guide says npm detects and blocks typosquat publishing attempts. That reduces risk, but it should not be treated as a guarantee that every confusing name will be caught. Academic research covering more than 1,200 documented package-confusion attacks identified 13 confusion categories, including semantic patterns that go beyond simple spelling mistakes. The USENIX Security 2023 study also found that many confusing pairs were not flagged by existing tools.
Typosquatting is related to, but different from, dependency confusion. A typosquat imitates another package's identity. Dependency confusion causes a package manager to select an unintended public package in place of a private one. Scoped private packages and explicit registry routing help with dependency confusion, while exact-name verification and package policy are central to typosquatting defense.
Why can a fake npm package be dangerous before import?
A malicious package may not need your application to import it. npm packages can declare lifecycle scripts that execute during installation. If the environment permits those scripts, a fake dependency can run code on a developer laptop or CI runner as soon as the install begins.
A May 2026 investigation by the Microsoft Defender Security Research Team documented 14 typosquatted packages that imitated OpenSearch, Elasticsearch, DevOps, and configuration libraries. Several copied the legitimate project's repository metadata and used inflated version numbers. Their preinstall hooks launched credential-stealing payloads that targeted cloud, Vault, GitHub Actions, and npm secrets.
The lesson is broader than that incident: a plausible repository URL, polished README, or high-looking version number is supporting evidence, not proof of identity. A package page is partly controlled by its publisher. Verification should connect the name and scope to a trusted source such as the official project's documentation, repository, or release notes.
How do you spot npm typosquatting before installation?
Use a repeatable check instead of relying on whether a name “looks right.” This takes longer the first few times, then becomes a quick review habit.
- Start from the official project. Follow the installation command in the project's official documentation or repository. Avoid reconstructing a package name from memory or taking an unverified command from a comment, generated answer, or random tutorial.
- Compare the full identity. Check every character, the exact scope, hyphens, word order, and capitalization. Treat
name,@scope/name, and similarly phrased packages as different identities. - Inspect registry metadata without installing. Use
npm view <package> name version dist-tags time maintainers repository. Look for a new publisher, a very recent first release, unusual version jumps, or metadata that conflicts with the official project. None of these signals proves malware; several mismatches justify stopping. - Check the requested version. Confirm that the version exists in the official project's releases and that the registry's repository link points where expected. Do not assume the default
latesttag is the version your team reviewed. - Review the dependency change. A pull request should show the exact manifest and lockfile change. Look for a new top-level dependency, unexpected transitive packages, registry URL changes, and large resolution churn.
- Search for security evidence. Check advisory databases and trustworthy threat research for the exact package and version. A clean result means only that no matching report was found; it is not proof that the package is safe.
For a broader package-vetting workflow, use the npm package safety checklist. It adds maintenance, release history, provenance, source review, and operational fit to the identity checks above.
How can teams stop typosquatted packages in development and CI?
The strongest setup does not depend on every person noticing every typo. It combines human verification with controls that narrow what can execute and what the registry may deliver.
1. Require dependency changes to be reviewed
Route direct dependency additions through pull requests. Require the author to link the official project, explain why the dependency is needed, and identify the exact package and version. CODEOWNERS or a lightweight security review can protect manifest and lockfile changes without slowing unrelated work.
2. Use reproducible, frozen installs
Commit the lockfile and use npm ci in CI. This prevents the job from quietly rewriting dependency resolution and makes an unexpected package visible in review. Integrity hashes help detect changed bytes for a locked artifact, but they do not tell you that the selected package name was the one you intended. A lockfile can faithfully reproduce the wrong dependency.
3. Restrict lifecycle scripts
Use --ignore-scripts where builds do not require dependency scripts, or use the current npm script-approval controls to permit only reviewed dependencies. Test the policy because some legitimate native modules need build steps. Script restrictions reduce automatic execution during install, but they do not make malicious code safe if the application later imports it.
4. Limit secrets and outbound access
Build untrusted changes in isolated, short-lived runners. Provide the minimum credentials needed, restrict network egress, and avoid exposing package-publishing or production cloud tokens to routine dependency installation. Containment matters because prevention and detection can both miss a new package.
5. Enforce registry and package policy
A proxy or npm registry firewall can apply policy before bytes reach a developer or agent. InstallSafe acts at this install boundary: it serves byte-for-byte npm tarballs for allowed requests and uses OSV.dev advisory data to block versions that are already flagged. It can cover local npm clients, CI, and coding agents through registry configuration.
That scope has an important limit. InstallSafe is advisory-based; it does not claim to detect a brand-new, unreported typosquat from its behavior or name similarity alone. Behavioral-analysis products can inspect code and install-time activity for suspicious signals before an advisory exists. Teams with higher risk should combine identity policy, behavioral analysis, endpoint controls, and advisory-based blocking.
Which controls reduce npm typosquatting risk?
| Control | What it helps catch or stop | Important limit |
|---|---|---|
| Exact-name and scope review | Obvious misspellings, scope changes, and copied bad commands | Humans can miss subtle or semantic lookalikes |
Lockfile plus npm ci | Unreviewed resolution changes and non-reproducible installs | Can reproduce a malicious package exactly |
| Script restrictions | Automatic execution from install hooks | Does not stop malicious runtime code after import |
| Behavioral analysis and endpoint security | Suspicious code, processes, files, or network activity | Can add noise and may detect only after artifacts are fetched |
| Advisory scanner or registry firewall | Known flagged package versions, including reported malware | Cannot block a zero-hour package before data sources identify it |
No single row is sufficient. The practical baseline is identity review, a locked install, restricted scripts, least-privilege execution, and a continuously updated policy source. See the npm supply-chain attack guide for the other compromise paths that typosquatting controls do not cover.
What should you do after installing a suspected typosquat?
- Stop the process and isolate the system. Disconnect the affected runner or workstation from sensitive networks. Do not keep testing the package on the same host.
- Preserve evidence. Record the exact package name, version, lockfile entry, install time, process tree, network connections, and CI logs before cleanup.
- Assume exposed secrets may be compromised. Rotate credentials available to the process, including npm, Git provider, cloud, registry, and CI secrets. Invalidate active sessions where appropriate.
- Remove the dependency and rebuild cleanly. Revert manifest and lockfile changes, clear affected caches, and rebuild from a known-clean environment using reviewed dependencies.
- Search across the organization. Look for the exact name and version in repositories, lockfiles, build logs, software inventories, and cached artifacts.
- Report the package. Send the evidence to npm and the relevant advisory or incident-response channels so others can benefit from removal and shared indicators.
You can check a package name or paste a package.json into InstallSafe's free npm malware scanner to look for versions matched by known advisory data. Treat the result as one layer of evidence, then complete the identity and execution checks described above.
FAQ about npm typosquatting
Does npm prevent every typosquatting package?
No. npm says it detects and blocks typosquat publishing attempts, but confusing names and malicious packages can still appear. Teams should keep their own verification and enforcement controls.
Is npm typosquatting the same as dependency confusion?
No. Typosquatting imitates a trusted package name. Dependency confusion exploits resolution between private and public packages. The defenses overlap, but registry scoping is especially important for dependency confusion.
Will a package-lock.json stop a typosquat?
Not by itself. A lockfile exposes and reproduces the selected package and artifact, but it can lock the wrong package if the original dependency change was not reviewed.
Does disabling npm install scripts make a fake package safe?
No. It reduces the chance of code running during installation, but malicious code can still execute when imported or called later.
Can an advisory scanner detect a new typosquatted package?
Only after the exact package or version is represented in its data. Behavioral tools may detect suspicious characteristics earlier, while package review and isolation reduce exposure before either signal exists.
