Trigon

Package registries ship artifacts: a .tgz on npm, a wheel on PyPI, a .crate, a .nupkg. Reviewers read source: the repository on GitHub. The registry does not check one against the other.

Attackers use that gap at build time. A malicious publisher, or an attacker on the build machine, can ship something the source never contained. In event-stream, ua-parser-js and the xz backdoor, the malicious code sat in the published artifact, outside the repository anyone was reading.

Trusted publishing and SLSA provenance record which workflow, in which repository, at which commit, produced an artifact. They do not show that the artifact corresponds to the source at that commit: a compromised workflow or a malicious build script still produces valid provenance. To find the source, Trigon reads the commit a package records about itself where it has one: npm’s gitHead, the <repository> commit in a .nupkg, a crate’s .cargo_vcs_info.json. Then it rebuilds to check the correspondence. Reading trusted-publishing and SLSA provenance is designed (docs/06 §5) and not built.

The judgement half links no network client, no async runtime and no model code. cargo run -p xtask -- policy fails the build if that changes, and the verifier build, cargo build -p trigon --no-default-features, contains only this half. Its line coverage is 88.4% whether or not the tests that need a network run, so tests that open no socket reach every line the suite covers there.

Trigon signs in a separate step, on purpose: trigon rebuild runs a stranger’s build scripts, so the key belongs to another process. trigon attest reads the stored bytes back by hash and re-derives the verdict before it signs. Trigon publishes a verdict only after a second, independent attempt agrees: on another machine, or on the same machine starting cold where the repository sets same_host_confirmation = true, as the end-to-end script does.

The script rebuilt pkg:npm/wrappy@1.0.2 at --egress mirror-only, confirmed it with a second, cold build, signed the verdict and published it to a local evidence repository. We ran the commands below against what it left in work/evidence-e2e/.

The build behind that verdict could reach the mirror and nothing else. Its network transcript lists the 403 responses that crossed into the build, each with its URL and SHA-256: 178 index requests, 224 package tarballs from registry.npmjs.org and one Node.js toolchain download. The mirror withheld 3,695 versions that did not yet exist when the publisher released wrappy 1.0.2. The source was github.com/npm/wrappy at commit 71d91b6d, the commit npm’s own gitHead names.

A consumer who trusts the evidence repository looks the package up in a verified local clone:

Signed statements

trigon attest signs in-toto statements in DSSE envelopes, in a process that runs no build and opens no socket. It fetches both artifacts from the store by hash, recomputes the comparison, and refuses to sign if the answer differs from the run’s record. For a run the publication gate calls void (its guard tripped, it ran at open egress, or a stabilizer somebody wrote fired), it signs void/v1 and nothing else, which says why and never which way the comparison went. For any other run it signs equivalence/v2 or divergence/v2, beside rebuild/v1 and buildobservation/v1.

A repository with an append-only log

trigon publish asks the publication gate about each run and writes what it allows to a git repository: the signed records, the evidence needed to re-derive each one, an index, and an append-only log whose checkpoint trigon log sign signs. It makes one commit per publication and never force-pushes. Nobody edits a published record: to correct one, you publish a new record that supersedes it, and both stay in the log.

Checking a lockfile

A consumer trusts a repository once, by pinning its log key and its attestation key. trigon evidence sync verifies each clone whole, and refuses a checkpoint that does not extend the one it accepted before. After that, trigon check answers every package in a lockfile from the clone, with no request per package, so no server learns which packages you asked about. It reads package-lock.json, npm-shrinkwrap.json, requirements.txt and SPDX JSON.

A package no source holds a record for reads never checked, and never counts as a pass. The exit codes are for CI:

0

every package is at or above the threshold

1

a divergence

2

a package never checked, or withdrawn

3

a void, or a result below the threshold you set with --min or --max-risk

4

a deleted record, a record or source that failed verification, a required source that is unknown, or a package no source could answer

5

Trigon could not run the check

Checking a verdict yourself

Each published verdict carries the command that would falsify it. Run that command with the two artifacts and it re-derives the verdict from the bytes, then checks the published comparison report against it, member by member. If someone changes one byte of a record, verification fails, because no leaf of the log names it.

--lookup reads a synced clone and fetches the evidence it re-derives from, so it belongs to the full build. The network-free verifier build carries eight commands, and checks a record with --record <file> and --evidence <dir> instead. Its dependency tree holds no tokio, reqwest or hyper:

npm, PyPI, crates.io and NuGet have registry clients, so Trigon resolves, fetches and rebuilds their packages. The design covers RubyGems and GitHub releases, and they come next; until then Trigon refuses a target in either by name. trigon verify compares two files from any of them and chooses the stabilizer set from the file name. With the gem set it compares two .gem files, but Trigon cannot yet resolve or rebuild a gem. An npm tarball takes the generic tar-gzip set, because nothing inside a .tgz says whose it is; pass --profile npm-tarball to select the npm set.

Rates, with their corpus

The figures come from the M1 common-path corpus: 197 npm and 200 PyPI targets, which we stratified by build system rather than popularity and ran at --egress mirror-only. Reproduce counts the targets whose rebuild matched, out of those that reached a comparison. Reach counts the targets that got that far.

npm’s 76% spans 88% for packages with no lifecycle script down to 33% for monorepo members, and 3 of the 17 monorepo members reach a comparison. PyPI’s 83% spans 100% for flit and hatchling down to 54% for maturin and C extensions.

Sixteen of npm’s 65 targets that reached no comparison were our fault: a missing tool, a workspace: protocol npm does not speak, a workspace sibling the recipe did not build first. The reproduction rate leaves them out by design and the reach figure counts them, so read reach as a floor.

crates.io and NuGet have no rate, because neither has a stratified corpus yet. Both rebuild end to end at mirror-only. Of the twelve crates we have tried by hand, six reproduce, hashbrown@0.17.1 and serde@1.0.219 among them; each remaining divergence is the Cargo.toml manifest rewrite that backlog item B20 is about.

A rate describes the pipeline on one corpus. The strata are weighted by build system, not by how common each build system is, so neither total says how much of an ecosystem reproduces. docs/15-corpora.md argues why the strata matter more than the totals.

Then read Using Trigon, the task-oriented guide, starting with its section on what a verdict does not tell you.