feat(security): Add package name typosquatting detection

Implement typosquatting detection for package names during analysis.
Compares package names against a list of popular packages using the Jaro-Winkler similarity algorithm.
Packages exceeding a defined threshold of similarity to a popular package are flagged.

Signed-off-by: Amine <[email protected]>

Author: Amine

src/macaron/__main__.py

@@ -367,6 +367,16 @@ def main(argv: list[str] | None = None) -> None:
         help="The directory where Macaron looks for already cloned repositories.",
     )
 
+    main_parser.add_argument(
+        "-pp",
+        "--popular-packages-path",
+        required=False,
+        type=str,
+        default=None,
+        help="The path to the popular packages file used for typosquatting detection.",
+        dest="popular_packages_path",
+    )
+
     # Add sub parsers for each action.
     sub_parser = main_parser.add_subparsers(dest="action", help="Run macaron <action> --help for help")
 
@@ -579,6 +589,7 @@ def main(argv: list[str] | None = None) -> None:
         build_log_path=os.path.join(args.output_dir, "build_log"),
         debug_level=log_level,
         local_repos_path=args.local_repos_path,
+        popular_packages_path=args.popular_packages_path,
         resources_path=os.path.join(macaron.MACARON_PATH, "resources"),
     )
 

src/macaron/config/global_config.py

@@ -49,6 +49,9 @@ class GlobalConfig:
     #: The path to the local .m2 Maven repository. This attribute is None if there is no available .m2 directory.
     local_maven_repo: str | None = None
 
+    #: The path to the popular packages file.
+    popular_packages_path: str | None = None
+
     def load(
         self,
         macaron_path: str,
@@ -57,6 +60,7 @@ def load(
         debug_level: int,
         local_repos_path: str,
         resources_path: str,
+        popular_packages_path: str,
     ) -> None:
         """Initiate the GlobalConfig object.
 
@@ -81,6 +85,7 @@ def load(
         self.debug_level = debug_level
         self.local_repos_path = local_repos_path
         self.resources_path = resources_path
+        self.popular_packages_path = popular_packages_path
 
     def load_expectation_files(self, exp_path: str) -> None:
         """

src/macaron/malware_analyzer/pypi_heuristics/heuristics.py

@@ -37,6 +37,9 @@ class Heuristics(str, Enum):
     #: Indicates that the package has an unusually large version number for a single release.
     ANOMALOUS_VERSION = "anomalous_version"
 
+    #: Indicates that the package name is similar to a popular package.
+    TYPOSQUATTING_PRESENCE = "typosquatting_presence"
+
 
 class HeuristicResult(str, Enum):
     """Result type indicating the outcome of a heuristic."""

src/macaron/malware_analyzer/pypi_heuristics/metadata/typosquatting_presence.py

@@ -0,0 +1,249 @@
+# Copyright (c) 2024 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
+
+"""Analyzer checks if there is typosquatting presence in the package name."""
+import logging
+import os
+
+from macaron.config.global_config import global_config
+from macaron.json_tools import JsonType
+from macaron.malware_analyzer.pypi_heuristics.base_analyzer import BaseHeuristicAnalyzer
+from macaron.malware_analyzer.pypi_heuristics.heuristics import HeuristicResult, Heuristics
+from macaron.slsa_analyzer.package_registry.pypi_registry import PyPIPackageJsonAsset
+
+logger = logging.getLogger(__name__)
+
+
+class TyposquattingPresenceAnalyzer(BaseHeuristicAnalyzer):
+    """Check whether the PyPI package has typosquatting presence."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="typosquatting_presence_analyzer", heuristic=Heuristics.TYPOSQUATTING_PRESENCE, depends_on=None
+        )
+        self.popular_packages_path = os.path.join(global_config.resources_path, "popular_packages.txt")
+        self.distance_ratio_threshold = 0.95
+        self.cost = 1
+        self.scaling = 0.15
+        self.keyboard = 0.8
+        self.keyboard_layout = {
+            "1": (-1, 0),
+            "2": (-1, 1),
+            "3": (-1, 2),
+            "4": (-1, 3),
+            "5": (-1, 4),
+            "6": (-1, 5),
+            "7": (-1, 6),
+            "8": (-1, 7),
+            "9": (-1, 8),
+            "0": (-1, 9),
+            "-": (-1, 10),
+            "q": (0, 0),
+            "w": (0, 1),
+            "e": (0, 2),
+            "r": (0, 3),
+            "t": (0, 4),
+            "y": (0, 5),
+            "u": (0, 6),
+            "i": (0, 7),
+            "o": (0, 8),
+            "p": (0, 9),
+            "a": (1, 0),
+            "s": (1, 1),
+            "d": (1, 2),
+            "f": (1, 3),
+            "g": (1, 4),
+            "h": (1, 5),
+            "j": (1, 6),
+            "k": (1, 7),
+            "l": (1, 8),
+            "z": (2, 0),
+            "x": (2, 1),
+            "c": (2, 2),
+            "v": (2, 3),
+            "b": (2, 4),
+            "n": (2, 5),
+            "m": (2, 6),
+        }
+
+        if global_config.popular_packages_path is not None:
+            self.popular_packages_path = global_config.popular_packages_path
+
+    def are_neighbors(self, char1: str, char2: str) -> bool:
+        """Check if two characters are adjacent on a QWERTY keyboard.
+
+        Parameters
+        ----------
+        char1 : str
+            The first character.
+        char2 : str
+            The second character.
+
+        Returns
+        -------
+        bool
+            True if the characters are neighbors, False otherwise.
+        """
+        c1 = self.keyboard_layout.get(char1)
+        c2 = self.keyboard_layout.get(char2)
+        if not c1 or not c2:
+            return False
+        return (abs(c1[0] - c2[0]) <= 1) and (abs(c1[1] - c2[1]) <= 1)
+
+    def substitution_func(self, char1: str, char2: str) -> float:
+        """Calculate the substitution cost between two characters.
+
+        Parameters
+        ----------
+        char1 : str
+            The first character.
+        char2 : str
+            The second character.
+
+        Returns
+        -------
+        float
+            0.0 if the characters are the same, `self.keyboard` if they are
+            neighbors on a QWERTY keyboard, and `self.cost` otherwise.
+        """
+        if char1 == char2:
+            return 0.0
+        if self.keyboard and self.are_neighbors(char1, char2):
+            return self.keyboard
+        return self.cost
+
+    def jaro_distance(self, package_name: str, popular_package_name: str) -> float:
+        """Calculate the Jaro distance between two package names.
+
+        Parameters
+        ----------
+        package_name : str
+            The name of the package being analyzed.
+        popular_package_name : str
+            The name of a popular package to compare against.
+
+        Returns
+        -------
+        float
+            The Jaro distance between the two package names.
+        """
+        if package_name == popular_package_name:
+            return 1.0
+
+        len1, len2 = len(package_name), len(popular_package_name)
+        if len1 == 0 or len2 == 0:
+            return 0.0
+
+        match_distance = max(len1, len2) // 2 - 1
+
+        package_name_matches = [False] * len1
+        popular_package_name_matches = [False] * len2
+        matches = 0
+        transpositions = 0.0  # Now a float to handle partial costs
+
+        # Count matches
+        for i in range(len1):
+            start = max(0, i - match_distance)
+            end = min(i + match_distance + 1, len2)
+            for j in range(start, end):
+                if popular_package_name_matches[j]:
+                    continue
+                if package_name[i] == popular_package_name[j]:
+                    package_name_matches[i] = True
+                    popular_package_name_matches[j] = True
+                    matches += 1
+                    break
+
+        if matches == 0:
+            return 0.0
+
+        # Count transpositions with possible keyboard awareness
+        k = 0
+        for i in range(len1):
+            if package_name_matches[i]:
+                while not popular_package_name_matches[k]:
+                    k += 1
+                if package_name[i] != popular_package_name[k]:
+                    transpositions += self.substitution_func(package_name[i], popular_package_name[k])
+                k += 1
+
+        transpositions /= 2.0  # Adjust for transpositions being counted twice
+
+        return (matches / len1 + matches / len2 + (matches - transpositions) / matches) / 3.0
+
+    def ratio(self, package_name: str, popular_package_name: str) -> float:
+        """Calculate the Jaro-Winkler distance ratio.
+
+        Parameters
+        ----------
+        package_name : str
+            The name of the package being analyzed.
+        popular_package_name : str
+            The name of a popular package to compare against.
+
+        Returns
+        -------
+        float
+            The Jaro-Winkler distance ratio, incorporating a prefix bonus
+            for common initial characters.
+        """
+        scaling = self.scaling
+        jaro_dist = self.jaro_distance(package_name, popular_package_name)
+        prefix_length = 0
+        max_prefix = 4
+        for i in range(min(max_prefix, len(package_name), len(popular_package_name))):
+            if package_name[i] == popular_package_name[i]:
+                prefix_length += 1
+            else:
+                break
+
+        return jaro_dist + prefix_length * scaling * (1 - jaro_dist)
+
+    def analyze(self, pypi_package_json: PyPIPackageJsonAsset) -> tuple[HeuristicResult, dict[str, JsonType]]:
+        """Analyze the package.
+
+        Parameters
+        ----------
+        pypi_package_json: PyPIPackageJsonAsset
+            The PyPI package JSON asset object.
+
+        Returns
+        -------
+        tuple[HeuristicResult, dict[str, JsonType]]:
+            The result and related information collected during the analysis.
+        """
+        # If there is a popular packages file, check if the package name is similar to any of them
+        package_name = pypi_package_json.component_name
+        if not self.popular_packages_path or not os.path.exists(self.popular_packages_path):
+            err_msg = f"Popular packages file not found or path not configured: {self.popular_packages_path}"
+            logger.warning("%s. Skipping typosquatting check.", err_msg)
+            return HeuristicResult.SKIP, {"error": err_msg}
+
+        popular_packages = []
+        try:
+            with open(self.popular_packages_path, encoding="utf-8") as file:
+                popular_packages = file.read().splitlines()
+        except OSError as e:
+            err_msg = f"Could not read popular packages file {self.popular_packages_path}: {e}"
+            logger.error(err_msg)
+            return HeuristicResult.SKIP, {"error": err_msg}
+
+        for popular_package in popular_packages:
+            if package_name == popular_package:
+                return HeuristicResult.PASS, {"package_name": package_name}
+
+            distance_ratio = self.ratio(package_name, popular_package)
+            if distance_ratio >= self.distance_ratio_threshold:
+                logger.info(
+                    "Potential typosquatting detected: '%s' is similar to popular package '%s' (ratio: %.3f)",
+                    package_name,
+                    popular_package,
+                    distance_ratio,
+                )
+                return HeuristicResult.FAIL, {
+                    "package_name": package_name,
+                    "popular_package": popular_package,
+                    "similarity_ratio": distance_ratio,
+                }
+
+        return HeuristicResult.PASS, {"package_name": package_name}