Skip to content

verify-provenance.md

Latest commit

 

History

History
100 lines (72 loc) · 4.9 KB

verify-provenance.md

File metadata and controls

100 lines (72 loc) · 4.9 KB
Raw
title Verify SLSA provenance on a @hulumi/* tarball
description Confirm a published @hulumi/* tarball was built from this repo's HEAD by GitHub Actions, before installing it.

Verify SLSA provenance on a @hulumi/* tarball

When to use this recipe

Your supply-chain policy requires you to verify provenance before consuming third-party packages. From v1.0 every @hulumi/* package publishes with "provenance": true via npm trusted publishing (OIDC-backed; no NPM_TOKEN long-lived credential lives in this repo). Current releases are attested by the reusable .github/workflows/sign-and-publish.yml workflow; you can verify the SLSA Build L3 attestation locally with gh attestation verify.

Preconditions

  • GitHub CLI gh ≥ 2.49 (the version that ships gh attestation verify).
  • A signed-in gh auth login session against the kerberosmansour/hulumi repo's read-permitted user (the repo is public, so any logged-in user works).
  • npm CLI installed and able to fetch from the public registry.

Steps

1. Pack the tarball locally without installing it

npm pack @hulumi/baseline@1.3.2 --pack-destination /tmp --json
# -> [{"filename":"hulumi-baseline-1.3.2.tgz","files":[...]}]

Repeat for every @hulumi/* package you intend to install. The release:verify-attestations script in the root package.json does all six published packages in one shot:

pnpm run release:verify-attestations

2. Verify the attestation against the canonical repo

gh attestation verify /tmp/hulumi-baseline-1.3.2.tgz --repo kerberosmansour/hulumi

Expected output (paraphrased):

Loaded digest sha256:... for file:///tmp/hulumi-baseline-1.3.2.tgz
Loaded 1 attestation from GitHub API
✓ Verification succeeded!
The attestation was generated by https://github.com/kerberosmansour/hulumi
The attestation was generated for sha256:…
The attestation was generated by workflow .github/workflows/sign-and-publish.yml@<sha>

If verification fails, stop. A failed verification means either:

  • The tarball was tampered with after publish (treat as compromise; don't install).
  • The package was published from a fork or a non-canonical workflow (open an issue; see SECURITY.md for typosquat reporting).
  • Your gh session is signed into a user without read access to the repo's attestations API.

3. Pin the verified version in your package.json

{
  "dependencies": {
    "@hulumi/baseline": "1.3.2",
    "@hulumi/policies": "1.3.2",
    "@hulumi/drift": "1.3.2",
    "@hulumi/k8s-baseline": "1.3.2",
    "@hulumi/cloudflare-baseline": "1.3.2",
    "@hulumi/platform-patterns": "1.3.2"
  }
}

For deeper supply-chain discipline, capture the pnpm-lock.yaml integrity hash as the source of truth — that pins exact bytes, not just version labels. The Hulumi repo itself does this for @pulumi/* via scripts/exact-pin-guard.mjs; you can extend the same pattern in your own consumer repo.

Verify

  • gh attestation verify returns Verification succeeded! for each package you intend to install.
  • The attesting workflow path is .github/workflows/sign-and-publish.yml — anything else is suspicious for current releases.
  • The attesting repo is kerberosmansour/hulumi, not a fork.

Troubleshooting

gh attestation verify complains about a missing PEM bundle. Older gh versions don't ship attestation. Upgrade: brew upgrade gh or grab a newer release from https://github.com/cli/cli/releases.

Tarball SHA doesn't match what npm pack produced. npm pack is deterministic on a given Node + npm version pair. If you're packing on a different Node major than the publish workflow used, the in-tarball line endings / metadata can differ. Re-run on Node 22.14.0 to match the release signing workflow's setup-node config.

You forked the repo and want to verify your fork's attestations. Pass --repo <your-fork> instead of kerberosmansour/hulumi. Note that npm trusted publishing only works from the canonical repo by default — forks need their own npm package and trusted publisher set up.

You want to verify in CI before install. Wrap gh attestation verify in your CI's prerequisites. The Hulumi repo runs its own release-shape BDD and dry-run attestation checks in CI — that's the upstream provenance gate, but consumer-side verification is independent.

See also