=============================================================================== PartitionGuard -- read-only MBR / GPT partition table parser Techlosoft "Disk Operations Suite" =============================================================================== PartitionGuard reads the raw bytes of a disk image and decodes its partition layout. Where the other tools in the Disk Operations Suite measure how fast a disk is (DiskOps benchmarks throughput, DriveForge compares several targets), PartitionGuard is about STRUCTURE: what the partition table actually says, and whether it is internally consistent. PartitionGuard is strictly READ-ONLY. It opens the image with a read-only handle and performs bounds-checked reads. It contains no code that can write to, create, resize or repair anything. ------------------------------------------------------------------------------- USAGE ------------------------------------------------------------------------------- partitionguard [options] COMMANDS info Detect the partitioning scheme and report the GPT header fields, including header CRC32 and partition-array CRC32 validation. list List every partition: index, start/end LBA, sector count, size and type. verify Run structural checks and report each as PASS / FAIL / SKIP. help Show usage. OPTIONS --json Emit machine-readable JSON instead of text. --sector-size Logical sector size in bytes. Default 512. Must be a power of two between 512 and 65536. Use 4096 for 4Kn media. -h, --help Show usage. Options may be given before or after the image path; both orders behave identically. EXIT STATUS 0 success (for verify: every check passed or was skipped) 1 usage error, or the image could not be read or parsed 2 verify only: at least one check FAILED EXAMPLES partitionguard info disk.img partitionguard list disk.img --json partitionguard verify disk.img partitionguard list disk.img --sector-size 4096 ------------------------------------------------------------------------------- WHAT IS IMPLEMENTED ------------------------------------------------------------------------------- Scheme detection * MBR, GPT, GPT-with-protective-MBR, and "none" are distinguished. * A 0xEE protective entry does not fool the detector into calling a GPT disk an MBR disk. * An MBR that carries a 0xEE entry but has no readable GPT header at LBA 1 is reported as such, rather than being silently called a plain MBR. MBR parsing * 0x55AA boot signature at offset 510. * The four 16-byte primary entries at offset 446: status/boot flag, type byte, first LBA (LE), sector count (LE). * Human names for common type codes, including 0x07 NTFS/exFAT, 0x0B and 0x0C FAT32, 0x83 Linux, 0x82 Linux swap, 0xEE GPT protective, 0xEF EFI System, plus FAT12/16, extended, LVM, RAID and FreeBSD. GPT parsing * Header at LBA 1, "EFI PART" signature, all fields little-endian. * Revision, header size, current/backup LBA, first/last usable LBA, partition-entry LBA, entry count and entry size. * Disk GUID and per-partition GUIDs rendered in the usual mixed-endian (Microsoft) form: first three groups little-endian, last two as stored. * Header CRC32 recomputed with the header's own CRC field zeroed, and partition-array CRC32 recomputed over entry_count * entry_size bytes. Both are compared against the stored values and reported VALID or MISMATCH. CRC32 uses the IEEE polynomial. * Per partition: type GUID with a human name for the well-known types (EFI System, Microsoft Basic Data, Microsoft Reserved, Linux filesystem, Linux swap, and several more), unique partition GUID, attribute flags with the named bits decoded, and the 72-byte UTF-16LE partition name. * All-zero type GUIDs are treated as unused entries and skipped. verify checks * mbr-signature 0x55AA present at offset 510. * gpt-header-crc32 stored header CRC32 matches the recomputed value. * gpt-array-crc32 stored array CRC32 matches the recomputed value. * gpt-backup-header the backup header at the last LBA is present, has a valid CRC32 of its own, and agrees with the primary on disk GUID, usable range, entry geometry, array CRC32 and the reciprocal current/backup LBA pointers. * partition-overlap no two partitions share any LBA. Failures name both partitions and their ranges. * partition-bounds no partition extends past the end of the image. Checks that cannot apply (for example the GPT checks on an MBR-only disk) are reported SKIP with a reason rather than silently passing. Robustness * Every read is bounds-checked against the real file size. * Implausible header values (entry sizes that are not a multiple of 128, entry counts whose array would exceed 16 MiB, out-of-range LBAs) are rejected with an explanatory message instead of being used to allocate or seek. * Malformed, truncated, empty and non-disk files produce a clear error and exit 1. They do not panic and do not hang. Output * Human-readable text by default; --json for all three commands. ------------------------------------------------------------------------------- WHAT IS *NOT* IMPLEMENTED ------------------------------------------------------------------------------- These are real limitations, not oversights. PartitionGuard will not do any of the following, and does not pretend to: * It does NOT modify anything. Creating, editing, deleting or reordering partitions, writing a new partition table, or repairing a damaged one are all out of scope. verify tells you a CRC32 is wrong; it will not fix it. * It does NOT restore a bad primary GPT from the backup (or vice versa), even though it reads both. * It does NOT look inside a partition. There is no filesystem detection or inspection, so it cannot tell you whether a partition marked 0x83 really contains ext4, or report free space, labels or file counts. Type codes and type GUIDs are reported exactly as recorded in the table, which is a declaration of intent, not evidence of content. * It does NOT resize or move partitions. * It does NOT recover a lost or overwritten partition table. There is no scan for orphaned filesystem superblocks or boot sectors. * It does NOT read logical partitions inside an MBR extended partition (type 0x05 / 0x0F). The extended entry is listed, but its EBR chain is not walked. * It does NOT handle hybrid MBR/GPT layouts as a special case; such a disk is reported as GPT. * It operates on IMAGE FILES, not on live block devices. Pointing it at /dev/sda may work where the OS and permissions allow opening the device read-only, but this is untested and unsupported: proper live-device support needs privileged raw device access and a way to ask the kernel for the real logical and physical sector size instead of assuming it. * It does NOT support Apple Partition Map, BSD disklabels, or any scheme other than MBR and GPT. ------------------------------------------------------------------------------- ROADMAP ------------------------------------------------------------------------------- 1. Live block device support, with privileged raw read access and sector size queried from the kernel rather than assumed. 2. Filesystem-level inspection inside a partition: detect the filesystem actually present, and report its label, UUID and usage. 3. Recovery of a lost or damaged partition table by scanning the medium for filesystem signatures and proposing a reconstructed table. 4. Actually modifying and creating partition tables: write a new MBR or GPT, add and remove partitions, and repair a bad CRC32 or a damaged header from its counterpart. 5. Partition resizing and moving, coordinated with the filesystem inside. 6. Walking the MBR extended-partition EBR chain to list logical partitions. ------------------------------------------------------------------------------- BUILDING ------------------------------------------------------------------------------- Go standard library only; no third-party dependencies and no network access required. go build -o partitionguard . Prebuilt binaries are in dist/ for linux/amd64, darwin/amd64, darwin/arm64 and windows/amd64. ------------------------------------------------------------------------------- VERIFICATION ------------------------------------------------------------------------------- The parser was checked field by field against independent, widely used tools rather than against its own assumptions: * GPT: images produced by sgdisk (GPT fdisk 1.0.10) and compared against "sgdisk --print" and "sgdisk -i". 29 fields matched exactly, including the disk GUID, every partition's start and end LBA, sector count, type GUID, unique GUID, attributes and UTF-16LE name. * MBR: images produced by sfdisk (util-linux 2.39.3) and compared against "sfdisk -d" and "fdisk -l". 19 fields matched exactly. * Corruption detection was confirmed against gdisk's own verifier: a single flipped bit in the partition array and a damaged backup header are each detected, and PartitionGuard's per-check verdicts agree with gdisk's.