Classport is a tool to enable accurate runtime inspection of the supply chain in Maven Java programs.
Classport's main objective is to make software supply chain information available at runtime.
To reach this goal it:
- Embeds supply chain metadata in each class file that is to be part of the application during build time.
- Monitors the class loaded by the running application and extracts the embedded Software Supply Chain information from the loaded classes.
In this way, Classport is able to accurately connect the loaded classes to their corresponding upstream dependencies and build a runtime representation of the application’s code-related supply chain.
The picture gives an overview of the structure of Classport. The structure is divided into two phases: Embedding phase and Extracting Phase.
The inputs of this phase are the dependency JARs and the project source files.
The embedder is responsible for embedding the supply chain information in the form of Java Annotations into the class files.
This feature is implemented by the Maven plugin that
modifies the JAR files during the build process and is contained in the classport.commons module.
The embedded class files can be packaged together with the application, or just added to the classpath in place of the "regular" versions of the class files.
This is the phase in which the supply chain information is extracted.
It can be done dynamically or statically.
The classport.agent
package contains a Java agent that can be run alongside the Classport-ified JAR.
This agent logs all the supply-chain data for classes that get loaded,
and prints a dependency tree from these at the end. This way, the dependency tree
will consist of only those dependencies that were actually used at runtime.
The classport.analyser package contains two tools for statically analysing
and modifying JAR files.
Package all the modules. From the root of the Classport project:
mvn packageUse the Maven plugin to embed supply chain information into the class files of the project using the embed goal. From the root directory of the analysed Maven project:
mvn io.github.chains-project:classport-maven-plugin:0.1.0-SNAPSHOT:embedThe embed goal of the Maven plugin retrieves a list of project dependencies and their corresponding JAR files, embeds the annotation into all class files within each JAR, and recreates what can be seen as a dependency-only Maven local repository in the classport-files directory.
The JAR files from within there can then be included in the class path with the -cp flag as per usual.
For projects that get packaged into an Uber-JAR:
mvn package -Dmaven.repo.local=classport-filesFor multi-module projects, package each project separately as dependency properties may differ (e.g. a direct dependency for one module is a transitive one for another).
Use the agent to detect the used classes:
java -javaagent:<path-to-agent-jar> -jar <path-to-app-jar>This command outputs the runtime representation of the software supply chain of the analysed project:
classport-deps-list--> flat list of dependenciesclassport-deps-tree--> tree of dependnecies
This is the command to perform static analysis:
java -jar <path-to-analyzer-jar> -<printList|printTree|generateTestJar> <jarFile> [classes-to-be-ignored]The available flags are:
-printList, for statically generating a flat list of dependencies. Below is an example of the command output on a simple Java application with only one dependency.
org.apache.commons:commons-lang3:jar:3.17.0
-printTree, for staticaly generating a dependencies tree. Below is an example of the command output on a simple Java application with only one dependency.
org.example:hello:jar:0.1.0
\- org.apache.commons:commons-lang3:jar:3.17.0
-generateTestJar, for generating a JAR file where the main class has been modified to force-load classes from all dependencies.
- Maven
- Java >= 17