squat

Documentation

Overview

Package squat flags newly-added dependencies whose names are one edit away from a popular package on the same registry — the shape of a typosquatting attack (npm, PyPI, crates.io, RubyGems, Packagist).

The check is entirely local: the popular-package name lists are embedded at build time, so it runs offline and in the browser playground alike.

Noise control, in the spirit of every other lockvet signal:

• only packages ENTERING the tree are checked (an existing dependency being bumped cannot change its name);
• the incoming release must be young (≤ 30 days) or of unknown age — a name that has coexisted with its popular neighbour for years is an unfortunate name, not an attack;
• the added package must not itself be on the popular list;
• name pairs a registry treats as the SAME package never flag (PyPI: '-', '_' and '.' are interchangeable per PEP 503; crates.io: '-'/'_' collisions are blocked at publish time);
• names shorter than 4 characters are skipped (too collision-prone).

Popular-package data sources (regenerate with gen.sh):

• npm: the npm-high-impact list by Titus Wormer (MIT), https://github.com/wooorm/npm-high-impact
• PyPI: Top PyPI Packages by Hugo van Kemenade, https://github.com/hugovk/top-pypi-packages (DOI 10.5281/zenodo.2586599), top 8 000
• crates.io: the crates.io API, sorted by all-time downloads, top 2 500
• RubyGems: the ecosyste.ms packages API (data CC BY-SA 4.0), rubygems.org sorted by all-time downloads, top 5 000
• Packagist: packagist.org's official explore/popular API, top 4 000

Index

• Constants
• func Annotate(diffs []diffx.FileDiff)
• func Match(eco lock.Ecosystem, name string) string

Constants

const MaxAgeDays = 30

MaxAgeDays is the young-release gate: additions older than this never flag, however confusable their name is.

Functions

func Annotate

func Annotate(diffs []diffx.FileDiff)

Annotate flags added packages whose names are confusable with a popular package. Runs after the metadata layers so the young-release gate can use PublishedAt/AgeDays.

func Match

func Match(eco lock.Ecosystem, name string) string

Match returns the popular package name (in its original spelling) that `name` is at most one edit away from on the ecosystem's registry, or "" when there is none — or when the pair could never be a squat (same canonical package, name itself popular, name too short).