gem-guardian 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75caa51bf7916d1feb83062445a665ca34d89b8e476cf015355b5d86566dbb76
-  data.tar.gz: 4520cec08edf53406f26988cc5d48cd5794307fd12d59c4b661ee0e94dfc12db
+  metadata.gz: a18ee9f2f2111d0eca38def30302a7d66b9b6b9b96df06909f883be2978c1bcd
+  data.tar.gz: e6a421612c4c50423ef7fe29f74f2bc2503cb624b813befb114bc679940fcd5f
 SHA512:
-  metadata.gz: 15c736bf8890ca30c0fef05508b14ed85b75bcb660c14843773348fa0c413213f6b79ac2ad39bbdd9edf3cc00c62d3f23667529b0f9b3f1231001b6c3804f020
-  data.tar.gz: 5f50fc8de20b9691dc3ea84c9ef2eb542f4b58981552ee237ac1314e4860c7d47779dd078f29a936d632a6342b322237d73546dd139f8e6ddde94adadd8ff8b5
+  metadata.gz: 3577f45013b8bb9b94905e7f2c081501ef3b863f2913faee08a0604184e5181ed278bd75a57cee9f9d571d00395b26c3f666ab1c126abe251c88cc54f24cb8c3
+  data.tar.gz: faa68291c29be60c7b42d7cf1452dc8e5d29222ee8174e22ed7bbb6f913c5405a264555fe16c020e934d23863232aec74ee2befb537a7bb06192ab52d154bffb

data/.github/workflows/release.yml

@@ -25,7 +25,20 @@ jobs:
         with:
           ruby-version: "3.4"
           bundler-cache: true
+      - name: Build gem artifact
+        run: gem build gem-guardian.gemspec
+      - name: Generate checksum
+        run: |
+          gem_file=$(ls gem-guardian-*.gem)
+          shasum -a 256 "$gem_file" > "$gem_file.sha256"
       - name: Run tests
         run: bundle exec rake
       - name: Release gem to RubyGems.org
         uses: rubygems/release-gem@v1
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            gem-guardian-*.gem
+            gem-guardian-*.gem.sha256

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-12
+
+- Discover GitHub Release checksum and signature assets.
+- Verify signed Git tags and GitHub release attestations when provenance exposes a GitHub tag.
+- Fall back to version-derived release tags when RubyGems provenance exposes only a commit SHA.
+- Add GitHub release metadata to JSON and human-readable provenance output when available.
+- Package the new GitHub verifier classes into the released gem.
+
 ## [0.2.0] - 2026-06-12
 
 - Add `--json` output for CI-friendly verification reports.

data/README.md

@@ -8,7 +8,7 @@
 
 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.
+`gem-guardian` audits Bundler checksum coverage, verifies `.gem` artifacts against RubyGems SHA256 data when needed, and can verify Trusted Publishing provenance for supported releases, including GitHub release checksum/signature discovery and signed-tag attestation checks when the release data exposes them. It stays intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
 
 ## Why
 
@@ -28,7 +28,7 @@ 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.
+This reports whether your lockfile is using Bundler checksum protection, whether any locked gems are missing expected checksum data, whether RubyGems exposes Trusted Publishing provenance for the gem being verified, and whether GitHub release assets and tag attestations are available for the release being inspected.
 
 ## Installation
 
@@ -111,12 +111,11 @@ Use `--provenance` to inspect Trusted Publishing metadata when RubyGems exposes
 - 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.
+- GitHub Release checksum/signature discovery and signed tag/release attestation checks are supported when the release metadata is available.
 
 ## Roadmap
 
-- GitHub Release checksum/signature discovery.
-- Signed tag and release attestation checks.
+- Expand release provenance checks to additional publishing workflows beyond GitHub release provenance.
 
 
 ## License

data/gem-guardian.gemspec

@@ -24,7 +24,9 @@ Gem::Specification.new do |spec|
   }
 
   spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
+    tracked_files = `git ls-files -z`.split("\x0")
+    source_files = Dir["lib/**/*", "exe/*", "README.md", "LICENSE.txt", "CHANGELOG.md"]
+    (tracked_files + source_files).uniq.reject do |f|
       f.match(%r{\A(?:test|spec|features)/})
     end
   rescue StandardError

data/lib/gem/guardian/github_client.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Gem
+  module Guardian
+    # Reads GitHub release and tag metadata for provenance checks.
+    class GitHubClient
+      # Default GitHub API endpoint used by the client.
+      DEFAULT_HOST = "https://api.github.com"
+
+      def initialize(host: DEFAULT_HOST, http: Net::HTTP)
+        @host = host.delete_suffix("/")
+        @http = http
+      end
+
+      # Returns the release payload for +repository+ and +tag+.
+      def release(repository, tag)
+        fetch_json("/repos/#{repository}/releases/tags/#{tag}")
+      rescue StandardError
+        nil
+      end
+
+      # Returns the tag verification payload for +repository+ and +tag+.
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def tag_verification(repository, tag)
+        ref = fetch_json("/repos/#{repository}/git/ref/tags/#{tag}")
+        return unless ref.is_a?(Hash)
+
+        object = ref["object"]
+        return unless object.is_a?(Hash)
+        return object["verification"] if object["type"] == "tag" && object["verification"].is_a?(Hash)
+
+        commit = fetch_json("/repos/#{repository}/commits/#{object["sha"]}")
+        commit.is_a?(Hash) ? commit["commit"]&.fetch("verification", nil) : nil
+      rescue StandardError
+        nil
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      private
+
+      def fetch_json(path)
+        JSON.parse(get(path))
+      end
+
+      def get(path)
+        uri = URI("#{@host}#{path}")
+        response = @http.get_response(uri)
+        return response.body if response.is_a?(Net::HTTPSuccess)
+
+        raise Error, "GET #{uri} failed with #{response.code} #{response.message}"
+      end
+    end
+  end
+end

data/lib/gem/guardian/github_release_verifier.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Result object for GitHub release provenance checks.
+    GitHubReleaseResult = Data.define(
+      :dependency, :status, :repository, :tag, :checksum_assets, :signature_assets, :signed_tag,
+      :signed_tag_reason, :release_attestation, :release_url, :error
+    ) do
+      # Returns true when the GitHub release checks succeeded.
+      def verified?
+        status == :verified
+      end
+    end
+
+    # Verifies GitHub release checksum, signature, and attestation metadata.
+    # rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
+    class GitHubReleaseVerifier
+      def initialize(client: GitHubClient.new)
+        @client = client
+      end
+
+      # Verifies GitHub release metadata for +provenance+.
+      # rubocop:disable Metrics/AbcSize
+      def verify(provenance)
+        repository = github_repository(provenance.repository)
+        tag_candidates = github_tag_candidates(provenance)
+        return unsupported_result(provenance, repository, tag_candidates.first) unless repository && tag_candidates.any?
+
+        release, tag = release_for(repository, tag_candidates)
+        return unsupported_result(provenance, repository, tag) unless release
+
+        checksum_assets = discovered_assets(release, checksum_asset_name?)
+        signature_assets = discovered_assets(release, signature_asset_name?)
+        tag_verification = @client.tag_verification(repository, tag)
+        build_release_result(provenance, repository, tag, checksum_assets, signature_assets, tag_verification, release)
+      rescue StandardError => e
+        error_result(provenance, repository, tag, e)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def release_for(repository, tag_candidates)
+        tag_candidates.each do |candidate|
+          release = @client.release(repository, candidate)
+          return [release, candidate] if release
+        end
+
+        [nil, tag_candidates.first]
+      end
+
+      def build_release_result(provenance, repository, tag, checksum_assets, signature_assets, tag_verification,
+                               release)
+        signed_tag = signed_tag?(tag_verification)
+        attestation = release_attestation(release)
+        status = release_status(signed_tag, attestation, tag_verification)
+        GitHubReleaseResult.new(
+          dependency: provenance.dependency,
+          status: status,
+          repository:,
+          tag:,
+          checksum_assets:,
+          signature_assets:,
+          signed_tag:,
+          signed_tag_reason: verification_reason(tag_verification),
+          release_attestation: attestation,
+          release_url: release["html_url"],
+          error: nil
+        )
+      end
+
+      def unsupported_result(provenance, repository, tag)
+        GitHubReleaseResult.new(
+          dependency: provenance.dependency,
+          status: :unsupported,
+          repository: repository,
+          tag: tag,
+          checksum_assets: [],
+          signature_assets: [],
+          signed_tag: nil,
+          signed_tag_reason: nil,
+          release_attestation: nil,
+          release_url: nil,
+          error: nil
+        )
+      end
+
+      def error_result(provenance, repository, tag, error)
+        GitHubReleaseResult.new(
+          dependency: provenance.dependency,
+          status: :error,
+          repository: repository,
+          tag: tag,
+          checksum_assets: [],
+          signature_assets: [],
+          signed_tag: nil,
+          signed_tag_reason: nil,
+          release_attestation: nil,
+          release_url: nil,
+          error: error
+        )
+      end
+
+      def github_repository(repository)
+        return if repository.nil?
+
+        value = repository.to_s
+        return unless value.match?(%r{\Ahttps://github\.com/[^/]+/[^/]+\z}) || value.match?(%r{\A[^/]+/[^/]+\z})
+
+        value.delete_prefix("https://github.com/")
+      end
+
+      def github_tag(provenance)
+        github_tag_candidates(provenance).first
+      end
+
+      def github_tag_candidates(provenance)
+        [
+          tag_from_ref(provenance.ref),
+          tag_from_subject(provenance.subject),
+          tag_from_version(provenance.dependency.version),
+          provenance.dependency.version.to_s
+        ].compact.uniq
+      end
+
+      def tag_from_ref(ref)
+        ref = ref.to_s
+        return unless ref.start_with?("refs/tags/")
+
+        ref.delete_prefix("refs/tags/")
+      end
+
+      def tag_from_subject(subject)
+        match = subject.to_s.match(%r{:ref:refs/tags/([^:]+)\z})
+        match && match[1]
+      end
+
+      def tag_from_version(version)
+        version = version.to_s
+        return if version.empty?
+
+        "v#{version}"
+      end
+
+      def discovered_assets(release, matcher)
+        Array(release["assets"]).filter_map do |asset|
+          name = asset.is_a?(Hash) ? asset["name"].to_s : asset.to_s
+          name if matcher.call(name)
+        end
+      end
+
+      def checksum_asset_name?
+        @checksum_asset_name ||= lambda do |name|
+          name.match?(/\.(?:sha256|sha256sum|checksum|checksums|sha)\z/i) ||
+            name.match?(/\ASHA256SUMS(?:\.txt)?\z/i) ||
+            name.match?(/\Achecksums(?:\.txt)?\z/i)
+        end
+      end
+
+      def signature_asset_name?
+        @signature_asset_name ||= lambda do |name|
+          name.match?(/\.(?:sig|asc)\z/i) || name.match?(/\.(?:bundle|intoto\.jsonl)\z/i)
+        end
+      end
+
+      def signed_tag?(verification)
+        return nil unless verification.is_a?(Hash)
+
+        verification["verified"] == true || verification["verified"].to_s.casecmp("true").zero?
+      end
+
+      def verification_reason(verification)
+        return unless verification.is_a?(Hash)
+
+        verification["reason"]
+      end
+
+      def release_attestation(release)
+        value = release["attestations"] || release["attestation"] || release["provenance"] ||
+                release["artifact_attestations"]
+        return nil if value.nil?
+
+        value.is_a?(TrueClass) || value.is_a?(FalseClass) ? value : true
+      end
+
+      def release_status(signed_tag, attestation, verification)
+        return :error if verification.is_a?(Hash) &&
+                         verification["verified"] == true &&
+                         verification["reason"] == "invalid"
+        return :verified if signed_tag == true && attestation == true
+        return :mismatch if signed_tag == false
+        return :mismatch if attestation == false
+
+        :unsupported
+      end
+    end
+    # rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
+  end
+end

data/lib/gem/guardian/provenance_verifier.rb

@@ -5,7 +5,7 @@ module Gem
     # Result object for a provenance verification attempt.
     ProvenanceResult = Data.define(
       :dependency, :status, :trusted_publishing, :repository, :ref, :workflow, :issuer, :subject,
-      :expected_sha256, :actual_sha256, :error, :attestation_url
+      :expected_sha256, :actual_sha256, :error, :attestation_url, :github_release
     ) do
       # Returns true when provenance verification succeeded.
       def verified?
@@ -15,8 +15,9 @@ module Gem
 
     # Verifies RubyGems Trusted Publishing provenance metadata.
     class ProvenanceVerifier
-      def initialize(client: RubygemsClient.new)
+      def initialize(client: RubygemsClient.new, github_release_verifier: GitHubReleaseVerifier.new)
         @client = client
+        @github_release_verifier = github_release_verifier
       end
 
       # Verifies Trusted Publishing provenance for +dependency+.
@@ -38,20 +39,21 @@ module Gem
 
       # rubocop:disable Metrics/MethodLength
       def build_result(dependency, provenance, artifact_sha256)
-        ProvenanceResult.new(**result_attributes(
-          dependency, provenance, artifact_sha256, provenance_status(provenance, artifact_sha256)
-        ))
+        github_release = github_release_result(provenance)
+        status = combine_status(provenance_status(provenance, artifact_sha256), github_release&.status)
+        ProvenanceResult.new(**result_attributes(dependency, provenance, artifact_sha256, status, github_release))
       end
 
       def unsupported_result(dependency)
-        ProvenanceResult.new(**result_attributes(dependency, nil, nil, :unsupported))
+        ProvenanceResult.new(**result_attributes(dependency, nil, nil, :unsupported, nil))
       end
 
       def error_result(dependency, artifact_sha256, error)
-        ProvenanceResult.new(**result_attributes(dependency, nil, artifact_sha256, :error, error))
+        ProvenanceResult.new(**result_attributes(dependency, nil, artifact_sha256, :error, nil, error))
       end
 
-      def result_attributes(dependency, provenance, artifact_sha256, status, error = nil)
+      # rubocop:disable Metrics/ParameterLists
+      def result_attributes(dependency, provenance, artifact_sha256, status, github_release = nil, error = nil)
         {
           dependency:,
           status:,
@@ -64,9 +66,11 @@ module Gem
           expected_sha256: provenance&.sha256,
           actual_sha256: artifact_sha256,
           error:,
-          attestation_url: provenance&.attestation_url
+          attestation_url: provenance&.attestation_url,
+          github_release:
         }
       end
+      # rubocop:enable Metrics/ParameterLists
       # rubocop:enable Metrics/MethodLength
 
       def provenance_status(provenance, artifact_sha256)
@@ -76,6 +80,19 @@ module Gem
         secure_compare(provenance.sha256, artifact_sha256) ? :verified : :mismatch
       end
 
+      def github_release_result(provenance)
+        @github_release_verifier.verify(provenance)
+      rescue StandardError
+        nil
+      end
+
+      def combine_status(provenance_status, github_release_status)
+        return github_release_status if %i[mismatch error].include?(github_release_status)
+        return provenance_status if github_release_status.nil? || github_release_status == :unsupported
+
+        provenance_status == :unsupported ? github_release_status : provenance_status
+      end
+
       def secure_compare(left, right)
         left = left.to_s
         right = right.to_s

data/lib/gem/guardian/report_builder.rb

@@ -55,7 +55,8 @@ module Gem
 
       def provenance_hash(result)
         provenance_fields(result).merge(
-          error: error_hash(result.error)
+          error: error_hash(result.error),
+          github_release: github_release_hash(result.github_release)
         )
       end
 
@@ -77,6 +78,26 @@ module Gem
       end
       # rubocop:enable Metrics/MethodLength
 
+      # Returns the GitHub release details for a provenance result.
+      # rubocop:disable Metrics/MethodLength
+      def github_release_hash(result)
+        return nil unless result
+
+        {
+          status: result.status,
+          repository: result.repository,
+          tag: result.tag,
+          checksum_assets: result.checksum_assets,
+          signature_assets: result.signature_assets,
+          signed_tag: result.signed_tag,
+          signed_tag_reason: result.signed_tag_reason,
+          release_attestation: result.release_attestation,
+          release_url: result.release_url,
+          error: error_hash(result.error)
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
       # Returns the checksum payload for a verification result.
       def checksum_hash(result)
         {

data/lib/gem/guardian/result_printer.rb

@@ -83,6 +83,7 @@ module Gem
         provenance_fields(result).each do |label_name, value|
           @stdout.puts format_provenance_field(label_name, value) if value
         end
+        print_github_release_result(result.github_release) if result.github_release
       end
 
       # Prints a provenance checksum mismatch.
@@ -140,6 +141,31 @@ module Gem
         ]
       end
 
+      # Returns the GitHub release fields to render for a provenance result.
+      # rubocop:disable Metrics/MethodLength
+      def github_release_fields(result)
+        [
+          ["github release", result.status],
+          ["release repo", result.repository],
+          ["release tag", result.tag],
+          ["checksum assets", result.checksum_assets.join(", ")],
+          ["signature assets", result.signature_assets.join(", ")],
+          ["signed tag", result.signed_tag],
+          ["tag reason", result.signed_tag_reason],
+          ["attestation", result.release_attestation],
+          ["release url", result.release_url]
+        ]
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Prints a GitHub release provenance result.
+      def print_github_release_result(result)
+        @stdout.puts "GITHUB RELEASE #{result.status.to_s.upcase}"
+        github_release_fields(result).each do |label_name, value|
+          @stdout.puts format_provenance_field(label_name, value) if value
+        end
+      end
+
       # Formats one provenance field line.
       def format_provenance_field(label, value)
         format("%<label>11s %<value>s", label:, value:)

data/lib/gem/guardian/rubygems_client.rb

@@ -15,10 +15,15 @@ module Gem
         :trusted_publishing, :repository, :ref, :workflow, :issuer, :subject, :sha256, :attestation_url
       )
 
+      # Matches the `Source Commit` field on the RubyGems provenance page.
       SOURCE_COMMIT_PATTERN = %r{Source Commit\s+([A-Za-z0-9._/-]+@[A-Za-z0-9._-]+)}i
+      # Matches the `Build File` field on the RubyGems provenance page.
       BUILD_FILE_PATTERN = /Build File\s+([^\s]+)/i
+      # Matches the transparency log URL shown on the RubyGems provenance page.
       LOG_ENTRY_PATTERN = %r{transparency log entry\s*(https?://[^\s]+)}i
+      # Matches the SHA256 checksum shown on the RubyGems provenance page.
       SHA256_PATTERN = /SHA 256 checksum\s*([a-f0-9]{64})/i
+      # Matches the provenance workflow label shown on the RubyGems provenance page.
       WORKFLOW_PATTERN = /
         Built and signed on\s+
         ([A-Za-z0-9 ._-]+?)

data/lib/gem/guardian/version.rb

@@ -3,6 +3,6 @@
 module Gem
   module Guardian
     # gem-guardian version.
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/gem/guardian.rb

@@ -10,6 +10,8 @@ require_relative "guardian/checksum"
 require_relative "guardian/dependency"
 require_relative "guardian/lockfile_parser"
 require_relative "guardian/rubygems_client"
+require_relative "guardian/github_client"
+require_relative "guardian/github_release_verifier"
 require_relative "guardian/artifact_store"
 require_relative "guardian/verifier"
 require_relative "guardian/provenance_verifier"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-guardian
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kenneth Demanawa
@@ -43,6 +43,8 @@ files:
 - lib/gem/guardian/cli.rb
 - lib/gem/guardian/dependency.rb
 - lib/gem/guardian/error.rb
+- lib/gem/guardian/github_client.rb
+- lib/gem/guardian/github_release_verifier.rb
 - lib/gem/guardian/lockfile_parser.rb
 - lib/gem/guardian/provenance_verifier.rb
 - lib/gem/guardian/report_builder.rb