Skip to content

Home

Jump to bottom
smarkwal edited this page Apr 18, 2019 · 11 revisions

JarHC - JAR Health Check

JarHC is a static analysis tool to help you find your way through "JAR hell" or "classpath hell".

Its main purpose is to analyze a set of JAR files (*.jar) and check whether they are compatible on a binary level, and whether they contain any "unpleasant surprises" for you.

Motivation

If you don't know what JAR hell is, check out these articles:

How JarHC works

The input to JarHC is a set of JAR files, called the "classpath". This is usually a bunch of third-party libraries used in a Java project. JarHC analyzes these JAR files and generates a report for various aspects:

  • JAR Files: List of JAR files found in classpath with information like file size, number of classes and resources, whether the JAR file is a multi-release JAR or a JPMS module, the SHA-1 checksum, and Maven artifact coordinates (if the checksum is found on Maven Central).
  • Class Versions: Java versions for which the classes in the JAR files have been compiled. This allows you to find the "minimum Java version" required to run all classes.
  • JAR Dependencies: Dependencies between JAR files ("uses" and "used by").
  • Packages: List of packages per JAR file. Also checks for split packages (packages found in multiple JAR files) and "fat JARs" (JARs with a mix of very different packages, potentially because multiple JAR files have been merged).
  • Duplicate Classes: Java classes which exist in more than one JAR file and Java classes found in the classpath shadowing classes with the same name in the underlying JDK/JRE implementation. Also checks how "similar" those duplicate classes are (exact copy, same API, ...). Resources (files other than Java class files) found in more than one JAR file under the exact same path and name.
  • Binary Compatibility: Validates superclass and interface contracts, method calls, and field access. Reports missing classes, methods, or fields. Validates access permissions.
  • Blacklist: Use of dangerous, unsafe, unstable, or deprecated classes and methods, like "sun.misc.Unsafe" or "System.exit(...)", or annotations like @Beta or @Deprecated.
  • Java Runtime: Information about the Java runtime installation.

Planned:

  • Report usage of native code.
  • Check if JAR files are signed. Report signing information and validate the signatures.
  • Report unused JAR files.
  • Check if JAR files have known vulnerabilities (based on NVD database).

Usage

JarHC is currently only avaiable as command line application:

java -jar jarhc-1.1-with-deps.jar [options] <path> [<path>]*

where <path> is an absolute or relative path to a JAR file, a directory with JAR files, or Maven artifact coordinates of the form "<GroupID>:<ArtifactID>:<Version>". In case of a directory, all JAR files found in that directory and any subdirectories (recursive) are included in the analyis.

If <path> is a path to a WAR file, JarHC includes all JAR files from /WEB-INF/lib folder in the analysis.

Options

Report format

-f <type> | --format <type>

Report format: "text" or "html".

Default value is "text".

Report file path

-o <file> | --output <file>

Report file path. If this option is not present, the report is printed to STDOUT.

Note: If a file is specified but no format, JarHC tries to guess the format based on the filename extension:

  • *.txt -> text report
  • *.html -> HTML report

Report title

-t <title> | --title <title>

Report title.

Default: "JAR Health Check Report".

Example: -t "MyApp 1.0"

Report sections

-s <sections> | --sections <sections>

List of sections to include in the report.

Default: [none] (include all sections).

Example: -s "jf,cv,jd"

If the list of sections is prefixed with '-' the given sections are excluded. Example: -s "-p,bc,bl"

Sections:

  • jf - JAR Files
  • cv - Class Versions
  • jd - JAR Dependencies
  • p - Packages
  • dc - Duplicate Classes
  • bc - Binary Compatibility
  • bl - Blacklist
  • jr - Java Runtime

Classpath

--cp <path> | --classpath <path>

Instead of passing JAR files as arguments, you can also use the option "--classpath". As for arguments, this option supports passing a JAR file, a directory with JAR files, a WAR file, or Maven artifact coordinates.

Example: --classpath myapp-1.0.jar,mylib-1.0.jar,libs

Provided and runtime classpath

--provided <path>
--runtime <path>

Specify additional paths to JAR files or directories with JAR files handled as "provided" or "runtime" (JDK/JRE) libraries. Those JAR files are not analyzed, but references to them are validated.

The value for these options can be a single JAR file, a single directory, or a comma-separated list of JAR files and/or directories. These options can also be used multiple times to add multiple JAR files or directories.

Example: --provided servlet-api-3.0.jar,jsp-api-3.0.jar --runtime $JAVA_HOME/jre/lib

JAR file names

--remove-version
--use-artifact-name

Those two options can be used to "normalize" the JAR file names. This is useful if you later want to compare/diff two reports which were created with different versions of some libraries.

With "--remove-version", JarHC will try to remove the version number from the JAR file name. Example: "asm-tree-7.0.jar" becomes "asm-tree.jar". Note that the algorithm used to find and remove a version number is fuzzy. If third-party developers use non-standard version number schemes, JarHC may fail to remove the complete version number.

With "--use-artifact-name", JarHC will re-generate the JAR file name from the artifact coordinates (if available). Example: "l4j-127.jar" may become "log4j-1.2.7.jar".

You can also combine the two options, in which case JarHC will generate a JAR file name based on the artifact ID but without version number. Example: "l4j-127.jar" may become "log4j.jar".

Those options only have an impact on the JAR file names as they are shown in the report. The actual JAR files on disk are of course not renamed.

Reports

The report is available in text or HTML format.

Example reports

For ASM 7.0: Text report | HTML report

Dependencies

JarHC has dependencies on the following third-party libraries:

Requirements

  • JarHC requires at least Java 8.
  • JarHC has been tested with Java 8 - Java 11.

Note: JarHC is able to analyze Java classes compiled for Java 1.0 to Java 11, independent of which Java version is used to run JarHC.

Downloads

Releases

Version 1.1

  • Feature: Support for nested JAR files ("JARs in JARs").
  • Change: Combine Class Hierarchy analyzer, Missing Classes analyzer, Method References analyzer, and Field References analyzer into a new Binary Compatibility analyzer.
  • Change: Merge Shadowed Classes analyzer and Duplicate Resources analyzer into Duplicate Classes analyzer.
  • Change: Merge Unstable APIs analyzer into Blacklist analyzer.
  • Feature: Binary Compatibility: If a class is not found, check if the package of the class exists. If the package does exist, it is probably a compatibility issue. Otherwise, it is more likely a missing (potentially optional) dependency.

Licenses

JarHC is released under the Apache License version 2.

ASM is released under a 3-Clause BSD License.

org.json / JSON In Java is released unter The JSON License

Developers

JarHC - JAR Health Check

Website: http://jarhc.org

Twitter: @JarHealthCheck

JarHC - JAR Health Check | jarhc.org

JarHC - JAR Health Check

Clone this wiki locally