SecurityRonin/shellitem
GitHub: SecurityRonin/shellitem
纯 Rust 编写的 Windows Shell Item（PIDL）解析器，用于从 LNK 文件、注册表 ShellBags 等 artifact 中解码结构化条目并重构路径，是数字取证工具链的可复用基础组件。
Stars: 0 | Forks: 0
# shellitem
[](https://crates.io/crates/shellitem)
[](https://docs.rs/shellitem)
[](https://www.rust-lang.org)
[](LICENSE)
[](https://github.com/SecurityRonin/shellitem/actions)
[](https://github.com/sponsors/h4x0r)
**将 Windows `ITEMIDLIST` (PIDL) blob 解码为具有类型的 shell item 及重构路径——这是 LNK `LinkTargetIDList`、注册表 ShellBags 和 Jump Lists 背后可复用的基础组件。**
shell item 是 Windows shell 命名空间序列化 (`ITEMIDLIST`) 的一个组成部分：可以是卷、文件夹、文件（包含其短名称*和*长名称、大小、MAC 时间戳以及 NTFS MFT 引用）、网络共享或已知文件夹的 GUID。这种完全相同的 blob 格式出现在许多 artifacts 中，因此其解析逻辑理应集中在一处——就像 `xpress-huffman` 或 `lznt1` 一样，这是一个**解码器基础组件，而不是分析器**（它不输出任何分析结果；取证解释的逻辑由调用的 crate 负责）。
## 30 秒解析 PIDL
```
[dependencies]
shellitem = "0.1"
```
```
use shellitem::{parse_idlist, reconstruct_path};
let items = parse_idlist(pidl_bytes); // Vec, lenient + panic-free
let path = reconstruct_path(&items); // "C:\\Users\\beth\\Downloads\\evil.exe"
for item in &items {
if let Some(name) = item.display_name() {
println!("{:?} {name}", item.kind);
// FileEntry items also carry: long_name, file_size, modified/created/accessed,
// and the NTFS mft_entry / mft_sequence from the 0xbeef0004 extension block.
}
}
# fn _doc(pidl_bytes: &[u8]) { let _ = pidl_bytes; }
```
`reconstruct_path` 是其核心功能：将原始 IDList 转换为人类可读的路径，用于解析 `.lnk` 的*真实*目标（即使在缺少 `LinkInfo` 的情况下），以及从 ShellBag 中还原用户浏览过的文件夹。
## 解码内容
| Kind | Class | 携带信息 |
|---|---|---|
| `Root` | `0x1F` | shell-folder GUID（我的电脑、网络、控制面板 等） |
| `Volume` | `0x2E`/`0x2F` | 驱动器字符串 (`C:\`) |
| `FileEntry` | `0x30` 主体 (`0x31` 目录, `0x32` 文件, `0x35`/`0x36`, `0xB1`) | 短名称 + **长名称**、大小、修改/创建/访问时间、**NTFS MFT 条目+序列号** (`0xbeef0004`) |
| `Network` | `0xC3` | UNC / 网络位置 |
| `Uri` / `ControlPanel` | `0x60` / `0x70` | URI / 控制面板项 |
| `Unknown` | 其他 | 保留原始字节——不静默丢弃任何数据 |
格式常量（类字节、`0xbeef0004`/`0xbeef0026` 扩展签名、“我的电脑”GUID）来自 [`forensicnomicon::shellbags`](https://crates.io/crates/forensicnomicon)；规范源自 libyal 的 *Windows Shell Item 格式*。
## 使用对象
- **`lnk-core`** — `.lnk` 的 `LinkTargetIDList`（完整的目标路径重构）。
- **`winreg-artifacts`** — 注册表 **ShellBags**（`BagMRU` PIDL 值 → 文件夹访问路径）。
- Jump Lists 及其他 shell MRUs（OpenSave/LastVisited PIDL MRUs）。
## 信任但验证
对不可信的输入不会引发 panic（每个 `cb`/偏移量在使用前都经过了范围检查；UTF-16 采用无损解码；DOS 日期转换带有溢出保护），包含 `#![forbid(unsafe_code)]`，并针对 `parse_idlist` 进行了 fuzz 测试。已使用基于 libfwsi 提取的、完全符合规范的 `ITEMIDLIST` 测试样例进行了验证。
[隐私政策](https://securityronin.github.io/shellitem/privacy/) · [服务条款](https://securityronin.github.io/shellitem/terms/) · © 2026 Security Ronin Ltd
标签：Rust, 可视化界面, 安全, 数字取证, 数据解析, 文件系统, 网络流量审计, 自动化脚本, 超时处理, 通知系统