Provenance Verification Workflows

This workflow is part of Supply Chain Auditing & Dependency Verification. Without cryptographic provenance gating, your pipeline implicitly trusts every registry package it resolves — a trust that a compromised maintainer account, a typosquatted package name, or a malicious mirror can silently violate. Provenance verification replaces that implicit trust with a verifiable, policy-enforced chain of evidence from source commit to deployed artifact.

Prerequisites

• Node.js ≥ 18 or equivalent runtime installed in CI
• cosign CLI ≥ 2.0 available on the CI runner (brew install cosign / go install github.com/sigstore/cosign/v2/cmd/cosign@latest)
• slsa-verifier CLI installed (go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest)
• OIDC token available from your CI provider (GitHub Actions, GitLab CI, or Google Cloud Build all issue these automatically)
• A package lockfile committed to version control (package-lock.json, pnpm-lock.yaml, or yarn.lock)
• OPA binary or a policy-aware CI action if you plan to use Rego policy rules
• Familiarity with how Automated SBOM Generation works, since SBOM output feeds directly into the verification steps below

Conceptual foundation

Provenance is the cryptographically verifiable record of an artifact’s origin: who built it, from which source revision, on which infrastructure, and when. The main standards in this space are:

• SLSA (Supply-chain Levels for Software Artifacts) — a graduated framework (Levels 1–4) that defines what provenance must contain and how tamper-resistant the build process must be. SLSA provenance is a signed DSSE (Dead Simple Signing Envelope) document that asserts buildType, builder.id, materials (source commits), and a digest of the produced artifact.
• Sigstore / Cosign — a keyless PKI model where short-lived signing certificates are issued against OIDC identity claims (e.g. a GitHub Actions workflow URL). Every signature is appended to the Rekor immutable transparency log, so any party can audit signing history without obtaining private keys.
• in-toto — a framework for expressing supply chain layouts: which steps must occur, which functionaries are authorised to perform them, and what links (signed step records) must be present. SLSA provenance is expressed as an in-toto statement.

The SLSA specification is maintained at https://slsa.dev/spec. The Sigstore project specification lives at https://docs.sigstore.dev.

The diagram below shows how these pieces fit together in a typical CI/CD pipeline:

Step 1 — Map the dependency tree and resolve lockfile metadata

Before any cryptographic check can run you need an exact, reproducible inventory of every resolved package, including transitive dependencies. Use Lockfile Mapping & Analysis to extract that inventory from your committed lockfile. Skipping this step means signature verification covers only direct dependencies and leaves the transitive graph unvalidated.

# npm: export the full resolved tree as JSON
npm ls --all --json > resolved-tree.json

# pnpm: include transitive depth
pnpm list --recursive --json > resolved-tree.json

Parse the output to collect each package’s resolved URL and integrity field (a sha512- SRI hash written by the package manager). The integrity field is your first provenance signal — a mismatch between the registry checksum and the lockfile hash is an early-warning indicator of tampering.

// extract-lockfile-integrity.mjs
import { readFileSync } from 'fs';

const lock = JSON.parse(readFileSync('package-lock.json', 'utf8'));
const packages = lock.packages ?? {};

for (const [name, meta] of Object.entries(packages)) {
  if (!name || !meta.integrity) continue;
  // sha512- prefix means the package manager already computed an SRI-compatible digest
  console.log(JSON.stringify({ name, version: meta.version, integrity: meta.integrity, resolved: meta.resolved }));
}

Expected output: one JSON line per package, each carrying an integrity value beginning with sha512-. Any package missing an integrity field must be flagged for manual review before proceeding.

Step 2 — Generate an SBOM and attach component identities

An SBOM produced by Automated SBOM Generation converts the flat lockfile inventory into a structured document with Package URL (purl) identifiers, license metadata, and supplier information. Feed the SBOM into your verification engine as the authoritative component list.

# CycloneDX SBOM for a Node.js project
npx @cyclonedx/cyclonedx-npm --output-file sbom.cdx.json --output-format JSON

# Verify the SBOM is well-formed
npx @cyclonedx/cyclonedx-cli validate --input-file sbom.cdx.json --input-format JSON

The purl for each component (e.g. pkg:npm/[email protected]) is the stable identifier you carry forward into signature lookups. CycloneDX v1.5+ supports an attestations array in the metadata block — populate this once signatures are verified in Step 3 to produce a single attestation-enriched SBOM artifact that auditors and policy engines can consume.

Step 3 — Verify Sigstore signatures and SLSA provenance

This is the cryptographic core of the workflow. For each npm package that publishes Sigstore attestations (all packages generated with npm publish --provenance since npm 9.5), verify the attestation bundle against the Rekor transparency log.

The detailed mechanics of npm-specific Sigstore verification are covered in Verifying Sigstore Provenance for npm Packages.

Verifying an npm provenance attestation with the npm CLI:

# npm 9.5+ — built-in provenance check
npm audit signatures

# Example passing output:
# audited 312 packages in 4s
# 287 packages have verified registry signatures
# 25 packages have unverified registry signatures — investigate before deploying

Verifying a SLSA provenance bundle for a built artifact:

slsa-verifier verify-artifact \
  --provenance-path provenance.intoto.jsonl \
  --source-uri github.com/your-org/your-repo \
  --source-tag v2.1.0 \
  dist/app.tar.gz

A successful run prints PASSED: Verified SLSA provenance. A failure exits non-zero and prints the specific mismatch — treat non-zero exits as hard CI failures, not warnings.

Verifying a Cosign blob signature (keyless):

cosign verify-blob \
  --certificate-identity-regexp="^https://github.com/your-org/your-repo/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --signature=artifact.sig \
  --certificate=artifact.pem \
  dist/app.tar.gz

The --certificate-identity-regexp anchors the identity to a specific organisation path. Without this constraint any GitHub Actions workflow in any repo could produce a signature that passes the OIDC issuer check — the regexp is a security-critical argument, not a convenience option.

Step 4 — Enforce policy with OPA/Rego

Raw signature verification answers “is this signature valid?” but not “does this artifact meet our security policy?”. Express your constraints as Rego rules so they are auditable, version-controlled, and testable:

# policy/provenance.rego
package provenance

import future.keywords.if
import future.keywords.in

# Allow only artifacts signed by our GitHub Actions org
default allow := false

allow if {
  some attestation in input.attestations
  attestation.issuer == "https://token.actions.githubusercontent.com"
  startswith(attestation.subject, "https://github.com/your-org/")
  attestation.timestamp_ns > time.now_ns() - (90 * 24 * 60 * 60 * 1000000000)
}

deny contains msg if {
  not allow
  msg := sprintf("attestation rejected: issuer=%v subject=%v", [
    input.attestations[0].issuer,
    input.attestations[0].subject
  ])
}

# Evaluate at CI time
opa eval \
  --data policy/provenance.rego \
  --input attestation-bundle.json \
  --format pretty \
  "data.provenance.deny"

# CI step fails if deny set is non-empty

Policy rules should be pinned in a separate policy/ directory, reviewed in the same PR workflow as application code, and tested with opa test against fixture bundles covering both passing and failing cases.

Step 5 — Inject SRI hashes and propagate CSP headers

Provenance verification protects the build boundary. Subresource Integrity protects the browser fetch boundary. Once artifacts are verified, compute SHA-384 digests for every asset that will be loaded by the browser and inject them into your HTML templates before deployment.

// sri-inject.mjs — runs as a post-build step
import { createHash } from 'crypto';
import { readFileSync, readdirSync, statSync } from 'fs';
import { resolve, extname } from 'path';

function computeSRI(filePath) {
  const content = readFileSync(filePath);
  const digest = createHash('sha384').update(content).digest('base64');
  return `sha384-${digest}`;
}

const distDir = resolve('./dist');
const assets = readdirSync(distDir).filter(f =>
  ['.js', '.css'].includes(extname(f)) && statSync(resolve(distDir, f)).isFile()
);

const manifest = {};
for (const asset of assets) {
  manifest[asset] = computeSRI(resolve(distDir, asset));
  console.log(`${asset}: integrity="${manifest[asset]}"`);
}

// Write for use by your HTML template engine
import { writeFileSync } from 'fs';
writeFileSync('./dist/sri-manifest.json', JSON.stringify(manifest, null, 2));

This manifest feeds your server-side template engine or static site generator so that every <script> and <link> tag carries a correct integrity attribute. Pair this with Configuring Content-Security-Policy with SRI to enforce require-sri-for script style at the browser level.

Configuration reference

Integration with adjacent tooling

The output of each step feeds directly into the next:

1. Lockfile analysis (Step 1) produces a resolved component list with integrity hashes → feeds the SBOM generator.
2. SBOM (Step 2) assigns purl identifiers to every component → feeds the signature verification engine.
3. Signature + provenance verification (Step 3) produces a signed attestation bundle → feeds the OPA policy engine.
4. OPA policy evaluation (Step 4) gates the deployment and records a policy decision log → feeds the audit trail and compliance dashboards.
5. SRI injection (Step 5) produces a hash manifest → fed into HTML templates and Browser Enforcement & Security Boundaries at runtime.

For third-party scripts loaded from a CDN, the output of this pipeline also informs CDN Trust Mapping & Routing, where you map each CDN origin to an SRI policy.

Troubleshooting

Error: no matching signatures: none of the expected identities matched what was in the certificate The --certificate-identity-regexp pattern does not match the identity embedded in the signing certificate. Inspect the certificate with cosign verify-blob --output-file cosign-output.json ... and check the subject field. Common cause: the workflow was triggered by a fork where the path is your-org/your-repo but the cert records the fork’s path instead.

slsa-verifier: FAILED: builder identity: expected "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/..." mismatch The --builder-id implicit default expects the SLSA GitHub Generator reusable workflow. If you are using a different SLSA-conformant builder (e.g. actions/attest-build-provenance), pass --builder-id explicitly with the correct builder workflow URL.

npm audit signatures reports unverified registry signatures The package was published before npm 9.5 or the publisher did not pass --provenance. Check the registry entry at registry.npmjs.com/<package> for a dist.attestations field. If absent, pin to a specific version in the lockfile and add to a manual exception list in your policy, or replace with a provenance-publishing alternative.

opa eval returns a non-empty deny set on a valid artifact Most commonly caused by a stale timestamp_ns boundary. If the artifact was built more than 90 days ago and you are re-verifying it (e.g. from an artifact cache), adjust the policy window or re-sign with a fresh attestation. Do not extend the window permanently — rotate instead.

cosign verify-blob succeeds but the Rekor entry is missing If the --insecure-skip-verify flag was passed during signing, the entry was not logged to Rekor. This is a signing misconfiguration — re-sign without that flag. Production pipelines must never pass --insecure-skip-verify.

SRI hash mismatch in production after CDN delivery The CDN is transforming the asset (compression, minification, byte-order-mark injection). Hash computation must happen after all transformations. Run SRI injection as the final step before uploading to the CDN origin, not before. See Static Asset Hash Generation for build-time hash generation patterns.

Security boundary

Provenance verification confirms that an artifact was built by a specific pipeline from a specific source commit — it does not:

• Guarantee that the source code itself is free of malicious logic. A threat actor with repository write access can commit malicious code that passes all provenance checks because the provenance is technically valid.
• Protect against a compromised CI runner that has write access to the build environment. SLSA Level 3 raises the bar here (isolated, non-forgeable builds) but does not eliminate the risk entirely.
• Validate that npm package metadata (description, bin scripts, postinstall hooks) matches the provenance claim. Pair this workflow with Vulnerability Tracking & Triage and static analysis of install scripts.
• Replace network-level controls. An artifact that passes provenance verification can still be exfiltrated or tampered with in transit if HTTPS is not enforced end-to-end.
• Provide browser-level enforcement on its own. The SRI hash injected in Step 5 is what gives the browser the cryptographic signal it needs — provenance verification upstream is a prerequisite for trusting that hash is correct.

FAQ

Related

• Verifying Sigstore Provenance for npm Packages — step-by-step Sigstore attestation verification specific to the npm ecosystem
• Automated SBOM Generation — generate CycloneDX and SPDX inventories that feed the verification pipeline
• Lockfile Mapping & Analysis — extract precise version constraints and integrity hashes before provenance checks run
• Vulnerability Tracking & Triage — complement provenance gating with CVE-based risk scoring on verified components
• CDN Trust Mapping & Routing — extend provenance policy to third-party CDN origins using SRI enforcement