java-dependency-analyzer 1.3.0

Java Dependency Analyzer is a tool that inspects dependencies.

Java Dependency Analyzer 1.3.0

A Python CLI tool that inspects Java dependency hierarchies in Maven and Gradle projects and reports known vulnerabilities.

Prerequisites

• Python ^3.14
• Poetry 2.2

Installation

Via pip (recommended)

Install directly from PyPI:

pip install java-dependency-analyzer

From source

Clone the repository and install all dependencies using Poetry:

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
--project	-p		Root directory of the project to analyse. When supplied, the dependency tree is generated automatically and FILE / --dependencies must not be used.
--java-home		(system JAVA_HOME)	Directory to use as JAVA_HOME. Can only be used with --project.
--use-wrapper		false	Use the project wrapper script (gradlew/mvnw) instead of the system build tool. Can only be used with --project.
--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	./reports	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.

Exit Codes

Code	Meaning
0	Scan completed successfully; no vulnerabilities found.
10	Scan completed successfully; at least one vulnerability was detected.

Analysing a project directly (--project)

When a Gradle or Maven project is available locally, pass its root directory to --project and jda will generate the dependency tree automatically before scanning:

# Gradle project using the system gradle
jda gradle --project /path/to/my-project

# Maven project using the project wrapper, with a custom JAVA_HOME
jda maven --project /path/to/my-project --use-wrapper --java-home /usr/lib/jvm/java-21

• --java-home overrides the JAVA_HOME environment variable for the invocation. If neither is set, the command fails with a clear error.
• --use-wrapper invokes gradlew/gradlew.bat (Gradle) or mvnw/mvnw.cmd (Maven) from the project root. A UsageError is raised when the wrapper script is absent.
• --project is mutually exclusive with both FILE and --dependencies.

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:

jda maven pom.xml

Analyse a Gradle build file and write only an HTML report to ./reports/:

jda gradle build.gradle -f html -o reports/

Analyse direct dependencies only, with verbose output:

jda gradle build.gradle.kts --no-transitive -v

Scan using a pre-resolved Gradle dependency tree (skips transitive resolution):

jda gradle --dependencies runtime.txt -f json -o reports/

Scan using a pre-resolved Maven dependency tree (skips transitive resolution):

jda maven --dependencies maven.txt -f json -o reports/

Analyse a Gradle project directly (auto-generates the dependency tree):

jda gradle --project /path/to/my-gradle-project --use-wrapper

Analyse a Maven project directly with a custom JAVA_HOME:

jda maven --project /path/to/my-maven-project --java-home /usr/lib/jvm/java-21

Configuration

Environment Variable	Required	Default	Description
GITHUB_TOKEN	No	(none)	A GitHub personal access token. When set, the GhsaScanner uses it to authenticate requests to the GitHub Advisory Database REST API, which significantly increases the rate limit (from ~60 unauthenticated requests/hour to 5 000 authenticated requests/hour). Without it, scans with many dependencies may trigger HTTP 403/429 responses and fall back to the OSV.dev API.
GHSA_API_URL	No	https://api.github.com/advisories	Override the GitHub Advisory Database REST API endpoint used by GhsaScanner. Useful for proxies or air-gapped mirrors.
OSV_QUERY_URL	No	https://api.osv.dev/v1/query	Override the OSV.dev single-query endpoint used by OsvScanner.
OSV_VULN_URL	No	https://osv.dev/vulnerability/	Override the OSV.dev vulnerability detail base URL embedded in reports.
MAVEN_CENTRAL_URL	No	https://repo1.maven.org/maven2	Override the Maven Central repository URL used by TransitiveResolver to fetch POM files.

Set it in your shell or in a .env file in the working directory before running jda:

# shell
export GITHUB_TOKEN=ghp_yourTokenHere

# or in .env
GITHUB_TOKEN=ghp_yourTokenHere

Logging

The tool writes logs to java_dependency_analyzer.log in the current working directory, in addition to printing them to the console (stderr).

Logging requires a logging.ini file to be present in the working directory or any of its parent directories. The logger walks up the directory tree until it finds one.

When installed via pip, no logging.ini is bundled. Without it the tool falls back to console-only logging (no log file is created). To enable file logging, copy logging.ini from the repository to your working directory:

curl -O https://raw.githubusercontent.com/rcw3bb/java-dependency-analyzer/master/logging.ini

Then run jda from that same directory.

Architecture

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 batch API for known CVEs.
GhsaScanner	scanners/ghsa_scanner.py	Queries the GitHub Advisory Database REST API for security advisories; automatically falls back to OSV when rate-limited (HTTP 403/429).
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.
xml_helpers	util/xml_helpers.py	Shared POM XML utilities: POM_NS constant and detect_pom_namespace() for handling namespace-qualified and namespace-free POM documents.
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):

poetry install

Running Tests

Run the full test suite with coverage and generate an HTML report:

poetry run pytest --cov=java_dependency_analyzer tests --cov-report html

Code Quality

Format and lint the source code (linter must score 10/10):

poetry run black java_dependency_analyzer
poetry run pylint java_dependency_analyzer

Publishing to PyPI

Prerequisites

• A PyPI account with an API token.

Configure the token

poetry config pypi-token.pypi <your-token>

Build and publish

poetry publish --build

This builds the source distribution and wheel, then uploads them to PyPI in one step.

Note: PyPI releases are immutable. Once a version is published, it cannot be overwritten.
To fix a mistake, yank the release via the PyPI web UI and publish a new version.

Changelog

Author

Ron Webb <[e-mail]>