Nullgap.dev Docs

Dependencies and supply chain

Malicious and suspicious packages

The five verdicts a package can get, the reasons behind them, what is read to reach a verdict, what is never run, and which ecosystems are covered.

Published advisories tell you about vulnerabilities in honest packages. They say little about a package that is itself hostile, or one that was compromised last week. Nullgap gives every package a verdict from everything that can be learned without running it, and lists the reasons.

The verdicts come from fixed rules. No AI is asked, and no package code is executed.

#The five verdicts

verdictMeaningWhat to do
maliciousA malware advisory lists this exact version, or its published archive contains strong evidence of hostile behaviour.Do not install it. If it was installed, treat that as an incident.
suspiciousSignals a person should look at, listed in reasons. Not known to be malicious.Read the reasons before you trust it.
vulnerableA vulnerability advisory lists this version, and nothing worse was found. fixedVersion names the fix when there is one.Upgrade. See Advisories and findings.
cleanThe advisory database answered and nothing was found.Nothing. Read checked to see how far "clean" goes.
unknownIt could not be checked.Never treat it as clean. Read notes, and try again.

The verdicts are ordered: malicious is worst, then suspicious, vulnerable, unknown, clean. A package gets the worst that applies. A vulnerable package that also shows suspicious signals is suspicious, and its advisories are still listed in advisories.

#How a verdict is reached

  1. The advisory database is asked about the exact version. A malware advisory makes the package malicious. A vulnerability advisory makes it vulnerable. No advisory makes it clean. If the database cannot be asked, or the package was not given with an ecosystem, a name and an exact version, it is unknown.
  2. Signals are gathered: from the package's name, from the registry's metadata, from the project's lockfile when there is one, and from the contents of the published archive for packages that gave a reason to look.
  3. The signals can raise the verdict, never lower it.

    • One strong signal makes the package malicious.
    • Otherwise the signals are added up. If they reach the weight of one notable signal, the package is suspicious.
    • A malware advisory stands whatever the signals say.

#Strength

Every reason has a strength. It is what decides how much the reason counts.

strengthMeaningEffect
strongBehaviour with no honest explanation, found by reading the published archive. For example, an install script that reads SSH keys and sends them out.One is enough for malicious.
notableEnough for a person to look, by itself. For example, a name one letter away from a popular package.One is enough for suspicious.
weakCommon in honest packages. For example, having an install script.Recorded, and only matters in combination.

How weak reasons add up:

  • Three ordinary weak reasons together make a package suspicious.
  • Some weak reasons are rarer in honest projects and count double, so two of them are enough: a package fetched from git instead of a registry, a lockfile entry with no integrity hash, a package that first appeared days ago, a changed publisher, a withdrawn version, a sudden jump in size, network use in a setup script.
  • A few are so common that they never move the verdict and are shown as context only: an install script that starts another program, an encoded blob, a mention of wallet or credential files, a hard-coded chat webhook.
  • Each rule counts once, however many files it fired in.

This is why a clean result can still list reasons: a weak reason alone does not change a verdict.

#Reasons

Each entry of reasons is one signal.

{
  "id": "registry-new-install-script",
  "category": "registry",
  "strength": "notable",
  "severity": "high",
  "summary": "This version adds an install script that the previous version (4.2.0) did not have (postinstall). That is the usual shape of a compromised release."
}
FieldMeaning
idA stable rule name, such as typosquat or content-credential-exfiltration.
categoryOne of the six categories below.
strengthstrong, notable or weak.
severitycritical, high, medium, low or info.
summaryOne sentence saying what was seen.
file, lineWhere: a file of your project for lockfile reasons, a path inside the package's archive for content reasons.
excerptFor content reasons: a short piece of the text that matched, with secrets masked.

Reasons are listed strongest first. Up to 25 are returned for a package.

#Categories

categoryWhat it looks atExamples
typosquatThe nameA name one edit away from a widely used package (notable), or a renamed form of one, such as an added -js (weak). Checked for direct dependencies.
registryThe registry's metadataA version that adds an install script the previous version did not have; a package that first appeared less than 30 days ago; a version published less than 7 days ago; a different publisher from the previous version; a withdrawn version; a version several times the size of the one before; a package that has been unpublished.
install-scriptWhether it runs code at install timeThe package has an install script.
contentThe files of the published archiveAn install script that downloads a file and runs it; code that reads credential files, environment variables or wallet files and sends them out; code that is decoded and then executed; heavily obfuscated code; a Python .pth file that runs code; an install script the registry does not list.
lockfileHow your project resolves the packageFetched from git or a URL instead of a registry; fetched from a registry other than the one configured; no integrity hash; an insecure package index.
confusionDependency confusionA name that looks internal to your organisation, resolved from a public registry; an extra package index that could shadow a private one.

lockfile and confusion reasons need a project to look at. They appear on pull request reviews and pentests, not in the package check API, which sees only a name and a version.

Many content reasons are strong only when they are found in an install script, where the code runs on every machine that installs the package, and notable elsewhere.

#What is read, and what is never run

To reach a verdict Nullgap reads:

SourceWhatFor which packages
The advisory databasePublished malware and vulnerability advisoriesEvery package
The public registryThe package's metadata: versions, publication dates, publisher, size, whether it declares install scriptsnpm, PyPI and crates.io packages, up to a limit per check
The published archiveThe files of the package version, downloaded from the registry's own archive hostPackages that already gave a reason to look. On a pull request, every package the change adds or moves, up to a limit.
Your projectLockfiles and manifestsPull request reviews and pentests only

What is never done:

  • Nothing is installed. No package manager is run to fetch the package.
  • No package code is executed. Not the package, not its install scripts, not its tests. The archive is unpacked in memory and its files are read as text.
  • No AI reads the package. Verdicts are fixed rules over names, metadata and files.
  • Archives are fetched only from the registries' own hosts. An address anywhere else is not followed.

#checked and notes

Because reading has limits, every result says how far it went.

FieldMeaning
checked.advisoriesThe advisory database answered for this package.
checked.registryThe registry's metadata was read.
checked.contentThe published archive was read.
notesWhat could not be checked, in plain words.

"Clean" means clean as far as checked goes. A clean package with checked.content: false had no advisory and showed no signal in its name or metadata; its files were not read, because nothing gave a reason to.

Limits that produce a note:

  • In one package check call, registry metadata is read for up to 100 packages (direct dependencies first) and up to 8 archives are read. Beyond that, a package's note says the metadata or the archive was not read because there were too many packages in one check.
  • A file in an archive that is too large to read is skipped, and the note says how many were.
  • A registry that does not answer leaves checked.registry false, with the reason.

#Malicious packages as findings

On a pull request and in a pentest, a malicious package is a finding, with the reasons as its evidence.

How it was foundSeverityAssuranceRule
A published malware advisory lists the exact versionCriticalVerifiedThe advisory id
Strong evidence in the published archive, with no advisory yetCriticalUnverifiedsupply-chain/malicious-content
Suspicious (pull requests only)High at mostUnverifiedsupply-chain/suspicious

The second row deserves care. That verdict comes from fixed rules over the package's files, not from a published report. The finding says so, and it is marked unverified: read the evidence before you act on it.

A fix for a malicious package pins it to a clean release or removes it. See Dependency fixes. Removing the package does not undo what it did when it was installed.

#Ecosystems covered

CheckEcosystems
Advisory lookupAny ecosystem the advisory database covers. The package check API accepts npm, PyPI, crates.io, Go, Maven, RubyGems, Packagist, NuGet, Hex and Pub.
Registry metadata and archive contentsnpm, PyPI and crates.io
Reading a project's lockfiles (pull request reviews and pentests)npm, pnpm and Yarn; pip requirements, Poetry, uv and Pipenv; Cargo

For an ecosystem outside the second row, a verdict can only be malicious (from a malware advisory), vulnerable, clean or unknown. checked.registry and checked.content are false, and no name or content signal is looked for.

Nullgap documentation