{"id":51082982,"url":"https://github.com/kanutocd/gem-guardian","last_synced_at":"2026-06-23T20:00:53.390Z","repository":{"id":364183942,"uuid":"1266780704","full_name":"kanutocd/gem-guardian","owner":"kanutocd","description":"Consumer-side integrity verification for Ruby gems","archived":false,"fork":false,"pushed_at":"2026-06-21T08:00:29.000Z","size":187,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T08:12:44.362Z","etag":null,"topics":["artifact-verification","bundler","cli","dependency-management","developer-tools","devsecops","integrity-verification","provenance","ruby","rubygems","security-audit","sigstore","slsa","software-supply-chain","supply-chain-security","trusted-publishing"],"latest_commit_sha":null,"homepage":"https://kanutocd.github.io/gem-guardian/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kanutocd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T00:19:06.000Z","updated_at":"2026-06-21T07:58:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kanutocd/gem-guardian","commit_stats":null,"previous_names":["kanutocd/gem-guardian"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kanutocd/gem-guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Fgem-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Fgem-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Fgem-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Fgem-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanutocd","download_url":"https://codeload.github.com/kanutocd/gem-guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Fgem-guardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34704748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artifact-verification","bundler","cli","dependency-management","developer-tools","devsecops","integrity-verification","provenance","ruby","rubygems","security-audit","sigstore","slsa","software-supply-chain","supply-chain-security","trusted-publishing"],"created_at":"2026-06-23T20:00:52.401Z","updated_at":"2026-06-23T20:00:53.385Z","avatar_url":"https://github.com/kanutocd.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gem-guardian\n\n[![Gem Version](https://badge.fury.io/rb/gem-guardian.svg)](https://badge.fury.io/rb/gem-guardian)\n[![CI](https://github.com/kanutocd/gem-guardian/workflows/CI/badge.svg)](https://github.com/kanutocd/gem-guardian/actions)\n[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org/en/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nConsumer-side integrity and provenance verification for Ruby gems.\n\n`gem-guardian` audits Bundler checksum coverage, verifies `.gem` artifacts against lockfile and registry checksum sources, records artifact digests when no independent checksum exists, and reports Trusted Publishing provenance when the registry exposes it. It is intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.\n\n## Why\n\nRuby now has several useful supply-chain signals:\n\n- RubyGems.org exposes SHA256 checksums for published gem artifacts.\n- Bundler can store and enforce checksums in `Gemfile.lock`.\n- RubyGems exposes provenance metadata for gems published through Trusted Publishing.\n\nThe missing piece is consumer-side visibility.\n\n`gem-guardian` helps answer:\n\n```text\nDid the artifact match my lockfile checksum?\nDid it also match registry or publisher checksum metadata?\nWas only an artifact digest recorded?\nWas it published through Trusted Publishing?\nWhich repository, workflow, and commit produced it?\n```\n\n\n## Integrity model\n\n`gem-guardian` separates checksum sources from the downloaded artifact. The downloaded `.gem` is always hashed locally. A result is considered verified only when that artifact digest is compared with an independent expected digest.\n\n| Level | Required checks | Output | Meaning |\n| --- | --- | --- | --- |\n| Lockfile + registry + artifact | `lockfile SHA256 == registry SHA256 == artifact SHA256` | `PASS`, `source lockfile`, `registry ...` | Strongest path. The project lockfile and registry metadata agree with the downloaded artifact. |\n| Lockfile + artifact | `lockfile SHA256 == artifact SHA256` | `PASS`, `source lockfile` | Strong project-level verification. Works even when the registry does not expose checksum metadata. |\n| Registry + artifact | `registry SHA256 == artifact SHA256` | `PASS`, `source registry` | Registry-anchored verification for ad-hoc gem checks without a lockfile. |\n| Artifact only | `artifact SHA256` only | `RECORDED`, `source artifact` | Informational only. The artifact was hashed, but no independent checksum source was available. |\n\nVerification priority is:\n\n```text\nlockfile \u003e registry \u003e artifact\n```\n\n`RECORDED` is intentionally not called `PASS`: there is no independent checksum to compare against.\n\n## Real-world example\n\nAgainst a freshly generated Rails 8 application with lockfile checksums enabled:\n\n```bash\nbundle lock --add-checksums\ngem-guardian verify --provenance\n```\n\nObserved result:\n\n```text\nCHECKSUMS coverage: 142/142\n\nPROVENANCE PASS:        35\nPROVENANCE UNSUPPORTED: 107\n```\n\n| Signal | Coverage |\n| --- | ---: |\n| Bundler lockfile checksums | 142 / 142 (100%) |\n| Trusted Publishing provenance | 35 / 142 (24.6%) |\n| Provenance unavailable | 107 / 142 (75.4%) |\n\nThis illustrates the distinction between integrity and provenance:\n\n```text\nIntegrity:\n  Did I receive the expected artifact?\n\nProvenance:\n  Who built and published this artifact?\n```\n\nA dependency graph can have complete checksum coverage while still having limited provenance visibility.\n\n## Installation\n\nInstall from RubyGems:\n\n```bash\ngem install gem-guardian\n```\n\nOr build from a local checkout:\n\n```bash\ngem build gem-guardian.gemspec\ngem install ./gem-guardian-0.3.1.gem\n```\n\n## Quick start\n\nPrepare a Bundler project for checksum auditing:\n\n```bash\nbundle lock --add-checksums\n```\n\nVerify the lockfile:\n\n```bash\ngem-guardian verify\n```\n\nVerify integrity and provenance:\n\n```bash\ngem-guardian verify --provenance\n```\n\nEmit JSON for CI:\n\n```bash\ngem-guardian verify --json --provenance\n```\n\n## Usage\n\nShow help:\n\n```bash\ngem-guardian help\ngem-guardian --help\n```\n\nVerify a specific published gem:\n\n```bash\ngem-guardian verify rails:8.1.3\ngem-guardian verify cdc-sidekiq:0.1.1\ngem-guardian verify ratomic:0.4.1\n```\n\nVerify a platform-specific gem:\n\n```bash\ngem-guardian verify nokogiri:1.18.9:x86_64-linux\n```\n\nVerify all gems in a non-default lockfile:\n\n```bash\ngem-guardian verify --lockfile path/to/Gemfile.lock\n```\n\nVerify only selected gems from a lockfile:\n\n```bash\ngem-guardian verify --lockfile path/to/Gemfile.lock --provenance mammoth:0.1.1\ngem-guardian verify --lockfile path/to/Gemfile.lock --provenance nokogiri:1.18.9:x86_64-linux\n```\n\nWhen a platform is omitted in lockfile mode, `gem-guardian` matches every locked platform for that gem and version.\n\n## How verification works\n\n`gem-guardian` separates three integrity signals:\n\n1. **Lockfile checksum** — expected SHA256 comes from Bundler's `Gemfile.lock` `CHECKSUMS` section.\n2. **Registry or publisher checksum** — expected SHA256 comes from registry metadata or a configured checksum provider when available.\n3. **Artifact digest** — SHA256 is computed from the downloaded `.gem` file.\n\nThe artifact digest is always computed locally. Lockfile and registry/publisher checksums are independent trust anchors used for comparison.\n\n### Lockfile mode\n\n```bash\ngem-guardian verify --lockfile Gemfile.lock\n```\n\nIn lockfile mode, `gem-guardian` treats `Gemfile.lock` as the primary trust anchor:\n\n```text\nexpected SHA256 = Gemfile.lock CHECKSUMS\nactual SHA256   = downloaded .gem artifact\n```\n\nIf the registry also exposes a checksum, `gem-guardian` performs a stronger three-way check:\n\n```text\nlockfile SHA256 == registry SHA256 == artifact SHA256\n```\n\nThis mode is the preferred CI/CD path because Bundler has already recorded the expected artifact digest for the application. It is also registry-agnostic: the registry only needs to resolve and serve the artifact after the checksum has been committed to the lockfile.\n\nA successful lockfile-only verification reports:\n\n```text\nPASS cdc-orchestrator-pro 0.1.0 ruby\n     sha256 fa82bd6f...\n     source lockfile\n```\n\nIf a registry or publisher checksum is also available, the output includes the cross-check source:\n\n```text\nPASS cdc-sidekiq 0.1.1 ruby\n     sha256 d91d298d...\n     source lockfile\n     registry d91d298d...\n     provider rubygems-api\n     verify https://rubygems.org/api/v1/versions/cdc-sidekiq.json\n```\n\n### Explicit gem mode\n\n```bash\ngem-guardian verify GEM:VERSION[:PLATFORM]\n```\n\nIn explicit mode, there is no lockfile trust anchor. `gem-guardian` resolves the gem from the configured RubyGems source list, downloads the `.gem` artifact, computes its SHA256 digest, and then behaves as follows:\n\n```text\nIf registry or publisher checksum exists:\n  expected SHA256 = registry/publisher checksum\n  actual SHA256   = downloaded artifact checksum\n  result          = PASS or FAIL\n\nIf no independent checksum is available:\n  expected SHA256 = none\n  actual SHA256   = downloaded artifact checksum\n  result          = RECORDED\n```\n\n`RECORDED` means the artifact was found and hashed, but there was no independent checksum source to compare against. It is useful inventory data, not proof of integrity.\n\nExample with registry checksum support:\n\n```text\nPASS cdc-sidekiq 0.1.1 ruby\n     sha256 d91d298d...\n     source registry\n```\n\nExample without registry checksum support:\n\n```text\nRECORDED cdc-orchestrator-pro 0.1.0 ruby\n     sha256 fa82bd6f...\n     source artifact\n```\n\n### Checksum providers\n\nRegistry and publisher checksums are obtained through checksum providers. Built-in providers include:\n\n- `rubygems-api` — RubyGems.org-style versions API.\n- `compact-index` — RubyGems/Bundler compact index metadata when available.\n- `url` — publisher-controlled checksum files, useful for private or commercial gem distribution.\n\nProvider metadata is included in JSON output as:\n\n```json\n{\n  \"registry_sha256\": \"d91d298d...\",\n  \"registry_checksum_provider\": \"rubygems-api\",\n  \"registry_checksum_uri\": \"https://rubygems.org/api/v1/versions/cdc-sidekiq.json\"\n}\n```\n\nThe URL provider is intentionally generic so a publisher can expose a checksum file without implementing RubyGems.org's metadata API.\nA commercial or private registry can expose something like:\n\n```text\nhttps://example.com/checksums/{filename}.sha256\n```\n\nwith contents such as:\n\n```text\n\u003csha256\u003e  \u003cfilename\u003e\n```\n\n### Project configuration\n\nProject-level checksum providers can be declared in `.gem-guardian.yml`:\n\n```yaml\nchecksum_providers:\n  - name: awesome-gems-registry\n    source: https://gems.everything-is-awesome.com/\n    template: https://gems.everything-is-awesome.com/checksums/{filename}.sha256\n```\n\nThe `source` field scopes the provider to gems resolved from that registry, so a private checksum URL is not queried for unrelated public gems. The `template` field supports these placeholders:\n\n- `{name}`\n- `{version}`\n- `{platform}`\n- `{filename}`\n\nFor example, a locked `mammoth-pro` artifact named `mammoth-pro-1.0.0.gem` would resolve to:\n\n```text\nhttps://gems.everything-is-awesome.com/checksums/mammoth-pro-1.0.0.gem.sha256\n```\n\nThis lets private publishers integrate with gem-guardian without implementing the RubyGems.org versions API. When the checksum file is available, explicit mode can verify:\n\n```text\npublisher checksum == artifact checksum\n```\n\nand lockfile mode can perform the strongest path:\n\n```text\nlockfile checksum == publisher checksum == artifact checksum\n```\n\nSet `GEM_GUARDIAN_CONFIG=/path/to/config.yml` to load configuration from a non-default location.\n\n## Provenance mode\n\n```bash\ngem-guardian verify --provenance GEM:VERSION\ngem-guardian verify --lockfile Gemfile.lock --provenance\n```\n\nChecksum verification and provenance verification are related but separate. Checksums answer:\n\n```text\nDid the artifact bytes match an expected digest?\n```\n\nProvenance answers:\n\n```text\nWho built and published this artifact?\nWhich repository, workflow, and commit produced it?\n```\n\nWhen RubyGems exposes Trusted Publishing provenance, `gem-guardian` reports information such as:\n\n- repository\n- workflow\n- commit/ref\n- issuer\n- subject\n\nUnsupported provenance is reported as unsupported and does not fail the run. Provenance mismatches and verifier errors fail the run.\n\n## Private registries\n\n`gem-guardian` uses RubyGems' configured source list for source discovery. That means explicit and lockfile verification can work with RubyGems-compatible private registries such as GitHub Packages, Gemfury, CodeArtifact, Artifactory, or self-hosted gem servers when they are present in `gem sources`.\n\n```bash\ngem sources --list\ngem-guardian verify cdc-orchestrator-pro:0.1.0\n```\n\nPrivate registries vary in how much metadata they expose. Some expose enough metadata for registry-checksum verification. Others expose enough index data to resolve and download a gem, but do not expose an independent SHA256 checksum. Publishers can also provide checksums outside the registry through a configured checksum provider.\n\nIn explicit mode, that distinction is reflected in the result:\n\n```text\nPASS     source registry   # registry/publisher checksum matched artifact checksum\nRECORDED source artifact   # artifact was hashed, but no independent checksum was available\n```\n\nFor stronger verification of private gems, prefer lockfile mode after running:\n\n```bash\nbundle lock --add-checksums\n```\n\nOnce the checksum is recorded in `Gemfile.lock`, `gem-guardian` can verify the downloaded artifact against the lockfile checksum even if the registry does not expose checksum metadata later:\n\n```bash\ngem-guardian verify --lockfile Gemfile.lock cdc-orchestrator-pro:0.1.0\n```\n\n```text\nPASS cdc-orchestrator-pro 0.1.0 ruby\n     sha256 fa82bd6f...\n     source lockfile\nCHECKSUMS coverage: 1/1\n```\n\nIf the private registry or publisher also exposes a checksum, lockfile mode performs the stronger three-way comparison:\n\n```text\nlockfile SHA256 == registry SHA256 == artifact SHA256\n```\n\n## Registry audit research script\n\nThe repository includes an experimental registry audit script for ecosystem research:\n\n```bash\n./script/registry_provenance_audit.rb\n```\n\nBy default it inspects the RubyGems-compatible registries visible through `Gem.sources`.\n\nLimit the scan:\n\n```bash\nMAX_GEMS=100 ./script/registry_provenance_audit.rb\n```\n\nRestrict the scan to one source:\n\n```bash\nREGISTRY_SOURCE=https://rubygems.org/ MAX_GEMS=100 ./script/registry_provenance_audit.rb\n```\n\nThis script is intentionally separate from the main CLI. It is useful for answering questions such as:\n\n```text\nWhich gems visible from my configured registries expose Trusted Publishing provenance?\nWhich gems have checksum verification but no provenance metadata?\n```\n\n## CI/CD integration\n\nExample GitHub Actions steps:\n\n```yaml\n- name: Add Bundler checksums\n  run: bundle lock --add-checksums\n\n- name: Verify gem integrity and provenance\n  run: gem-guardian verify --json --provenance\n```\n\nThis can be used as a security job to:\n\n- verify Bundler checksum coverage\n- compare lockfile checksums with downloaded artifacts\n- cross-check registry or publisher checksums when available\n- detect artifact checksum mismatches\n- audit Trusted Publishing adoption\n- archive JSON results for later review\n\n## Exit codes\n\n- `0` — all required verification checks passed\n- `1` — mismatch, missing checksum, fetch error, provenance mismatch, or lockfile error\n- `2` — CLI usage error\n\n## Design constraints\n\n- Complements Bundler instead of replacing it.\n- Does not hook into `bundle install`.\n- Uses `Gemfile.lock` checksums as the preferred trust anchor.\n- Cross-checks registry or publisher checksums when available.\n- Records artifact digests only as informational data when no independent checksum exists.\n- Uses configured RubyGems sources for source discovery.\n- Keeps JSON output structured for CI consumers. (RubyGems fetcher noise in JSON mode is tracked separately.)\n- Treats unsupported provenance as visibility data, not as a failure.\n\n## Roadmap\n\n- Expand release provenance checks to additional publishing workflows beyond GitHub Trusted Publishing.\n- Add richer policy controls for CI enforcement.\n- Track provenance adoption over time using registry audit snapshots.\n\n## License\n\n[MIT](./LICENSE.txt)\n\n## Code of Conduct\n\nEveryone interacting in the Gem::Guardian project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kanutocd/gem-guardian/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanutocd%2Fgem-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanutocd%2Fgem-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanutocd%2Fgem-guardian/lists"}