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.
| Operation | Method and path | Who may call it |
|---|---|---|
| Check packages | POST /api/orgs/{org}/dependencies/check | read |
#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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
packages | array of object | yes | The package versions to check: 1 to 500. |
packages[].ecosystem | string | yes | The package ecosystem, as the advisory databases name it. Up to 40 characters. |
packages[].name | string | yes | The package name. Up to 214 characters. |
packages[].version | string | yes | The 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)
| Field | Type | Always present | Description |
|---|---|---|---|
results | array of PackageVerdict | yes | One verdict per package sent. |
malicious | integer | yes | How many results are malicious. |
suspicious | integer | yes | How many results are suspicious. |
vulnerable | integer | yes | How many results are vulnerable. |
unknown | integer | yes | How many results are unknown: not checked, so not clean. |
blocked | integer | yes | How 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
| Status | Code | When |
|---|---|---|
| 400 | not_configured | Package checks are not available on this server. |
#Objects
The objects the operations above take and return.
#PackageVerdict
The verdict on one package version.
| Field | Type | Always present | Description |
|---|---|---|---|
ecosystem | string | yes | The package ecosystem, as sent. |
name | string | yes | The package name, as sent. |
version | string | yes | The version, as sent. |
verdict | string | yes | malicious: 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. |
advisories | array of PackageAdvisory | yes | The advisories that list this version. Empty when there are none. |
fixedVersion | string | no | The first version without the flaw, when an advisory names one. |
reasons | array of SupplyChainReason | no | Every signal found, strongest first. May be present on a clean package: weak signals alone do not change the verdict. |
checked | object | no | Which sources were actually consulted. "Clean" means clean as far as these go. |
checked.advisories | boolean | yes | The advisory database answered. |
checked.registry | boolean | yes | The package registry was consulted. |
checked.content | boolean | yes | The published package contents were read. |
policy | PolicyMatch | no | |
notes | array of string | no | What could not be checked, in plain words. |
#PackageAdvisory
A published advisory that lists this package version.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The advisory id. |
summary | string | yes | What the advisory says, in one line. |
severity | string | yes | The severity the advisory states. |
kind | string | yes | Whether 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The stable name of the rule that matched. |
category | string | yes | What kind of signal it is. One of: lockfile, confusion, typosquat, install-script, registry, content. |
strength | string | yes | strong: no honest explanation. notable: worth a person's look by itself. weak: common in honest packages, given as context. |
severity | string | yes | How serious the signal is. One of: critical, high, medium, low, info. |
summary | string | yes | The signal in plain words. |
file | string | no | A project file (for lockfile signals) or a path inside the package (for signals from its contents). |
line | integer | no | The line in file, when there is one. |
excerpt | string | no | A short piece of the text that matched, with secrets masked. |
#PolicyMatch
The organisation rule that decided a package, and why.
| Field | Type | Always present | Description |
|---|---|---|---|
action | string | yes | block: the organisation does not permit this package. allow: the organisation exempted it. |
rule | string | yes | Which of the organisation's rules matched. One of: blocked-package, allowed-package, min-age, install-script, registry. |
detail | string | yes | The rule and why it matched, in plain words. |
Nullgap documentation