docker: add metadata finding support for org.opencontainers.image.version and org.opencontainers.image.revision

Extends metadata extraction to handle digest-only image references, where no tag is present.

This new logic will run when one of the following additional OCI metadata fields are present along with the digest:

- `org.opencontainers.image.version`: Packaged software version. This can sometimes be a tag
- `org.opencontainers.image.revision`: Source control revision identifier for the packaged software

Author: yeikel

docker/lib/dependabot/docker/metadata_finder.rb

@@ -13,24 +13,84 @@ class MetadataFinder < Dependabot::MetadataFinders::Base
 
       private
 
+      # Finds the repository for the Docker image using OCI annotations.
+      # @see https://specs.opencontainers.org/image-spec/annotations/
       sig { override.returns(T.nilable(Dependabot::Source)) }
       def look_up_source
         return if dependency.requirements.empty?
 
         new_source = dependency.requirements.first&.fetch(:source)
-        return unless new_source && new_source[:registry] && new_source[:tag]
+        return unless new_source && new_source[:registry] && (new_source[:tag] || new_source[:digest])
 
-        image_ref = "#{new_source[:registry]}/#{dependency.name}:#{new_source[:tag]}"
-        image_details_output = SharedHelpers.run_shell_command("regctl image inspect #{image_ref}")
-        image_details = JSON.parse(image_details_output)
-        image_source = image_details.dig("config", "Labels", "org.opencontainers.image.source")
+        details = image_details(new_source)
+        image_source = details.dig("config", "Labels", "org.opencontainers.image.source")
+        # If the tag is present, we can use it directly to build the source
         return unless image_source
 
-        Dependabot::Source.from_url(image_source)
+        return Dependabot::Source.from_url(image_source) if new_source[:tag]
+
+        build_source_from_image_version(image_source, details)
       rescue StandardError => e
         Dependabot.logger.warn("Error looking up Docker source: #{e.message}")
         nil
       end
+
+      sig do
+        params(
+          source: T::Hash[Symbol, T.untyped]
+        ).returns(
+          T::Hash[String, T.untyped]
+        )
+      end
+      def image_details(source)
+        registry = source[:registry]
+        tag = source[:tag]
+        digest = source[:digest]
+
+        image_ref =
+          # If both tag and digest are present, use the digest as docker ignores the tag when a digest is present
+          if digest
+            "#{registry}/#{dependency.name}@sha256:#{digest}"
+          else
+            "#{registry}/#{dependency.name}:#{tag}"
+          end
+
+        Dependabot.logger.info("Looking up Docker source #{image_ref}")
+        output = SharedHelpers.run_shell_command("regctl image inspect #{image_ref}")
+        JSON.parse(output)
+      end
+
+      # Builds a Dependabot::Source object using the OCI image version label.
+      #
+      # This is used as a fallback when an image is referenced by digest rather than a tag
+      sig do
+        params(
+          image_source: String,
+          details: T::Hash[String, T.untyped]
+        ).returns(T.nilable(Dependabot::Source))
+      end
+      def build_source_from_image_version(image_source, details)
+        image_version = details.dig("config", "Labels", "org.opencontainers.image.version")
+        revision = details.dig("config", "Labels", "org.opencontainers.image.revision")
+        # Sometimes the versions are not tags (e.g., "24.04")
+        # We only want to build a source if the version looks like a tag (starts with "v")
+        is_tag = image_version&.start_with?("v")
+
+        return unless is_tag || revision
+
+        parsed_source = Dependabot::Source.from_url(image_source)
+        return unless parsed_source
+
+        Dependabot.logger.info "Building source with branch '#{image_version}' and commit '#{revision}'"
+
+        Dependabot::Source.new(
+          provider: parsed_source.provider,
+          repo: parsed_source.repo,
+          directory: parsed_source.directory,
+          branch: image_version,
+          commit: revision
+        )
+      end
     end
   end
 end

docker/spec/dependabot/docker/metadata_finder_spec.rb

@@ -73,7 +73,53 @@
             requirement: nil,
             groups: [],
             source: { registry: "ghcr.io",
-                      digest: "sha256:389a5a9a5457ed237b05d623ddc31a42fa97811051dcd02d7ca4ad46bd3edd3e" }
+                      digest: "389a5a9a5457ed237b05d623ddc31a42fa97811051dcd02d7ca4ad46bd3edd3e" }
+          }],
+          package_manager: "docker"
+        )
+      end
+
+      it "doesn't find the repository" do
+        expect(finder.source_url).to be_nil
+      end
+    end
+
+    context "with a docker image without a tag but with org.opencontainers.image.version populated" do
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: "regclient/regctl",
+          version: "",
+          requirements: [{
+            file: "Dockerfile",
+            requirement: nil,
+            groups: [],
+            source: { registry: "ghcr.io",
+                      digest: "a734f285c0962e46557bff24489fa0b0521455733f72d9eb30c4f7a5027aeed6" }
+          }],
+          package_manager: "docker"
+        )
+      end
+
+      it "finds the repository" do
+        expect(finder.source_url).to eq "https://github.com/regclient/regclient"
+        expect(finder.send(:source).branch).to eq "v0.11.1"
+        expect(finder.send(:source).commit).to eq "bf3bcfc47173b49ee8000d1d3a1ac15036e83cf0"
+      end
+    end
+
+    context "with a docker image without a tag but without a proper tag format or revision" do
+      # The image used here has org.opencontainers.image.version set to "24.04"
+      # which refers to the Ubuntu version rather than a tag
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: "maven",
+          version: "",
+          requirements: [{
+            file: "Dockerfile",
+            requirement: nil,
+            groups: [],
+            source: { registry: "docker.io",
+                      digest: "800a33a4cb190082c47abcd57944c852e1dece834f92c0aef65bea6336c52a72" }
           }],
           package_manager: "docker"
         )