Screening what comes in

Every artifact passes a gate before the repository serves it - whether a client published it or the repository fetched it from upstream. The gate reaches one of three verdicts:

Verdict What happens
Allow The artifact is stored and served.
Quarantine The artifact is stored but withheld: clients get 404 for it until someone releases it from the review queue.
Reject The artifact is refused and nothing is stored. The client gets an error, and the refusal is recorded.

A version's dependencies are screened where a build fetches them, not when the version is published: a package your own library pulls in from upstream passes the gate as the build fetches it through the repository, however deep it sits in the graph, and a build that needs one the gate holds fails on that fetch, with the package in the review queue. A build only reaches what the repository serves when every dependency comes through it, so point the clients at the repository rather than at the upstream beside it.

This chapter covers what the gate checks, how to tune it, and the Screening pages every repository has in the console.

What the gate checks

Check Default Settings
Known vulnerabilities - advisories at or above a severity band, for what is fetched from an upstream Quarantine at CRITICAL vulnerability-threshold, vulnerability-action
Malicious packages - packages a curated feed marks malicious, for what is fetched from an upstream Reject malware-action
The deny list - coordinates you forbid outright Reject deny-list, deny-list-action
Signatures - an untrusted signer, a signature that does not match its bytes, a coordinate whose signer changed Reject a broken signature, quarantine a changed signer, allow an untrusted signer and record it on the version signature-untrusted, signature-invalid, signature-signer-changed
Provenance - build attestations that name the wrong builder or source Quarantine, once you name what to expect provenance-admission-*
Your own rules - expressions over what the gate knows None policy-rules
Release immutability - republishing a release version with different bytes, in every format but Hugging Face, whose revisions move by design Refused with 409, or npm's own 403 allow-redeploy

Every setting here is under Settings → Settings, in the Compliance group, and takes effect at once unless it says it needs a restart.

The advisory feeds are asked about what the repository fetches from an upstream, by its coordinate. A version published into the repository is asked of no feed: it is your own code, and a feed knows nothing about it. It is screened instead through what it relies on, as What a published version relies on describes.

Switching the feeds on

The vulnerability and malware checks need something to check against, and nothing reaches a third party until you say so. Three feeds ship with the image, each off by default:

Feed Setting What it answers
OSV (osv.dev) osv Known vulnerabilities across every ecosystem
GitHub Advisory Database github Known vulnerabilities, with GitHub's reviewed severities
OpenSSF malicious packages openssf Packages published with malicious intent

Switch them on during Setup, or in Settings → Settings; the gate screens with a feed from the moment it is switched on, with no restart. Each feed has an endpoint setting beside it (osv-endpoint, github-endpoint, openssf-endpoint) for a mirror or a proxy.

A switched-on feed screens every repository. A repository can narrow that with its own advisory-feeds setting: the names of the feeds that screen it, comma-separated, or none for none. A feed's switch and its endpoint stay the deployment's, so a repository chooses only among the feeds that are on, and naming one that is off is treated as that feed being unreachable rather than quietly screening with fewer.

A feed fails closed by default. While it is on and cannot be reached, an artifact it would have screened is held for review rather than served unscreened - so switch a feed on only where the deployment can reach it, and read a held artifact's reason before taking it for a verdict on the content. A repository's screening mode changes this, as [When a feed cannot answer](#when-a-feed-cannot-answer) describes.

Beyond checking each fetch, the repository re-scans every copy it already holds against the feeds on a schedule - hourly by default (scheduled-scan, scan-interval-millis) - so an advisory published after a copy was fetched still reaches it, and what a scan finds lands on Vulnerabilities and Findings. Every 24th pass (scan-full-every) asks about every copy. The passes between ask about the copies fetched since, and about every package whose records a feed's published change list says changed.

A local copy of OSV

osv-mirror keeps a copy of the OSV database inside the deployment, drawn from OSV's public export for the ecosystems the repositories using it hold. A screen then reads that copy instead of asking OSV about each version, so screening needs no outbound call at fetch time and a scan costs no request per version. The copy follows OSV's change lists and is drawn whole again every seven days (osv-mirror-rebuild); osv-export points it at a mirror of the export.

Switching it on keeps nothing yet: a repository uses the copy only when its advisory-feeds names osv-mirror, and setting that at the deployment level names it for every repository. An ecosystem's first copy is its whole export - hundreds of megabytes for the largest - and until it lands, what it would screen is treated as a feed that cannot answer.

What a published version relies on

A version published into the repository is resolved to its closure: every package its declared dependencies reach, and theirs in turn, each the newest version the repository holds that its requirement admits. It is the set a build through this repository resolves. The closure is read from what the repository and the repositories its fallbacks name already hold, and nothing is fetched to make it, so a dependency the repository does not hold is listed as unresolved.

The closure is how a published version is screened. The version's page shows it under Resolved closure, with the versions it reaches that are held for review or carry findings, and the dependencies each is reached through. A new finding or hold on one of those copies reaches the versions relying on it within a pass, and a release or a withdrawn advisory clears it the same way. The signal is shown, not enforced: a published version is never held because something it relies on is vulnerable.

Setting Default What it does
closure-resolution true Resolves each version a repository publishes; a repository setting
closure-interval PT5M How long a new version waits to be resolved
closure-full-every 168 Every how many passes one revisits every published version, which is how a version published before resolution was on is resolved

The other direction is the Dependents page, under the repository's Provenance topic: for a package, or one version of it, the published versions of the tenant whose closure reaches it, each with the path it is reached along, and the versions in this repository whose manifest declares the package, with the requirement each states. On the command line, jenrepo closure <repo> <ecosystem> <coordinate> <version> prints a closure and jenrepo dependents <repo> <ecosystem> <coordinate> its dependents.

When a feed cannot answer

A repository's screening-mode says what the screen does when an advisory feed or a scanner cannot answer, and whether what it finds holds at all:

Mode What happens
Hold (HOLD, the default) An artifact the screen could not clear is held for review, with the outage named.
Admit (ADMIT) The artifact is decided by every check that could answer and served when they allow it, with the check that could not answer recorded among its reasons.
Record only (RECORD) Nothing is held for what the screen found or could not find; every finding is recorded and the artifact is served.

Record only is the mode to run while screening is rolled out over what a repository already serves: the findings pile up for review and no build breaks. The deny list refuses in every mode, and a hardened proxy screens strictly in every mode.

A copy served under Admit while a feed was down is screened again once the feed answers, every fifteen minutes by default (pending-rescreen-interval), and held then if the feed flags it.

Rules of your own

policy-rules takes one rule per line, each a verdict and an expression. The expression sees the artifact's ecosystem, coordinate, version, licences, advisories and their severity:

reject #severityRank >= 4
quarantine #ecosystem == "npm" and #advisoryCount > 0
quarantine !#licenses.?[#this matches "(?i).*agpl.*"].empty

Expressions are sandboxed - no method calls and no type references - and an empty setting switches the rules off.

Quarantine

Quarantine is the review queue: every version the gate is holding, with what it is held for - the rules that decided its holds, such as Deny list or Version held - the reasons beneath, and each of its held files. A reason only one file has, such as a missing signature, is shown beside that file. An editor answers each version, for all its files at once, since a jar is no use without its POM:

  • release publishes it into the repository, and clients can fetch it from then on;
  • discard drops it for good, after confirming - it cannot be released afterwards.

The API and jenrepo quarantine release or discard answer versions the same way: naming any one held file of a version acts on every held file of it.

A version is reviewed whole. While one of its files is held, a file arriving for the same version - a sources jar, another wheel - lands held with it, under the rule Version held, whatever the gate finds of that file alone; a file the gate refuses is still refused. The exception is a file that completes what its held siblings lacked, such as a POM or an ivy.xml declaring the licence its jar, sent first, was held without. It is admitted, so that its arrival can release them; once they have been assessed again, it is held with the version if the version is still held.

The queue pages through a backlog of any size. A hold placed by a module that has since been removed is still listed, marked as not installed, and can still be released.

Holding a version by hand

An editor can hold any version that serves, whatever the gate found of it: Hold beside it in its package's list of versions, or Hold for review on the version's own page. Every file of it stops serving until it is released, and the queue lists it as held for Held by an operator. A script holds a version by its ecosystem, coordinate and version:

curl -X POST -H "Jenesis-Repository-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"ecosystem":"Maven","coordinate":"org.acme:widget","version":"1.2.0"}' \
  'https://repo.example.com/api/quarantine/hold?repo=libraries'
jenrepo quarantine hold libraries Maven org.acme:widget 1.2.0

The answer, {"held":true} or {"held":false}, says whether anything was held: a version that serves no file holds nothing. The hold is audited as quarantine.hold, and is released or discarded like any other.

Refused

Refused lists what the gate turned away outright, most recent first: the coordinate, the verdict, the reasons and when. A refusal stores nothing, so there is nothing to release - this page is the record of a denied publish, and often the only one.

Vulnerabilities

Vulnerabilities lists the advisories that apply to the copies the repository cached from an upstream, from the last scan, and says when that scan ran. A version published here carries none of its own: what it relies on is on its page. A version whose findings reach vulnerability-risk-threshold, LOW by default, is marked as a risk on its package's list of versions and on its own page; what is held stays the vulnerability threshold's to decide. Rescan against the advisory feeds starts a fresh one in the background; the page shows it running and refreshes itself until it finishes. With no feed switched on, the page says so and links to the settings that change it.

Findings

Findings is the ledger every check writes into: one row per thing found about a package version - an advisory, a malicious-package record, a signature problem - filterable by coordinate, kind, source, category and severity. An editor can Confirm a finding or Dismiss it, and the decision is kept beside the finding for the next person who reads it.

Licenses

Licenses counts the licences declared by every version the repository holds, by category - the broad class a licence belongs to, such as permissive or copyleft - and by SPDX identifier, each with how many versions carry it. A version that declares nothing readable counts as unknown. The count is made on request rather than on every visit: Count now starts it in the background, the page shows it running and refreshes itself, and the result stays with the time it was counted until the next count - shown beside a new count while it runs, and after one that fails. Where the repository's full-text search is on, each row leads to the versions behind it; where it is off, the counts are all the page shows.

A declared licence is identified against a built-in table of about sixty SPDX licences, by its identifier or by the names and addresses it is published under - "Apache License, Version 2.0", gnu.org/licenses/gpl-3.0, and so on. Versions stay apart: GPL-2.0 and GPL-3.0 are two rows, and a GNU licence named without a version counts as the earliest version "or later". A name the table does not know counts as unknown. Licences of your own - an in-house licence, or one your packages name in a way the table does not - are added under License definitions (license-definitions), one per line: an identifier, a category, and the names and addresses it goes by:

Acme-Internal-1.0 | proprietary | Acme Internal License | https://acme.example/license

A row there is tried before the built-in table, its category may be a word of your own, and the gate's allow and deny lists and the counts here use it like any other. A search filter on a licence takes its exact identifier.

A script asks the same of GET /api/licenses?repo=<name>, which answers the stored count - its state (not-counted, running, done or failed), when it started and finished, and the counts - and starts a new one with refresh=true, carrying the last finished count as previous while a new one runs, and saying in its Jenesis-Refresh header whether this request started it or one was already running. jenrepo licenses <repo> --count --refresh starts a count and prints its progress until it lands.

Signers

Signers lists who signed the versions the gate accepted - each signer's OpenPGP key or certificate identity. Opening a signer lists everything it signed in this repository: the reach of a key you are about to stop trusting. Which signers are trusted is set in Settings: signature-trusted-keys for OpenPGP keys, signature-trusted-certificates for certificate chains, and signature-trusted-signers to pin a namespace to one signer.

The gate decides on the way in, and the scheduled scan keeps deciding afterwards. When a later scan finds a problem with something already served, it lands in Vulnerabilities and Findings, where it can be reviewed like anything the gate held on arrival.