How to Verify Package Provenance with SLSA Attestations

Advanced 25 minutes Security Engineers Security & Policy

Understand provenance statuses, create policies that require verified provenance, and interpret provenance data in the BOM.

Overview

SLSA (Supply-chain Levels for Software Artifacts) provenance attestations prove that a package was built from a specific source repository using a specific build process. Chainsaw automatically checks for Sigstore-based SLSA attestations on supported ecosystems and records the provenance status for every package.

Provenance verification answers: “Was this package actually built from the source code it claims?”

Prerequisites

  • Admin or Manager role in Chainsaw
  • Understanding of SLSA framework concepts
  • Packages from supported ecosystems flowing through the proxy

Step 1: Understand Provenance Statuses

Chainsaw assigns one of five provenance statuses to each package:

StatusMeaning
VerifiedValid SLSA attestation found and signature verified via Sigstore
UnverifiedAttestation found but signature verification failed
UnavailableEcosystem doesn’t support provenance attestations
MissingEcosystem supports provenance but this package has none
FailedError during provenance check (timeout, network issue)
Provenance status indicators
The five provenance statuses and what they mean for your supply chain

Step 2: Check Ecosystem Support

Provenance verification is currently supported for:

EcosystemSupportHow It Works
npmFullSigstore attestation verification
PyPIFullSigstore attestations
Maven / GradleFullSigstore + PGP signature verification; Gradle reuses the Maven checker
NuGetFullIn-file Sigstore detached signatures
RubyGemsFullIn-file detached PGP signatures
GoFullsum.golang.org transparency walk
Docker / OCIFullSigstore cosign signatures
Hugging FaceFullSigstore where published
APTFull (NEW)Clearsigned InRelease + hash-chain to the requested .deb; trust root via CHAINSAW_APT_KEYRING — see How to Detect Mirror Tampering with APT / Yum / DNF Hash-Chain
Yum / DNFFull (NEW)Detached repomd.xml.asc + hash-chain to the requested .rpm; trust root via CHAINSAW_RPM_KEYRING
SwiftConfigurableThree-tier: unavailable → signature-presence probe → full SE-0391 CMS verification. Set WithSwiftRegistryURL and optionally WithSwiftFullVerify
Cargo / Composer / CocoaPodsUnavailableNo standard attestation mechanism yet — pair with trustScoreMin and checksum enforcement
Provenance verification runs asynchronously after the initial sync checks. The status may update from “Missing” to “Verified” shortly after the first request for a package.

Step 3: Review Provenance in the Bill of Materials

Navigate to Bill of Materials. The Provenance Status column shows the verification result for each package.

BOM page with provenance status column
Provenance status is tracked for every package in your Bill of Materials

Click on a package with Verified status to see additional details:

  • Builder ID (e.g., https://github.com/actions/runner)
  • Attestation type
  • Source repository link
Provenance verification details
Verified packages show the builder ID and source repository

Step 4: Create a Provenance Requirement Policy

Navigate to Policies and click Create Policy.

Require Verified Provenance

  1. Name: Require Verified Provenance
  2. Action: Block
  3. Condition: Provenance Status → not verified
  4. Scope: npm and PyPI repositories only (where provenance is available)
Creating a provenance requirement policy
Block packages that lack verified SLSA provenance
Not all legitimate npm/PyPI packages have provenance attestations yet. Start with Quarantine instead of Block to assess impact before enforcing.

Gradual Rollout Strategy

  1. Week 1: Create a Quarantine policy and monitor which packages lack provenance
  2. Week 2: Create exceptions for legitimate packages without provenance
  3. Week 3: Switch from Quarantine to Block

Step 5: Monitor Provenance Impact on Trust Scores

Provenance verification contributes significantly to the composite trust score:

Provenance StatusTrust Score Impact
Verified+25 points
Unverified+0 points
Unavailable+0 points (not penalized)
Missing+0 points
Failed+0 points

A verified provenance is worth 25 points out of the possible 100, making it one of the most impactful trust score signals.

Trust score breakdown showing provenance impact
Provenance contributes up to 25 points to the trust score

Step 6: Investigate with Billy

Ask Billy to find packages lacking provenance in supported ecosystems:

"Show me npm packages with missing provenance in the last 30 days"

"What percentage of our PyPI packages have verified provenance?"
Billy answering a provenance query
Use Billy to analyze provenance coverage across your supply chain

Understanding the Provenance Check Flow

  1. Package request arrives at Chainsaw
  2. Sync checks run first (malware, typosquat, sync trust score)
  3. Package is served to the client
  4. Async enrichment kicks in (bounded worker pool, 20 concurrent workers)
  5. Provenance check queries the registry’s attestation endpoint (30s timeout)
  6. Result is stored in the metadata store
  7. Trust score is recomputed with the provenance signal
Because provenance runs asynchronously, the first request for a new package may show “Missing” provenance. Subsequent requests will reflect the verified status.

Next Steps