SecurityRonin/forensic-vfs
GitHub: SecurityRonin/forensic-vfs
该项目是数字取证虚拟文件系统的核心契约库，通过定义只读字节源和递归路径定位器 trait，为磁盘镜像的分层组合与并行安全读取提供统一抽象。
Stars: 0 | Forks: 0
# forensic-vfs
[](https://crates.io/crates/forensic-vfs-core)
[](https://docs.rs/forensic-vfs-core)
[](https://www.rust-lang.org)
[](LICENSE)
[](https://github.com/sponsors/h4x0r)
[](https://github.com/SecurityRonin/forensic-vfs/actions/workflows/ci.yml)
[](https://github.com/SecurityRonin/forensic-vfs/actions/workflows/ci.yml)
[](https://github.com/rust-secure-code/safety-dance/)
**一个只读、支持定位读取的字节边界 —— `ImageSource` —— 证据堆栈中的每个磁盘、容器和文件系统读取器都使用它，因此整个证据链（`E01 → GPT → BitLocker → NTFS`）可以组合成一个单一的 `Arc`，供 N 个 worker 并行读取，且任何代码路径都无法执行写入操作。**
`forensic-vfs-core` 是通用取证 VFS 的 KNOWLEDGE-leaf 合同 crate。它定义了分层模型 —— 字节源、卷系统、加密层、文件系统，以及递归的 `PathSpec` 定位器 —— 除此之外别无其他：没有格式解析，也没有读取器依赖。读取器负责实现这些 trait；引擎（`forensic-vfs-engine`）和 `disk4n6` CLI 负责组合它们。
## 决定一切的唯一决策
```
pub trait ImageSource: Send + Sync {
fn len(&self) -> u64;
fn read_at(&self, offset: u64, buf: &mut [u8]) -> Result;
// no seek cursor, and no write method — anywhere
}
```
## 30 秒内实现一个读取器
```
use forensic_vfs_core::{ImageSource, VfsResult};
struct RawFile(std::fs::File, u64);
impl ImageSource for RawFile {
fn len(&self) -> u64 { self.1 }
fn read_at(&self, offset: u64, buf: &mut [u8]) -> VfsResult {
use std::os::unix::fs::FileExt;
Ok(self.0.read_at(buf, offset)?) // positioned, lock-free, parallel-safe
}
}
```
`forensic-vfs-core` 提供了 `FileSource`（即本 crate，跨平台）、`SubRange`（一个本身也是 `ImageSource` 的字节窗口）和 `SourceCursor`（一个用于遗留调用点的 `Read + Seek` 桥接器）—— 因此，大多数读取器都是包装现有的源，而不是从头编写一个。
## 使用 `PathSpec` 寻址任何节点
`PathSpec` 是一个递归的、自我描述的定位器，供调查发现引用并由会话重新打开。它通过规范的 URI 进行逐字节的往返转换：
```
use forensic_vfs_core::PathSpec;
let spec = PathSpec::from_uri(
"fvfs:os:%2Fevidence%2FDC01.E01|container:ewf|volume:gpt,1|fs:ntfs,p/Windows/System32/config/SYSTEM",
)?;
assert_eq!(PathSpec::from_uri(&spec.to_uri())?, spec); // lossless
# Ok::<(), forensic_vfs_core::VfsError>(())
```
`[A-Za-z0-9._-]` 之外的每个字节都会进行百分号编码，因此包含 `/` 或非 UTF-8 文件名的 Windows 路径也能原封不动地保留。凭据永远不会存储在地址中——它们是在解析时通过带外方式提供的。
## 信任但验证
- **无 panic。** `unsafe_code = forbid`；在生产环境中不使用 `unwrap`/`expect`/`panic!`；每一次偏移量/长度的读取都会经过有界读取器，当超出范围时返回 0，绝不 panic。
- **经过模糊测试。** `PathSpec` 的 URI 解析器和有界读取器都经过了模糊测试——执行了 1570 万 + 2020 万次，没有发生 panic，且往返不变式始终保持成立。
- **100% 行覆盖率**，每个 trait 的对象安全性均通过一个经由 `Arc` 驱动的读取器双重实现得到了验证。
## 适用场景
`forensic-vfs-core` 实现了通用取证 VFS 的第一阶段。其上层目前正在开发中：
| Crate | 角色 | 状态 |
|---|---|---|
| **`forensic-vfs-core`** | 字节源、卷/加密/文件系统 trait、`PathSpec` | 本 crate |
| `forensic-vfs-engine` | 覆盖所有读取器的注册表 + 图解析器 | 计划中 |
| `disk-forensic` / `disk4n6` | 引擎之上的轻量级 CLI | 迭代演进中 |
请在 [`disk-forensic`](https://github.com/SecurityRonin/disk-forensic/blob/main/docs/design/2026-07-06-universal-forensic-vfs.md) 中查看设计方案。
[隐私政策](https://securityronin.github.io/forensic-vfs/privacy/) · [服务条款](https://securityronin.github.io/forensic-vfs/terms/) · © 2026 Security Ronin Ltd
标签：Rust, 可视化界面, 存储取证, 接口定义, 数字取证, 网络流量审计, 自动化脚本, 虚拟文件系统, 通知系统