Crate shellitem 

shellitem — a Windows Shell Item / ITEMIDLIST (PIDL) parser primitive.

A Windows ITEMIDLIST (also “PIDL”, pointer to an item identifier list) is the binary form of a shell path: a sequence of variable-length shell items, each one component of the path, terminated by an empty item. The same structure appears inside a .lnk file’s LinkTargetIDList, inside registry ShellBags (BagMRU) values, jump lists, and elsewhere. This crate turns those bytes into typed ShellItems and, via reconstruct_path, into a human-readable path such as My Computer\C:\Users\bob\secret.docx.

This is a reusable parser primitive, in the same spirit as the lznt1 / xpress-huffman codecs: it decodes the structure and surfaces the fields, but emits no findings and makes no forensic judgements. The forensic interpretation (timeline placement, anomaly grading) lives in the consumers — lnk-core (LinkTargetIDList) and winreg-artifacts (ShellBags).

Robustness

Shell-item blobs are attacker-controllable. Parsing is panic-free and bounds-checked throughout: the per-item cb size field is validated against the remaining buffer and capped, every integer read goes through a bounds-checked helper, FAT-date conversion is overflow-safe, and UTF-16 decoding is lossy (unpaired surrogates become U+FFFD). A truncated or corrupt list stops cleanly at the point of damage rather than panicking.

Authoritative source

libyal libfwsi, Windows Shell Item format (Joachim Metz) — the reverse-engineered reference for the ITEMIDLIST framing and every shell-item class layout (root 0x1f, volume 0x2e/0x2f, file entry 0x30-major and its 0xbeef0004 extension block, network 0xc3): https://github.com/libyal/libfwsi/blob/main/documentation/Windows%20Shell%20Item%20format.asciidoc. Format constants (class-type bytes, the 0x70 major-class mask, the My-Computer GUID, the beef0004/beef0026 signatures) are sourced from forensicnomicon::shellbags.

Example

use shellitem::{parse_idlist, reconstruct_path};

let items = parse_idlist(pidl_bytes);
let path = reconstruct_path(&items);

Structs

ShellItem

One decoded shell item — a single component of an ITEMIDLIST.

Enums

ShellItemKind

The decoded kind of a ShellItem, naming the shell-item class family the bytes belong to (libfwsi). Coarser than the raw class byte: several raw bytes collapse into one kind (e.g. 0x31/0x32/0x35/0x36/0xb1 are all ShellItemKind::FileEntry).

Functions

parse_idlist

Parse a Windows ITEMIDLIST (PIDL) blob into its sequence of shell items.

reconstruct_path

Reconstruct a human-readable path from a parsed item list by joining each item’s best display name with \.