attestation: add initial attestation helpers, integrate into brew install

Library/Homebrew/attestation.rb

@@ -0,0 +1,138 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "utils/popen"
+require "exceptions"
+
+module Homebrew
+  module Attestation
+    # @api private
+    HOMEBREW_CORE_REPO = "Homebrew/homebrew-core"
+    # @api private
+    HOMEBREW_CORE_CI_URI = "https://github.com/Homebrew/homebrew-core/.github/workflows/publish-commit-bottles.yml@refs/heads/master"
+
+    # @api private
+    BACKFILL_REPO = "trailofbits/homebrew-brew-verify"
+    # @api private
+    BACKFILL_REPO_CI_URI = "https://github.com/trailofbits/homebrew-brew-verify/.github/workflows/backfill_signatures.yml@refs/heads/main"
+
+    # No backfill attestations after this date are considered valid.
+    #
+    # This date is shortly after the backfill operation for homebrew-core
+    # completed, as can be seen here: <https://github.com/trailofbits/homebrew-brew-verify/attestations>.
+    #
+    # In effect, this means that, even if an attacker is able to compromise the backfill
+    # signing workflow, they will be unable to convince a verifier to accept their newer,
+    # malicious backfilled signatures.
+    #
+    # @api private
+    BACKFILL_CUTOFF = T.let(DateTime.new(2024, 3, 14).freeze, DateTime)
+
+    # Raised when attestation verification fails.
+    #
+    # @api private
+    class InvalidAttestationError < RuntimeError; end
+
+    # Returns a path to a suitable `gh` executable for attestation verification.
+    #
+    # @api private
+    sig { returns(Pathname) }
+    def self.gh_executable
+      # NOTE: We disable HOMEBREW_VERIFY_ATTESTATIONS when installing `gh` itself,
+      # to prevent a cycle during bootstrapping. This can eventually be resolved
+      # by vendoring a pure-Ruby Sigstore verifier client.
+      @gh_executable ||= T.let(with_env("HOMEBREW_VERIFY_ATTESTATIONS" => nil) do
+        ensure_executable!("gh")
+      end, T.nilable(Pathname))
+    end
+
+    # Verifies the given bottle against a cryptographic attestation of build provenance.
+    #
+    # The provenance is verified as originating from `signing_repo`, which is a `String`
+    # that should be formatted as a GitHub `owner/repo`.
+    #
+    # Callers may additionally pass in `signing_workflow`, which will scope the attestation
+    # down to an exact GitHub Actions workflow, in
+    # `https://github/OWNER/REPO/.github/workflows/WORKFLOW.yml@REF` format.
+    #
+    # @return [Hash] the JSON-decoded response.
+    # @raise [InvalidAttestationError] on any verification failures
+    #
+    # @api private
+    sig {
+      params(bottle: Bottle, signing_repo: String,
+             signing_workflow: T.nilable(String), subject: T.nilable(String)).returns(T::Hash[T.untyped, T.untyped])
+    }
+    def self.check_attestation(bottle, signing_repo, signing_workflow = nil, subject = nil)
+      cmd = [gh_executable, "attestation", "verify", bottle.cached_download, "--repo", signing_repo, "--format",
+             "json"]
+
+      cmd += ["--cert-identity", signing_workflow] if signing_workflow.present?
+
+      begin
+        output = Utils.safe_popen_read(*cmd)
+      rescue ErrorDuringExecution => e
+        raise InvalidAttestationError, "attestation verification failed: #{e}"
+      end
+
+      begin
+        attestations = JSON.parse(output)
+      rescue JSON::ParserError
+        raise InvalidAttestationError, "attestation verification returned malformed JSON"
+      end
+
+      # `gh attestation verify` returns a JSON array of one or more results,
+      # for all attestations that match the input's digest. We want to additionally
+      # filter these down to just the attestation whose subject matches the bottle's name.
+      subject = bottle.filename.to_s if subject.blank?
+      attestation = attestations.find do |a|
+        a.dig("verificationResult", "statement", "subject", 0, "name") == subject
+      end
+
+      raise InvalidAttestationError, "no attestation matches subject" if attestation.blank?
+
+      attestation
+    end
+
+    # Verifies the given bottle against a cryptographic attestation of build provenance
+    # from homebrew-core's CI, falling back on a "backfill" attestation for older bottles.
+    #
+    # This is a specialization of `check_attestation` for homebrew-core.
+    #
+    # @return [Hash] the JSON-decoded response
+    # @raise [InvalidAttestationError] on any verification failures
+    #
+    # @api private
+    sig { params(bottle: Bottle).returns(T::Hash[T.untyped, T.untyped]) }
+    def self.check_core_attestation(bottle)
+      begin
+        attestation = check_attestation bottle, HOMEBREW_CORE_REPO, HOMEBREW_CORE_CI_URI
+        return attestation
+      rescue InvalidAttestationError
+        odebug "falling back on backfilled attestation for #{bottle}"
+
+        # Our backfilled attestation is a little unique: the subject is not just the bottle
+        # filename, but also has the bottle's hosted URL hash prepended to it.
+        # This was originally unintentional, but has a virtuous side effect of further
+        # limiting domain separation on the backfilled signatures (by committing them to
+        # their original bottle URLs).
+        url_sha256 = Digest::SHA256.hexdigest(bottle.url)
+        subject = "#{url_sha256}--#{bottle.filename}"
+
+        backfill_attestation = check_attestation bottle, BACKFILL_REPO, BACKFILL_REPO_CI_URI, subject
+        timestamp = backfill_attestation.dig("verificationResult", "verifiedTimestamps",
+                                             0, "timestamp")
+
+        raise InvalidAttestationError, "backfill attestation is missing verified timestamp" if timestamp.nil?
+
+        if DateTime.parse(timestamp) > BACKFILL_CUTOFF
+          raise InvalidAttestationError, "backfill attestation post-dates cutoff"
+        end
+      end
+
+      backfill_attestation
+    end
+  end
+end

Library/Homebrew/env_config.rb

@@ -422,6 +422,11 @@ module EnvConfig
                      "useful to avoid long-running Homebrew commands being killed due to no output.",
         boolean:     true,
       },
+      HOMEBREW_VERIFY_ATTESTATIONS:              {
+        description: "If set, Homebrew will use the `gh` tool to verify cryptographic attestations " \
+                     "of build provenance for bottles from homebrew-core.",
+        boolean:     true,
+      },
       SUDO_ASKPASS:                              {
         description: "If set, pass the `-A` option when calling `sudo`(8).",
       },

Library/Homebrew/formula_installer.rb

@@ -22,6 +22,7 @@
 require "deprecate_disable"
 require "unlink"
 require "service"
+require "attestation"
 
 # Installer for a formula.
 #
@@ -1256,6 +1257,25 @@
 
   sig { void }
   def pour
+    if Homebrew::EnvConfig.verify_attestations? && formula.tap&.core_tap?
+      ohai "Verifying attestation for #{formula.name}"
+      begin
+        Homebrew::Attestation.check_core_attestation formula.bottle
+      rescue Homebrew::Attestation::InvalidAttestationError => e
+        raise CannotInstallFormulaError, <<~EOS
+          The bottle for #{formula.name} has an invalid build provenance attestation.
+
+          This may indicate that the bottle was not produced by the expected
+          tap, or was maliciously inserted into the expected tap's bottle
+          storage.
+
+          Additional context:
+
+          #{e}
+        EOS
+      end
+    end
+
     HOMEBREW_CELLAR.cd do
       downloader.stage
     end

Library/Homebrew/software_spec.rb

@@ -423,6 +423,11 @@ def tab_attributes
     github_packages_manifest_resource_tab(github_packages_manifest_resource)
   end
 
+  sig { returns(Filename) }
+  def filename
+    Filename.create(resource.owner, @tag, @spec.rebuild)
+  end
+
   private
 
   def github_packages_manifest_resource_tab(github_packages_manifest_resource)

Library/Homebrew/test/attestation_spec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "diagnostic"
+
+RSpec.describe Homebrew::Attestation do
+  let(:fake_gh) { Pathname.new("/extremely/fake/gh") }
+  let(:cached_download) { "/fake/cached/download" }
+  let(:fake_bottle_filename) { instance_double(Bottle::Filename, to_s: "fakebottle--1.0.faketag.bottle.tar.gz") }
+  let(:fake_bottle_url) { "https://example.com/#{fake_bottle_filename}" }
+  let(:fake_bottle) do
+    instance_double(Bottle, cached_download:, filename: fake_bottle_filename, url: fake_bottle_url)
+  end
+  let(:fake_json_resp) do
+    JSON.dump([
+      { verificationResult: {
+        verifiedTimestamps: [{ timestamp: "2024-03-13T00:00:00Z" }],
+        statement:          { subject: [{ name: fake_bottle_filename.to_s }] },
+      } },
+    ])
+  end
+  let(:fake_json_resp_backfill) do
+    JSON.dump([
+      { verificationResult: {
+        verifiedTimestamps: [{ timestamp: "2024-03-13T00:00:00Z" }],
+        statement:          {
+          subject: [{ name: "#{Digest::SHA256.hexdigest(fake_bottle_url)}--#{fake_bottle_filename}" }],
+        },
+      } },
+    ])
+  end
+  let(:fake_json_resp_too_new) do
+    JSON.dump([
+      { verificationResult: {
+        verifiedTimestamps: [{ timestamp: "2024-03-15T00:00:00Z" }],
+        statement:          { subject: [{ name: fake_bottle_filename.to_s }] },
+      } },
+    ])
+  end
+  let(:fake_json_resp_wrong_sub) do
+    JSON.dump([
+      { verificationResult: {
+        verifiedTimestamps: [{ timestamp: "2024-03-13T00:00:00Z" }],
+        statement:          { subject: [{ name: "wrong-subject.tar.gz" }] },
+      } },
+    ])
+  end
+
+  describe "::gh_executable" do
+    it "calls ensure_executable" do
+      expect(described_class).to receive(:ensure_executable!)
+        .with("gh")
+        .and_return(fake_gh)
+
+      described_class.gh_executable
+    end
+  end
+
+  describe "::check_attestation" do
+    before do
+      allow(described_class).to receive(:gh_executable)
+        .and_return(fake_gh)
+    end
+
+    it "raises when gh subprocess fails" do
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::HOMEBREW_CORE_REPO, "--format", "json")
+        .and_raise(ErrorDuringExecution.new(["foo"], status: 1))
+
+      expect do
+        described_class.check_attestation fake_bottle,
+                                          described_class::HOMEBREW_CORE_REPO
+      end.to raise_error(described_class::InvalidAttestationError)
+    end
+
+    it "raises when gh returns invalid JSON" do
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::HOMEBREW_CORE_REPO, "--format", "json")
+        .and_return("\"invalid json")
+
+      expect do
+        described_class.check_attestation fake_bottle,
+                                          described_class::HOMEBREW_CORE_REPO
+      end.to raise_error(described_class::InvalidAttestationError)
+    end
+
+    it "raises when gh returns other subjects" do
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::HOMEBREW_CORE_REPO, "--format", "json")
+        .and_return(fake_json_resp_wrong_sub)
+
+      expect do
+        described_class.check_attestation fake_bottle,
+                                          described_class::HOMEBREW_CORE_REPO
+      end.to raise_error(described_class::InvalidAttestationError)
+    end
+  end
+
+  describe "::check_core_attestation" do
+    before do
+      allow(described_class).to receive(:gh_executable)
+        .and_return(fake_gh)
+    end
+
+    it "calls gh with args for homebrew-core" do
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::HOMEBREW_CORE_REPO, "--format", "json", "--cert-identity",
+              described_class::HOMEBREW_CORE_CI_URI)
+        .and_return(fake_json_resp)
+
+      described_class.check_core_attestation fake_bottle
+    end
+
+    it "calls gh with args for backfill when homebrew-core fails" do
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::HOMEBREW_CORE_REPO, "--format", "json", "--cert-identity",
+              described_class::HOMEBREW_CORE_CI_URI)
+        .once
+        .and_raise(described_class::InvalidAttestationError)
+
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::BACKFILL_REPO, "--format", "json", "--cert-identity",
+              described_class::BACKFILL_REPO_CI_URI)
+        .and_return(fake_json_resp_backfill)
+
+      described_class.check_core_attestation fake_bottle
+    end
+
+    it "raises when the backfilled attestation is too new" do
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::HOMEBREW_CORE_REPO, "--format", "json", "--cert-identity",
+              described_class::HOMEBREW_CORE_CI_URI)
+        .once
+        .and_raise(described_class::InvalidAttestationError)
+
+      expect(Utils).to receive(:safe_popen_read)
+        .with(fake_gh, "attestation", "verify", cached_download, "--repo",
+              described_class::BACKFILL_REPO, "--format", "json", "--cert-identity",
+              described_class::BACKFILL_REPO_CI_URI)
+        .and_return(fake_json_resp_too_new)
+
+      expect do
+        described_class.check_core_attestation fake_bottle
+      end.to raise_error(described_class::InvalidAttestationError)
+    end
+  end
+end