aoiflux/libxfat

GitHub: aoiflux/libxfat

libxfat 是一个 Go 库，专为解析和读取 ExFAT 文件系统镜像而设计，支持数字取证中的数据提取和元数据分析。

Stars: 2 | Forks: 1

# libxfat libxfat 是一个用于读取 exFAT 文件系统镜像的 Go 库。它旨在用于取证和检查工作流程：打开镜像、解析 VBR、遍历目录、读取元数据和提取文件内容。该库是面向读取的。它不创建或修改 exFAT 卷。 ## 亮点 - 直接从 `*os.File` 解析 exFAT 镜像。 - 读取根目录或递归遍历可索引条目。 - 提取常规文件同时保留目录结构。 - 报告卷统计信息，如集群大小、已用空间和分配位图计数。 - 显示 exFAT 元数据条目，如 `$BitMap`、`$UpCase`、`$Volume GUID`、 `$TexFAT` 和 `$ACT`。 - 在根目录列表中添加虚拟元数据条目，如 `$MBR`、`$FAT1` 和 `$FAT2`。 - 比原始实现更防御性地处理截断和畸形镜像。 ## 安装

## 目录 - [目录](#table-of-contents) - [概述](#overview) - [功能](#features) - [项目结构](#project-structure) - [项目索引](#project-index) - [内部解析笔记](#internal-parsing-notes) - [快速开始](#getting-started) - [前置条件](#prerequisites) - [安装](#installation) - [贡献](#contributing) - [引用论文](#cite) - [阅读论文](#paper) ## 概述 libxfat 是一个 Go 库，为解析和操作 ExFAT 文件系统提供强大高效的解决方案。它提供全面的工具来提取数据和访问元数据。 **为什么选择 libxfat？** 该项目简化了开发者与 ExFAT 文件系统的交互。核心功能包括： - **🟢 强大的 ExFAT 解析：** 处理连续和链式集群分配方案，确保可靠的数据提取。 - **🔵 全面的元数据访问：** 轻松检索文件大小、属性、时间戳，并生成目录列表。 - **🟡 高效的数据提取：** 在处理大型 ExFAT 卷时针对速度和性能进行了优化。 - **🔴 清晰的数据结构：** 良好定义的结构体（VBR、Entry）简化了 ExFAT 数据操作和理解。 - **🟣 彻底的错误处理：** 包括完整性检查和强大的错误处理以防止数据丢失。 - **🟠 文档完善的代码：** 清洁、注释良好的代码确保了易于集成和维护。 ## 内部解析笔记内部解析器架构和零拷贝边界记录在 [INTERNAL_PARSING.md](./INTERNAL_PARSING.md)。 ## 功能 | | 组件 | 详情 | | :- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ⚙️ | **架构** |

纯 Go 实现
模块化设计，为不同 FAT 功能提供独立包

| | 🔩 | **代码质量** |

代码结构总体良好
使用描述性变量和函数名
某些区域可能受益于更多注释

| | 📄 | **文档** |

文档有限
严重依赖代码注释进行解释
没有正式的 API 文档

| | 🔌 | **集成** |

设计为易于集成到其他 Go 项目中
除了 Go 标准库外，没有外部库依赖

| | 🧩 | **模块化** |

模块化良好，具有用于文件系统操作、目录处理等的不同包
便于独立测试和维护

| | ⚡️ | **性能** |

代码中没有明确优化性能
需要进一步分析以确定性能特征

| | 🛡️ | **安全性** |

没有实施明确的安全措施（例如输入验证）
生产使用需要解决安全考虑

| | 📦 | **依赖** |

仅依赖 Go 标准库
没有外部依赖，减少复杂性和潜在冲突

| | 🚀 | **可扩展性** |

可扩展性取决于使用库的应用程序
库本身在可扩展性上没有固有限制
已测试高达 1TiB 的数据集

| ## 项目结构 ``` └── libxfat/ ├── README.md ├── cluster.go ├── const.go ├── entry.go ├── exfat.go ├── go.mod ├── go.sum ├── struct.go ├── util.go └── vbr.go ``` 该模块目前目标为 Go 1.25，如 `go.mod` 中声明。 ## 快速开始 ``` package main import ( "fmt" "log" "os" "github.com/aoiflux/libxfat" ) func main() { imageFile, err := os.Open("disk.exfat") if err != nil { log.Fatal(err) } defer imageFile.Close() fs, err := libxfat.New(imageFile, false) if err != nil { log.Fatal(err) } rootEntries, err := fs.ReadRootDir() if err != nil { log.Fatal(err) } for _, entry := range rootEntries { fmt.Printf("name=%q size=%d dir=%t special=%t virtual=%t\n", entry.GetName(), entry.GetSize(), entry.IsDir(), entry.IsSpecialFile(), entry.IsVirtualEntry(), ) } allocated, err := fs.GetAllocatedClusters() if err != nil { log.Fatal(err) } fmt.Printf("cluster size: %d bytes\n", fs.GetClusterSize()) fmt.Printf("allocated clusters: %d\n", allocated) fmt.Printf("used space: %s\n", fs.GetUsedSpace()) } ``` `libxfat.New` 的第二个参数是 `optimistic`： - `false`：严格模式，首选用于取证用途。 - `true`：在处理不太可靠的镜像或嵌入式卷时，跳过严格的 VBR 偏移验证。如果 exFAT 文件系统位于更大镜像内部，您还可以传递可选的扇区偏移量： ``` fs, err := libxfat.New(imageFile, false, 2048) ``` ## 核心 API ### 打开和检查 - `New(imagefile *os.File, optimistic bool, offset ...uint64) (ExFAT, error)` - `ReadRootDir() ([]Entry, error)` - `ReadDir(entry Entry) ([]Entry, error)` - `ReadDirs(entries []Entry) ([]Entry, error)` - `GetAllEntries(rootEntries []Entry, indexable ...bool) ([]Entry, error)` - `GetFullPathIndexableEntries(entries []Entry, path string) ([]Entry, error)` ### 提取数据 - `ExtractEntryContent(entry Entry, dstpath string) error` - `ExtractAllFiles(rootEntries []Entry, dstdir string) error` ### 删除条目恢复 - `RecoverDeletedEntries() ([]Entry, error)` ### 卷统计 - `GetVolumeLabel() string` - `GetClusterSize() uint64` - `GetAllocatedClusters() (uint32, error)` - `GetFreeClusters() (uint32, error)` - `GetUsedSpace() string` - `CountClusters(entry Entry) (int, error)` - `GetClusterList(entry Entry) ([]uint32, uint64, error)` - `GetClusterOffset(cluster uint32) uint64` ### 条目助手每个解析的目录项由 `Entry` 表示。常用助手包括： - `GetName()` - `GetSize()` - `GetEntryCluster()` - `IsDir()` 和 `IsFile()` - `IsDeleted()` - `IsIndexed()` - `IsSpecialFile()` - `IsVirtualEntry()` - `HasFatChain()` 和 `DoesNotHaveFatChain()` ## 特殊和虚拟条目 `ReadRootDir()` 返回普通文件系统条目和元数据条目。特殊条目是镜像中找到的真实 exFAT 元数据记录，包括： - `$BitMap` - `$UpCase` - `$Volume GUID` - `$TexFAT` - `$ACT` 虚拟条目是库添加的合成助手，使文件系统元数据更容易从根目录列表检查，包括： - `$MBR` - `$FAT1` - `$FAT2` 使用 `entry.IsSpecialFile()` 和 `entry.IsVirtualEntry()` 来区分它们与常规文件和目录。 ## 示例可运行的示例位于 `examples/` 目录下。 ``` go run ./examples/list-root -image /path/to/volume.exfat go run ./examples/list-all -image /path/to/volume.exfat go run ./examples/volume-stats -image /path/to/volume.exfat go run ./examples/extract-all -image /path/to/volume.exfat -out ./recovered ``` 常用标志： - `-image`：exFAT 镜像文件的路径。 - `-optimistic`：跳过严格的 VBR 偏移验证。 - `-offset`：exFAT 卷开始的扇区偏移量。示例程序涵盖： - 列出根目录条目，包括元数据和虚拟条目。 - 遍历整个文件系统并打印可索引条目的完整路径。 - 报告卷和分配统计信息。 - 将所有常规文件提取到输出目录。 ## 测试运行完整测试套件： ``` go test ./... ``` 仓库包括包级测试和位于 `tests/` 下的高级测试，这些测试涉及： - VBR 验证。 - FAT 循环和 EOF 范围处理。 - 根目录解析。 - 虚拟和特殊条目行为。 - 分配位图计数。 - 路径保留提取行为。 ## 健壮性笔记该仓库中最近的解析器改进包括： - 读取集群支持记录时更好的边界检查。 - 更安全的 UTF-16 文件名解码。 - 目录集校验和验证。 - 关键 exFAT 目录记录类型的验证助手。 - 更可靠地处理短位图、FAT 循环和截断镜像。有关更详细的实现摘要，请参阅 `IMPROVEMENTS.md`。 ## 仓库布局 ``` . |-- exfat.go # high-level filesystem operations |-- vbr.go # VBR parsing and volume metadata |-- cluster.go # cluster traversal and content reads |-- entry.go # directory-entry formatting helpers |-- struct.go # core ExFAT, VBR, and Entry types |-- util.go # shared parsing and formatting helpers |-- validators.go # exFAT directory-record validation helpers |-- examples/ # runnable example programs `-- tests/ # higher-level behavioral tests ``` ## 贡献 - **🐛 [报告问题](https://github.com/aoiflux/libxfat/issues)**：提交发现的错误或为 `libxfat` 项目记录功能请求。 - **💡 [提交拉取请求](https://github.com/aoiflux/libxfat/blob/main/CONTRIBUTING.md)**：审查开放的 PR，并提交您自己的 PR。欢迎问题和拉取请求。如果您更改解析行为，建议在同一更改中添加或更新测试，以便覆盖畸形镜像处理和元数据行为。 ## 引用 Gogia, G., & Rughani, P. (2024). Parex: A novel exfat parser for file system forensics. Computación y Sistemas, 28(2). https://doi.org/10.13053/cys-28-2-4804 ## 论文 ## [PAREX: 用于文件系统取证的新型 exFAT 解析器](https://www.scielo.org.mx/scielo.php?script=sci_arttext&pid=S1405-55462024000200421#:~:text=This%20research%20proposes%20a%20novel%20open-source%20exFAT%20file,of%20disk%20images%20ranging%20from%201MiB%20to%201TiB)