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

java_dependency_analyzer/__init__.py

@@ -0,0 +1,11 @@
+"""
+java_dependency_analyzer package.
+
+Java Dependency Analyzer is a tool that inspects dependencies.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"

java_dependency_analyzer/cache/__init__.py

@@ -0,0 +1,11 @@
+"""
+cache package.
+
+Provides SQLite-backed persistence for vulnerability scan results.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"

java_dependency_analyzer/cache/db.py

@@ -0,0 +1,101 @@
+"""
+db module.
+
+Manages the SQLite database lifecycle: path resolution, connection,
+schema creation, and deletion.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import sqlite3
+from pathlib import Path
+
+from ..util.logger import setup_logger
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+_DB_DIR = Path.home() / ".jda"
+_DB_FILE = "cache.db"
+
+_CREATE_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS vulnerability_cache (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    source      TEXT    NOT NULL,
+    group_id    TEXT    NOT NULL,
+    artifact_id TEXT    NOT NULL,
+    version     TEXT    NOT NULL,
+    payload     TEXT    NOT NULL,
+    cached_at   TEXT    NOT NULL,
+    UNIQUE(source, group_id, artifact_id, version)
+)
+"""
+
+_CREATE_INDEX_SQL = """
+CREATE INDEX IF NOT EXISTS idx_cache_lookup
+ON vulnerability_cache(group_id, artifact_id, version, source)
+"""
+
+
+def get_db_path() -> Path:
+    """
+    Return the absolute path to the SQLite cache database file.
+
+    The default location is ``~/.jda/cache.db``.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    return _DB_DIR / _DB_FILE
+
+
+def get_connection() -> sqlite3.Connection:
+    """
+    Open (and initialise) the SQLite database, creating the parent directory
+    and schema if they do not yet exist.
+
+    Returns a ``sqlite3.Connection`` with ``check_same_thread=False`` so the
+    connection can be shared within a single CLI invocation.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    db_path = get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    _logger.debug("Opening cache database at %s", db_path)
+    conn = sqlite3.connect(str(db_path), check_same_thread=False)
+    _initialise_schema(conn)
+    return conn
+
+
+def _initialise_schema(conn: sqlite3.Connection) -> None:
+    """
+    Create the cache table and lookup index when they do not already exist.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    with conn:
+        conn.execute(_CREATE_TABLE_SQL)
+        conn.execute(_CREATE_INDEX_SQL)
+
+
+def delete_database() -> bool:
+    """
+    Delete the SQLite cache database file.
+
+    Returns ``True`` if the file was deleted, ``False`` if it did not exist.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    db_path = get_db_path()
+    if db_path.exists():
+        db_path.unlink()
+        _logger.info("Deleted cache database at %s", db_path)
+        return True
+    _logger.debug("Cache database not found at %s, nothing to delete", db_path)
+    return False

java_dependency_analyzer/cache/vulnerability_cache.py

@@ -0,0 +1,156 @@
+"""
+vulnerability_cache module.
+
+Provides a SQLite-backed cache for vulnerability scan API responses.
+Cache entries expire after a configurable number of days (default: 7).
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import sqlite3
+from datetime import datetime, timedelta
+
+from ..util.logger import setup_logger
+from .db import get_connection
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+_DEFAULT_TTL_DAYS = 7
+
+_SELECT_SQL = """
+SELECT payload, cached_at FROM vulnerability_cache
+WHERE source = ? AND group_id = ? AND artifact_id = ? AND version = ?
+"""
+
+_UPSERT_SQL = """
+INSERT INTO vulnerability_cache(source, group_id, artifact_id, version, payload, cached_at)
+VALUES (?, ?, ?, ?, ?, ?)
+ON CONFLICT(source, group_id, artifact_id, version)
+DO UPDATE SET payload = excluded.payload, cached_at = excluded.cached_at
+"""
+
+_DELETE_SQL = """
+DELETE FROM vulnerability_cache
+WHERE source = ? AND group_id = ? AND artifact_id = ? AND version = ?
+"""
+
+
+class VulnerabilityCache:
+    """
+    SQLite-backed cache for raw vulnerability API payloads.
+
+    Each entry is keyed by ``(source, group_id, artifact_id, version)`` and stores
+    the raw JSON response payload string.  Entries older than ``ttl_days`` are
+    treated as expired and will not be returned.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    def __init__(
+        self,
+        connection: sqlite3.Connection | None = None,
+        ttl_days: int = _DEFAULT_TTL_DAYS,
+    ) -> None:
+        """
+        Initialise the cache with an optional SQLite connection and TTL.
+
+        When *connection* is ``None`` the default on-disk database is used.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        self._conn = connection or get_connection()
+        self._ttl_days = ttl_days
+
+    def get(
+        self,
+        source: str,
+        group_id: str,
+        artifact_id: str,
+        version: str,
+    ) -> str | None:
+        """
+        Return the cached JSON payload for the given key, or ``None`` when there
+        is no valid (non-expired) entry.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        cursor = self._conn.execute(_SELECT_SQL, (source, group_id, artifact_id, version))
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        payload, cached_at = row
+        if self._is_expired(cached_at):
+            with self._conn:
+                self._conn.execute(_DELETE_SQL, (source, group_id, artifact_id, version))
+            _logger.debug(
+                "Cache entry expired and deleted for %s/%s:%s@%s",
+                source,
+                group_id,
+                artifact_id,
+                version,
+            )
+            return None
+        _logger.debug(
+            "Cache hit for %s/%s:%s@%s", source, group_id, artifact_id, version
+        )
+        return payload
+
+    def put(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        source: str,
+        group_id: str,
+        artifact_id: str,
+        version: str,
+        payload: str,
+    ) -> None:
+        """
+        Insert or replace the cache entry for the given key.
+
+        *payload* must be a JSON string representing the raw API response.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        with self._conn:
+            self._conn.execute(
+                _UPSERT_SQL,
+                (source, group_id, artifact_id, version, payload, now),
+            )
+        _logger.debug(
+            "Cached payload for %s/%s:%s@%s", source, group_id, artifact_id, version
+        )
+
+    def close(self) -> None:
+        """
+        Close the underlying SQLite connection.
+
+        Call this when the cache is no longer needed to release the database
+        file handle immediately.  Callers that passed their own *connection* to
+        the constructor are responsible for not using the connection after calling
+        this method.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        self._conn.close()
+
+    def _is_expired(self, cached_at: str) -> bool:
+        """
+        Return ``True`` when *cached_at* is older than the configured TTL.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        try:
+            entry_time = datetime.strptime(cached_at, "%Y-%m-%d %H:%M:%S")
+        except ValueError:
+            return True
+        return datetime.now() - entry_time > timedelta(days=self._ttl_days)

java_dependency_analyzer/cli.py

@@ -0,0 +1,394 @@
+"""
+cli module.
+
+Command-line interface entry point for the Java Dependency Analyzer.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from pathlib import Path
+
+import click
+
+from .cache.db import delete_database
+from .cache.vulnerability_cache import VulnerabilityCache
+from .models.dependency import Dependency
+from .models.report import ScanResult
+from .parsers.gradle_dep_tree_parser import GradleDepTreeParser
+from .parsers.gradle_parser import GradleParser
+from .parsers.maven_dep_tree_parser import MavenDepTreeParser
+from .parsers.maven_parser import MavenParser
+from .reporters.html_reporter import HtmlReporter
+from .reporters.json_reporter import JsonReporter
+from .resolvers.transitive import TransitiveResolver
+from .scanners.ghsa_scanner import GhsaScanner
+from .scanners.osv_scanner import OsvScanner
+from .util.logger import setup_logger
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Shared CLI options applied to both subcommands
+# ---------------------------------------------------------------------------
+
+_COMMON_OPTIONS = [
+    click.option(
+        "--output-format",
+        "-f",
+        type=click.Choice(["json", "html", "all"], case_sensitive=False),
+        default="all",
+        show_default=True,
+        help="Output format for the vulnerability report.",
+    ),
+    click.option(
+        "--output-dir",
+        "-o",
+        default="./reports",
+        show_default=True,
+        type=click.Path(file_okay=False),
+        help="Directory to write the report file(s) into.",
+    ),
+    click.option(
+        "--no-transitive",
+        is_flag=True,
+        default=False,
+        help="Skip transitive dependency resolution (direct dependencies only).",
+    ),
+    click.option(
+        "--verbose",
+        "-v",
+        is_flag=True,
+        default=False,
+        help="Enable verbose progress output.",
+    ),
+    click.option(
+        "--rebuild-cache",
+        is_flag=True,
+        default=False,
+        help="Delete the vulnerability cache database before scanning.",
+    ),
+    click.option(
+        "--cache-ttl",
+        default=7,
+        show_default=True,
+        type=int,
+        help="Cache TTL in days. Set to 0 to disable caching.",
+    ),
+]
+
+
+def _common_options(func):
+    """Apply all shared options to a Click command."""
+    for option in reversed(_COMMON_OPTIONS):
+        func = option(func)
+    return func
+
+
+# ---------------------------------------------------------------------------
+# Click group
+# ---------------------------------------------------------------------------
+
+
+@click.group()
+def main() -> None:
+    """Java Dependency Analyzer -- inspect Java dependency trees for known vulnerabilities."""
+
+
+# ---------------------------------------------------------------------------
+# gradle subcommand
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.argument(
+    "file",
+    required=False,
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+)
+@click.option(
+    "--dependencies",
+    "-d",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    help=(
+        "Path to a pre-resolved Gradle dependency tree text file "
+        "(output of ``gradle dependencies``). When supplied, transitive "
+        "resolution is skipped."
+    ),
+)
+@_common_options
+def gradle(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    file: str | None,
+    dependencies: str | None,
+    output_format: str,
+    output_dir: str,
+    no_transitive: bool,
+    verbose: bool,
+    rebuild_cache: bool,
+    cache_ttl: int,
+) -> None:
+    """
+    Analyse a Gradle build file (build.gradle or build.gradle.kts) for known
+    dependency vulnerabilities.
+
+    FILE is the path to a build.gradle or build.gradle.kts file.  Alternatively,
+    supply a pre-resolved dependency tree via --dependencies to skip both parsing
+    and transitive resolution.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    if file is None and dependencies is None:
+        raise click.UsageError("Provide FILE or --dependencies (or both).")
+
+    if file is not None:
+        file_path = Path(file)
+        name = file_path.name
+        if not (name.endswith("build.gradle.kts") or name.endswith("build.gradle")):
+            raise click.UsageError(
+                f"Unsupported file: {name}. Expected build.gradle or build.gradle.kts."
+            )
+
+    cache = _init_cache(rebuild_cache, cache_ttl, verbose)
+
+    try:
+        if dependencies is not None:
+            if verbose:
+                click.echo(f"Loading dependency tree from {dependencies}...")
+            parsed_deps = GradleDepTreeParser().parse(dependencies)
+            source = file if file is not None else dependencies
+            _run_analysis(
+                parsed_deps,
+                source_file=source,
+                output_format=output_format,
+                output_dir=output_dir,
+                no_transitive=True,
+                verbose=verbose,
+                cache=cache,
+            )
+        else:
+            if verbose:
+                click.echo(f"Parsing {Path(file).name}...")  # type: ignore[arg-type]
+            parsed_deps = GradleParser().parse(file)  # type: ignore[arg-type]
+            _run_analysis(
+                parsed_deps,
+                source_file=file,  # type: ignore[arg-type]
+                output_format=output_format,
+                output_dir=output_dir,
+                no_transitive=no_transitive,
+                verbose=verbose,
+                cache=cache,
+            )
+    finally:
+        if cache is not None:
+            cache.close()
+
+
+# ---------------------------------------------------------------------------
+# maven subcommand
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.argument(
+    "file",
+    required=False,
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+)
+@click.option(
+    "--dependencies",
+    "-d",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    help=(
+        "Path to a pre-resolved Maven dependency tree text file "
+        "(output of ``mvn dependency:tree``). When supplied, transitive "
+        "resolution is skipped."
+    ),
+)
+@_common_options
+def maven(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    file: str | None,
+    dependencies: str | None,
+    output_format: str,
+    output_dir: str,
+    no_transitive: bool,
+    verbose: bool,
+    rebuild_cache: bool,
+    cache_ttl: int,
+) -> None:
+    """
+    Analyse a Maven POM file (pom.xml) for known dependency vulnerabilities.
+
+    FILE is the path to a pom.xml file.  Alternatively, supply a pre-resolved
+    dependency tree via --dependencies to skip both parsing and transitive
+    resolution.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    if file is None and dependencies is None:
+        raise click.UsageError("Provide FILE or --dependencies (or both).")
+
+    if file is not None:
+        file_path = Path(file)
+        if not file_path.name.endswith("pom.xml"):
+            raise click.UsageError(
+                f"Unsupported file: {file_path.name}. Expected pom.xml."
+            )
+
+    cache = _init_cache(rebuild_cache, cache_ttl, verbose)
+
+    try:
+        if dependencies is not None:
+            if verbose:
+                click.echo(f"Loading dependency tree from {dependencies}...")
+            parsed_deps = MavenDepTreeParser().parse(dependencies)
+            source = file if file is not None else dependencies
+            _run_analysis(
+                parsed_deps,
+                source_file=source,
+                output_format=output_format,
+                output_dir=output_dir,
+                no_transitive=True,
+                verbose=verbose,
+                cache=cache,
+            )
+        else:
+            if verbose:
+                click.echo(f"Parsing {Path(file).name}...")  # type: ignore[arg-type]
+            parsed_deps = MavenParser().parse(file)  # type: ignore[arg-type]
+            _run_analysis(
+                parsed_deps,
+                source_file=file,  # type: ignore[arg-type]
+                output_format=output_format,
+                output_dir=output_dir,
+                no_transitive=no_transitive,
+                verbose=verbose,
+                cache=cache,
+            )
+    finally:
+        if cache is not None:
+            cache.close()
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _init_cache(
+    rebuild_cache: bool, cache_ttl: int, verbose: bool
+) -> VulnerabilityCache | None:
+    """
+    Optionally clear and then create the vulnerability cache.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    if rebuild_cache:
+        delete_database()
+        if verbose:
+            click.echo("Vulnerability cache cleared.")
+
+    return VulnerabilityCache(ttl_days=cache_ttl) if cache_ttl > 0 else None
+
+
+def _run_analysis(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    dependencies: list[Dependency],
+    source_file: str,
+    output_format: str,
+    output_dir: str,
+    no_transitive: bool,
+    verbose: bool,
+    cache: VulnerabilityCache | None,
+) -> None:
+    """
+    Resolve transitive dependencies (unless skipped), scan for vulnerabilities,
+    and write the requested reports.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    if not dependencies:
+        click.echo("No runtime dependencies found.", err=True)
+
+    if verbose:
+        click.echo(f"Found {len(dependencies)} direct dependencies.")
+
+    if not no_transitive:
+        if verbose:
+            click.echo("Resolving transitive dependencies from Maven Central...")
+        TransitiveResolver().resolve_all(dependencies)
+
+    if verbose:
+        click.echo("Scanning for vulnerabilities...")
+
+    osv = OsvScanner(cache=cache)
+    ghsa = GhsaScanner(cache=cache)
+    _scan_all(dependencies, osv, ghsa, verbose)
+
+    result = ScanResult(source_file=source_file, dependencies=dependencies)
+
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    _write_reports(result, Path(output_dir), output_format, verbose)
+
+    click.echo(
+        f"\nScan complete. "
+        f"{result.total_dependencies} dependencies, "
+        f"{result.total_vulnerabilities} vulnerabilities found."
+    )
+
+
+def _scan_all(
+    dependencies: list[Dependency],
+    osv: OsvScanner,
+    ghsa: GhsaScanner,
+    verbose: bool,
+) -> None:
+    """
+    Recursively scan all dependencies (direct + transitive) for vulnerabilities.
+
+    Uses the GitHub Advisory Database (GHSA) as the primary source.  When GHSA
+    returns no results -- either because the API failed or no advisories were
+    found -- the OSV.dev scanner is used as a fallback.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    for dep in dependencies:
+        if verbose:
+            click.echo(f"  Scanning {dep.coordinates}...")
+        ghsa_vulns = ghsa.scan(dep)
+        dep.vulnerabilities = ghsa_vulns if ghsa_vulns else osv.scan(dep)
+        _scan_all(dep.transitive_dependencies, osv, ghsa, verbose)
+
+
+def _write_reports(
+    result: ScanResult, output_dir: Path, output_format: str, verbose: bool
+) -> None:
+    """
+    Write one or both report formats based on the --output-format flag.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    stem = Path(result.source_file).stem
+
+    if output_format in ("json", "all"):
+        json_path = output_dir / f"{stem}-report.json"
+        JsonReporter().report(result, str(json_path))
+        if verbose:
+            click.echo(f"JSON report: {json_path}")
+
+    if output_format in ("html", "all"):
+        html_path = output_dir / f"{stem}-report.html"
+        HtmlReporter().report(result, str(html_path))
+        if verbose:
+            click.echo(f"HTML report: {html_path}")

java_dependency_analyzer/models/__init__.py

@@ -0,0 +1,11 @@
+"""
+models package.
+
+Data models for the Java Dependency Analyzer.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"