java-dependency-analyzer 1.0.0__tar.gz

java_dependency_analyzer-1.0.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: java-dependency-analyzer
+Version: 1.0.0
+Summary: Java Dependency Analyzer is a tool that inspects dependencies.
+Author: Ron Webb
+Author-email: ron@ronella.xyz
+Requires-Python: >=3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: beautifulsoup4 (>=4.14.3,<5.0.0)
+Requires-Dist: click (>=8.3.1,<9.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: lxml (>=6.0.2,<7.0.0)
+Requires-Dist: python-dotenv (>=1.2.2,<2.0.0)
+Description-Content-Type: text/markdown
+
+# Java Dependency Analyzer 1.0.0
+
+> A Python CLI tool that inspects Java dependency hierarchies in Maven and Gradle projects and reports known vulnerabilities.
+
+## Prerequisites
+
+- Python `^3.14`
+- [Poetry](https://python-poetry.org/) `2.2`
+
+## Installation
+
+Clone the repository and install all dependencies:
+
+```bash
+git clone <repository-url>
+cd java-dependency-analyzer
+poetry install
+```
+
+## Usage
+
+```
+jda <COMMAND> [OPTIONS] [FILE]
+```
+
+`COMMAND` is one of `gradle` or `maven`.
+
+### gradle
+
+```
+jda gradle [OPTIONS] [FILE]
+```
+
+`FILE` is the path to a `build.gradle` or `build.gradle.kts` file.
+Omit `FILE` when supplying `--dependencies`.
+
+### maven
+
+```
+jda maven [OPTIONS] [FILE]
+```
+
+`FILE` is the path to a `pom.xml` file.
+Omit `FILE` when supplying `--dependencies`.
+
+### Options (both subcommands)
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--dependencies` | `-d` | | Path to a pre-resolved dependency tree text file (see below). When supplied, parsing and transitive resolution are skipped. |
+| `--output-format` | `-f` | `all` | Report format: `json`, `html`, or `all` (both). |
+| `--output-dir` | `-o` | `.` | Directory to write the report file(s) into. |
+| `--no-transitive` | | `false` | Skip transitive dependency resolution; analyse direct dependencies only. |
+| `--verbose` | `-v` | `false` | Print progress messages to the console. |
+| `--rebuild-cache` | | `false` | Delete the vulnerability cache before scanning. |
+| `--cache-ttl` | | `7` | Cache TTL in days. Set to `0` to disable caching. |
+
+### Pre-resolved dependency trees (`--dependencies`)
+
+When a Gradle or Maven project already has a dependency tree available (e.g. from CI), you can pass it directly to skip the parser and transitive resolver:
+
+- **Gradle**: generate with `gradle dependencies --configuration runtimeClasspath > gradle.txt`
+- **Maven**: generate with `mvn dependency:tree -Dscope=runtime > maven.txt`
+
+The report will reflect the exact tree from the file, including all transitive dependencies.
+
+### Examples
+
+Analyse a Maven POM and produce both JSON and HTML reports in the current directory:
+
+```bash
+jda maven pom.xml
+```
+
+Analyse a Gradle build file and write only an HTML report to `./reports/`:
+
+```bash
+jda gradle build.gradle -f html -o reports/
+```
+
+Analyse direct dependencies only, with verbose output:
+
+```bash
+jda gradle build.gradle.kts --no-transitive -v
+```
+
+Scan using a pre-resolved Gradle dependency tree (skips transitive resolution):
+
+```bash
+jda gradle --dependencies runtime.txt -f json -o reports/
+```
+
+Scan using a pre-resolved Maven dependency tree (skips transitive resolution):
+
+```bash
+jda maven --dependencies maven.txt -f json -o reports/
+```
+
+## Architecture
+
+```mermaid
+graph TD
+    CLI["jda CLI (cli.py)"] --> Parser["DependencyParser (ABC)"]
+    Parser --> MavenParser
+    Parser --> GradleParser
+    Parser --> MavenDepTreeParser
+    Parser --> GradleDepTreeParser
+    CLI --> Resolver["TransitiveResolver<br/>(Maven Central)"]
+    CLI --> Scanner["VulnerabilityScanner (ABC)"]
+    Scanner --> OsvScanner["OsvScanner<br/>(OSV.dev API)"]
+    Scanner --> GhsaScanner["GhsaScanner<br/>(GitHub Advisory DB)"]
+    OsvScanner --> Cache["VulnerabilityCache<br/>(SQLite)"]
+    GhsaScanner --> Cache
+    CLI --> Reporter["Reporter (ABC)"]
+    Reporter --> JsonReporter
+    Reporter --> HtmlReporter
+    MavenParser --> Dependency["Dependency / Vulnerability<br/>Dataclasses"]
+    GradleParser --> Dependency
+    MavenDepTreeParser --> Dependency
+    GradleDepTreeParser --> Dependency
+    Resolver --> Dependency
+    OsvScanner --> Dependency
+    GhsaScanner --> Dependency
+    JsonReporter --> ScanResult["ScanResult"]
+    HtmlReporter --> ScanResult
+    Dependency --> ScanResult
+```
+
+### Components
+
+| Component | Location | Responsibility |
+|---|---|---|
+| CLI | `java_dependency_analyzer/cli.py` | Entry point (`gradle` / `maven` subcommands); orchestrates parsing, resolving, scanning, and reporting. |
+| `MavenParser` | `parsers/maven_parser.py` | Parses `pom.xml`, resolves `${property}` placeholders, filters by runtime scope. |
+| `GradleParser` | `parsers/gradle_parser.py` | Parses Groovy DSL (`build.gradle`) and Kotlin DSL (`build.gradle.kts`) files. |
+| `MavenDepTreeParser` | `parsers/maven_dep_tree_parser.py` | Parses `mvn dependency:tree` text output into a full dependency tree. |
+| `GradleDepTreeParser` | `parsers/gradle_dep_tree_parser.py` | Parses `gradle dependencies` text output into a full dependency tree. |
+| `TransitiveResolver` | `resolvers/transitive.py` | Fetches transitive dependencies by downloading POM files from Maven Central. |
+| `OsvScanner` | `scanners/osv_scanner.py` | Queries the [OSV.dev](https://osv.dev/) batch API for known CVEs. |
+| `GhsaScanner` | `scanners/ghsa_scanner.py` | Queries the [GitHub Advisory Database](https://github.com/advisories) REST API for security advisories. |
+| `VulnerabilityCache` | `cache/vulnerability_cache.py` | SQLite-backed cache for raw vulnerability API payloads with configurable TTL. |
+| `DatabaseManager` | `cache/db.py` | Manages SQLite connection lifecycle and schema initialisation. |
+| `JsonReporter` | `reporters/json_reporter.py` | Writes a `ScanResult` to a JSON file. |
+| `HtmlReporter` | `reporters/html_reporter.py` | Renders a `ScanResult` to a styled HTML report via a Jinja2 template. |
+
+## Development Setup
+
+Install all dependencies (including dev tools):
+
+```bash
+poetry install
+```
+
+### Running Tests
+
+Run the full test suite with coverage and generate an HTML report:
+
+```bash
+poetry run pytest --cov=java_dependency_analyzer tests --cov-report html
+```
+
+### Code Quality
+
+Format and lint the source code (linter must score 10/10):
+
+```bash
+poetry run black java_dependency_analyzer
+poetry run pylint java_dependency_analyzer
+```
+
+## [Changelog](CHANGELOG.md)
+
+## Author
+
+Ron Webb &lt;ron@ronella.xyz&gt;
+

java_dependency_analyzer-1.0.0/README.md

@@ -0,0 +1,175 @@
+# Java Dependency Analyzer 1.0.0
+
+> A Python CLI tool that inspects Java dependency hierarchies in Maven and Gradle projects and reports known vulnerabilities.
+
+## Prerequisites
+
+- Python `^3.14`
+- [Poetry](https://python-poetry.org/) `2.2`
+
+## Installation
+
+Clone the repository and install all dependencies:
+
+```bash
+git clone <repository-url>
+cd java-dependency-analyzer
+poetry install
+```
+
+## Usage
+
+```
+jda <COMMAND> [OPTIONS] [FILE]
+```
+
+`COMMAND` is one of `gradle` or `maven`.
+
+### gradle
+
+```
+jda gradle [OPTIONS] [FILE]
+```
+
+`FILE` is the path to a `build.gradle` or `build.gradle.kts` file.
+Omit `FILE` when supplying `--dependencies`.
+
+### maven
+
+```
+jda maven [OPTIONS] [FILE]
+```
+
+`FILE` is the path to a `pom.xml` file.
+Omit `FILE` when supplying `--dependencies`.
+
+### Options (both subcommands)
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--dependencies` | `-d` | | Path to a pre-resolved dependency tree text file (see below). When supplied, parsing and transitive resolution are skipped. |
+| `--output-format` | `-f` | `all` | Report format: `json`, `html`, or `all` (both). |
+| `--output-dir` | `-o` | `.` | Directory to write the report file(s) into. |
+| `--no-transitive` | | `false` | Skip transitive dependency resolution; analyse direct dependencies only. |
+| `--verbose` | `-v` | `false` | Print progress messages to the console. |
+| `--rebuild-cache` | | `false` | Delete the vulnerability cache before scanning. |
+| `--cache-ttl` | | `7` | Cache TTL in days. Set to `0` to disable caching. |
+
+### Pre-resolved dependency trees (`--dependencies`)
+
+When a Gradle or Maven project already has a dependency tree available (e.g. from CI), you can pass it directly to skip the parser and transitive resolver:
+
+- **Gradle**: generate with `gradle dependencies --configuration runtimeClasspath > gradle.txt`
+- **Maven**: generate with `mvn dependency:tree -Dscope=runtime > maven.txt`
+
+The report will reflect the exact tree from the file, including all transitive dependencies.
+
+### Examples
+
+Analyse a Maven POM and produce both JSON and HTML reports in the current directory:
+
+```bash
+jda maven pom.xml
+```
+
+Analyse a Gradle build file and write only an HTML report to `./reports/`:
+
+```bash
+jda gradle build.gradle -f html -o reports/
+```
+
+Analyse direct dependencies only, with verbose output:
+
+```bash
+jda gradle build.gradle.kts --no-transitive -v
+```
+
+Scan using a pre-resolved Gradle dependency tree (skips transitive resolution):
+
+```bash
+jda gradle --dependencies runtime.txt -f json -o reports/
+```
+
+Scan using a pre-resolved Maven dependency tree (skips transitive resolution):
+
+```bash
+jda maven --dependencies maven.txt -f json -o reports/
+```
+
+## Architecture
+
+```mermaid
+graph TD
+    CLI["jda CLI (cli.py)"] --> Parser["DependencyParser (ABC)"]
+    Parser --> MavenParser
+    Parser --> GradleParser
+    Parser --> MavenDepTreeParser
+    Parser --> GradleDepTreeParser
+    CLI --> Resolver["TransitiveResolver<br/>(Maven Central)"]
+    CLI --> Scanner["VulnerabilityScanner (ABC)"]
+    Scanner --> OsvScanner["OsvScanner<br/>(OSV.dev API)"]
+    Scanner --> GhsaScanner["GhsaScanner<br/>(GitHub Advisory DB)"]
+    OsvScanner --> Cache["VulnerabilityCache<br/>(SQLite)"]
+    GhsaScanner --> Cache
+    CLI --> Reporter["Reporter (ABC)"]
+    Reporter --> JsonReporter
+    Reporter --> HtmlReporter
+    MavenParser --> Dependency["Dependency / Vulnerability<br/>Dataclasses"]
+    GradleParser --> Dependency
+    MavenDepTreeParser --> Dependency
+    GradleDepTreeParser --> Dependency
+    Resolver --> Dependency
+    OsvScanner --> Dependency
+    GhsaScanner --> Dependency
+    JsonReporter --> ScanResult["ScanResult"]
+    HtmlReporter --> ScanResult
+    Dependency --> ScanResult
+```
+
+### Components
+
+| Component | Location | Responsibility |
+|---|---|---|
+| CLI | `java_dependency_analyzer/cli.py` | Entry point (`gradle` / `maven` subcommands); orchestrates parsing, resolving, scanning, and reporting. |
+| `MavenParser` | `parsers/maven_parser.py` | Parses `pom.xml`, resolves `${property}` placeholders, filters by runtime scope. |
+| `GradleParser` | `parsers/gradle_parser.py` | Parses Groovy DSL (`build.gradle`) and Kotlin DSL (`build.gradle.kts`) files. |
+| `MavenDepTreeParser` | `parsers/maven_dep_tree_parser.py` | Parses `mvn dependency:tree` text output into a full dependency tree. |
+| `GradleDepTreeParser` | `parsers/gradle_dep_tree_parser.py` | Parses `gradle dependencies` text output into a full dependency tree. |
+| `TransitiveResolver` | `resolvers/transitive.py` | Fetches transitive dependencies by downloading POM files from Maven Central. |
+| `OsvScanner` | `scanners/osv_scanner.py` | Queries the [OSV.dev](https://osv.dev/) batch API for known CVEs. |
+| `GhsaScanner` | `scanners/ghsa_scanner.py` | Queries the [GitHub Advisory Database](https://github.com/advisories) REST API for security advisories. |
+| `VulnerabilityCache` | `cache/vulnerability_cache.py` | SQLite-backed cache for raw vulnerability API payloads with configurable TTL. |
+| `DatabaseManager` | `cache/db.py` | Manages SQLite connection lifecycle and schema initialisation. |
+| `JsonReporter` | `reporters/json_reporter.py` | Writes a `ScanResult` to a JSON file. |
+| `HtmlReporter` | `reporters/html_reporter.py` | Renders a `ScanResult` to a styled HTML report via a Jinja2 template. |
+
+## Development Setup
+
+Install all dependencies (including dev tools):
+
+```bash
+poetry install
+```
+
+### Running Tests
+
+Run the full test suite with coverage and generate an HTML report:
+
+```bash
+poetry run pytest --cov=java_dependency_analyzer tests --cov-report html
+```
+
+### Code Quality
+
+Format and lint the source code (linter must score 10/10):
+
+```bash
+poetry run black java_dependency_analyzer
+poetry run pylint java_dependency_analyzer
+```
+
+## [Changelog](CHANGELOG.md)
+
+## Author
+
+Ron Webb &lt;ron@ronella.xyz&gt;

java_dependency_analyzer-1.0.0/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-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-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-1.0.0/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)