NullPath

NullPath is a static analysis tool for Java designed to detect NullPointerException (NPE) issues. It leverages the Tai-e static analysis framework to perform a deep and precise analysis of Java bytecode or source code. Compared to existing approaches, NullPath can efficiently discover much more NPE bugs while maintaining a reasonable precision. Statically finding NPEs is valuable because it helps prevent runtime errors, improves application reliability, and enhances overall software quality by identifying potential crashes before they occur in production.

Getting Started

As NullPath is built upon Tai-e, its prerequisites and fundamental build procedures are consistent with Tai-e. The primary difference in the build process is the addition of a specific Gradle task, nullpath, designed to generate a JAR file with pascal.taie.analysis.bugfinder.pathsensnullpointer.NullPointerMain as its main entry point.

Build the Project: NullPath uses Gradle for its build system. To generate the specific NullPath JAR with NullPointerMain as the entry point, run: bash ./gradlew nullpath The resulting JAR (e.g., nullpath-[version].jar) will typically be found in the build/libs/ directory. For the command examples below, we'll refer to this as nullpath.jar. Please check your build output for the precise filename.

For other build operations consistent with Tai-e (like generating a `tai-e-all.jar` if configured), you would use the standard Tai-e Gradle tasks (e.g., `./gradlew fatJar`).

How to Run NullPath (command-line options)?

As NullPath is built upon Tai-e, its command-line parameters and general usage align with Tai-e's conventions. For comprehensive details on all available Tai-e command-line options, please consult the official Tai-e Command-Line Options Documentation.

NullPath offers two primary ways to execute the NPE detection analysis:

1. Using NullPointerMain (Recommended for Standard NPE Detection)

To simplify the execution of NPE detection, which involves a complex set of underlying analyses and parameters, NullPath provides a dedicated entry point: pascal.taie.analysis.bugfinder.pathsensnullpointer.NullPointerMain. This method conveniently bundles all the required analysis configurations.

In most cases, you only need to specify the parameters related to the program you want to analyze (i.e., Tai-e's "Program options").

Command Example:

java -jar build/libs/nullpath.jar -cp <path_to_java_project_classes_or_jar> -m <main_class_of_target_project> [other_program_options]

• build/libs/nullpath.jar: The runnable fat JAR for NullPath. Remember to use the actual filename generated in your build/libs/ directory.
• -cp <path_to_java_project_classes_or_jar>: This is the classpath for the Java project you want to analyze. This can be a path to a directory containing .class files, or a path to a JAR file.
• -m <main_class_of_target_project>: The fully qualified name of the main class of the application you are analyzing (e.g., com.example.MyApplication). This helps Tai-e determine the entry points for the analysis.
• [other_program_options]: Additional Tai-e program options, such as -java <version> to specify the Java version of the target project. Refer to the Tai-e documentation for defaults and available program options.

This command will run the pre-configured set of analyses for NPE detection on the specified target program.

Output: The analysis results, including detected potential NullPointerExceptions, are typically printed to the console or logged to files (as configured by Log4j2 within Tai-e). The NullPointerResultProcessor component is responsible for formatting and presenting these findings.

2. Using Tai-e's pascal.taie.Main (For Advanced Control)

If you require more fine-grained control over the analysis process (e.g., specifying parameters for pointer analysis, or modifying the analysis chain), you can directly use Tai-e's original Main class (pascal.taie.Main).

When using this approach, you will need to manually specify all relevant analysis options (the -a flags as used in Tai-e), including those specific to path-sens-nullpointer, its dependencies, and any custom configurations you require, in addition to the program options.

Conceptual Example:

java -cp build/libs/nullpath.jar pascal.taie.Main \\\
     -cp <path_to_java_project_classes_or_jar> \\\
     -m <main_class_of_target_project> \\\
     -a must-alias \\\n     -a non-null \\\n     -a icfg \\\n     -a side-effect \\\n     -a cg \\\n     -a null-slice \\\n     -a path-sens-nullpointer \\\n     -a nullpointer-result-processor \\\n     -a \"pta=cs:2-type;plugins:[pascal.taie.analysis.bugfinder.pathsensnullpointer.NullPointerAnalysis,pascal.taie.analysis.pta.plugin.NumberLiteralHandler];propagate-types:[reference,null,int,long,boolean];\" \\\
     [other_tai-e_options]

To get the exact list of analyses and their configurations as bundled in NullPointerMain, you can refer to the src/main/java/pascal/taie/analysis/bugfinder/pathsensnullpointer/NullPointerMain.java source file.

Acknowledgements

• This project is built using the Tai-e static analysis framework. We extend our gratitude to the Tai-e developers and contributors for their excellent work. You can find the Tai-e framework at https://github.com/pascal-lab/Tai-e.