guarddog 2.7.1__py3-none-any.whl → 2.9.0__py3-none-any.whl

guarddog/analyzer/metadata/rubygems/__init__.py

@@ -0,0 +1,26 @@
+from typing import Type
+
+from guarddog.analyzer.metadata import Detector
+from guarddog.analyzer.metadata.rubygems.typosquatting import RubyGemsTyposquatDetector
+from guarddog.analyzer.metadata.rubygems.empty_information import (
+    RubyGemsEmptyInfoDetector,
+)
+from guarddog.analyzer.metadata.rubygems.release_zero import RubyGemsReleaseZeroDetector
+from guarddog.analyzer.metadata.rubygems.bundled_binary import RubyGemsBundledBinary
+from guarddog.analyzer.metadata.rubygems.repository_integrity_mismatch import (
+    RubyGemsIntegrityMismatchDetector,
+)
+
+RUBYGEMS_METADATA_RULES = {}
+
+classes: list[Type[Detector]] = [
+    RubyGemsTyposquatDetector,
+    RubyGemsEmptyInfoDetector,
+    RubyGemsReleaseZeroDetector,
+    RubyGemsBundledBinary,
+    RubyGemsIntegrityMismatchDetector,
+]
+
+for detectorClass in classes:
+    detectorInstance = detectorClass()  # type: ignore
+    RUBYGEMS_METADATA_RULES[detectorInstance.get_name()] = detectorInstance

guarddog/analyzer/metadata/rubygems/bundled_binary.py

@@ -0,0 +1,13 @@
+from guarddog.analyzer.metadata.bundled_binary import BundledBinary
+from typing import Optional
+
+
+class RubyGemsBundledBinary(BundledBinary):
+    def detect(
+        self,
+        package_info,
+        path: Optional[str] = None,
+        name: Optional[str] = None,
+        version: Optional[str] = None,
+    ) -> tuple[bool, str]:
+        return super().detect(package_info, path, name, version)

guarddog/analyzer/metadata/rubygems/empty_information.py

@@ -0,0 +1,24 @@
+import logging
+from typing import Optional
+
+from guarddog.analyzer.metadata.empty_information import EmptyInfoDetector
+
+log = logging.getLogger("guarddog")
+
+
+class RubyGemsEmptyInfoDetector(EmptyInfoDetector):
+    def detect(
+        self,
+        package_info,
+        path: Optional[str] = None,
+        name: Optional[str] = None,
+        version: Optional[str] = None,
+    ) -> tuple[bool, str]:
+        log.debug(f"Running RubyGems empty description heuristic on package {name}")
+        info = package_info.get("info", "")
+        if info is None:
+            info = ""
+        return (
+            len(info.strip()) == 0,
+            EmptyInfoDetector.MESSAGE_TEMPLATE % "RubyGems",
+        )

guarddog/analyzer/metadata/rubygems/release_zero.py

@@ -0,0 +1,22 @@
+import logging
+from typing import Optional
+
+from guarddog.analyzer.metadata.release_zero import ReleaseZeroDetector
+
+log = logging.getLogger("guarddog")
+
+
+class RubyGemsReleaseZeroDetector(ReleaseZeroDetector):
+    def detect(
+        self,
+        package_info,
+        path: Optional[str] = None,
+        name: Optional[str] = None,
+        version: Optional[str] = None,
+    ) -> tuple[bool, str]:
+        log.debug(f"Running zero version heuristic on RubyGems package {name}")
+        gem_version = package_info.get("version", "")
+        return (
+            gem_version in ["0.0.0", "0.0"],
+            ReleaseZeroDetector.MESSAGE_TEMPLATE % gem_version,
+        )

guarddog/analyzer/metadata/rubygems/repository_integrity_mismatch.py

@@ -0,0 +1,49 @@
+import logging
+from typing import Optional
+
+import urllib3.util
+
+from guarddog.analyzer.metadata.repository_integrity_mismatch import IntegrityMismatch
+
+log = logging.getLogger("guarddog")
+
+
+def normalize_github_url(url):
+    if url is None:
+        return None
+    url = url.strip()
+    if url.endswith(".git"):
+        url = url[:-4]
+    if url.startswith("git://"):
+        url = url.replace("git://", "https://")
+    if url.startswith("http://"):
+        url = url.replace("http://", "https://")
+    parsed = urllib3.util.parse_url(url)
+    if parsed.host not in ("github.com", "www.github.com"):
+        return None
+    return url
+
+
+class RubyGemsIntegrityMismatchDetector(IntegrityMismatch):
+    EXCLUDED_EXTENSIONS = [".md", ".txt", ".rdoc"]
+
+    def extract_github_url(self, package_info, name: str) -> Optional[str]:
+        """Extract GitHub URL from RubyGems metadata."""
+        source_code_uri = package_info.get("source_code_uri")
+        homepage_uri = package_info.get("homepage_uri")
+
+        github_url = normalize_github_url(source_code_uri)
+        if github_url is None:
+            github_url = normalize_github_url(homepage_uri)
+
+        return github_url
+
+    def get_base_path(self, path: str, name: str) -> str:
+        """RubyGems: files are extracted directly to the path."""
+        return path
+
+    def get_version(self, package_info, version: Optional[str]) -> Optional[str]:
+        """Get version from RubyGems metadata or use provided version."""
+        if version is None:
+            version = package_info.get("version")
+        return version

guarddog/analyzer/metadata/rubygems/typosquatting.py

@@ -0,0 +1,91 @@
+import logging
+from typing import Optional
+
+from guarddog.analyzer.metadata.typosquatting import TyposquatDetector
+
+log = logging.getLogger("guarddog")
+
+
+class RubyGemsTyposquatDetector(TyposquatDetector):
+    """
+    Detector for typosquatting attacks on RubyGems.
+    Checks for distance one Levenshtein, one-off character swaps,
+    permutations around hyphens, and substrings.
+
+    Attributes:
+        popular_packages (set): set of critical/popular gems from ecosyste.ms
+    """
+
+    def _get_top_packages(self) -> set:
+        """
+        Gets the top 1000 critical RubyGems packages.
+        Uses the base class implementation with RubyGems-specific parameters.
+        """
+        url = "https://packages.ecosyste.ms/api/v1/registries/rubygems.org/package_names?critical=true&per_page=1000"
+        return self._get_top_packages_with_refresh(
+            packages_filename="top_rubygems_packages.json",
+            popular_packages_url=url,
+            refresh_days=30,
+        )
+
+    def detect(
+        self,
+        package_info,
+        path: Optional[str] = None,
+        name: Optional[str] = None,
+        version: Optional[str] = None,
+    ) -> tuple[bool, Optional[str]]:
+        """
+        Uses a gem's information to determine if it's attempting
+        a typosquatting attack.
+        """
+        gem_name = package_info.get("name", name)
+        log.debug(f"Running typosquatting heuristic on RubyGems package {gem_name}")
+
+        similar_package_names = self.get_typosquatted_package(gem_name)
+        if len(similar_package_names) > 0:
+            return True, TyposquatDetector.MESSAGE_TEMPLATE % ", ".join(
+                similar_package_names
+            )
+        return False, None
+
+    def _get_confused_forms(self, package_name) -> list:
+        """
+        Gets confused terms for Ruby gems.
+        Confused terms are:
+            - ruby to rb swaps (or vice versa)
+            - the removal of ruby/rb terms
+            - rails to ruby-on-rails swaps
+
+        Args:
+            package_name (str): name of the package
+
+        Returns:
+            list: list of confused terms
+        """
+        confused_forms = []
+
+        terms = package_name.split("-")
+
+        for i in range(len(terms)):
+            confused_term = None
+
+            if "ruby" in terms[i]:
+                confused_term = terms[i].replace("ruby", "rb")
+            elif "rb" in terms[i]:
+                confused_term = terms[i].replace("rb", "ruby")
+            else:
+                continue
+
+            replaced_form = terms[:i] + [confused_term] + terms[i + 1 :]
+            removed_form = terms[:i] + terms[i + 1 :]
+
+            for form in (replaced_form, removed_form):
+                confused_forms.append("-".join(form))
+
+        if package_name == "rails":
+            confused_forms.append("ruby-on-rails")
+        elif package_name == "ruby-on-rails":
+            confused_forms.append("rails")
+
+        return confused_forms

guarddog/analyzer/metadata/typosquatting.py

@@ -1,7 +1,18 @@
 import abc
+import json
+import logging
+import os
+import time
+from datetime import datetime, timedelta
 from itertools import permutations
+from typing import Optional
+
+import requests
 
 from guarddog.analyzer.metadata.detector import Detector
+from guarddog.utils.config import TOP_PACKAGES_CACHE_LOCATION
+
+log = logging.getLogger("guarddog")
 
 
 class TyposquatDetector(Detector):
@@ -19,8 +30,215 @@ class TyposquatDetector(Detector):
 
     @abc.abstractmethod
     def _get_top_packages(self) -> set:
+        """
+        Subclasses should implement this to return a set of top package names.
+
+        For simple implementations without network refresh, override this directly.
+        For implementations with network refresh, use _get_top_packages_with_refresh().
+        """
         pass
 
+    def _get_top_packages_with_refresh(
+        self,
+        packages_filename: str,
+        popular_packages_url: Optional[str] = None,
+        refresh_days: int = 30,
+    ) -> set:
+        """
+        Common implementation for getting top packages with optional network refresh.
+
+        Args:
+            packages_filename: Name of the JSON file (e.g., "top_pypi_packages.json")
+            popular_packages_url: URL to fetch fresh package data. If None, refresh is disabled.
+            refresh_days: Number of days before file is considered expired
+
+        Returns:
+            set: Set of package names
+        """
+        resources_dir = TOP_PACKAGES_CACHE_LOCATION
+        if resources_dir is None:
+            resources_dir = os.path.abspath(
+                os.path.join(os.path.dirname(__file__), "resources")
+            )
+
+        top_packages_path = os.path.join(resources_dir, packages_filename)
+        log.debug(f"Loading cache from: {top_packages_path}")
+
+        cache_data = self._load_cache_file(top_packages_path)
+
+        if cache_data:
+            log.debug(f"Cache loaded successfully with keys: {list(cache_data.keys())}")
+        else:
+            log.debug("Cache is empty or invalid")
+
+        top_packages_information = cache_data.get("packages") if cache_data else None
+
+        # Enable refresh if URL is provided
+        enable_refresh = popular_packages_url is not None
+        is_expired = self._cache_is_expired(cache_data, days=refresh_days)
+        log.debug(
+            f"Cache expired check: {is_expired} (refresh enabled: {enable_refresh})"
+        )
+
+        if enable_refresh and is_expired and popular_packages_url is not None:
+            log.info(
+                f"Cache is expired, attempting to refresh from: {popular_packages_url}"
+            )
+            new_response_data = self._get_top_packages_network_raw(popular_packages_url)
+            if new_response_data is not None:
+                log.debug("Downloaded new data, extracting package names")
+                top_packages_information = self._extract_package_names(
+                    new_response_data
+                )
+
+                # Save with new standardized format
+                cache_data = {
+                    "downloaded_timestamp": int(time.time()),
+                    "packages": top_packages_information,
+                }
+
+                if top_packages_information is not None:
+                    log.info(
+                        f"Saving refreshed cache with {len(top_packages_information)} packages to {top_packages_path}"
+                    )
+                with open(top_packages_path, "w+") as f:
+                    json.dump(cache_data, f, ensure_ascii=False, indent=4)
+            else:
+                log.warning(
+                    f"Failed to download new cache data from {popular_packages_url}"
+                )
+
+        if top_packages_information is None:
+            return set()
+
+        return set(top_packages_information)
+
+    def _cache_is_expired(self, cache_data: dict | None, days: int) -> bool:
+        """
+        Check if cache data is expired based on downloaded_timestamp.
+
+        Args:
+            cache_data: Cache dictionary with 'downloaded_timestamp' key
+            days: Number of days before cache is considered expired
+
+        Returns:
+            bool: True if expired or timestamp missing, False otherwise
+        """
+        if cache_data is None:
+            log.debug("Cache is expired: cache_data is None")
+            return True
+
+        timestamp = cache_data.get("downloaded_timestamp")
+        if timestamp is None:
+            # Missing timestamp, consider expired
+            log.debug("Cache is expired: missing 'downloaded_timestamp' field")
+            return True
+
+        try:
+            download_time = datetime.fromtimestamp(timestamp)
+            age = datetime.now() - download_time
+            is_expired = age > timedelta(days=days)
+            log.debug(
+                f"Cache age: {age.days} days, threshold: {days} days, expired: {is_expired}"
+            )
+            return is_expired
+        except (ValueError, OSError) as e:
+            # Invalid timestamp
+            log.debug(f"Cache is expired: invalid timestamp {timestamp} - {e}")
+            return True
+
+    def _load_cache_file(self, path: str) -> dict | None:
+        """
+        Load cache data from local JSON file.
+
+        Expected format: {"downloaded_timestamp": epoch, "packages": [...]}
+
+        If the file doesn't match this format, it will be considered invalid
+        and trigger a refresh to download data in the correct format.
+
+        Args:
+            path: Path to the JSON file
+
+        Returns:
+            dict: Cache data with 'packages' and 'downloaded_timestamp', or None if invalid
+        """
+        try:
+            with open(path, "r") as f:
+                result = json.load(f)
+
+                # Validate new format structure
+                if (
+                    isinstance(result, dict)
+                    and "packages" in result
+                    and "downloaded_timestamp" in result
+                ):
+                    # Validate that packages is a list
+                    if isinstance(result["packages"], list):
+                        return result
+                    else:
+                        log.warning(
+                            f"Invalid cache format in {path}: 'packages' must be a list. Will trigger refresh."
+                        )
+                        return None
+
+                # File doesn't have the correct format - invalidate it
+                log.info(
+                    f"Cache file {path} has old or invalid format. Will trigger refresh to new format."
+                )
+                return None
+
+        except FileNotFoundError:
+            log.debug(f"Cache file not found: {path}")
+            return None
+        except json.JSONDecodeError:
+            log.error(f"Invalid JSON in file: {path}")
+            return None
+
+    def _get_top_packages_network_raw(self, url: str) -> dict | list | None:
+        """
+        Fetch the complete response data from the network.
+        Returns the full JSON structure to preserve format when saving.
+
+        Args:
+            url: URL to fetch package data from
+
+        Returns:
+            dict | list: Full response data or None on error
+        """
+        try:
+            response = requests.get(url)
+            response.raise_for_status()
+            return response.json()
+        except json.JSONDecodeError:
+            log.error(f'Couldn\'t convert to json: "{response.text}"')
+            return None
+        except requests.exceptions.RequestException as e:
+            log.error(f"Network error: {e}")
+            return None
+
+    def _extract_package_names(self, data: dict | list | None) -> list | None:
+        """
+        Extract package names from the raw data structure.
+
+        Override this method in subclasses if the data format is specific to the ecosystem.
+        Default implementation assumes data is already a list of package names.
+
+        Args:
+            data: Raw data from JSON file or network response
+
+        Returns:
+            list: List of package names or None
+        """
+        if data is None:
+            return None
+
+        # Default: assume data is already a list
+        if isinstance(data, list):
+            return data
+
+        # If it's a dict, subclasses should override this method
+        return None
+
     def _is_distance_one_Levenshtein(self, name1, name2) -> bool:
         """
         Returns True if two names have a Levenshtein distance of one

guarddog/analyzer/metadata/utils.py

@@ -2,6 +2,7 @@ from datetime import datetime, timezone
 from functools import cache
 from typing import Optional
 
+import hashlib
 import whois  # type: ignore
 
 NPM_MAINTAINER_EMAIL_WARNING = (
@@ -53,3 +54,25 @@ def extract_email_address_domain(email_address: str):
 
     except IndexError:
         raise ValueError(f"Invalid email address: {email_address}")
+
+
+def get_file_hash(path: str) -> tuple[str, list[str]]:
+    """
+    Gets the sha256 of the file
+
+    Args:
+        path (str): Full file path
+
+    Returns:
+        str: The SHA256 hash of the file as a hexadecimal string
+        list: The file contents as a list of lines
+    """
+    with open(path, "rb") as f:
+        # Read the contents of the file
+        file_contents = f.read()
+        # Create a hash object
+        hash_object = hashlib.sha256()
+        # Feed the file contents to the hash object
+        hash_object.update(file_contents)
+        # Get the hexadecimal hash value
+        return hash_object.hexdigest(), str(file_contents).strip().splitlines()

guarddog/analyzer/sourcecode/__init__.py

@@ -89,6 +89,8 @@ for file_name in semgrep_rule_file_names:
                         ecosystems.add(ECOSYSTEM.EXTENSION)
                     case "go":
                         ecosystems.add(ECOSYSTEM.GO)
+                    case "ruby":
+                        ecosystems.add(ECOSYSTEM.RUBYGEMS)
                     case _:
                         continue
 

guarddog/analyzer/sourcecode/api-obfuscation.yml

@@ -1,42 +1,37 @@
 rules:
-    - id: api-obfuscation
-      languages:
-        - python
-      message: This package uses obfuscated API calls that may evade static analysis detection
-      metadata:
-        description: Identify obfuscated API calls using alternative Python syntax patterns
-      severity: WARNING
-      patterns:
-        - pattern-either:
-          # Covered cases:
-          # 1) __dict__ access patterns: $MODULE.__dict__[$METHOD](...) / .__call__(...)
-          # 2) __getattribute__ patterns: $MODULE.__getattribute__($METHOD)(...) / .__call__(...)
-          # 3) getattr patterns: getattr($MODULE, $METHOD)(...) / .__call__(...)
-          # It also covers the case where $MODULE is imported as __import__('mod')
-          - patterns:
-              - pattern-either:
-                  - pattern: $MODULE.__dict__[$METHOD]($...ARGS)
-                  - pattern: $MODULE.__dict__[$METHOD].__call__($...ARGS)
-                  - pattern: $MODULE.__getattribute__($METHOD)($...ARGS)
-                  - pattern: $MODULE.__getattribute__($METHOD).__call__($...ARGS)
-                  - pattern: getattr($MODULE, $METHOD)($...ARGS)
-                  - pattern: getattr($MODULE, $METHOD).__call__($...ARGS)
-              - metavariable-regex:
-                  metavariable: $MODULE
-                  regex: "^[A-Za-z_][A-Za-z0-9_\\.]*$|^__import__\\([\"'][A-Za-z_][A-Za-z0-9_]*[\"']\\)$"
-              - metavariable-regex:
-                  metavariable: $METHOD
-                  regex: "^[\"'][A-Za-z_][A-Za-z0-9_]*[\"']$"
+  - id: api-obfuscation
+    languages:
+      - python
+    message: This package uses obfuscated API calls that may evade static analysis detection
+    metadata:
+      description: Identify obfuscated API calls using alternative Python syntax patterns
+    severity: WARNING
+    patterns:
+      - pattern-either:
+        # Covered cases:
+        # 1) __dict__ access patterns: $MODULE.__dict__[$METHOD](...) / .__call__(...)
+        # 2) __getattribute__ patterns: $MODULE.__getattribute__($METHOD)(...) / .__call__(...)
+        # 3) getattr patterns: getattr($MODULE, $METHOD)(...) / .__call__(...)
+        # It also covers the case where $MODULE is imported as __import__($mod),
+        # where $mod is a generic expression (e.g., string literal, variable, etc.)
+        - patterns:
+          - pattern-either:
+              - pattern: $MODULE.__dict__[$METHOD]($...ARGS)
+              - pattern: $MODULE.__dict__[$METHOD].__call__($...ARGS)
+              - pattern: $MODULE.__getattribute__($METHOD)($...ARGS)
+              - pattern: $MODULE.__getattribute__($METHOD).__call__($...ARGS)
+              - pattern: getattr($MODULE, $METHOD)($...ARGS)
+              - pattern: getattr($MODULE, $METHOD).__call__($...ARGS)
+          - metavariable-regex:
+              metavariable: $MODULE
+              regex: "^[A-Za-z_][A-Za-z0-9_\\.]*$|^__import__\\(.*\\)$"
 
-          # --- Additional Cases: __import__('mod').method(...) / .__call__(...)
-          - patterns:
-              - pattern-either:
-                  - pattern: __import__($MODULE).$METHOD($...ARGS)
-                  - pattern: __import__($MODULE).$METHOD.__call__($...ARGS)
-              - metavariable-regex:
-                  metavariable: $MODULE
-                  regex: "^[\"'][A-Za-z_][A-Za-z0-9_]*[\"']$"
-              - metavariable-regex:
-                  metavariable: $METHOD
-                  # avoid matching __getattribute__
-                  regex: "[^(__getattribute__)][A-Za-z_][A-Za-z0-9_]*"
+        # --- Additional Cases: __import__('mod').method(...) / .__call__(...)
+        - patterns:
+          - pattern-either:
+              - pattern: __import__($MODULE).$METHOD($...ARGS)
+              - pattern: __import__($MODULE).$METHOD.__call__($...ARGS)
+          - metavariable-regex:
+              metavariable: $METHOD
+              # avoid matching __getattribute__
+              regex: "[^(__getattribute__)][A-Za-z_][A-Za-z0-9_]*"

guarddog/analyzer/sourcecode/code-execution.yml

@@ -114,6 +114,26 @@ rules:
           - pattern-either:
               - pattern: globals()['eval']($ARG1)
               - pattern: globals()['\x65\x76\x61\x6c']($ARG1) # that's "eval" in hexadecimal
+              
+          # vars() indirection to access builtins
+          - pattern: vars(__builtins__)['compile']($ARG1, ...)
+          - pattern: vars(__builtins__)['exec']($ARG1)
+          - pattern: vars(__builtins__)['eval']($ARG1)
+
+          # vars().get() variant
+          - pattern: vars(__builtins__).get('compile')($ARG1, ...)
+          - pattern: vars(__builtins__).get('exec')($ARG1)
+          - pattern: vars(__builtins__).get('eval')($ARG1)
+
+          # vars/globals combinations
+          - pattern: vars(globals()['__builtins__'])['exec']($ARG1)
+          - pattern: vars(globals()['__builtins__'])['eval']($ARG1)
+          - pattern: vars(locals()['__builtins__'])['exec']($ARG1)
+          - pattern: vars(locals()['__builtins__'])['eval']($ARG1)
+
+          # Direct compile() calls
+          - pattern: compile($ARG1, '<string>', 'exec')
+          - pattern: compile($ARG1, '<string>', 'eval')
 
       - metavariable-pattern:
           metavariable: $ARG1

guarddog/analyzer/sourcecode/exec-base64.yml

@@ -56,4 +56,23 @@ rules:
           - pattern: __import__("base64").b64decode(...)
           - pattern: marshal.loads(zlib.decompress(...))
           - pattern: $FUNC("...").decrypt(...)
+
+          # codecs.decode with base64 (all valid aliases)
+          - pattern: codecs.decode(..., 'base64')
+          - pattern: codecs.decode(..., 'base_64')
+          - pattern: codecs.decode(..., 'base-64')
+          - pattern: codecs.decode(..., 'BASE64')
+          - pattern: codecs.decode(..., 'BASE_64')
+          - pattern: codecs.decode(..., 'BASE-64')
+
+          # importlib + base64 module
+          - pattern: importlib.import_module('base64').b64decode(...)
+
+          # importlib + codecs module (all base64 aliases)
+          - pattern: importlib.import_module('codecs').decode(..., 'base64')
+          - pattern: importlib.import_module('codecs').decode(..., 'base_64')
+          - pattern: importlib.import_module('codecs').decode(..., 'base-64')
+          - pattern: importlib.import_module('codecs').decode(..., 'BASE64')
+          - pattern: importlib.import_module('codecs').decode(..., 'BASE_64')
+          - pattern: importlib.import_module('codecs').decode(..., 'BASE-64')
     severity: WARNING