Nullgap.dev Docs

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 read scope is enough: the request changes nothing, although it is a POST.
  • The exact version of each package. A range such as ^4.17.0 cannot 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:

FieldMeaning
ecosystemWhere the package is published. Up to 40 characters.
nameThe package name, with its scope for a scoped npm package. Up to 214 characters.
versionOne 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:

SendRead as
npmnpm
pypi, pipPyPI
crates.io, cargocrates.io
go, golangGo
mavenMaven
rubygems, gemRubyGems
packagist, composerPackagist
nugetNuGet
hexHex
pubPub

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

FieldMeaning
ecosystem, name, versionThe package, with the ecosystem in its canonical spelling.
verdictmalicious, suspicious, vulnerable, clean or unknown. See the five verdicts.
advisoriesUp to 20 published advisories: id, summary, severity, and kind, which is malware or vulnerability.
fixedVersionFor a vulnerable package: the smallest version that clears every listed advisory. Absent when an advisory has no fix, and for malware.
reasonsEvery signal found, strongest first, up to 25. See Reasons. May be non-empty on a clean result.
checkedWhich sources were consulted: advisories, registry, content.
policyPresent when one of your organisation's rules decided this package: action (block or allow), rule, and a one-sentence detail.
notesUp to 10 sentences saying what could not be checked.

#Reading the answer safely

  • unknown is not clean. It means the check could not be made: the advisory database did not answer, or a field was missing. notes says why. Decide in advance whether your pipeline fails or retries on unknown.
  • clean means clean as far as checked goes. With content: false, the package's files were not read, because nothing in its advisories, name or metadata gave a reason to.
  • A weak reason alone does not change a verdict. A clean result can list one.
  • policy.action is separate from verdict. A clean package 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 clears malicious.
  • 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

WhatLimit
Packages per call500
Packages whose registry metadata is read per call100. The rest get a note.
Package archives read per call8, 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 codeWhen
400 bad_requestpackages is missing, empty or longer than 500; or a package lacks ecosystem, name or version, or one of them is too long.
400 not_configuredPackage checks are not available on this server.
401, 404The 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, vulnerable and unknown through. To stop on those too, add them to both select(...) conditions, for example .verdict == "unknown".
  • It reads package-lock.json. For another lockfile, change the first jq program 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.

Nullgap documentation