How Provenix works¶
This page follows a package from the moment one of your clients first asks for it until it's installed.
Your client talks only to Provenix¶
Your .npmrc points the registry at Provenix and carries a client
token. Every request a client makes (package metadata, version metadata,
tarballs) goes to Provenix with that token. Provenix never redirects a
client to the upstream registry: every tarball URL it serves points back at
Provenix.
Each client token belongs to one workspace, and each workspace has its own approvals and policies. Two teams in different workspaces can install from the same Provenix and see different approved versions.
What a client sees¶
When npm asks for a package's metadata, Provenix returns the upstream
document with only the approved versions in it. The latest tag
points at the newest approved stable version that isn't above the
publisher's own latest, so a held release never moves your installs
forward.
If the newest version upstream is being held, the response carries
X-DF-Quarantine-Active: true. Your semver ranges simply resolve to the
newest approved version that matches.
A package Provenix has never seen¶
The first time any client asks for a package Provenix doesn't know, the
install fails with 451 Unavailable For Legal Reasons, and Provenix
starts discovery in the background. It records every version upstream
publishes and starts downloading and scanning the ones the dist-tags point
at. The 451 tells you roughly when the package should be available and,
where your install has one, links to it in the console.
Provenix limits how many unknown packages one client can trigger per hour,
so a typo or a script can't flood the scanners. Over the limit, it answers
429 with Retry-After.
Scanning and quarantine¶
Every version goes through the scanners, which produce findings and a score from 0 to 100. The version is then quarantined for a hold period set by your workspace's policy. The defaults are:
| Case | Default hold |
|---|---|
| A new version of a package you already use | 24 hours after Provenix first saw it, and at least 72 hours after it was published upstream |
| A package with no approved version yet | 7 days after Provenix first saw it |
When the hold ends, a version that scored at or above the auto-approve threshold (80 by default) is approved automatically. Anything below it waits in the console's Quarantine queue for a reviewer.
A reviewer can also act before the hold ends:
- Approve a quarantined version.
- Reject a version, so it's never served.
- Bypass: an admin approves a version immediately, with a required justification. Bypass is meant for emergencies.
If your team needs a version sooner, you can request an expedited review. Your request puts an Expedited badge on the version in the queue.
Once a version is approved¶
The version appears in the metadata clients see, and the tarball is served from Provenix's own storage: the exact bytes that were scanned. If upstream ever serves different bytes for the same version, Provenix refuses to serve them.
Provenix keeps approved metadata and tarballs, so installs of approved
versions keep working when the upstream registry is unreachable. Responses
served that way carry X-DF-Upstream-Unavailable: true.
Next¶
Try it yourself: Quickstart.