Classport

Classport is a passport for Java classes.

It is a JVM instrumentation agent and Maven plugin that embeds and retrieves dependency metadata (GAV: Group, Artifact, Version) directly from Java .class files. It enables runtime introspection of runtime dependencies in Java.

🎯 Motivation

Java applications often rely on third-party libraries via Maven, but all dependency metadata is lost once the application is packaged and deployed. This creates blind spots for:

• Vulnerability scanners
• Runtime permission enforcement

🧩 Classport solves this by preserving dependency origin metadata all the way to runtime.

🚀 Key Features

• 🔍 Embeds Maven GAV coordinates as runtime-visible annotations into compiled .class files.
• 🎯 Retrieves this metadata at runtime using a lightweight Java agent.
• 🧪 Compatible with real-world projects and benchmarks (see classport-experiments).

⚙️ How It Works

Classport has two components:

Component	Description
🧵 Embedder	A Maven plugin that injects GAV metadata as Java annotations into every .class file.
🕵️ Introspector	A Java agent that dynamically inspects dependencies at runtime to retrieve their GAV info.

🛠️ Getting Started

Requirements

• Java 17+
• Maven 3.8+

Setup

Clone and install the project.

git clone git@github.com:chains-project/classport.git
cd classport
mvn clean install -DskipTests

How to use

In order to achieve runtime dependencies introspection with classport, you have to first embed and then to run the instrospector together with you application.

1. Embed Inside the target project folder.

Add the following profile to the pom.xml file of the project you want to embed. To try out introspection, you should add this to the pom.xml file of the project which generates the executable jar (with Main-Class in the manifest).

<profile>
  <id>embed</id>
  <build>
    <plugins>
      <plugin>
        <groupId>io.github.project</groupId>
        <artifactId>classport-maven-plugin</artifactId>
        <version>0.1.0-SNAPSHOT</version>
        <executions>
          <execution>
            <id>classport-embed</id>
            <goals>
              <goal>embed</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

Then run the following command to embed the dependencies into the project.

mvn clean package -DskipTests -Pembed

2. Introspect

java -javaagent:classport-instr-agent/target/classport-instr-agent-0.1.0-SNAPSHOT.jar=<name-of-the-project>,<path-to-output-dir>,dependency -jar <path-to-jar-of-the-target-app> [optional-args-of-the-target-app]

Note:

• name-of-the-project can be any name and it is used to build the name of the output file.
• path-to-output-dir must be a path of an existing folder

Example of usage

Run the following command from the root folder of Classport to try out the example. Or you may also see the test under EmbeddingMojoIT.java.

cd resources/simple-app-monitoring

# Embed
mvn clean package -DskipTests -Pembed

# Introspect
mkdir output
java -javaagent:../../classport-instr-agent/target/classport-instr-agent-0.1.0-SNAPSHOT.jar=test,./output,dependency -jar target/test-agent-app-1.0-SNAPSHOT.jar

In the output folder there will be the csv file with the resulting detected runtime dependencies.

This is the expected output.

group,artefact,version
org.apache.commons,commons-lang3,3.17.0
com.example,test-agent-app,1.0-SNAPSHOT