trustpkg

Know what a package will do before you install it.

trustpkg audits a package (or your entire package.json) against the npm registry and flags the things that actually matter in a supply-chain attack: install scripts that run arbitrary code, typosquatted names, brand-new packages with zero track record, missing repository links, and abandoned single-maintainer projects.

No install needed — run it with npx. It has zero runtime dependencies, which matters more than usual for a tool whose whole job is telling you what to trust.

$ npx trustpkg reqeust
[email protected]  MEDIUM RISK (score 30)
published 2015-11-18 · 1337 downloads/mo · 1 maintainer(s)
  ✗ Name is dangerously similar to popular package "request" (edit distance 2). Possible typosquat.

Why

Every few months another popular package gets compromised — a maintainer account gets phished, a "helpful" postinstall script quietly exfiltrates environment variables, or a typosquatted name slips into someone's package.json via autocomplete or an AI coding assistant that hallucinated the wrong name. npm install doesn't warn you about any of this before it runs.

trustpkg doesn't replace npm audit (which checks known CVEs) — it checks the things that happen before a CVE exists: the moment you're about to add a new, unvetted dependency.

Install

You don't need to. Just run it:

npx trustpkg express

Or install it if you want it around:

npm install -g trustpkg

Usage

# Audit a single package
npx trustpkg left-pad
npx trustpkg [email protected]

# Audit every dependency + devDependency in the current project
npx trustpkg
npx trustpkg .

# Machine-readable output
npx trustpkg express --json

# Fail (exit code 1) if anything is MEDIUM risk or higher — for CI
npx trustpkg --strict

Example: scanning a project

$ npx trustpkg
PACKAGE    RISK      SCORE  FLAGS
reqeust    MEDIUM    30     1
node-sass  MEDIUM    25     1
express    LOW       0      0
left-pad   LOW       0      0

4 packages checked · 0 high · 2 medium risk
Run "trustpkg <name>" on a flagged package for details.

What it checks

| Check | Why it matters | |---|---| | preinstall / install / postinstall scripts | The most common way malicious packages execute code without you noticing | | Typosquat similarity to top packages | Catches names like reqeust, expres, chalkk before you paste one in | | Package age | A brand-new package has no track record and no time for the community to notice problems | | Repository link | No public source means no way to verify what's published matches what's on GitHub | | Maintainer count | A lone maintainer on a young package is a single point of compromise | | Download volume | Vanishingly low adoption is a signal worth knowing, not a verdict on its own |

Each check adds to a risk score; packages are bucketed into LOW, MEDIUM, or HIGH. None of this is a guarantee — it's a fast, honest first pass before you commit code you haven't read to running on your machine.

CI usage

- run: npx trustpkg --strict

Add it as a pre-merge check so a new dependency with red flags gets a second look before it lands.

Contributing

Issues and PRs welcome — especially additions to the popular-package list used for typosquat detection (lib/popular-packages.js).

License

MIT