npm-provenance-easy

Easily publish npm packages with provenance (SLSA attestations) and verify them.

Provenance (SLSA) ensures your npm package was built and published securely from the source you expect, reducing supply chain risks. It helps users trust that your published code matches your repository and build process.

• 🛠 Easy GitHub Actions workflow scaffolding for provenance-enabled publishing
• 🔍 One-command verification of provenance for any npm package
• 📊 Monorepo dashboard to check provenance status across all packages
• 📦 Optional SBOM generation (CycloneDX) for enhanced security
• 🎯 Strict verification mode to check SBOM and security metadata
• 🚀 GitHub release automation with changelogs
• ⚙️ Config file support for custom workflows and badges
• 🔄 Self-update checking to keep CLI current
• 🎨 Beautiful UI with spinners, colors, and interactive menus
• 🐚 Shell completion for bash, zsh, and fish
• 🎓 First-run onboarding for new users

npm i -D npm-provenance-easy

Or use directly with npx:

npx npm-provenance-easy --help

Run the CLI for an interactive setup experience:

npx npm-provenance-easy

npx npm-provenance-easy init

Features:

• Creates .github/workflows/release.yml for provenance-enabled publishing
• Optional SBOM generation - choose whether to include CycloneDX SBOM
• Monorepo detection - automatically detects pnpm/yarn workspaces
• GitHub release automation - optional automatic releases with changelogs
• Custom configuration - supports .provenancerc.json for advanced options
• Generates a badge for your README

✅ GitHub Actions workflow created at .github/workflows/release.yml
🧩 Monorepo detected (pnpm). Scaffolding monorepo-aware workflow.
📦 SBOM generation included.
📝 GitHub release automation included.
Add this badge to your README:
![npm-provenance](https://img.shields.io/badge/provenance-enabled-brightgreen)

Commit and push your code, then push a tag:

git add .
git commit -m "Release: provenance-enabled publish"
git tag v1.0.0
git push --tags

The workflow will:

• Build your project
• Generate SBOM (if enabled)
• Run npm publish --provenance --access public
• Create GitHub release (if enabled)

Check if a published npm package has provenance:

npx npm-provenance-easy verify <package>@<version>

Strict mode (check SBOM and security metadata):

npx npm-provenance-easy verify <package>@<version> --strict

Examples:

npx npm-provenance-easy verify react@18.2.0
npx npm-provenance-easy verify mylib@1.0.0 --strict

Check provenance status for all packages in your monorepo:

npx npm-provenance-easy dashboard

Shows:

• ✅ Provenance status for each package
• 📦 SBOM attachment status
• 📈 Summary statistics
• 💡 Recommendations for missing features

Keep your CLI up to date:

npx npm-provenance-easy update

Setup autocomplete for your shell:

# Show setup instructions
npx npm-provenance-easy completion

# Generate completion script
npx npm-provenance-easy completion bash
npx npm-provenance-easy completion zsh
npx npm-provenance-easy completion fish

Create .provenancerc.json for custom settings:

{
  "workflow": {
    "nodeVersion": "20",
    "includeReleases": true,
    "customSteps": [
      "- name: Custom step",
      "  run: echo 'Custom action'"
    ]
  },
  "badge": {
    "style": "flat-square",
    "color": "brightgreen",
    "label": "provenance",
    "message": "enabled"
  },
  "sbom": {
    "enabled": true,
    "format": "xml",
    "includeDevDeps": false
  },
  "monorepo": {
    "packages": ["@myorg/core", "@myorg/ui"],
    "publishStrategy": "all"
  }
}

name: Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - name: Generate SBOM (CycloneDX)
        run: npx @cyclonedx/cyclonedx-npm --output-format xml --output-file sbom.xml
      - name: Publish with provenance and attach SBOM
        run: npm publish --provenance --access public --sbom=sbom.xml || npm publish --provenance --access public
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref_name }}
          body: |
            ## What's Changed
            
            This release includes provenance-enabled packages with SBOM attachments.
            
            ### Security Features
            - ✅ SLSA Level 3+ provenance
            - 📦 CycloneDX SBOM attached
            - 🔒 Supply chain security verified
          draft: false
          prerelease: false

name: Monorepo Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ["@myorg/core", "@myorg/ui"]
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - name: Build all packages
        run: npm run build --workspaces
      - name: Generate SBOM (CycloneDX)
        run: npx @cyclonedx/cyclonedx-npm --output-format xml --output-file sbom.xml
      - name: Publish with provenance and attach SBOM
        run: npm publish --provenance --access public --workspaces --sbom=sbom.xml || npm publish --provenance --access public --workspaces
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref_name }}
          body: |
            ## What's Changed
            
            This release includes provenance-enabled packages with SBOM attachments.
            
            ### Security Features
            - ✅ SLSA Level 3+ provenance
            - 📦 CycloneDX SBOM attached
            - 🔒 Supply chain security verified
          draft: false
          prerelease: false

Add this to your README to show provenance support:

![npm-provenance](https://img.shields.io/badge/provenance-enabled-brightgreen)

Run without arguments for a beautiful interactive experience:

npx npm-provenance-easy

Features:

• 🎨 Colorful ASCII banner
• 📋 Interactive menu with all commands
• 🎯 Guided setup process
• 💡 Helpful suggestions and tips

• npm login required: Make sure you are logged in to npm before publishing.
• Workflow not running?: Ensure you push a tag (e.g., v1.0.0).
• Provenance not detected?: Check that your workflow uses npm publish --provenance.
• SBOM not attaching?: Ensure you have @cyclonedx/cyclonedx-npm installed.
• Monorepo issues?: Verify your workspace configuration (pnpm-workspace.yaml or package.json workspaces).

npx npm-provenance-easy verify mylib@1.0.0 --strict

Checks for:

• ✅ Provenance attestation
• 📦 SBOM attachment
• 🔒 Security audit metadata

npx npm-provenance-easy dashboard

Provides:

• 📊 Status overview for all packages
• 🎯 Actionable recommendations
• 📈 Progress tracking

Use .provenancerc.json to customize:

• Workflow templates
• Badge styles
• SBOM settings
• Monorepo strategies

PRs and issues welcome! See LICENSE.

MIT