Nullgap.dev Docs

API reference

Dependencies

Check package versions for malware, known vulnerabilities and your own package rules.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
Check packagesPOST /api/orgs/{org}/dependencies/checkread

#Check packages

POST /api/orgs/{org}/dependencies/check

Says, for each package version sent, whether it is malicious, suspicious, vulnerable, clean or unknown, and whether the organisation's supply-chain rules permit it. It needs no repository and changes nothing, so it suits a CI step or a registry proxy: although it is a POST, a read-only API key is enough. Results come back in the order sent. Never treat unknown as clean: it means the package could not be checked. A package the organisation's rules refuse has policy.action set to block, whatever its verdict.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
packagesarray of objectyesThe package versions to check: 1 to 500.
packages[].ecosystemstringyesThe package ecosystem, as the advisory databases name it. Up to 40 characters.
packages[].namestringyesThe package name. Up to 214 characters.
packages[].versionstringyesThe exact version. Up to 100 characters.

Example 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"

Answer (200, application/json)

FieldTypeAlways presentDescription
resultsarray of PackageVerdictyesOne verdict per package sent.
maliciousintegeryesHow many results are malicious.
suspiciousintegeryesHow many results are suspicious.
vulnerableintegeryesHow many results are vulnerable.
unknownintegeryesHow many results are unknown: not checked, so not clean.
blockedintegeryesHow many results the organisation's rules refuse.
{
  "results": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20",
      "verdict": "vulnerable",
      "advisories": [
        {
          "id": "GHSA-35jh-r3h4-6jhm",
          "summary": "Command injection in the template function",
          "severity": "high",
          "kind": "vulnerability"
        }
      ],
      "fixedVersion": "4.17.21",
      "reasons": [
        {
          "id": "typosquat",
          "category": "typosquat",
          "strength": "notable",
          "severity": "medium",
          "summary": "The name is one letter away from the popular package \"lodash\".",
          "file": "package-lock.json",
          "line": 412,
          "excerpt": "\"lodahs\": \"^1.0.2\""
        }
      ],
      "checked": {
        "advisories": true,
        "registry": true,
        "content": false
      },
      "policy": {
        "action": "block",
        "rule": "min-age",
        "detail": "Published 2 days ago; your organisation requires versions to be at least 7 days old."
      },
      "notes": [
        "The package contents were too large to read."
      ]
    }
  ],
  "malicious": 0,
  "suspicious": 0,
  "vulnerable": 1,
  "unknown": 0,
  "blocked": 0
}

Errors specific to this call

StatusCodeWhen
400not_configuredPackage checks are not available on this server.

#Objects

The objects the operations above take and return.

#PackageVerdict

The verdict on one package version.

FieldTypeAlways presentDescription
ecosystemstringyesThe package ecosystem, as sent.
namestringyesThe package name, as sent.
versionstringyesThe version, as sent.
verdictstringyesmalicious: a malware advisory lists it, or its published contents hold strong evidence. suspicious: signals a person should look at. vulnerable: a vulnerability advisory lists it and nothing worse was found. clean: checked and nothing found. unknown: it could not be checked; never treat it as clean.
advisoriesarray of PackageAdvisoryyesThe advisories that list this version. Empty when there are none.
fixedVersionstringnoThe first version without the flaw, when an advisory names one.
reasonsarray of SupplyChainReasonnoEvery signal found, strongest first. May be present on a clean package: weak signals alone do not change the verdict.
checkedobjectnoWhich sources were actually consulted. "Clean" means clean as far as these go.
checked.advisoriesbooleanyesThe advisory database answered.
checked.registrybooleanyesThe package registry was consulted.
checked.contentbooleanyesThe published package contents were read.
policyPolicyMatchno
notesarray of stringnoWhat could not be checked, in plain words.

#PackageAdvisory

A published advisory that lists this package version.

FieldTypeAlways presentDescription
idstringyesThe advisory id.
summarystringyesWhat the advisory says, in one line.
severitystringyesThe severity the advisory states.
kindstringyesWhether the advisory reports malicious code in the package or a flaw in it. One of: malware, vulnerability.

#SupplyChainReason

One reason a package is worth a look. A reason is a signal, not a verdict.

FieldTypeAlways presentDescription
idstringyesThe stable name of the rule that matched.
categorystringyesWhat kind of signal it is. One of: lockfile, confusion, typosquat, install-script, registry, content.
strengthstringyesstrong: no honest explanation. notable: worth a person's look by itself. weak: common in honest packages, given as context.
severitystringyesHow serious the signal is. One of: critical, high, medium, low, info.
summarystringyesThe signal in plain words.
filestringnoA project file (for lockfile signals) or a path inside the package (for signals from its contents).
lineintegernoThe line in file, when there is one.
excerptstringnoA short piece of the text that matched, with secrets masked.

#PolicyMatch

The organisation rule that decided a package, and why.

FieldTypeAlways presentDescription
actionstringyesblock: the organisation does not permit this package. allow: the organisation exempted it.
rulestringyesWhich of the organisation's rules matched. One of: blocked-package, allowed-package, min-age, install-script, registry.
detailstringyesThe rule and why it matched, in plain words.

Nullgap documentation