Skip to content

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.