Nullgap.dev Docs

Dependencies and supply chain

Package rules

Set your organisation's rules about which packages may be used, in the console or by API, and see where they are applied and what each field means.

Package rules are your organisation's own policy about dependencies: packages that must never be used, a minimum age for new versions, a ban on install scripts, a list of registries. They are separate from Nullgap's verdicts. A verdict says what a package is. A rule says what you permit.

A new organisation has no rules.

#Where the rules apply

PlaceAppliedWhat a block does
The pull request checkYes, to the packages a pull request adds or moves to a new versionThe check fails, whatever Fail the check at is set to. A finding titled "Blocked by organisation policy" is raised, naming the rule. See Supply chain checks.
The package check APIYes, to every package in the requestThe result carries policy with action: "block", and the response's blocked count goes up. What your pipeline does with that is up to you.
PentestsNoA pentest lists malicious, suspicious and vulnerable packages. It does not apply your rules.

#The rules

FieldConsole labelRule
blockedPackagesBlocked packagesNever permitted. Up to 500 entries.
allowedPackagesAllowed packagesExempt from the rules below it, and no longer raised as suspicious on pull requests. Up to 500 entries.
allowedRegistriesAllowed registriesHosts packages may come from, besides the ecosystems' public registries. Up to 50. An empty list means any registry.
minAgeDaysMinimum age in daysBlock a version published fewer than this many days ago. A whole number from 1 to 365, or null for no minimum.
blockInstallScriptsBlock install scriptsBlock a package that runs a script when it is installed, unless it is on the list below. true or false.
installScriptAllowlistPackages allowed to run install scriptsExempt from the install-script rule. Up to 500 entries.

#The order of evaluation

For each package the rules are checked in a fixed order, and the first one that decides is the one named in the result.

  1. Blocked packages. A match blocks, with rule blocked-package.
  2. Allowed packages. A match allows, with rule allowed-package, and none of the rules below is checked.
  3. Allowed registries. If the list is not empty, and the project's lockfile shows the package coming from a host that is neither on the list nor the ecosystem's public registry, it is blocked, with rule registry.
  4. Minimum age. A version younger than the minimum is blocked, with rule min-age.
  5. Install scripts. A package with an install script that is not on the allow list is blocked, with rule install-script.

Because blocking comes first, a package on both the blocked and the allowed list is blocked.

#What allowing a package does and does not do

Allowing a package exempts it from rules 3 to 5, and stops a suspicious finding from being raised for it on a pull request.

It never changes what the package is. An allowed package that carries a malware advisory, or strong evidence of hostile code, is still malicious and is still reported. In the package check API an allowed package keeps its verdict and gains policy.action: "allow".

#When a rule cannot be evaluated

A rule needs a fact, and a fact is not always known.

RuleNeedsWhen it is not known
Minimum ageThe publication date, from the registryThe rule does not block. A note says it could not be checked.
Install scriptsWhether the package has one, from the registry or the lockfileThe rule does not block. A note says it could not be checked.
Allowed registriesThe host the lockfile fetches the package fromThe rule is not applied. This is always the case in the package check API, which sees no lockfile.

In the package check API the notes are in notes on each result. A rule that could not be evaluated never blocks: read the notes if you rely on it.

Publication dates and install-script facts are available for npm, PyPI and crates.io packages.

#Entry syntax

blockedPackages, allowedPackages and installScriptAllowlist take the same kind of entry.

EntryMatches
left-padEvery version of the package named left-pad, in any ecosystem
left-pad@1.3.0That exact version only
pypi:requestsThe package requests on PyPI only
npm:left-pad@1.3.0That version of that package on npm only
@acme/configOne scoped package
@acme/*Every package in the @acme scope
lodash*Every package whose name starts with lodash

Rules for entries:

  • Names are matched without regard to case. On PyPI, -, _ and . in a name are treated as the same character.
  • A version must match exactly. There are no ranges.
  • * may only be the last character of the name, after at least one other character. An entry of * alone is refused: a rule that matches everything is a mistake, not a policy.
  • The ecosystem prefix takes the same spellings as the package check API: npm, pypi, crates.io, go, maven and so on.
  • An entry may be up to 260 characters. Duplicates are dropped.

allowedRegistries takes host names:

  • A host name such as packages.acme.example. A value given as an https:// address is reduced to its host.
  • http:// is refused, and so is a private or internal host. A registry is a public https host.
  • You do not need to list the ecosystems' own public registries. They are always allowed.

#Setting the rules in the console

  1. Open Settings, then the Supply chain tab.
  2. Under Package rules, fill in the lists, one entry per line.
  3. Set Minimum age in days, or leave it empty for no minimum.
  4. Switch Block install scripts on or off. When it is on, Packages allowed to run install scripts appears.
  5. Press Save rules.

Any member can see the rules. Only admins and owners can change them.

#Setting the rules by API

The rules are part of the organisation's settings, under supplyChain. Changing them needs the admin role, or an API key with the admin scope.

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supplyChain":{"blockedPackages":["event-stream@3.3.6"],"minAgeDays":7,"blockInstallScripts":true,"installScriptAllowlist":["esbuild","sharp"]}}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/settings"
  • Only the fields you send are changed. The request above leaves allowedPackages and allowedRegistries as they were.
  • A list you send replaces that list. To add one entry, send the whole list with the new entry in it.
  • Send "minAgeDays": null to remove the minimum.

The answer is the organisation's settings, with the rules as they now are under supplyChain. To read them without changing anything:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/settings"
{
  "supplyChain": {
    "blockedPackages": ["event-stream@3.3.6"],
    "allowedPackages": [],
    "minAgeDays": 7,
    "blockInstallScripts": true,
    "installScriptAllowlist": ["esbuild", "sharp"],
    "allowedRegistries": []
  }
}

The sample is abridged: the answer holds the organisation's other settings as well.

A value that is not valid is refused with 400 bad_request, and the message names the field: an entry that is not a package, a * in the wrong place, a minimum age outside 1 to 365, a registry that is not a public https host.

The change is written to the audit log as settings.updated. It takes effect for the next pull request check and the next package check call.

#What a decided result looks like

When a rule decides a package, the result carries policy.

{
  "ecosystem": "npm",
  "name": "left-pad",
  "version": "1.3.0",
  "verdict": "clean",
  "policy": {
    "action": "block",
    "rule": "min-age",
    "detail": "left-pad@1.3.0 was published 2 day(s) ago; the organisation requires at least 7."
  }
}

The sample is abridged.

FieldValues
actionblock or allow
ruleblocked-package, allowed-package, registry, min-age or install-script
detailOne sentence naming the rule and the value that matched

A package no rule decided has no policy.

On a pull request, the finding raised for a blocked package says in its description that this is a rule your organisation set, not a judgement about the package.

#Choosing rules

  • A minimum age is the cheapest protection against a compromised release, which is usually found and removed within days. It also delays urgent security upgrades by the same number of days. Add the fixed version to Allowed packages when you need it sooner.
  • Blocking install scripts stops the way most malicious packages run. Honest packages that build native code use install scripts too, so expect to fill the allow list.
  • Blocked packages is for names and versions you have decided against, such as a release you know was compromised.
  • Allowed registries matters when you use a private registry: it catches a package that should come from it and does not.

Nullgap documentation