java-serialization 0.1.0

Java object serialization stream parser written in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# java-serialization-rs

**English** | [**中文**](README.zh.md)

[![CI](https://github.com/ejfkdev/java-serialization-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/ejfkdev/java-serialization-rs/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/java-serialization.svg)](https://crates.io/crates/java-serialization)
[![Documentation](https://docs.rs/java-serialization/badge.svg)](https://docs.rs/java-serialization)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-1.71%2B-orange.svg)](https://www.rust-lang.org/)
[![MSRV](https://img.shields.io/badge/MSRV-1.71-blue.svg)](https://blog.rust-lang.org/2023/07/13/Rust-1.71.0.html)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
[![Lines of Code](https://tokei.rs/b1/github/ejfkdev/java-serialization-rs)](https://github.com/XAMPPRocky/tokei)

A Java object serialization stream parser written in Rust, based on the [Java Object Serialization Specification](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/protocol.html).

## 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`:

```toml
[dependencies]
java-serialization = "0.1"
```

Parse a serialization stream:

```rust
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:

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

```rust
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:

```rust
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) |

[`SerializationStream`]: https://docs.rs/java-serialization/latest/java_serialization/struct.SerializationStream.html
[`StreamObject`]: https://docs.rs/java-serialization/latest/java_serialization/enum.StreamObject.html
[`ClassDesc`]: https://docs.rs/java-serialization/latest/java_serialization/enum.ClassDesc.html
[`FieldValue`]: https://docs.rs/java-serialization/latest/java_serialization/enum.FieldValue.html
[`BlockData`]: https://docs.rs/java-serialization/latest/java_serialization/enum.BlockData.html

## Testing

```bash
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](https://github.com/frohoff/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](LICENSE)