java-dependency-analyzer 1.0.0__py3-none-any.whl

java_dependency_analyzer/scanners/__init__.py

@@ -0,0 +1,11 @@
+"""
+scanners package.
+
+Provides vulnerability scanners for Java dependencies.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"

java_dependency_analyzer/scanners/base.py

@@ -0,0 +1,102 @@
+"""
+base module.
+
+Defines the abstract base class for vulnerability scanners.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import json
+from abc import ABC, abstractmethod
+
+from ..cache.vulnerability_cache import VulnerabilityCache
+from ..models.dependency import Dependency, Vulnerability
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+
+class VulnerabilityScanner(ABC):
+    """
+    Abstract base class for all vulnerability scanners.
+
+    Provides shared cache helpers so concrete scanners can check and store
+    raw API payloads without duplicating the logic.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    # Subclasses set this in __init__; None disables caching.
+    _cache: VulnerabilityCache | None = None
+
+    @abstractmethod
+    def scan(self, dependency: Dependency) -> list[Vulnerability]:
+        """
+        Scan the given dependency for known vulnerabilities.
+
+        Returns a list of Vulnerability objects found for this exact version.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+
+    @abstractmethod
+    def _parse_response(self, data) -> list[Vulnerability]:
+        """
+        Parse the raw API response payload into Vulnerability objects.
+
+        Concrete scanners receive either a ``dict`` (OSV) or a ``list`` (GHSA),
+        so the parameter is intentionally untyped here.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+
+    def _get_cached(self, source: str, dependency: Dependency) -> str | None:
+        """
+        Return the cached JSON payload for *dependency* under *source*, or ``None``.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        if self._cache is None:
+            return None
+        return self._cache.get(
+            source, dependency.group_id, dependency.artifact_id, dependency.version
+        )
+
+    def _put_cached(self, source: str, dependency: Dependency, payload: str) -> None:
+        """
+        Persist *payload* in the cache under *source* for *dependency*.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        if self._cache is not None:
+            self._cache.put(
+                source,
+                dependency.group_id,
+                dependency.artifact_id,
+                dependency.version,
+                payload,
+            )
+
+    def _apply_cache_source(
+        self, data: str, source: str
+    ) -> list[Vulnerability]:
+        """
+        Deserialise *data* (a cached JSON string), parse into ``Vulnerability``
+        objects, and mark each with ``source = "<source>-cache"``.
+
+        Concrete scanners implement :meth:`_parse_response`; this helper
+        delegates to it after decoding the cached payload.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        parsed = self._parse_response(json.loads(data))
+        for vuln in parsed:
+            vuln.source = f"{source}-cache"
+        return parsed

java_dependency_analyzer/scanners/ghsa_scanner.py

@@ -0,0 +1,204 @@
+"""
+ghsa_scanner module.
+
+Queries the GitHub Advisory Database REST API to get vulnerability information
+for Maven packages.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import json
+import os
+
+import httpx
+from dotenv import load_dotenv
+
+from ..cache.vulnerability_cache import VulnerabilityCache
+from ..models.dependency import Dependency, Vulnerability
+from ..util.logger import setup_logger
+from .base import VulnerabilityScanner
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+load_dotenv()
+
+_logger = setup_logger(__name__)
+
+_GHSA_API_URL = "https://api.github.com/advisories"
+_ACCEPT_HEADER = "application/vnd.github+json"
+_API_VERSION_HEADER = "2022-11-28"
+
+
+class GhsaScanner(VulnerabilityScanner):
+    """
+    Queries the GitHub Advisory Database REST API (https://api.github.com/advisories)
+    to find reviewed security advisories for a given Maven dependency version.
+
+    Supports optional authentication via the ``GITHUB_TOKEN`` environment variable to
+    increase the API rate limit from 60 to 5000 requests per hour.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        cache: VulnerabilityCache | None = None,
+    ) -> None:
+        """
+        Initialise the scanner with an optional shared httpx client and cache.
+
+        If ``GITHUB_TOKEN`` is set in the environment, it is forwarded as a
+        ``Bearer`` token to raise the GitHub API rate limit.
+        When *cache* is provided, scan results are read from and written to it.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        headers = {
+            "Accept": _ACCEPT_HEADER,
+            "X-GitHub-Api-Version": _API_VERSION_HEADER,
+        }
+        token = os.environ.get("GITHUB_TOKEN")
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+
+        self._client = client or httpx.Client(timeout=30, headers=headers)
+        self._cache = cache
+
+    def scan(self, dependency: Dependency) -> list[Vulnerability]:
+        """
+        Query the GitHub Advisory Database for advisories affecting this dependency.
+
+        Checks the cache first when one is configured; only calls the API on a
+        cache miss and stores the raw response on success.
+
+        Uses the ``affects`` query parameter with ``group:artifact@version`` notation
+        and filters by ``ecosystem=maven`` and ``type=reviewed``.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        _logger.debug("Querying GHSA for %s", dependency.coordinates)
+        cached = self._get_cached("ghsa", dependency)
+        if cached is not None:
+            return self._apply_cache_source(cached, "ghsa")
+
+        affects = f"{dependency.group_id}:{dependency.artifact_id}@{dependency.version}"
+        params = {
+            "ecosystem": "maven",
+            "affects": affects,
+            "type": "reviewed",
+        }
+        try:
+            response = self._client.get(_GHSA_API_URL, params=params)
+            if response.status_code == 429:
+                _logger.warning(
+                    "GitHub Advisory API rate limit exceeded for %s", dependency.coordinates
+                )
+                return []
+            response.raise_for_status()
+            data = response.json()
+        except httpx.HTTPError as exc:
+            _logger.warning("GHSA query failed for %s: %s", dependency.coordinates, exc)
+            return []
+
+        self._put_cached("ghsa", dependency, json.dumps(data))
+        return self._parse_response(data)
+
+    def _parse_response(self, data: list) -> list[Vulnerability]:
+        """
+        Parse the GitHub Advisory API response (a JSON array) into Vulnerability objects.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        vulns: list[Vulnerability] = []
+        for advisory in data:
+            vuln_obj = self._parse_advisory(advisory)
+            if vuln_obj is not None:
+                vulns.append(vuln_obj)
+        return vulns
+
+    def _parse_advisory(self, advisory: dict) -> Vulnerability | None:
+        """
+        Convert a single GitHub Advisory dict into a Vulnerability object.
+
+        The ``cve_id`` field prefers the CVE identifier when available and falls
+        back to the GHSA identifier so every returned advisory has a unique ID.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        ghsa_id = advisory.get("ghsa_id", "UNKNOWN")
+        cve_id = advisory.get("cve_id") or ghsa_id
+        summary = advisory.get("summary", "No summary available")
+        severity = self._extract_severity(advisory)
+        affected_versions = self._extract_affected_versions(advisory)
+        reference_url = advisory.get("html_url", "")
+
+        return Vulnerability(
+            cve_id=cve_id,
+            summary=summary,
+            severity=severity,
+            affected_versions=affected_versions,
+            source="ghsa",
+            reference_url=reference_url,
+        )
+
+    def _extract_severity(self, advisory: dict) -> str:
+        """
+        Extract a human-readable severity string from a GitHub Advisory entry.
+
+        Tries, in order:
+        1. The top-level ``severity`` label (e.g. ``"high"``, ``"critical"``).
+        2. The CVSS v4 score from ``cvss_severities.cvss_v4.score``.
+        3. The CVSS v3 score from ``cvss_severities.cvss_v3.score``.
+        4. The legacy ``cvss.score`` field.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        label = advisory.get("severity")
+        if label and label not in ("", "unknown"):
+            return label.upper()
+
+        cvss_severities = advisory.get("cvss_severities", {})
+        for key in ("cvss_v4", "cvss_v3"):
+            score = (cvss_severities.get(key) or {}).get("score")
+            if score is not None:
+                return str(score)
+
+        legacy_score = (advisory.get("cvss") or {}).get("score")
+        if legacy_score is not None:
+            return str(legacy_score)
+
+        return "UNKNOWN"
+
+    def _extract_affected_versions(self, advisory: dict) -> list[str]:
+        """
+        Extract affected version range strings from a GitHub Advisory entry.
+
+        Each entry in ``vulnerabilities`` may carry a ``vulnerable_version_range``
+        string (e.g. ``"< 2.17.0"`` or ``">= 2.0.0, < 2.15.0"``).  The method
+        splits compound ranges on commas so the returned list contains individual
+        constraint tokens.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        affected_versions: list[str] = []
+        seen: set[str] = set()
+        for vuln_entry in advisory.get("vulnerabilities", []):
+            version_range = vuln_entry.get("vulnerable_version_range")
+            if not version_range:
+                continue
+            for part in version_range.split(","):
+                constraint = part.strip()
+                if constraint and constraint not in seen:
+                    affected_versions.append(constraint)
+                    seen.add(constraint)
+        return affected_versions

java_dependency_analyzer/scanners/osv_scanner.py

@@ -0,0 +1,167 @@
+"""
+osv_scanner module.
+
+Queries the OSV.dev API to get vulnerability information for Maven packages.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import json
+
+import httpx
+
+from ..cache.vulnerability_cache import VulnerabilityCache
+from ..models.dependency import Dependency, Vulnerability
+from ..util.logger import setup_logger
+from .base import VulnerabilityScanner
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+_OSV_QUERY_URL = "https://api.osv.dev/v1/query"
+_OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch"
+_OSV_VULN_URL = "https://osv.dev/vulnerability/"
+
+
+class OsvScanner(VulnerabilityScanner):
+    """
+    Queries the OSV.dev API (https://api.osv.dev) to find vulnerabilities
+    for a given Maven dependency version.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        cache: VulnerabilityCache | None = None,
+    ) -> None:
+        """
+        Initialise the scanner with an optional shared httpx client and cache.
+
+        When *cache* is provided, scan results are read from and written to it.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        self._client = client or httpx.Client(timeout=30)
+        self._cache = cache
+
+    def scan(self, dependency: Dependency) -> list[Vulnerability]:
+        """
+        Query OSV.dev for vulnerabilities affecting this dependency version.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        _logger.debug("Querying OSV for %s", dependency.coordinates)
+        cached = self._get_cached("osv", dependency)
+        if cached is not None:
+            return self._apply_cache_source(cached, "osv")
+
+        payload = {
+            "version": dependency.version,
+            "package": {
+                "name": f"{dependency.group_id}:{dependency.artifact_id}",
+                "ecosystem": "Maven",
+            },
+        }
+        try:
+            response = self._client.post(_OSV_QUERY_URL, json=payload)
+            response.raise_for_status()
+            data = response.json()
+        except httpx.HTTPError as exc:
+            _logger.warning("OSV query failed for %s: %s", dependency.coordinates, exc)
+            return []
+
+        self._put_cached("osv", dependency, json.dumps(data))
+        return self._parse_response(data)
+
+    def _parse_response(self, data: dict) -> list[Vulnerability]:
+        """
+        Parse the OSV API response JSON into Vulnerability objects.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        vulns: list[Vulnerability] = []
+        for vuln in data.get("vulns", []):
+            vuln_obj = self._parse_vuln(vuln)
+            if vuln_obj is not None:
+                vulns.append(vuln_obj)
+        return vulns
+
+    def _parse_vuln(self, vuln: dict) -> Vulnerability | None:
+        """
+        Convert a single OSV vulnerability dict into a Vulnerability object.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        vuln_id = vuln.get("id", "UNKNOWN")
+        summary = vuln.get("summary", "No summary available")
+        severity = self._extract_severity(vuln)
+        affected_versions = self._extract_affected_versions(vuln)
+        reference_url = self._extract_reference_url(vuln, vuln_id)
+
+        return Vulnerability(
+            cve_id=vuln_id,
+            summary=summary,
+            severity=severity,
+            affected_versions=affected_versions,
+            source="osv",
+            reference_url=reference_url,
+        )
+
+    def _extract_severity(self, vuln: dict) -> str:
+        """
+        Extract a human-readable severity from the vulnerability entry.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        severity_list = vuln.get("severity", [])
+        if severity_list:
+            return severity_list[0].get("score", "UNKNOWN")
+        # Try database_specific CVSS score
+        db_specific = vuln.get("database_specific", {})
+        return db_specific.get("severity", "UNKNOWN")
+
+    def _extract_affected_versions(self, vuln: dict) -> list[str]:
+        """
+        Extract a flat list of affected version strings from the vulnerability entry.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        affected_versions: list[str] = []
+        for affected in vuln.get("affected", []):
+            for version_range in affected.get("ranges", []):
+                for event in version_range.get("events", []):
+                    introduced = event.get("introduced")
+                    fixed = event.get("fixed")
+                    if introduced:
+                        affected_versions.append(f">={introduced}")
+                    if fixed:
+                        affected_versions.append(f"<{fixed}")
+            # Collect explicit version strings
+            for ver in affected.get("versions", []):
+                if ver not in affected_versions:
+                    affected_versions.append(ver)
+        return affected_versions
+
+    def _extract_reference_url(self, vuln: dict, vuln_id: str) -> str:
+        """
+        Return the most relevant reference URL for the vulnerability.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        for ref in vuln.get("references", []):
+            if ref.get("type") == "WEB":
+                return ref.get("url", "")
+        return f"{_OSV_VULN_URL}{vuln_id}"

java_dependency_analyzer/util/__init__.py

@@ -0,0 +1,11 @@
+"""
+util package.
+
+Provides utility modules for the java_dependency_analyzer package.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"

java_dependency_analyzer/util/logger.py

@@ -0,0 +1,48 @@
+"""
+logger module.
+
+Provides a setup_logger function for consistent logging configuration.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import logging
+import logging.config
+import os
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+
+def setup_logger(name: str) -> logging.Logger:
+    """
+    Set up and return a logger with consistent configuration.
+
+    Args:
+        name: The name of the logger to create
+
+    Returns:
+        A configured logger instance
+    """
+
+    def find_logging_ini(start_dir: str) -> str | None:
+        current = start_dir
+        while True:
+            candidate = os.path.join(current, "logging.ini")
+            if os.path.exists(candidate):
+                return candidate
+            parent = os.path.dirname(current)
+            if parent == current:
+                break
+            current = parent
+        return None
+
+    search_dir = os.getcwd()
+    config_path = find_logging_ini(search_dir)
+    if config_path is not None and os.path.exists(config_path):
+        logging.config.fileConfig(config_path, disable_existing_loggers=False)
+    else:
+        logging.basicConfig(level=logging.INFO)
+    logger = logging.getLogger(name)
+    return logger