Typosquat Detector

Catch malicious package name impersonation before you install

Typosquat Detector identifies npm packages that are likely attempting to impersonate popular libraries through similar-looking names. Protect yourself from one of the most common supply chain attack vectors.

The Problem

Typosquatting is when attackers publish malicious packages with names almost identical to popular packages, hoping developers will make a typo during installation:

• react-d0m instead of react-dom (zero instead of O)
• lodas instead of lodash (missing h)
• expresss instead of express (extra s)
• @fake-scope/axios instead of axios

In November 2025, researchers found 197 malicious packages with over 31,000 downloads using typosquatting to steal credentials. This tool helps you avoid becoming a victim.

Features

• ✅ Detects 8 types of typosquatting patterns
• ✅ Scans against 50+ most popular npm packages
• ✅ Uses Levenshtein distance for similarity detection
• ✅ Identifies visual character substitution (0/O, 1/l, rn/m)
• ✅ Flags fake scopes and common suffixes
• ✅ Confidence scoring for each threat
• ✅ Fast - scans hundreds of packages in milliseconds

Installation

npm install -g typosquat-detector

Or use without installing:

npx typosquat-detector scan

Usage

Check a single package name

typosquat-detector check react-d0m

Output:

 Typosquat Detector

 react-d0m
   Risk Level: CRITICAL
   Threats Found: 1

    Likely typosquat of 'react-dom' using similar character '0' instead of 'o'
      Type: similar_char
      Confidence: 95%

Scan your dependencies

typosquat-detector scan package.json

Audit all installed packages

typosquat-detector audit package-lock.json

Short alias

tsd check express

Detection Methods

1. Character Substitution (CRITICAL)

Visually similar characters that are easy to miss:

• 0 / O / o
• 1 / l / I / i
• 5 / S / s
• rn / m
• vv / w

Example: 1odash → lodash

2. Missing Character (HIGH)

One character removed from popular package:

• expres → express
• reactdom → react-dom

3. Extra Character (HIGH)

One extra character added:

• expresss → express
• reactt → react

4. Character Swap (HIGH)

Adjacent characters swapped:

• raect → react
• expres → express

5. Hyphen Variant (MEDIUM)

Hyphens added or removed:

• reactdom → react-dom
• body_parser → body-parser

6. Fake Scope (HIGH)

Legitimate package wrapped in fake organization:

• @malicious/express → express
• @fake-org/axios → axios

7. Common Suffix (MEDIUM)

Adding nodejs/js suffixes to appear official:

• express-js → express
• react-node → react
• npm-lodash → lodash

8. Plural Form (MEDIUM)

Pluralized versions:

• axios → axios
• requests → request

CI/CD Integration

Protect your pipeline:

# .github/workflows/security.yml
name: Typosquat Check
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for typosquatting
        run: npx typosquat-detector scan

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/sh
npx typosquat-detector scan || exit 1

Use as a Library

const TyposquatDetector = require('typosquat-detector');

const detector = new TyposquatDetector();

// Check a single package
const result = detector.checkPackage('react-d0m');
console.log(result.isClean); // false
console.log(result.highestSeverity); // 'CRITICAL'
console.log(result.threats); // Array of threat objects

// Scan dependencies
const deps = detector.scanDependencies('./package.json');
const critical = deps.filter(d => d.highestSeverity === 'CRITICAL');

Protected Packages

The detector checks against 50+ popular packages including:

• Frameworks: react, vue, angular, next, nuxt
• Utilities: lodash, underscore, ramda, moment, axios
• Build Tools: webpack, vite, rollup, babel, typescript
• Testing: jest, mocha, chai, puppeteer
• Backend: express, mongodb, redis, passport, socket.io
• Styling: tailwindcss, bootstrap, styled-components

See index.js for the complete list.

Real-World Examples

These were actual malicious packages found in 2025:

| Fake Package | Real Package | Attack Type | |--------------|--------------|-------------| | react-d0m | react-dom | Character substitution (0/o) | | expresss | express | Extra character | | @malware/chalk | chalk | Fake scope | | lodas | lodash | Missing character | | axois | axios | Character swap | | moment-js | moment | Suffix variant |

When to Use

• ✅ Before installing any new package
• ✅ When reviewing pull requests
• ✅ In CI/CD pipelines
• ✅ During security audits
• ✅ When something "doesn't work" after installation

Limitations

• Only checks against included popular packages list
• Cannot detect brand-new packages (no install history)
• May have false positives for legitimate variants
• Does not analyze package code (use with preinstall-guardian)

Best Practices

1. Always verify package names before installing
2. Check npm weekly downloads - legitimate packages have millions
3. Review the GitHub repository - does it match the package?
4. Use exact package names - copy from official docs
5. Enable 2FA on npm - protect your publishing rights
6. Combine with other tools:
   • preinstall-guardian for script analysis
   • npm audit for known vulnerabilities
   • socket.dev for runtime behavior

Contributing

Know a popular package that should be included? Submit a PR adding it to the popularPackages array in index.js.

Found a new typosquatting pattern? Open an issue with details.

License

MIT

Disclaimer

This tool provides heuristic analysis based on pattern matching. It cannot guarantee detection of all typosquatting attempts. Always verify packages through official channels.