https://github.com/danielroe/provenance-action
Fail CI when dependencies in your lockfile lose npm provenance or trusted publisher status
https://github.com/danielroe/provenance-action
github-actions provenance security trusted-publishing
Last synced: 9 months ago
JSON representation
Fail CI when dependencies in your lockfile lose npm provenance or trusted publisher status
- Host: GitHub
- URL: https://github.com/danielroe/provenance-action
- Owner: danielroe
- License: mit
- Created: 2025-09-16T11:08:14.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-06T09:02:41.000Z (9 months ago)
- Last Synced: 2025-10-06T11:15:06.358Z (9 months ago)
- Topics: github-actions, provenance, security, trusted-publishing
- Language: TypeScript
- Homepage:
- Size: 380 KB
- Stars: 284
- Watchers: 1
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# `danielroe/provenance-action`
Fail CI when dependencies in your lockfile lose npm provenance or trusted publisher status.
> [!WARNING]
> This action is under active development and is only one tool to assist in securing your dependencies.
## ✨ Features
- supports `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock` (v1 and v2+), `bun.lock`
- handles transitives by comparing resolved versions
- inline GitHub annotations at the lockfile line
- JSON output and optional hard‑fail (default: on)
- pure TypeScript, Node 24+
👉 See it in action: [danielroe/provenance-action-test](https://github.com/danielroe/provenance-action-test)
## 🚀 Quick start
```yaml
name: ci
on:
pull_request:
branches:
- main
paths:
# Trigger a run only on PRs that change the lockfile
# (keep whichever is relevant and/or configure its path):
- pnpm-lock.yaml
- package-lock.json
- yarn.lock
- bun.lock
permissions:
contents: read
jobs:
check-provenance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Check provenance downgrades
uses: danielroe/provenance-action@main
id: check
with:
fail-on-provenance-change: true # optional, default: false
# lockfile: pnpm-lock.yaml # optional
# base-ref: origin/main # optional, default: origin/main
# fail-on-downgrade: true # optional, default: true
- name: Print result
run: "echo 'Downgraded: ${{ steps.check.outputs.downgraded }}'"
```
## 🔧 Inputs
- `lockfile` (optional): Path to the lockfile. Auto-detected if omitted.
- `workspace-path` (optional): Path to workspace root. Default: `.`
- `base-ref` (optional): Git ref to compare against. Default: `origin/main`.
- `fail-on-downgrade` (optional): Controls failure behavior. Accepts `true`, `false`, `any`, or `only-provenance-loss`. Default: `true` (which is the same as `any`).
- `fail-on-provenance-change` (optional): When `true`, fail on provenance repository/branch changes. Default: `false`.
## 📤 Outputs
- `downgraded`: JSON array of `{ name, from, to, downgradeType }` for detected downgrades. `downgradeType` is `provenance` or `trusted_publisher`.
- `changed`: JSON array of provenance change events `{ name, from, to, type, previousRepository?, newRepository?, previousBranch?, newBranch? }`.
## 🧠 How it works
1. Diffs your lockfile against the base ref and collects changed resolved versions (including transitives).
2. Checks npm provenance via the attestations API for each `name@version`.
3. Falls back to version metadata for `dist.attestations`.
4. Emits file+line annotations in the lockfile.
5. If provenance exists for both the previous and new version, extracts GitHub `owner/repo` and branch from attestations and warns when they differ (repo changed or branch changed).
## 🔒 Why this matters
Trusted publishing links a package back to its source repo and build workflow, providing strong provenance guarantees. It helps ensure the package you install corresponds to audited source and CI.
However, maintainers can still be phished or coerced into publishing without trusted publishing enabled, or switching to a non‑trusted path. In those cases, packages may still carry attestations, but the chain back to the trusted publisher can be weakened.
This action:
- Detects when a dependency update loses npm provenance (no attestations) or loses trusted publisher (attestations but no trusted publisher marker), and
- Fails CI by default (configurable), before that change lands in your main branch.
This is a stopgap until package managers enforce stronger policies natively. Until then, it offers a lightweight guardrail in CI.
## ⚠️ Notes
- Runs on Node 24+ and executes the TypeScript entrypoint directly.
- `bun.lockb` is not supported. (You can generate a `bun.lock` with `bun install --save-text-lockfile`.)
- Repository and branch change detection is best‑effort; attestation shapes vary and some packages omit repo/ref details.