Execution phases

A package manager asks a registry for three things: which versions of a package exist, the file for one of those versions, and to accept a file it is publishing. A firewall answers all three, so all three are points where your rules can act.

Every rule runs in exactly one of them. The three execution phases are versions, download, and upload, which is the lowercase spelling the config, API, and CLI use, and what this page uses. The dashboard's Applies when (Execution Phase) picker spells them out instead, as "Resolving package versions", "Downloading a package", and "Uploading a package".

Each phase gives something up: a versions rule can still steer an install but only sees the registry's metadata, a download rule sees the actual package but can only allow or fail it. That tradeoff decides what happens to the developer's install when a rule matches, which is the choice worth settling before you write the rest of the rule.

A policy is not a rule. A policy is what your organization requires: no dependency younger than a week, no copyleft license in a shipped product, nothing carrying a known critical vulnerability. A rule is how one phase enforces part of that. One policy is usually several rules, sometimes across different phases, plus the exceptions you decide to grant. This page is about the phase a rule runs in; who sets the policy behind it is covered in Prevention model.

What the package manager asks for

The firewall answers each of these in the ecosystem's own protocol, so the package manager talks to what looks like a registry and gets answers shaped by your rules (see Client operations).

Which of the three you get depends on what the project already carries, not on the command someone typed. A project that declares ranges has versions to work out; a project with a lockfile, or with exact versions written down, has none, so installing it is downloads and nothing else. The phase follows the request, not the command.

The three execution phases

Versions phase

This phase is version resolution. A project depending on lodash ^4.17.0 has not named a version: the caret means any 4.x release from 4.17.0 upward, so the package manager has to find out what exists before it can choose. That question is what this phase answers, for the whole dependency tree, and a build installing from a lockfile never asks it. The rules still apply to those installs, enforced at download time instead; the callout below explains the difference.

A blocking rule here removes the matching versions from the metadata response before the package manager sees it, along with any tags pointing at them. The package manager then picks the newest version that is left and still satisfies the dependency range, so resolution lands on something that complies with your rules.

A maturity rule like the one above, blocking versions younger than some age, can be declared in either phase, and the phase changes what happens when a dependency range would otherwise resolve to a young version.

Declared in download, it fails the install outright. In the example above, an install allowed to pick 4.17.23 would be rejected two days after that release went out, including for transitive dependencies nobody chose directly, and keep failing until the version ages past the window or someone grants an exception.

Declared in versions, the same install steers around it instead, the way the illustration shows: the package manager never sees 4.17.23 in the version list it gets back, so it resolves straight to 4.17.21 without ever asking for the younger one.

Either phase still stops a request that names the young version directly instead of resolving a range, such as a lockfile pinned to 4.17.23. There is no older version to fall back to there, so it fails the same way a download block would, enforced at download time (see the callout below).

It is also how you control which copy of a package wins when upstreams overlap, say a patched internal build alongside the public release. The package manager picks from the combined list, and a versions rule decides what goes into it.

Two limits are worth knowing:

• There has to be another version to pick. An exact pin of a removed version, or a tag pointing at one, has nothing to fall back to and fails.
• It only sees what the registry knows. A versions rule can use the package name, the upstream, registry status such as deprecation, and the publish date (maxAgeHours). Anything that needs the package file itself is out of reach.

Download phase

This phase is downloading a package. Every package that reaches a build is fetched one file at a time, whether its version was resolved a moment earlier or written into a lockfile months ago. The firewall has that file in hand when it decides.

A blocking rule here fails the request. The package manager has already committed to a version, so there is nothing for it to fall back to. download rules run once per package fetched, with the package file available to read, which is what makes content checks possible.

What this phase gives you is coverage that resolution cannot provide. Every package file entering a build passes through it, including the dependencies several levels down that no developer picked. Nothing gets in by being requested a different way, which is what makes a download rule the one you can state as a guarantee, to an auditor or to a customer.

Use it when a different version of the same package would not make the problem acceptable: a malware verdict, a vulnerability threshold, a package that must never be fetched from outside your organization.

A block answers the request with the firewall's error instead of the package file. How much of that error a developer sees depends on the package manager, so each ecosystem page shows what its clients print. The reason lives in the firewall log either way: the block carries a request ID, and the entry it points at names the rule that fired, the package, and the version. See Investigate a blocked install.

Upload phase

This phase is publishing. When a developer or a pipeline pushes a package to your publish target, it goes through the firewall on the way. It is the only phase that looks at packages leaving your organization.

upload rules evaluate publishes before they reach the publish target. A blocked publish is never forwarded, and the rejection names the package, the version, and a request ID. Because this is where you can still stop something before it leaves, secrets scanning runs here. Malware and install-time code execution checks also run here for ecosystems with publish support, so what you publish is held to the standard you apply to what you consume.

Comparing versions and download

The two phases that act on packages coming in are the pair you choose between when you write a rule.

Which checks run in which phase

The phase also decides which selector functions a rule can use, and that often decides the phase for you. Check the selector function matrix before writing a rule. The dashboard only offers compatible combinations, and the API rejects a rule when its selector function cannot evaluate in the selected phase.

Two consequences come up often. Vulnerability and license checks are offered in download, so rules built on them fail the install rather than steering it. Package age, deprecation, unlisted status, publishing trust, and Composer plugin metadata can be checked in versions and steer resolution instead.

What each phase records

• A versions rule with log: true records the versions it removed, so filtering stays visible in the firewall log even though the install succeeded.
• Webhook events come from download and upload decisions. Metadata filtering never produces events, however many versions it removes. A versions rule that blocks an artifact request is a download decision, so that block does produce one.

Choosing a phase for a rule

Start from what you want to enforce rather than from the phase. Two questions settle it.

1. Would another version of this package be acceptable? If yes, versions enforces it and lets the install continue on a version that complies. If no version of it may enter, download is the phase that says so.
2. Does the check need to read the package file? If it does, the phase is decided for you: download for what comes in, upload for what you publish. The selector function matrix is the list.

Many requirements want both phases, and the two rule sets are separate gates, so a version that survives filtering is still evaluated on download. A common baseline is a maxAgeHours window in versions to delay fresh releases without breaking installs, plus malware and vulnerabilities rules in download as hard stops. Pairing the same selector across both phases works too, when you want resolution steered away from something and a hard stop if a lockfile asks for it anyway.

Starting points in the dashboard

You do not have to pick a phase cold. Add Rule opens with a short list of common goals, each one a policy people usually want, and choosing one starts the rule in the phase that policy needs.

What you get is a starting point, not a finished rule. The next screen is the normal rule form, where you add the selector that says which packages to match and the selector function that says what to check, and where every seeded value stays editable, phase included.

The how-to guides each work one policy through end to end and state the phase they use and why.

Related

• Concept: Rule evaluation, Exception model
• How-to: Delay new versions (versions), Block malware (download), Scan for secrets on publish (upload), Investigate a blocked install
• Reference: Client operations, Rules and selectors, Selector functions