feat: added in support for different data representations, thresholds updated

art1f1c3R · art1f1c3R · commit fae73ec5128b · 2025-01-07T15:36:10.000+10:00
diff --git a/src/macaron/config/defaults.ini b/src/macaron/config/defaults.ini
@@ -581,3 +581,10 @@ releases_frequency_threshold = 2
 # The gap threshold.
 # The timedelta indicate the gap between the date maintainer registers their pypi's account and the date of latest release.
 timedelta_threshold_of_join_release = 5
+
+# Any major version above this value is detected as anomalistic and marked as suspicious
+major_threshold = 20
+# Any epoch number avove this value is detected as anomalistic and marked as suspicious
+epoch_threshold = 3
+# The number of days +/- the day of publish the calendar versioning day may be
+day_publish_error = 4
diff --git a/src/macaron/malware_analyzer/pypi_heuristics/heuristics.py b/src/macaron/malware_analyzer/pypi_heuristics/heuristics.py
@@ -34,6 +34,9 @@ class Heuristics(str, Enum):
     #: Indicates that the package does not include a .whl file
     WHEEL_ABSENCE = "wheel_absence"
 
+    #: Indicates that the package has an unusually large version number for a single release
+    ANOMALISTIC_VERSION = "anomalistic_version"
+
 
 class HeuristicResult(str, Enum):
     """Result type indicating the outcome of a heuristic."""
diff --git a/src/macaron/malware_analyzer/pypi_heuristics/metadata/anomalistic_version.py b/src/macaron/malware_analyzer/pypi_heuristics/metadata/anomalistic_version.py
@@ -0,0 +1,190 @@
+# Copyright (c) 2024 - 2024, 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/.
+
+"""The heuristic analyzer to check for an anomalistic package version."""
+
+import logging
+from enum import Enum
+
+from packaging.version import InvalidVersion, parse
+
+from macaron.config.defaults import defaults
+from macaron.errors import HeuristicAnalyzerValueError
+from macaron.json_tools import JsonType, json_extract
+from macaron.malware_analyzer.datetime_parser import parse_datetime
+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.Logger = logging.getLogger(__name__)
+
+
+class AnomalisticVersionAnalyzer(BaseHeuristicAnalyzer):
+    """
+    Analyze the version number (if there is only a single release) to detect if it is anomalistic.
+
+    A version number is anomalistic if it is above the thresholds for an epoch, major, or minor value.
+    If the version does not adhere to PyPI standards (PEP 440, as per the 'packaging' module), this heuristic
+    cannot analyze it.
+
+    Calendar versioning is detected as version numbers with the major value as the year (either yyyy or yy),
+    the minor as the month, and the micro as the day (+/- 2 days), with no further values.
+
+    Calendar-semantic versioning is detected as version numbers with the major value as the year (either yyyy or yy),
+    and any other series of numbers following it.
+
+    All other versionings are detected as semantic versioning.
+    """
+
+    DETAIL_INFO_KEY: str = "versioning"
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="anomalistic_version_analyzer",
+            heuristic=Heuristics.ANOMALISTIC_VERSION,
+            depends_on=[(Heuristics.ONE_RELEASE, HeuristicResult.FAIL)],
+        )
+        self.major_threshold, self.epoch_threshold, self.day_publish_error = self._load_defaults()
+
+    def _load_defaults(self) -> tuple[int, int, int]:
+        """Load default settings from defaults.ini."""
+        section_name = "heuristic.pypi"
+        if defaults.has_section(section_name):
+            section = defaults[section_name]
+            return (
+                section.getint("major_threshold"),
+                section.getint("epoch_threshold"),
+                section.getint("day_publish_error"),
+            )
+        # Major threshold, Epoch threshold, Day pushlish error
+        return 20, 3, 4
+
+    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.
+
+        Raises
+        ------
+        HeuristicAnalyzerValueError
+            if there is no release information available.
+        """
+        releases = pypi_package_json.get_releases()
+        if releases is None:  # no release information
+            error_msg = "There is no information for any release of this package."
+            logger.debug(error_msg)
+            raise HeuristicAnalyzerValueError(error_msg)
+
+        if len(releases) != 1:
+            error_msg = (
+                "This heuristic depends on a single release, but somehow there are multiple when the one release"
+                + " heuristic failed."
+            )
+            logger.debug(error_msg)
+            raise HeuristicAnalyzerValueError(error_msg)
+
+        # Since there is only one release, the latest version should be that release
+        release = pypi_package_json.get_latest_version()
+        if release is None:
+            error_msg = "No latest version information available"
+            logger.debug(error_msg)
+            raise HeuristicAnalyzerValueError(error_msg)
+
+        try:
+            release_metadata = releases[release]
+        except KeyError as release_error:
+            error_msg = "The latest release is not available in the list of releases"
+            logger.debug(error_msg)
+            raise HeuristicAnalyzerValueError(error_msg) from release_error
+
+        try:
+            version = parse(release)
+        except InvalidVersion:
+            return HeuristicResult.SKIP, {self.DETAIL_INFO_KEY: Versioning.INVALID.value}
+
+        years = []
+        months = []
+        publish_days = []
+
+        for distribution in release_metadata:
+            upload_time = json_extract(distribution, ["upload_time"], str)
+            if upload_time is None:
+                error_msg = "Missing upload time from release information"
+                logger.debug(error_msg)
+                raise HeuristicAnalyzerValueError(error_msg)
+
+            parsed_time = parse_datetime(upload_time)
+            if parsed_time is None:
+                error_msg = "Upload time is not of the expected PyPI format"
+                logger.debug(error_msg)
+                raise HeuristicAnalyzerValueError(error_msg)
+
+            years.append(parsed_time.year)
+            years.append(parsed_time.year % 100)  # last 2 digits
+            months.append(parsed_time.month)
+            publish_days.append(parsed_time.day)
+
+        days = list(range(min(publish_days) - self.day_publish_error, max(publish_days) + self.day_publish_error + 1))
+
+        calendar = False
+        calendar_semantic = False
+
+        # check for year YY[YY]...
+        if version.major in years:
+            # calendar versioning: YY[YY].(M[M].D[D])(D[D].M[M])...
+            if (version.minor in months and version.micro in days) or (
+                version.minor in days and version.micro in months
+            ):
+                calendar = True
+            else:
+                calendar_semantic = True
+        # check for calendar versioning: M[M].D[D].YY[YY]... or D[D].M[M].YY[YY]...
+        elif (
+            (version.major in months and version.minor in days) or (version.major in days and version.minor in months)
+        ) and version.micro in years:
+            # must include day and year for this to be calendar
+            calendar = True
+
+        if calendar:  # just check epoch
+            detail_info: dict[str, JsonType] = {self.DETAIL_INFO_KEY: Versioning.CALENDAR.value}
+            if version.epoch > self.epoch_threshold:
+                return HeuristicResult.FAIL, detail_info
+
+            return HeuristicResult.PASS, detail_info
+
+        if calendar_semantic:  # check minor (as major) and epoch
+            detail_info = {self.DETAIL_INFO_KEY: Versioning.CALENDAR_SEMANTIC.value}
+
+            if version.epoch > self.epoch_threshold:
+                return HeuristicResult.FAIL, detail_info
+            if version.minor > self.major_threshold:
+                return HeuristicResult.FAIL, detail_info
+
+            return HeuristicResult.PASS, detail_info
+
+        # semantic versioning
+        detail_info = {self.DETAIL_INFO_KEY: Versioning.SEMANTIC.value}
+
+        if version.epoch > self.epoch_threshold:
+            return HeuristicResult.FAIL, detail_info
+        if version.major > self.major_threshold:
+            return HeuristicResult.FAIL, detail_info
+
+        return HeuristicResult.PASS, detail_info
+
+
+class Versioning(Enum):
+    """Enum used to assign different versioning methods."""
+
+    INVALID = "invalid"
+    CALENDAR = "calendar"
+    CALENDAR_SEMANTIC = "calendar_semantic"
+    SEMANTIC = "semantic"
diff --git a/src/macaron/slsa_analyzer/checks/detect_malicious_metadata_check.py b/src/macaron/slsa_analyzer/checks/detect_malicious_metadata_check.py
@@ -15,6 +15,7 @@
 from macaron.json_tools import JsonType, json_extract
 from macaron.malware_analyzer.pypi_heuristics.base_analyzer import BaseHeuristicAnalyzer
 from macaron.malware_analyzer.pypi_heuristics.heuristics import HeuristicResult, Heuristics
+from macaron.malware_analyzer.pypi_heuristics.metadata.anomalistic_version import AnomalisticVersionAnalyzer
 from macaron.malware_analyzer.pypi_heuristics.metadata.closer_release_join_date import CloserReleaseJoinDateAnalyzer
 from macaron.malware_analyzer.pypi_heuristics.metadata.empty_project_link import EmptyProjectLinkAnalyzer
 from macaron.malware_analyzer.pypi_heuristics.metadata.high_release_frequency import HighReleaseFrequencyAnalyzer
@@ -73,6 +74,7 @@ class MaliciousMetadataFacts(CheckFacts):
     CloserReleaseJoinDateAnalyzer,
     SuspiciousSetupAnalyzer,
     WheelAbsenceAnalyzer,
+    AnomalisticVersionAnalyzer,
 ]
 
 # The HeuristicResult sequence is aligned with the sequence of ANALYZERS list
@@ -86,6 +88,7 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult,
         HeuristicResult,
         HeuristicResult,
+        HeuristicResult,
     ],
     float,
 ] = {
@@ -98,9 +101,26 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult.FAIL,  # Closer Release Join Date
         HeuristicResult.FAIL,  # Suspicious Setup
         HeuristicResult.FAIL,  # Wheel Absence
+        HeuristicResult.FAIL,  # Anomalistic Version
         # No project link, only one release, and the maintainer released it shortly
         # after account registration.
         # The setup.py file contains suspicious imports and .whl file isn't present.
+        # Anomalistic version has no effect.
+    ): Confidence.HIGH,
+    (
+        HeuristicResult.FAIL,  # Empty Project
+        HeuristicResult.SKIP,  # Unreachable Project Links
+        HeuristicResult.FAIL,  # One Release
+        HeuristicResult.SKIP,  # High Release Frequency
+        HeuristicResult.SKIP,  # Unchanged Release
+        HeuristicResult.FAIL,  # Closer Release Join Date
+        HeuristicResult.FAIL,  # Suspicious Setup
+        HeuristicResult.FAIL,  # Wheel Absence
+        HeuristicResult.PASS,  # Anomalistic Version
+        # No project link, only one release, and the maintainer released it shortly
+        # after account registration.
+        # The setup.py file contains suspicious imports and .whl file isn't present.
+        # Anomalistic version has no effect.
     ): Confidence.HIGH,
     (
         HeuristicResult.FAIL,  # Empty Project
@@ -111,6 +131,7 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult.FAIL,  # Closer Release Join Date
         HeuristicResult.FAIL,  # Suspicious Setup
         HeuristicResult.FAIL,  # Wheel Absence
+        HeuristicResult.SKIP,  # Anomalistic Version
         # No project link, frequent releases of multiple versions without modifying the content,
         # and the maintainer released it shortly after account registration.
         # The setup.py file contains suspicious imports and .whl file isn't present.
@@ -124,6 +145,7 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult.FAIL,  # Closer Release Join Date
         HeuristicResult.FAIL,  # Suspicious Setup
         HeuristicResult.FAIL,  # Wheel Absence
+        HeuristicResult.SKIP,  # Anomalistic Version
         # No project link, frequent releases of multiple versions,
         # and the maintainer released it shortly after account registration.
         # The setup.py file contains suspicious imports and .whl file isn't present.
@@ -137,6 +159,7 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult.FAIL,  # Closer Release Join Date
         HeuristicResult.PASS,  # Suspicious Setup
         HeuristicResult.PASS,  # Wheel Absence
+        HeuristicResult.SKIP,  # Anomalistic Version
         # No project link, frequent releases of multiple versions without modifying the content,
         # and the maintainer released it shortly after account registration. Presence/Absence of
         # .whl file has no effect
@@ -150,6 +173,7 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult.FAIL,  # Closer Release Join Date
         HeuristicResult.PASS,  # Suspicious Setup
         HeuristicResult.FAIL,  # Wheel Absence
+        HeuristicResult.SKIP,  # Anomalistic Version
         # No project link, frequent releases of multiple versions without modifying the content,
         # and the maintainer released it shortly after account registration. Presence/Absence of
         # .whl file has no effect
@@ -163,10 +187,56 @@ class MaliciousMetadataFacts(CheckFacts):
         HeuristicResult.FAIL,  # Closer Release Join Date
         HeuristicResult.FAIL,  # Suspicious Setup
         HeuristicResult.FAIL,  # Wheel Absence
+        HeuristicResult.SKIP,  # Anomalistic Version
         # All project links are unreachable, frequent releases of multiple versions,
         # and the maintainer released it shortly after account registration.
         # The setup.py file contains suspicious imports and .whl file isn't present.
     ): Confidence.HIGH,
+    (
+        HeuristicResult.FAIL,  # Empty Project
+        HeuristicResult.SKIP,  # Unreachable Project Links
+        HeuristicResult.FAIL,  # One Release
+        HeuristicResult.SKIP,  # High Release Frequency
+        HeuristicResult.SKIP,  # Unchanged Release
+        HeuristicResult.FAIL,  # Closer Release Join Date
+        HeuristicResult.PASS,  # Suspicious Setup
+        HeuristicResult.PASS,  # Wheel Absence
+        HeuristicResult.FAIL,  # Anomalistic Version
+        # No project link, only one release, and the maintainer released it shortly
+        # after account registration.
+        # The setup.py file has no effect and .whl file is present.
+        # The version number is anomalistic.
+    ): Confidence.MEDIUM,
+    (
+        HeuristicResult.FAIL,  # Empty Project
+        HeuristicResult.SKIP,  # Unreachable Project Links
+        HeuristicResult.FAIL,  # One Release
+        HeuristicResult.SKIP,  # High Release Frequency
+        HeuristicResult.SKIP,  # Unchanged Release
+        HeuristicResult.FAIL,  # Closer Release Join Date
+        HeuristicResult.FAIL,  # Suspicious Setup
+        HeuristicResult.PASS,  # Wheel Absence
+        HeuristicResult.FAIL,  # Anomalistic Version
+        # No project link, only one release, and the maintainer released it shortly
+        # after account registration.
+        # The setup.py file has no effect and .whl file is present.
+        # The version number is anomalistic.
+    ): Confidence.MEDIUM,
+    (
+        HeuristicResult.FAIL,  # Empty Project
+        HeuristicResult.SKIP,  # Unreachable Project Links
+        HeuristicResult.FAIL,  # One Release
+        HeuristicResult.SKIP,  # High Release Frequency
+        HeuristicResult.SKIP,  # Unchanged Release
+        HeuristicResult.FAIL,  # Closer Release Join Date
+        HeuristicResult.SKIP,  # Suspicious Setup
+        HeuristicResult.PASS,  # Wheel Absence
+        HeuristicResult.FAIL,  # Anomalistic Version
+        # No project link, only one release, and the maintainer released it shortly
+        # after account registration.
+        # The setup.py file has no effect and .whl file is present.
+        # The version number is anomalistic.
+    ): Confidence.MEDIUM,
 }
 
 
diff --git a/tests/malware_analyzer/pypi/test_anomalistic_version.py b/tests/malware_analyzer/pypi/test_anomalistic_version.py
