🛡️ UnCheckGuard – SCAM 2025 Artifact

• Authors: Vinayak Sharma, Patrick Lam
• Persistent paper link: Detecting Exception-Related Behavioural Breaking Changes with UnCheckGuard (preprint)
• Conference: IEEE International Conference on Source Code Analysis and Manipulation (SCAM) 2025
• DOI (Artifact): Zenodo DOI link
• Abstract / Artifact Description: This artifact is a Dockerized version of the research tool UnCheckGuard. It is a research tool for detecting newly added unchecked exceptions in upgraded Java libraries that may cause behavioral breaking changes (BBCs) in client applications. Given a client repository and commit (or a batch of repositories), it automatically clones, builds, and analyzes both the old and updated library versions, compares exception-throwing behavior, and identifies affected client call sites. The artifact includes all required Java code, Python scripts, datasets, and step-by-step instructions to fully reproduce the results reported in the associated paper, along with an automated summary report generated at the end of each run.

This repository contains the Dockerized artifact for UnCheckGuard, enabling easy setup and execution in a controlled environment.
The original main repository is available at: https://github.com/vinayaksh42/UncheckedException

---

🏷️ Badges Claimed

• Open Research Object – This artifact is publicly available in a persistent archival repository with a DOI, is released under an OSI-approved open-source license, and includes complete documentation and source code.

• Research Object Reviewed – This artifact is complete, consistent with the associated paper, well-documented, and fully exercisable via Docker. It includes all necessary data, code, and scripts to reproduce the results, along with clear step-by-step instructions and automated summary reporting.

---

📄 License

This artifact is released under the MIT License license. See LICENSE.md for details.
OSI-approved license ✔ — requirement for the Open Research Object badge.

---

🖥 Requirements

• Hardware:
  • CPU: 2+ cores
  • RAM: 8 GB minimum
  • Disk: 10 GB free space
• Software:
  • Docker ≥ 20.10
  • Python3 (if running the summary python script manually)
  • Tested on:
    • Ubuntu 24.04 LTS
    • Windows 11
• Skills & Knowledge:
  • Docker Usage
  • Python
  • Java

No proprietary software or special hardware is required.

---

⚙️ Installation

1. Clone the repository

git clone https://github.com/vinayaksh42/uncheckguard-docker.git
cd uncheckguard-docker

2. Build the Docker image

docker build -t artifactuncheckguard:latest .
mkdir results

Note: The command to build the Docker image takes around 60 seconds to 100 seconds (depending on internet bandwidth).

3. Verify installation

docker run --rm artifactuncheckguard:latest --help

Expected output:

Usage:
  docker run ... run  <file.txt>                   # Batch Analysis
  docker run ... analyzeClient <repo> <commit>     # Targeted Analysis

---

🚀 Running the Tool

1️⃣ Targeted Analysis on a Specific Client

Targeted Analysis: Analyze a single client repository at a specific commit to check for potential behavioral breaking changes caused by newly added unchecked exceptions in its dependencies.

docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest analyzeClient <repoOwner/repoName> <commitHash>

Example:

docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest analyzeClient a63881763/HttpAsyncClientUtils 4eff19ca23d587654ecb022c7178c29ab0aaca68

---

2️⃣ Analysis on a List of Clients

Batch Analysis: Analyze multiple clients in one run using a list of repositories, enabling large-scale evaluation similar to the experiments in the paper.

docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run <path/to/list.txt>

The text file containing the list of clients should be placed within the scripts/ folder before building the image.

Example:

docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run clientDataSet.txt

File format (list.txt):

repoOwner/repoName

---

📊 Reproducing Paper Results

The file clientDataSet.txt contains all the clients showcased in the paper’s findings. To reproduce them, from scratch:

docker build -t artifactuncheckguard:latest .
mkdir results
docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run clientDataSet.txt

Note: The results in the summary may differ from those in the research paper because the tool analyzes the latest available library versions at runtime. A library may receive new updates after this artifact is published, which can change the analysis outcomes.

Time Estimate: Running this script can take approximately 16 hours.

---

📊 Automatic Run Summary

At the end of both Docker commands —

docker run ... analyzeClient <repo> <commit>
docker run ... run <file.txt>

the scripts/summarize_results.py script is executed automatically.

It reads results/results.csv from the run and prints a summary that includes:

• Unique libraries analyzed
• Unique Client–Library pairs
• Total matched methods (possible BBC call sites)
• Libraries with at least one matched method
• Total library usage calls
• Total unique clients
• Semantic Version Change Types — classification of each impactful LibraryOld → LibraryNew pair with > 0 matched methods as major, minor, patch, none, or unknown.

The same summary is also saved to results/summary.json for later reference.

---

📌 Mapping to Paper Results

Paper Result	Command	Output Location
Library-Client pairs, libraries, callsites	docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run clientDataSet.txt	results/ Summary.json
Table 1: Exception Analysis Funnel	docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run clientDataSet.txt	results/ Summary.json
Table 2: Distribution of reachable newly-added exceptions across version types	docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run clientDataSet.txt	results/ Summary.json
Table 3: Clients, libraries,versions, andcountsofcallsitesreachingnewly-addedexceptions	docker run --rm -v "$(pwd)/results:/app/results" artifactuncheckguard:latest run clientDataSet.txt	results/ results.csv

---

📁 Output

All results are stored in the mounted results/ directory on your host machine. Additional outputs:

• Match/
• LibraryResult/
• CompareResult/

---

🔍 Implementation Discussion

The artifact’s core functionality — detecting newly added unchecked exceptions between two versions of a Java library and mapping them to client call sites — is implemented primarily in the Java sources under src/.

• ConfigLoader.java
  • Reads and validates configuration settings.
• DriverStubGenerator.java
  • Generates driver stubs for taint analysis based on the library methods under inspection.
• JavaCompilerUtil.java
  • Utility to compile Java source code programmatically during analysis.
• Main.java
  • Entry point for the analysis tool. Parses command-line arguments, loads configuration, and coordinates the client–library analysis pipeline.
  • Collects the external methods present in the client application.
  • Collects the public methods present in the java library under analysis.
  • Performs the call graph based analysis on library for finding and storing all the exceptions thrown by the method.
• RunFlowDroid.java
  • Integrates with the FlowDroid taint analysis framework to trace data flows from client inputs to library throw statements.
  • Provides the information required for creating the DriverStub and XML file.
  • Sets the configuration for taint analysis.
• StmtCallGraphVisitor.java
  • Implements the logic for traversing library bytecode, identifying newly added throw statements, and determining their reachability.
• StmtClientVisitor.java
  • Implements the logic for traversing client bytecode to identify external method calls.
• XMLGenerator.java
  • Produces XML files describing the analysis results, used as input to taint analysis.

---

📂 Repository Structure

├── Dockerfile               # Docker build instructions
├── LICENSE.md               # License information
├── README.md                # This file
├── scripts/                 # Helper scripts for running the Java-based analysis
├── results/                 # Output directory (contains csv files)
├── main.pdf/                # SCAM 2025 research paper
├── requirements.txt/        # Python requirements
├── run.sh/                  # shell script commands for running analysis
├── src/                     # Java program (client-library analysis)
├── savedResults/            # Contains the saved results from the run of scripts/clientDataSet.txt list

More information about each script can be found in the scripts/ folder’s README. The src/ folder contains the Java application responsible for analyzing client applications as well as libraries.

The src/main/resources/config.properties contains the configuration required by the Java program.

---

📬 Contact

For questions or support, contact:

• Vinayak Sharma – [email protected]
• Patrick Lam – [email protected]