Dependencies and supply chain
Package check API
Ask Nullgap for a verdict on package versions before they are installed, read the answer, and fail a CI build on a malicious or blocked package.
POST /dependencies/check answers one question for each package version you send: is it malicious, suspicious or vulnerable, and do your organisation's rules permit it? It needs no repository, so it fits a CI step that runs before install, or a registry proxy.
Nothing is installed and no package code is run. How verdicts are reached is on Malicious and suspicious packages.
#What you need first
- An API key. The
readscope is enough: the request changes nothing, although it is aPOST. - The exact version of each package. A range such as
^4.17.0cannot be checked. Read versions from your lockfile.
#The request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"packages":[{"ecosystem":"npm","name":"lodash","version":"4.17.20"}]}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/dependencies/check"
packages is a list of 1 to 500 packages. Each has three fields, all required:
| Field | Meaning |
|---|---|
ecosystem | Where the package is published. Up to 40 characters. |
name | The package name, with its scope for a scoped npm package. Up to 214 characters. |
version | One exact version. Up to 100 characters. A leading v or = is ignored. |
Ecosystem names are matched without regard to case, and the common spellings are accepted:
| Send | Read as |
|---|---|
npm | npm |
pypi, pip | PyPI |
crates.io, cargo | crates.io |
go, golang | Go |
maven | Maven |
rubygems, gem | RubyGems |
packagist, composer | Packagist |
nuget | NuGet |
hex | Hex |
pub | Pub |
Registry metadata and archive contents are read for npm, PyPI and crates.io. Other ecosystems get the advisory lookup only.
#The answer
{
"results": [
{
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"verdict": "vulnerable",
"advisories": [
{ "id": "GHSA-29mw-wpgm-hmr9", "summary": "Regular Expression Denial of Service (ReDoS) in lodash", "severity": "medium", "kind": "vulnerability" },
{ "id": "GHSA-35jh-r3h4-6jhm", "summary": "Command Injection in lodash", "severity": "high", "kind": "vulnerability" }
],
"fixedVersion": "4.17.21",
"reasons": [],
"checked": { "advisories": true, "registry": true, "content": false },
"notes": []
}
],
"malicious": 0,
"suspicious": 0,
"vulnerable": 1,
"unknown": 0,
"blocked": 0
}
The sample is illustrative: the advisories a real call returns depend on what is published on the day you ask.
results has one entry per package you sent, in the same order. The five numbers count results by verdict, and blocked counts results your organisation's rules block. A package can be counted in both a verdict and blocked.
#One result
| Field | Meaning |
|---|---|
ecosystem, name, version | The package, with the ecosystem in its canonical spelling. |
verdict | malicious, suspicious, vulnerable, clean or unknown. See the five verdicts. |
advisories | Up to 20 published advisories: id, summary, severity, and kind, which is malware or vulnerability. |
fixedVersion | For a vulnerable package: the smallest version that clears every listed advisory. Absent when an advisory has no fix, and for malware. |
reasons | Every signal found, strongest first, up to 25. See Reasons. May be non-empty on a clean result. |
checked | Which sources were consulted: advisories, registry, content. |
policy | Present when one of your organisation's rules decided this package: action (block or allow), rule, and a one-sentence detail. |
notes | Up to 10 sentences saying what could not be checked. |
#Reading the answer safely
unknownis notclean. It means the check could not be made: the advisory database did not answer, or a field was missing.notessays why. Decide in advance whether your pipeline fails or retries onunknown.cleanmeans clean as far ascheckedgoes. Withcontent: false, the package's files were not read, because nothing in its advisories, name or metadata gave a reason to.- A
weakreason alone does not change a verdict. Acleanresult can list one. policy.actionis separate fromverdict. Acleanpackage can be blocked by a rule, such as one against versions published in the last few days. An allowed package keeps its verdict: allowing a package never clearsmalicious.- A rule that could not be evaluated does not block. If a publication date or an install script could not be determined, the rule is named in
notes.
#Limits
| What | Limit |
|---|---|
| Packages per call | 500 |
| Packages whose registry metadata is read per call | 100. The rest get a note. |
| Package archives read per call | 8, those with the most reason to look first. The rest get a note. |
For a full lockfile, send several calls. The limits on reading are per call, so smaller batches are also read more thoroughly.
Your key's rate limit applies as for any request. See API overview.
#Errors
| Status and code | When |
|---|---|
400 bad_request | packages is missing, empty or longer than 500; or a package lacks ecosystem, name or version, or one of them is too long. |
400 not_configured | Package checks are not available on this server. |
401, 404 | The key is missing or invalid, or belongs to another organisation. |
A problem with one package, such as a registry that did not answer for it, is not an error. That package gets unknown or a note, and the others are answered.
#Failing a CI build
This script checks every package in an npm lockfile and fails the build when one is malicious or blocked by your organisation's rules. It needs curl and jq, and the three variables NULLGAP_URL, NULLGAP_ORG and NULLGAP_API_KEY.
Run it before npm ci, so that a hostile install script never gets the chance to run.
#!/usr/bin/env bash
set -euo pipefail
# Every package version in package-lock.json (lockfile version 2 or 3), in batches of 500.
jq -c '[.packages | to_entries[]
| select((.key | contains("node_modules/")) and .value.version != null and .value.link != true)
| {ecosystem: "npm", name: (.value.name // (.key | split("node_modules/") | last)), version: .value.version}]
| unique | . as $all | range(0; length; 500) | {packages: $all[.:.+500]}' \
package-lock.json > nullgap-batches.jsonl
stop=0
while IFS= read -r batch; do
result=$(curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d "$batch" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/dependencies/check")
# Anything that is not a list of results is a failed check, never a clean one.
if ! echo "$result" | jq -e 'has("results")' > /dev/null; then
echo "Package check failed: $result" >&2
exit 1
fi
echo "$result" | jq -r '.results[]
| select(.verdict == "malicious" or .policy.action == "block")
| "\(.verdict) \(.name)@\(.version) \(.policy.detail // .advisories[0].summary // .reasons[0].summary // "")"'
bad=$(echo "$result" | jq '[.results[] | select(.verdict == "malicious" or .policy.action == "block")] | length')
stop=$((stop + bad))
done < nullgap-batches.jsonl
if [ "$stop" -gt 0 ]; then
echo "$stop package(s) are malicious or blocked by your organisation's rules. Stopping before install." >&2
exit 1
fi
echo "No malicious or blocked packages."
What the script does and does not do:
- It fails closed. If the request fails, or the answer is an error, the build stops.
- It stops on
malicious, and on any package a rule blocks, whatever that package's verdict. - It lets
suspicious,vulnerableandunknownthrough. To stop on those too, add them to bothselect(...)conditions, for example.verdict == "unknown". - It reads
package-lock.json. For another lockfile, change the firstjqprogram to produce the same{ecosystem, name, version}objects.
As a job in a GitHub Actions workflow, with the script saved as scripts/nullgap-check.sh:
jobs:
dependencies:
runs-on: ubuntu-latest
env:
NULLGAP_URL: ${{ vars.NULLGAP_URL }}
NULLGAP_ORG: ${{ vars.NULLGAP_ORG }}
NULLGAP_API_KEY: ${{ secrets.NULLGAP_API_KEY }}
steps:
- uses: actions/checkout@v4
- name: Check packages before install
run: bash scripts/nullgap-check.sh
- name: Install
run: npm ci
Use a key with the read scope for CI. See API keys and CI.
#The pull request check does this for you
If the repository is connected and pull request review is on, you do not need this script for pull requests. When a pull request changes a manifest or a lockfile, the packages it adds or moves are checked the same way, with the project's lockfile as an extra source, and a blocked package fails the check. See Supply chain checks.
The package check API is for the cases the pull request check does not cover: a pipeline that installs outside a pull request, a registry proxy that decides per download, or a check before adding a dependency at all.
#Related
Nullgap documentation