Jirubizu/reclass-rs
GitHub: Jirubizu/reclass-rs
一款用 Rust 编写的 Linux 原生实时内存查看器，用于交互式地重建运行中进程的内存结构体布局并导出为 C/C++/Rust 代码。
Stars: 9 | Forks: 1
# reclass-rs
一个原生的 Linux 平台、[ReClass.NET](https://github.com/ReClassNET/ReClass.NET) 风格的**实时内存查看器**，用于重建正在运行的进程的内存布局——使用 Rust 编写，无需 Mono/WinForms。
你将一个 *class* 定义为一个有序的、具有类型的 *fields* 列表；reclass-rs 会解析基址，每秒重新读取目标内存几次，并渲染每个字段的 **offset / address / type / name / value / 原始字节**，且支持内联编辑。将其指向一个进程，交互式地构建 struct，跟随 pointer 链，并将结果导出为 C / C++ / Rust。
## 核心亮点
- **实时批量读取。** 渲染循环会收集所有可见的地址，并在每个 pointer 链级别上仅发出**一次** scatter read（`process_vm_readv`）——绝不是每个字段一次系统调用。支持部分读取，因此超出其映射的 class 仍然会显示已映射的前缀。
- **完整的 ReClass 风格节点集：** `Hex8/16/32/64`、有符号/无符号整数、`Float`、`Double`、`Bool`、`Vec2/3/4`、`Text`/`WText`、`Pointer`、`FunctionPtr`、`Array[N]`、内联 `ClassInstance`、`ClassPtr`、`Padding`、`Unknown`，以及汇编大小关键字（`byte/word/dword/qword/tword/oword/yword/zword`）。
- **派生的 offset** 会在每次结构编辑时重新计算并重新缓存；内联 `ClassInstance` 的循环会被检测并拒绝（`ClassPtr` 循环是可以的——因为它们是一个读取边界）。
- **地址表达式：** ` + 0x10`、`[0xADDR]`、`[ + 0x10] + 0x20`，支持 `+ - * /`。
- **egui 桌面 UI**（默认）和基于相同核心的 **ratatui 终端 UI**（`--tui`）：
- 彩色、等宽字体、虚拟化表格（包含数千个字段也很流畅），支持水平滚动；
- **可折叠的** array / class 实例 / pointer；
- 左键单击类型可进行更改；右键单击行可进行重命名 / 删除 / 插入 / *为 pointer 的目标添加字节*；
- 多选行（Click / Ctrl / Shift）+ `Delete`；class 列表操作相同；
- 批量**添加字节**和 **Array 构建器**（`element × count`）；
- **全部展开 / 全部折叠**，以及一个用于隐藏 Classes 面板并专注于内存的 **View** 菜单；
- **值更改闪烁**，会逐渐淡出，便于轻松发现实时变化；
- 内联编辑 value、名称和注释，并回写到目标中。
- **进程选择器**、**内存映射视图**和**项目保存/加载** (RON)，会记住附加的进程名称，并在加载时**自动附加**。
- **设置**窗口（*View → Settings*）持久化到 `~/.config/reclass-rs/settings.ron`：值更改高亮颜色 + 淡出效果 + 开/关、新 class 的默认字段类型（例如 `Hex64` → `Int64`）和种子行数，以及渲染的最大数组元素数。
- **代码生成**，支持 C、C++ 和 Rust (`#[repr(C, packed)]`)，并将 offset 作为注释——生成的 Rust 代码的 `size_of`/`offset_of` 与模型匹配（已通过测试验证）。
- **可选的 ptrace 访问追踪器**（`access-tracker` feature）：通过 x86-64 硬件断点实现“是哪条指令写入/访问了这个地址”。
## 试一试 — playground
一个自包含的 C 目标程序包含一个实时修改的 `Player` struct（以及它所指向的一个 `Weapon`），位于 [`examples/playground`](examples/playground/)，并提供完整的**[引导教程](examples/playground/README.md)**。构建它，附加，并实时重建 struct——没有游戏，没有反作弊，使用默认的 ptrace 设置：
## 架构
所有内容都通过 trait 与内存后端解耦，因此整个模型和渲染循环都可以使用内存中的 fake 进行单元测试——不需要实时的进程。
```
flowchart LR
UI["UI
egui + ratatui"] <--> CORE["core
nodes · classes · expr · engine"] CORE <--> BE["MemoryBackend (trait)"] BE --- VMEM["backend-vmem
(over vmem)"] BE --- MOCK["MockBackend
(tests / benches)"] ``` ``` pub trait MemoryBackend { fn read(&self, addr: u64, buf: &mut [u8]) -> Result<(), MemError>; fn write(&self, addr: u64, data: &[u8]) -> Result<(), MemError>; fn read_scatter(&self, reqs: &mut [ScatterReq<'_>]) -> Result<(), MemError>; fn regions(&self) -> Result, MemError>;
fn module_base(&self, name: &str) -> Option;
}
```
### 工作区布局
```
reclass-rs/
crates/
core/ # reclass-core — no UI, no vmem dep; nodes, classes, expr, engine, codegen, project
backend-vmem/ # reclass-backend-vmem — MemoryBackend over the `vmem` crate (+ smoke CLI, access tracker)
app/ # reclass — egui (default) + ratatui (--tui) front-ends
docs/vmem-api.md # vmem capability → API mapping
```
## 前置条件
- **Rust**（stable，2024 edition）——推荐使用 `rustup`。
- [`vmem`](https://github.com/Jirubizu/vmem) crate 被检出到**同级目录中**：
git clone https://github.com/Jirubizu/reclass-rs # this repo
- 用于读取另一个进程的 **ptrace 权限**。对于开发来说，最简单的方法是：
sudo sysctl -w kernel.yama.ptrace_scope=0
或者授予 `cap_sys_ptrace`、以 root 身份运行，或者只附加到你自己的后代进程。跨进程的 I/O 使用 `process_vm_readv`/`writev`，因此对于普通的读取/写入，不需要 `ptrace`-stop。
## 构建与运行
```
cd reclass-rs
# desktop (egui) UI — 启动时通过 pid 附加并指向一个 address
cargo run --release -p reclass -- --pid 1234 --addr 0x5A3518
# terminal (ratatui) UI
cargo run --release -p reclass -- --tui --pid 1234
# CLI flags
# --pid 附加到 pid N
# --addr 填充 starter class 的 address bar（例如 0x5A3518 或 "[+0x10]"）
# --project 启动时加载已保存的项目（classes + expressions）
# --tui 使用 terminal front-end
```
### 一次性测试工具
一个微型 CLI，用于对进程进行后端的健全性检查：
```
cargo run -p reclass-backend-vmem --bin smoke -- 0x5A3518 64 # hexdump 64 bytes
cargo run -p reclass-backend-vmem --bin smoke -- --maps # list mapped regions
cargo run -p reclass-backend-vmem --bin smoke -- --modules libc.so.6
```
## 使用 UI
1. **附加** —— 输入一个 PID 并点击 *Attach*，或者从列表中选择一个进程（按名称过滤）。
2. **设置地址** —— 在地址栏中输入一个表达式（见下文）。当它解析到可读区域时，`= 0x…` 指示器会变为**绿色**，如果未映射则变为**黄色**，如果出现解析/deref 错误则变为**红色**。
3. **构建 class** —— 使用 *Add field* / *Add bytes* / *Array* 构建器，或者**左键单击字段的 Type** 进行更改。内存会实时显示；**更改的值会闪烁红光**并淡出。
4. **编辑** —— 双击 value/名称/注释进行编辑；值的编辑将被回写到目标中。
5. **跟随 pointer** —— 展开一个 `Ptr`/`ClassPtr` (▶) 来跟随它；右键单击一个 pointer → *Add bytes to target*，无需打开它即可增加指向的 class。
6. **保存/加载** —— *File → Save / Save as… / Open project…* 打开应用内文件浏览器（过滤为 `*.ron`）；*File → Open recent* 列出你最近的项目。项目格式为 RON；附加进程的**名称**会被保存，并在加载时自动重新连接。
7. **导出** —— *View → Code generation* 将注册表导出为 C / C++ / Rust。
### 地址表达式语法
| 表达式 | 含义 |
|---|---|
| `0x5A3518` | 绝对地址 |
| ` + 0x10` | 模块加载基址 + offset |
| `[0xADDR]` | pointer 大小的 dereference |
| `[ + 0x10] + 0x20` | 嵌套的 deref 然后 offset |
| `+ - * /` | 整数算术 |
### 鼠标和按键（表格）
- **单击 offset 单元格** —— 选择行 · **Ctrl-单击** 切换 · **Shift-单击** 范围 · **Delete** 删除选中项。
- **左键单击 Type** —— 更改类型 · **右键单击 offset** —— 重命名 / 插入 / 删除 / 为目标添加字节。
- **▶/▼** —— 展开/折叠 array、class 实例和 pointer。
## Feature 标志
| Crate | Feature | 默认 | 用途 |
|---|---|---|---|
| `reclass-core` | `mock` | ✅ | 内存中的 `MockBackend`（测试、基准测试、离线） |
| `reclass-core` | `serde` | ✅ | RON 项目保存/加载 |
| `reclass` (app) | `gui` | ✅ | egui 桌面前端 |
| `reclass` (app) | `tui` | ✅ | ratatui 终端前端 |
| `reclass-backend-vmem` | `access-tracker` | ❌ | ptrace 硬件断点访问追踪器（包含唯一的 `unsafe`） |
```
cargo build -p reclass-backend-vmem --features access-tracker # enable the access tracker
```
## 测试与基准测试
```
cargo test --workspace --all-features # full suite (incl. live read against a spawned child)
cargo bench -p reclass-core --bench engine # render-loop benchmarks (criterion)
```
这些基准测试证明了引擎会批量读取——一个扁平的 256 字节 / 64 字段的 class 每个 tick 仅需**一次** scatter 调用；一个深度为 4 的 pointer 链需要四次调用（每层一次）。实时内存测试会生成一个辅助子进程，如果 `ptrace` 被拒绝，则会自动跳过。
## 规范与质量标准
- Edition 2024，stable 工具链。在 `core` 中使用了 `#![forbid(unsafe_code)]`；`unsafe` 仅限于 `backend-vmem` 访问追踪器，每次调用都附有 `// SAFETY` 注释。
- 错误：库中使用 `thiserror`，应用中仅使用 `anyhow`。
- `cargo fmt --all --check` 和 `cargo clippy --all-targets --all-features -D warnings` 是整洁的；每个 `core` 模块都提供了单元测试。
- CI (`.github/workflows/ci.yml`) 运行 fmt + clippy + test + bench-compile（并将 `vmem` 作为同级目录检出）。
## 法律与道德
reclass-rs 会读取并**写入**另一个进程的内存。这样做可能会损坏或导致目标崩溃。仅在你拥有或获得明确许可进行分析的软件上使用它，并尊重你所检查程序的 EULA/Terms。本项目用于逆向工程、调试和教育——不适用于在线游戏作弊或任何未经授权的篡改。你需对自己的使用方式负责。
## 许可证
MIT —— 见 [`LICENSE`](LICENSE)。`vmem` 依赖项采用 MIT OR Apache-2.0 双重许可。
## 鸣谢
- UX 灵感来源于 [ReClass.NET](https://github.com/ReClassNET/ReClass.NET)。
- 内存后端由 [`vmem`](https://github.com/Jirubizu/vmem) 提供支持。
egui + ratatui"] <--> CORE["core
nodes · classes · expr · engine"] CORE <--> BE["MemoryBackend (trait)"] BE --- VMEM["backend-vmem
(over vmem)"] BE --- MOCK["MockBackend
(tests / benches)"] ``` ``` pub trait MemoryBackend { fn read(&self, addr: u64, buf: &mut [u8]) -> Result<(), MemError>; fn write(&self, addr: u64, data: &[u8]) -> Result<(), MemError>; fn read_scatter(&self, reqs: &mut [ScatterReq<'_>]) -> Result<(), MemError>; fn regions(&self) -> Result
标签：JARM, ReClass, Rust, 云资产清单, 内存分析, 内存结构重建, 内存读取, 可视化界面, 游戏安全, 网络流量审计, 逆向工程, 通知系统