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
| Place | Applied | What a block does |
|---|---|---|
| The pull request check | Yes, to the packages a pull request adds or moves to a new version | The 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 API | Yes, to every package in the request | The result carries policy with action: "block", and the response's blocked count goes up. What your pipeline does with that is up to you. |
| Pentests | No | A pentest lists malicious, suspicious and vulnerable packages. It does not apply your rules. |
#The rules
| Field | Console label | Rule |
|---|---|---|
blockedPackages | Blocked packages | Never permitted. Up to 500 entries. |
allowedPackages | Allowed packages | Exempt from the rules below it, and no longer raised as suspicious on pull requests. Up to 500 entries. |
allowedRegistries | Allowed registries | Hosts packages may come from, besides the ecosystems' public registries. Up to 50. An empty list means any registry. |
minAgeDays | Minimum age in days | Block a version published fewer than this many days ago. A whole number from 1 to 365, or null for no minimum. |
blockInstallScripts | Block install scripts | Block a package that runs a script when it is installed, unless it is on the list below. true or false. |
installScriptAllowlist | Packages allowed to run install scripts | Exempt 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.
- Blocked packages. A match blocks, with rule
blocked-package. - Allowed packages. A match allows, with rule
allowed-package, and none of the rules below is checked. - 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. - Minimum age. A version younger than the minimum is blocked, with rule
min-age. - 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.
| Rule | Needs | When it is not known |
|---|---|---|
| Minimum age | The publication date, from the registry | The rule does not block. A note says it could not be checked. |
| Install scripts | Whether the package has one, from the registry or the lockfile | The rule does not block. A note says it could not be checked. |
| Allowed registries | The host the lockfile fetches the package from | The 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.
| Entry | Matches |
|---|---|
left-pad | Every version of the package named left-pad, in any ecosystem |
left-pad@1.3.0 | That exact version only |
pypi:requests | The package requests on PyPI only |
npm:left-pad@1.3.0 | That version of that package on npm only |
@acme/config | One 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,mavenand 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 anhttps://address is reduced to its host. http://is refused, and so is a private or internal host. A registry is a publichttpshost.- You do not need to list the ecosystems' own public registries. They are always allowed.
#Setting the rules in the console
- Open Settings, then the Supply chain tab.
- Under Package rules, fill in the lists, one entry per line.
- Set Minimum age in days, or leave it empty for no minimum.
- Switch Block install scripts on or off. When it is on, Packages allowed to run install scripts appears.
- 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
allowedPackagesandallowedRegistriesas 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": nullto 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.
| Field | Values |
|---|---|
action | block or allow |
rule | blocked-package, allowed-package, registry, min-age or install-script |
detail | One 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.
#Related
Nullgap documentation