java-serialization 0.1.0

# java-serialization-rs

[**English**](README.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)

基于 [Java 对象序列化规范](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/protocol.html) 的 Java 对象序列化流解析器，使用 Rust 编写。

## 特性

- 完整支持 Java 序列化协议（magic `0xACED`，版本 5）
- 支持所有类型码：`TC_OBJECT`、`TC_ARRAY`、`TC_CLASSDESC`、`TC_ENUM`、`TC_PROXYCLASSDESC`、`TC_STRING`、`TC_LONGSTRING` 等
- 块数据（Block Data）和注解（Annotation）解析
- 句柄引用解析（通过 `TC_REFERENCE` 的反向引用）
- 自动适配 JDK 8u20 漏洞利用载荷（缺失 `TC_ENDBLOCKDATA` 时自动重试）
- 可选 `serde` 支持，支持 JSON 等格式输出
- 通过 35 个 ysoserial gadget chain 载荷测试验证

## 快速开始

在 `Cargo.toml` 中添加依赖：

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

解析序列化流：

```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 支持

启用 `serde` feature 可将解析结果序列化为 JSON 或其他格式：

```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 预处理

JDK 8u20 漏洞利用载荷在 `TC_REFERENCE` 引用句柄 `0x7e0009` 后省略了 `TC_ENDBLOCKDATA` 字节，导致标准解析器失败。`parse_serialization_stream` 在首次解析失败时会自动重试预处理。你也可以手动应用预处理：

```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 概览

| 类型 | 说明 |
|------|------|
| [`SerializationStream`] | 顶层解析结果，包含版本号和内容列表 |
| [`StreamObject`] | 所有对象类型的枚举（NewObject、NewArray、NewString、NewEnum 等） |
| [`ClassDesc`] | 类描述符（普通类或代理类） |
| [`FieldValue`] | 基本类型或对象字段值 |
| [`BlockData`] | 块数据（短格式或长格式） |

[`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

## 测试

```bash
cargo test                    # 运行所有测试
cargo test --all-features     # 包含 serde feature
cargo clippy --all-features -- -D warnings  # 代码检查
```

测试套件通过 35 个 ysoserial 生成的 `.ser` 文件进行验证，涵盖 CommonsCollections、Spring、Groovy、Clojure、Hibernate 等多种 gadget chain。

## 安全声明

本项目**仅作为解析器**——不会执行或实例化任何 Java 对象。`testcases/` 目录中的 `.ser` 文件仅用于测试解析器对已知 Java 反序列化载荷格式的正确性。

这些文件由 [ysoserial](https://github.com/frohoff/ysoserial) 生成，仅适用于**经授权的安全研究、漏洞评估和教育目的**。请勿对未经授权的系统使用这些载荷。

## 许可证

[MIT](LICENSE)