gem-guardian

Gem Version CI Ruby Version License: MIT

Consumer-side integrity verification for Ruby gems.

gem-guardian audits Bundler checksum coverage, verifies .gem artifacts against RubyGems SHA256 data when needed, and can verify Trusted Publishing provenance for supported releases. It stays intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.

Why

RubyGems.org displays SHA256 checksums for published gem artifacts, Bundler 2.6 can store and enforce checksums in Gemfile.lock, and RubyGems now exposes attestation data for Trusted Publishing releases. That means the most useful current release is an audit and verification tool that tells you whether your bundle and release metadata are actually protected.

This 0.2.0 scope is:

Gemfile.lock
    ↓
CHECKSUMS coverage audit
    ↓
RubyGems.org checksum comparison when needed
    ↓
Trusted Publishing provenance verification when available
    ↓
Actionable report for CI or local review

This reports whether your lockfile is using Bundler checksum protection, whether any locked gems are missing expected checksum data, and whether RubyGems exposes Trusted Publishing provenance for the gem being verified. It does not yet prove source provenance for releases that do not publish attestation data.

Installation

From a local checkout:

gem build gem-guardian.gemspec
gem install ./gem-guardian-0.2.0.gem

Usage

Build and install the current release from a local checkout:

gem build gem-guardian.gemspec
gem install ./gem-guardian-0.2.0.gem
gem-guardian version

Show the built-in help:

gem-guardian help
gem-guardian --help

Prepare a locked project for checksum auditing:

bundle lock --add-checksums

Verify all gems in Gemfile.lock:

gem-guardian verify

Verify a specific gem version:

gem-guardian verify cdc-sidekiq:0.1.1
gem-guardian verify ratomic:0.4.1

Verify a platform gem:

gem-guardian verify nokogiri:1.18.9:x86_64-linux

Use a non-default lockfile:

gem-guardian verify --lockfile path/to/Gemfile.lock

Emit JSON for CI:

gem-guardian verify --json
gem-guardian verify --json --provenance

When you verify a lockfile that already contains Bundler CHECKSUMS, gem-guardian reports coverage and compares the locked checksum to the downloaded artifact. When a checksum is missing, it falls back to RubyGems.org metadata and marks that verification accordingly.

Use --provenance to inspect Trusted Publishing metadata when RubyGems exposes it. Unsupported gems are reported, but they do not fail the run unless the provenance data is present and mismatched.

Exit codes

  • 0 — all verified artifacts matched
  • 1 — mismatch, missing checksum, fetch error, or lockfile error
  • 2 — CLI usage error

MVP constraints

  • Audits Gemfile.lock for Bundler CHECKSUMS coverage.
  • Uses RubyGems.org as a fallback checksum source when the lockfile is incomplete or an explicit gem is supplied.
  • Downloads artifacts from RubyGems.org /downloads/<gem-file>.gem only when verification is needed.
  • Caches downloaded artifacts under the system temp directory.
  • Does not integrate into Bundler install hooks.
  • Does not yet verify Sigstore, SLSA, GitHub Actions provenance, or signed git tags.

Roadmap

  • GitHub Release checksum/signature discovery.
  • Signed tag and release attestation checks.

License

MIT

Code of Conduct

Everyone interacting in the Gem::Guardian project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.