Added support for automatic switch between fast and slow dumping.

BenjaminSoelberg · BenjaminSoelberg · commit b3202b17419a · 2025-09-19T08:21:51.000+02:00
Updated readme.
Sorted classes in jar.
diff --git a/README.md b/README.md
@@ -1,96 +1,74 @@
-# Java Forensics Toolkit
+# Easy and compact Java Forensics Toolkit
 
 ![broken java cup](BrokenJavaCup.jpg)
 
-A little *Java Forensics Toolkit* that can dump all loaded classes within a JVM
+# Java Forensics Toolkit
+
+The **Java Forensics Toolkit** is a lightweight JVM agent that allows you to **inspect, snapshot, and export all loaded classes** from a running Java process.<br>
+Designed for **forensic analysis, debugging, and reverse engineering**, making it easier to discover unexpected or malicious code inside live JVMs.
+
+## Features
+
+- 📦 **Snapshot all loaded classes** – capture bytecode *after* any runtime transformations.
+- 🔍 **Class loader analysis** – see which classes exist in which class loader.
+- 🛡️ **Security investigations** – detect hidden, injected, or malicious classes.
+- 🧩 **Reverse engineering** – dumped classes can be decompiled with standard tools.
+- 🎯 **Flexible filters** – include/exclude classes with regex filters.
+- ⚡ **Simple usage** – attach to any running JVM by PID with a single command.
+
+## Installation
+
+Download the latest release JAR from [here](https://github.com/BenjaminSoelberg/JavaForensicsToolkit/releases).
+
+## Usage
+
 ```
+java -jar JavaForensicsToolkit-<version>.jar 
+
+---------------------------------------------------------
+--> Java Forensics Toolkit v1.0.2 by Benjamin Sølberg <--
+---------------------------------------------------------
+https://github.com/BenjaminSoelberg/JavaForensicsToolkit
+
 usage: java -jar JavaForensicsToolkit.jar [-v] [-e] [-d destination.jar] [-f filter]... [-x] <pid>
 
 options:
--v	verbose agent logging
--e	agent will log to stderr instead of stdout
--d	jar file destination of dumped classes
-	Relative paths will be relative with respect to the target process.
-	A jar file in temp will be generated if no destination was provided.
--f	regular expression class name filter
-	Can be specified multiple times.
--x	exclude classes matching the filter
-pid	process id of the target java process
+-v      verbose agent logging
+-e      agent will log to stderr instead of stdout
+-d      jar file destination of dumped classes
+        Relative paths will be relative with respect to the target process.
+        A jar file in temp will be generated if no destination was provided.
+-f      regular expression class name filter
+        Can be specified multiple times.
+-x      exclude classes matching the filter
+pid     process id of the target java process
 
 example:
 java -jar JavaForensicsToolkit.jar -d dump.jar -f java\\..* -f sun\\..* -f jdk\\..* -f com\\.sun\\..* -x 123456
 ```
 
-A small report with information about each class is generated and placed in the destination jar as well.
+## Example
+
+Dump all non-JDK classes from a running process with PID 123456:
 
-Here is an example:
 ```
-$ java -jar JavaForensicsToolkit.jar -v 24576
---------------------------------------------------------
---> Java Forensics Toolkit v1.00 by Benjamin Sølberg <--
---------------------------------------------------------
-https://github.com/BenjaminSoelberg/JavaForensicsToolkit
+java -jar JavaForensicsToolkit.jar -v -d dump.jar -f java\\..* -f sun\\..* -f jdk\\..* -f com\\.sun\\..* -x 123456
+```
 
-Injecting agent into JVM with pid: 24576
-Dumping classes to: /tmp/dump-24651-9890604330559988075.jar
---------------------------------------------------------
---> Java Forensics Toolkit v1.00 by Benjamin Sølberg <--
---------------------------------------------------------
-https://github.com/BenjaminSoelberg/JavaForensicsToolkit
+## Typical Use Cases
 
-Agent loaded with options: -v -d /tmp/dump-24651-9890604330559988075.jar -f .* 24576
-
-Querying classes...
-
-Dumping started...
-Ignoring io/github/benjaminsoelberg/jft/Transformer
-Ignoring io/github/benjaminsoelberg/jft/ParserException
-Ignoring io/github/benjaminsoelberg/jft/Utils
-Ignoring io/github/benjaminsoelberg/jft/Options
-Ignoring io/github/benjaminsoelberg/jft/ClassInfo
-Ignoring io/github/benjaminsoelberg/jft/Report
-Ignoring io/github/benjaminsoelberg/jft/ClassDumper
-Ignoring io/github/benjaminsoelberg/jft/DummyRunner
-Dumping java.io.FileOutputStream$1
-Dumping java.util.Vector$Itr
-Dumping java.util.concurrent.ConcurrentLinkedQueue$CLQSpliterator
-Dumping java.util.zip.ZipOutputStream$XEntry
-...
-Dumping java.lang.Throwable
-Dumping java.lang.System
-Dumping java.lang.ClassLoader
-Dumping java.lang.Cloneable
-Dumping java.lang.Class
-Dumping java.lang.reflect.Type
-Dumping java.lang.reflect.GenericDeclaration
-Dumping java.lang.reflect.AnnotatedElement
-Dumping java.lang.String
-Dumping java.lang.CharSequence
-Dumping java.lang.Comparable
-Dumping java.io.Serializable
-Dumping java.lang.Object
-
-Creating jar...
-Class info: java.io.FileOutputStream$1@null@0 726 bytes
-Class info: java.util.Vector$Itr@null@0 2492 bytes
-Class info: java.util.concurrent.ConcurrentLinkedQueue$CLQSpliterator@null@0 3608 bytes
-Class info: java.util.zip.ZipOutputStream$XEntry@null@0 563 bytes
-Class info: java.time.chrono.IsoChronology@null@0 11739 bytes
-Class info: java.time.chrono.AbstractChronology@null@0 15281 bytes
-Class info: java.time.chrono.Chronology@null@0 8639 bytes
-Class info: java.time.temporal.TemporalAdjusters@null@0 6423 bytes
-Class info: java.time.LocalDate@null@0 27720 bytes
-...
-Class info: java.time.chrono.ChronoLocalDate@null@0 9575 bytes
-Class info: java.time.zone.ZoneOffsetTransition@null@0 6109 bytes
-Class info: java.time.temporal.ValueRange@null@0 4463 bytes
-Class info: java.math.BigInteger@null@0 59485 bytes
-Class info: java.time.Duration@null@0 18086 bytes
-Class info: java.time.temporal.TemporalAmount@null@0 399 bytes
-Class info: java.lang.Comparable@null@0 235 bytes
-Class info: java.io.Serializable@null@0 113 bytes
-Class info: java.lang.Object@null@0 1944 bytes
-
-Dumped classes, including report.txt, can be found in: /tmp/dump-24651-9890604330559988075.jar
-Done
-```
+- 🔐 **Malware hunting** – identify injected or malicious classes hidden inside a compromised JVM.
+- 🛠️ **Debugging classpath issues** – find out which versions of classes are actually loaded and by which class loaders.
+- 📊 **Security audits** – verify that only expected code is running inside production JVMs.
+- 🕵️ **Incident response** – capture a live snapshot of loaded classes for later offline analysis.
+- ⚙️ **Reverse engineering & research** – decompile transformed classes to understand runtime modifications (e.g. instrumentation, bytecode weaving, or AOP frameworks).
+
+## How It Works
+
+1) **Attach to target JVM**<br>The toolkit uses the standard com.sun.tools.attach API to connect to a running Java process by PID.
+2) **Load agent**<br>Once attached, it dynamically loads a lightweight Java agent into the target JVM without requiring a restart.
+3) **Enumerate classes**<br>The agent queries the JVM for all currently loaded classes and their associated class loaders.
+4) **Dump bytecode**<br>Each class is retrieved as it exists in memory after any transformations (e.g. instrumentation, weaving, or obfuscation).
+5) **Write output**<br>The classes are packaged into a JAR file (either user-specified or temporary) for convenient storage and analysis.
+
+This approach ensures the dumped classes reflect the exact state of the JVM at runtime, providing a faithful snapshot for investigation.
diff --git a/src/main/java/io/github/benjaminsoelberg/jft/ClassDumper.java b/src/main/java/io/github/benjaminsoelberg/jft/ClassDumper.java
@@ -17,6 +17,8 @@ public class ClassDumper {
     // Public and non-final for testing purposes only.
     public static String TEST_AGENT_CMD_LINE = null;
 
+    public static final int DUMP_BATCH_SIZE = 500;
+
     public static void agentmain(String cmdline, Instrumentation instrumentation) throws Exception {
         // We are unable to parse arguments to agentmain while running unit test, hence this inject-hook
         if (TEST_AGENT_CMD_LINE != null) {
@@ -31,27 +33,44 @@ public static void agentmain(String cmdline, Instrumentation instrumentation) th
 
         report.println("Querying classes...");
         Class<?>[] classes = Arrays.stream(instrumentation.getAllLoadedClasses())
-                .filter(clazz -> !clazz.isArray())
-                .filter(clazz -> !clazz.isSynthetic())
                 .filter(instrumentation::isModifiableClass)
                 .filter(clazz -> options.getFilterPredicate().test(clazz.getName()))
-                .toArray(Class[]::new);
+                .toArray(Class<?>[]::new);
         report.println("");
 
-        if (classes.length == 0) {
-            report.println("WARNING: No classes were found, bad filter ?%n");
-        }
-
         // The transformer could (as a side effect by the JVM) be called with classes not in the list which is why we pass the filtered classes to it as well
-        Transformer dumper = new Transformer(report, Arrays.asList(classes));
+        Transformer dumper = new Transformer(report, classes);
 
-        // Invoke the transformer and remove it when filtered classes are processed
-        report.println("Dumping started...");
-        instrumentation.addTransformer(dumper, true);
-        try {
-            instrumentation.retransformClasses(classes);
-        } finally {
-            instrumentation.removeTransformer(dumper);
+        if (classes.length > 0) {
+            report.println("%d classes found.%n", classes.length);
+            instrumentation.addTransformer(dumper, true);
+
+            report.println("Dumping started...");
+
+            // Invoke the transformer and remove it when filtered classes are processed
+            try {
+                for (int from = 0; from < classes.length; from += DUMP_BATCH_SIZE) {
+                    int to = Math.min(from + DUMP_BATCH_SIZE, classes.length);
+                    Class<?>[] batch = Arrays.copyOfRange(classes, from, to);
+                    try {
+                        // Transform the full batch in one go, and if this throws an exception, no classes have been retransformed.
+                        instrumentation.retransformClasses(batch);
+                    } catch (Throwable ignored) {
+                        // Transform classes one-by-one if batch transformation failed
+                        for (Class<?> clazz : batch) {
+                            try {
+                                instrumentation.retransformClasses(clazz);
+                            } catch (Throwable th) {
+                                report.println("Failed to dump %s", clazz.getName());
+                            }
+                        }
+                    }
+                }
+            } finally {
+                instrumentation.removeTransformer(dumper);
+            }
+        } else {
+            report.println("WARNING: No classes found, bad filter ?%n");
         }
         report.println("");
 
@@ -66,10 +85,10 @@ public static void agentmain(String cmdline, Instrumentation instrumentation) th
 
         report.println("Creating jar...");
         try (JarOutputStream jar = new JarOutputStream(new FileOutputStream(destination))) {
-            dumper.getClassInfos().forEach(classInfo -> {
+            dumper.getClassInfos().stream().sorted().forEach(classInfo -> {
                 try {
                     report.dump(classInfo);
-                    writeZipEntry(jar, classInfo.getClassName() + ".class", classInfo.getBytecode());
+                    writeZipEntry(jar, classInfo.getNativeClassName() + ".class", classInfo.getBytecode());
                 } catch (IOException e) {
                     throw new RuntimeException(e);
                 }
@@ -87,7 +106,7 @@ private static void writeZipEntry(JarOutputStream jar, String name, byte[] data)
     private static String getHeader() {
         return "" +
                 "---------------------------------------------------------%n" +
-                "--> Java Forensics Toolkit v1.0.1 by Benjamin Sølberg <--%n" +
+                "--> Java Forensics Toolkit v1.0.2 by Benjamin Sølberg <--%n" +
                 "---------------------------------------------------------%n" +
                 "https://github.com/BenjaminSoelberg/JavaForensicsToolkit%n%n";
     }
diff --git a/src/main/java/io/github/benjaminsoelberg/jft/ClassInfo.java b/src/main/java/io/github/benjaminsoelberg/jft/ClassInfo.java
@@ -2,7 +2,7 @@
 
 import java.security.ProtectionDomain;
 
-public class ClassInfo {
+public class ClassInfo implements Comparable<ClassInfo> {
     private final String nativeClassName;
     private final ClassLoader classLoader;
     private final ProtectionDomain protectionDomain;
@@ -51,4 +51,9 @@ public byte[] getBytecode() {
     public String toString() {
         return String.format("%s@%s %d bytes", getClassName(), getClassLoaderName(), bytecode.length);
     }
+
+    @Override
+    public int compareTo(ClassInfo o) {
+        return getNativeClassName().compareTo(o.getNativeClassName());
+    }
 }
diff --git a/src/main/java/io/github/benjaminsoelberg/jft/Transformer.java b/src/main/java/io/github/benjaminsoelberg/jft/Transformer.java
@@ -2,6 +2,7 @@
 
 import java.lang.instrument.ClassFileTransformer;
 import java.security.ProtectionDomain;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 import java.util.concurrent.ConcurrentLinkedQueue;
@@ -13,9 +14,9 @@ public class Transformer implements ClassFileTransformer {
     private final List<Class<?>> classes;
     private volatile Throwable lastException;
 
-    public Transformer(Report report, List<Class<?>> classes) {
+    public Transformer(Report report, Class<?>[] classes) {
         this.report = report;
-        this.classes = classes;
+        this.classes = Arrays.asList(classes);
     }
 
     @Override
@@ -28,7 +29,7 @@ public byte[] transform(ClassLoader loader, String nativeClassName, Class<?> cla
         try {
             // Ignore our own classes
             if (nativeClassName.startsWith(FILTER_JFT_CLASSES)) {
-                report.println("Ignoring %s", nativeClassName);
+                report.println("Ignoring %s", classBeingRedefined.getName());
                 return null;
             }
 
