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
verdict | Meaning | What to do |
|---|---|---|
malicious | A 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. |
suspicious | Signals a person should look at, listed in reasons. Not known to be malicious. | Read the reasons before you trust it. |
vulnerable | A vulnerability advisory lists this version, and nothing worse was found. fixedVersion names the fix when there is one. | Upgrade. See Advisories and findings. |
clean | The advisory database answered and nothing was found. | Nothing. Read checked to see how far "clean" goes. |
unknown | It 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
- The advisory database is asked about the exact version. A malware advisory makes the package
malicious. A vulnerability advisory makes itvulnerable. No advisory makes itclean. If the database cannot be asked, or the package was not given with an ecosystem, a name and an exact version, it isunknown. - 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.
The signals can raise the verdict, never lower it.
- One
strongsignal makes the packagemalicious. - Otherwise the signals are added up. If they reach the weight of one
notablesignal, the package issuspicious. - A malware advisory stands whatever the signals say.
- One
#Strength
Every reason has a strength. It is what decides how much the reason counts.
strength | Meaning | Effect |
|---|---|---|
strong | Behaviour 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. |
notable | Enough for a person to look, by itself. For example, a name one letter away from a popular package. | One is enough for suspicious. |
weak | Common 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."
}
| Field | Meaning |
|---|---|
id | A stable rule name, such as typosquat or content-credential-exfiltration. |
category | One of the six categories below. |
strength | strong, notable or weak. |
severity | critical, high, medium, low or info. |
summary | One sentence saying what was seen. |
file, line | Where: a file of your project for lockfile reasons, a path inside the package's archive for content reasons. |
excerpt | For 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
category | What it looks at | Examples |
|---|---|---|
typosquat | The name | A 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. |
registry | The registry's metadata | A 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-script | Whether it runs code at install time | The package has an install script. |
content | The files of the published archive | An 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. |
lockfile | How your project resolves the package | Fetched 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. |
confusion | Dependency confusion | A 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:
| Source | What | For which packages |
|---|---|---|
| The advisory database | Published malware and vulnerability advisories | Every package |
| The public registry | The package's metadata: versions, publication dates, publisher, size, whether it declares install scripts | npm, PyPI and crates.io packages, up to a limit per check |
| The published archive | The files of the package version, downloaded from the registry's own archive host | Packages that already gave a reason to look. On a pull request, every package the change adds or moves, up to a limit. |
| Your project | Lockfiles and manifests | Pull 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.
| Field | Meaning |
|---|---|
checked.advisories | The advisory database answered for this package. |
checked.registry | The registry's metadata was read. |
checked.content | The published archive was read. |
notes | What 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.registryfalse, 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 found | Severity | Assurance | Rule |
|---|---|---|---|
| A published malware advisory lists the exact version | Critical | Verified | The advisory id |
| Strong evidence in the published archive, with no advisory yet | Critical | Unverified | supply-chain/malicious-content |
| Suspicious (pull requests only) | High at most | Unverified | supply-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
| Check | Ecosystems |
|---|---|
| Advisory lookup | Any 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 contents | npm, 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.
#Related
Nullgap documentation