chore: add support for Git tag aliases in vuln GHA check (#1065)

This PR adds a utility function to identify the highest semantic version tag from a set of Git tags, specifically for cases where multiple tags point to the same commit SHA in a third-party GitHub Action. 

Signed-off-by: behnazh-w <behnaz.hassanshahi@oracle.com>

Author: behnazh-w

src/macaron/errors.py

@@ -32,6 +32,10 @@ class CloneError(MacaronError):
     """Happens when cannot clone a git repository."""
 
 
+class GitTagError(MacaronError):
+    """Happens when there is a Git tag related error."""
+
+
 class RepoCheckOutError(MacaronError):
     """Happens when there is an error when checking out the correct revision of a git repository."""
 

src/macaron/slsa_analyzer/git_url.py

@@ -16,12 +16,13 @@
 from git import GitCommandError
 from git.objects import Commit
 from git.repo import Repo
+from packaging import version
 from pydriller.git import Git
 
 from macaron.config.defaults import defaults
 from macaron.config.global_config import global_config
 from macaron.environment_variables import get_patched_env
-from macaron.errors import CloneError
+from macaron.errors import CloneError, GitTagError
 
 logger: logging.Logger = logging.getLogger(__name__)
 
@@ -984,3 +985,73 @@ def get_tags_via_git_remote(repo: str) -> dict[str, str] | None:
     logger.debug("Found %s tags via ls-remote of %s", len(tags), repo)
 
     return tags
+
+
+def find_highest_git_tag(tags: set[str]) -> str:
+    """
+    Find and return the highest (most recent) semantic version tag from a set of Git tags.
+
+    Parameters
+    ----------
+    tags : set[str]
+        A set of version strings (e.g., {"v1.0.0", "v2.3.4", "v2.1.0"}). Tags must follow PEP 440 or
+        semver format, otherwise they will be skipped.
+
+    Returns
+    -------
+    str
+        The tag string corresponding to the highest version.
+
+    Raises
+    ------
+    GitTagError
+        If no valid tag is found or if a tag is not a valid version.
+
+    Example
+    -------
+    >>> find_highest_git_tag({"v2.0.0"})
+    'v2.0.0'
+
+    >>> find_highest_git_tag({"v4", "v4.2.1"})
+    'v4.2.1'
+
+    >>> find_highest_git_tag({"1.2.3", "2.0.0", "1.10.1"})
+    '2.0.0'
+
+    >>> find_highest_git_tag({"0.1", "0.1.1", "0.0.9"})
+    '0.1.1'
+
+    >>> find_highest_git_tag({"invalid", "1.0.0"})
+    '1.0.0'
+
+    >>> find_highest_git_tag(set())
+    Traceback (most recent call last):
+        ...
+    GitTagError: No tags provided.
+
+    >>> find_highest_git_tag({"invalid"})
+    Traceback (most recent call last):
+        ...
+    GitTagError: No valid version tag found.
+    """
+    if not tags:
+        raise GitTagError("No tags provided.")
+
+    highest_tag = None
+    highest_parsed_tag = version.Version("0")
+
+    for tag in tags:
+        try:
+            parsed_tag = version.Version(tag)
+        except version.InvalidVersion:
+            logger.debug("Invalid version tag encountered while finding the highest tag: %s", tag)
+            continue
+
+        if parsed_tag > highest_parsed_tag:
+            highest_parsed_tag = parsed_tag
+            highest_tag = tag
+
+    if highest_tag is None:
+        raise GitTagError("No valid version tag found.")
+
+    return highest_tag

src/macaron/slsa_analyzer/package_registry/osv_dev.py

@@ -10,9 +10,9 @@
 from packaging import version
 
 from macaron.config.defaults import defaults
-from macaron.errors import APIAccessError
+from macaron.errors import APIAccessError, GitTagError
 from macaron.json_tools import json_extract
-from macaron.slsa_analyzer.git_url import get_tags_via_git_remote, is_commit_hash
+from macaron.slsa_analyzer.git_url import find_highest_git_tag, get_tags_via_git_remote, is_commit_hash
 from macaron.util import send_post_http_raw
 
 logger: logging.Logger = logging.getLogger(__name__)
@@ -328,15 +328,22 @@ def is_version_affected(
         # and try to match the commit hash with the tag. If a match is found, update `pkg_version` to the tag.
         if source_repo and is_commit_hash(pkg_version):
             tags: dict = get_tags_via_git_remote(source_repo) or {}
+            # There might be tag aliases for a release, e.g., v4 and v4.2.1.
+            commit_tags = set()
             for tag, commit in tags.items():
                 if commit.startswith(pkg_version):
-                    pkg_version = tag
-                    break
+                    commit_tags.add(tag)
 
             # If we were not able to find a tag for the commit hash, raise an exception.
-            if is_commit_hash(pkg_version):
+            if not commit_tags:
                 raise APIAccessError(f"Failed to find a tag for {pkg_name}@{pkg_version}.")
 
+            # Pick the most recent (highest) tag if there are aliases.
+            try:
+                pkg_version = find_highest_git_tag(commit_tags)
+            except GitTagError as error:
+                raise APIAccessError from error
+
         affected = json_extract(vuln, ["affected"], list)
         if not affected:
             raise APIAccessError(f"Received invalid response for {pkg_name}@{pkg_version}.")