java-serialization-rs

English | 中文

A Java object serialization stream parser written in Rust, based on the Java Object Serialization Specification.

Features

Full support for Java serialization protocol (magic 0xACED, version 5)
All type codes: TC_OBJECT, TC_ARRAY, TC_CLASSDESC, TC_ENUM, TC_PROXYCLASSDESC, TC_STRING, TC_LONGSTRING, etc.
Block data and annotation parsing
Handle reference resolution (back-references via TC_REFERENCE)
Automatic JDK 8u20 exploit payload adaptation (missing TC_ENDBLOCKDATA retry)
Optional serde support for JSON/other format output
Tested against 35 ysoserial gadget chain payloads

Quick Start

Add to your Cargo.toml:

[dependencies]
java-serialization = "0.1"

Parse a serialization stream:

use java_serialization::parse_serialization_stream;

let data = std::fs::read("payload.ser")?;
let (_, stream) = parse_serialization_stream(&data)?;
for obj in stream.objects() {
    println!("{:?}", obj);
}

Serde Support

Enable the serde feature to serialize parsed structures to JSON or other formats:

[dependencies]
java-serialization = { version = "0.1", features = ["serde"] }

use java_serialization::parse_serialization_stream;

let data = std::fs::read("payload.ser")?;
let (_, stream) = parse_serialization_stream(&data)?;
let json = serde_json::to_string_pretty(&stream)?;
println!("{}", json);

JDK 8u20 Preprocessing

JDK 8u20 exploit payloads omit a TC_ENDBLOCKDATA byte after a TC_REFERENCE to handle 0x7e0009, causing standard parsers to fail. parse_serialization_stream automatically retries with preprocessing on failure. You can also apply it manually:

use java_serialization::{parse_serialization_stream, preprocess_jdk8u20};

let data = std::fs::read("JDK8u20.ser")?;
let preprocessed = preprocess_jdk8u20(&data);
let (_, stream) = parse_serialization_stream(&preprocessed)?;

API Overview

Type	Description
`SerializationStream`	Top-level parsed stream with version and contents
`StreamObject`	Enum of all object types (NewObject, NewArray, NewString, NewEnum, etc.)
`ClassDesc`	Class descriptor (normal or proxy)
`FieldValue`	Primitive or object field value
`BlockData`	Block data (short or long)

Testing

cargo test              # run all tests
cargo test --all-features  # include serde feature
cargo clippy --all-features -- -D warnings  # lint

The test suite validates against 35 ysoserial-generated .ser files covering gadget chains including CommonsCollections, Spring, Groovy, Clojure, Hibernate, and more.

Security Disclaimer

This project is a parser only — it does not execute or instantiate any Java objects. The .ser files in the testcases/ directory are included solely for testing parser correctness against known Java deserialization payload formats.

These files are generated by ysoserial and are intended for authorized security research, vulnerability assessment, and educational purposes only. Do not use them against systems you do not own or have explicit permission to test.

License

MIT

java-serialization 0.1.0