Detecting Typosquatting Packages in npm and PyPI

When to Use

• Auditing project dependencies to identify packages whose names are suspiciously similar to popular libraries
• Proactively scanning package registries for newly published packages that may be typosquats of your organization's packages
• Investigating a suspected supply chain compromise where a developer installed a misspelled package name
• Building automated monitoring that alerts when new packages appear with names close to critical dependencies
• Assessing the risk profile of unfamiliar packages before adding them to a project's dependency tree

Do not use as the sole determination of malicious intent; name similarity alone does not prove a package is malicious. Do not use for bulk automated takedown requests without manual review of flagged packages. Do not use against private registries without authorization.

Prerequisites

• Python 3.9+ with requests and python-Levenshtein (or rapidfuzz) packages installed
• Network access to https://pypi.org/pypi/<package>/json (PyPI JSON API) and https://registry.npmjs.org/<package> (npm registry API)
• A list of popular or critical packages to monitor (e.g., top 1000 PyPI packages, organization's dependency list)
• Understanding of common typosquatting patterns: character omission, transposition, insertion, substitution, and hyphen/underscore manipulation

Workflow

Step 1: Build the Target Package Watchlist

Establish the set of legitimate packages to monitor for typosquats:

• Extract project dependencies: Parse requirements.txt, Pipfile.lock, package.json, or package-lock.json to extract all direct and transitive dependency names
• Include popular packages: Supplement with high-value targets from the top 1000 PyPI downloads (available from https://hugovk.github.io/top-pypi-packages/) or top npm packages by download count
• Add organization packages: Include any packages published by your organization that attackers might target with typosquats to intercept internal installations
• Normalize names: PyPI treats hyphens, underscores, and periods as equivalent (PEP 503 normalization: re.sub(r"[-_.]+", "-", name).lower()). npm package names are case-sensitive but scoped packages use @scope/name format. Normalize before comparison.

Step 2: Generate Candidate Typosquat Names

Produce potential typosquat variants for each target package:

• Character omission: Remove each character one at a time (requests -> rquests, requets, reqests)
• Character transposition: Swap adjacent characters (requests -> erquests, rqeuests, reques ts)
• Character substitution: Replace characters with keyboard-adjacent keys using a QWERTY distance map (requests -> rrquests, requesta)
• Character insertion: Insert common characters at each position (requests -> rrequests, reqquests)
• Separator manipulation: For hyphenated names, try removing, doubling, or replacing separators (my-package -> mypackage, my--package, my_package)
• Common prefix/suffix attacks: Prepend or append common strings (python-requests, requests-python, requests2, requests-lib)

Step 3: Query Registry APIs for Candidate Packages

Check whether generated candidate names actually exist in the registry:

• PyPI JSON API: Send GET https://pypi.org/pypi/<candidate>/json for each candidate. A 200 response means the package exists; 404 means it does not. Extract from the response: info.name, info.version, info.author, info.summary, info.home_page, info.project_urls, and releases (keyed by version with upload_time_iso_8601 timestamps).
• npm registry API: Send GET https://registry.npmjs.org/<candidate> with Accept: application/json. Extract: name, description, dist-tags.latest, time.created, time.modified, maintainers, and versions.
• Rate limiting: PyPI has no published rate limits but respect reasonable request rates (1-2 requests/second). npm registry returns 429 when rate limited; implement exponential backoff.
• Batch optimization: For large candidate lists, parallelize requests with connection pooling (requests.Session) and limit concurrency to avoid triggering abuse protections.

Step 4: Analyze Package Metadata for Suspicion Signals

Score each existing candidate package against multiple heuristic signals:

…