RescueUSB - pre-flight bootability verifier for ISO disc images =============================================================== Techlosoft "ISO + Boot Workshop" product line WHAT IT IS FOR -------------- Writing an ISO to a USB stick takes twenty minutes. Discovering afterwards that the download was corrupt, or that the image has no UEFI boot entry and the laptop in front of you has no legacy BIOS, takes another twenty. RescueUSB answers the questions beforehand: 1. Did the download arrive intact? -> rescueusb verify 2. Is this image actually bootable, and on which firmware? -> rescueusb boot 3. Is it ready to write to that stick? -> rescueusb preflight It answers them by reading the raw bytes of the image: the ISO 9660 volume descriptors, the El Torito Boot Record Volume Descriptor at sector 17, and the El Torito boot catalog that descriptor points at - the structure that actually makes an ISO bootable. READ-ONLY. THIS IS IMPORTANT. ----------------------------- RescueUSB NEVER WRITES ANYTHING. It does not write to USB sticks or any other device, it does not create images, and it does not modify the image you point it at. It opens files read-only and it never opens block devices at all. Every image file this tool has ever been run against is byte-for-byte identical afterwards. Actually writing an image to removable media requires privileged raw-device access, and getting it wrong destroys the wrong disk. That is deliberately not implemented here. Use your platform's own tool for the write step; use RescueUSB to be sure the write is worth doing. COMMANDS -------- rescueusb verify [--sha256 H] [--md5 H] [--checksum-file F] [--json] Streams the file once and computes its SHA-256 (and MD5 when asked), then compares against the values the publisher announced. Reports MATCH, MISMATCH or NOT CHECKED. A mismatch exits non-zero. --checksum-file accepts the format Linux distributions publish: one image per line, hash first, two spaces, then the filename (a "*" instead of the second space, for binary mode, is also accepted). The BSD tagged form "SHA256 (file) = hash" is understood as well. When the file lists several images, the line whose filename matches the image being checked is the one used. SHA-256 and MD5 lines are checked; SHA-1 and SHA-512 lines are reported as skipped rather than silently ignored. rescueusb boot [--json] The core feature. Decodes and reports: - The El Torito Boot Record Volume Descriptor at sector 17 (byte offset 34816): descriptor type 0, standard identifier "CD001", the boot system identifier "EL TORITO SPECIFICATION", and the absolute pointer to the boot catalog. - The boot catalog validation entry: header ID, platform ID (0x00 x86, 0x01 PowerPC, 0x02 Mac, 0xEF EFI), ID string, the 0x55 0xAA key bytes, and the 16-bit checksum - which is VERIFIED, not merely printed. All sixteen little-endian words of the 32-byte validation entry must sum to zero modulo 0x10000. A single flipped byte anywhere in that entry breaks the sum and is reported as INVALID. - The default (initial) entry: bootable flag, boot media type (0 no emulation, 1 1.2M floppy, 2 1.44M floppy, 3 2.88M floppy, 4 hard disk), load segment, system type, sector count and load RBA. - Every section header and section entry that follows, in particular an EFI entry under a platform 0xEF section header. That entry is what decides whether a UEFI machine will boot the image, and it is the part most other inspection tools stop short of. It finishes with a plain-English verdict: BIOS-bootable, UEFI-bootable, both, or not bootable. rescueusb preflight [--target-size N] [--json] A combined readiness report, each item marked PASS, WARN or FAIL: Image size the file is not empty Sector alignment the size is a whole multiple of 2048 bytes; a remainder almost always means a cut-short download, and the arithmetic is shown ISO 9660 volume the volume identifier and logical block size Declared volume size what the volume claims to contain, against what the file actually holds El Torito boot record present or absent Boot catalog validation checksum verified Firmware support BIOS, UEFI, both or neither Fits target device whether the image fits the destination, given --target-size --target-size takes a byte count (8589934592) or a suffix: 8G and 512MiB are powers of two, 8GB and 500MB are powers of ten, matching how drive capacities are printed on the packaging. OPTIONS ------- --sha256 HASH Expected SHA-256 (64 hex characters) --md5 HASH Expected MD5 (32 hex characters) --checksum-file FILE Published checksum file --target-size N Destination device capacity, bytes or with a suffix --json Machine-readable JSON on stdout -h, --help, help Show usage Flags may be given before or after the filename; both orders work. EXIT STATUS ----------- 0 the answer is yes: checksums match, the image boots, all checks passed 1 the command could not be carried out: file missing, unreadable, or not an ISO 9660 image at all 2 the report is complete but the answer is no: a checksum mismatched, the image will not boot, the boot catalog is corrupt, or a pre-flight check failed Exit code 2 is the one to test for in a script. It means "RescueUSB understood the image and is telling you not to write it". EXAMPLES -------- rescueusb verify ubuntu-24.04-desktop-amd64.iso --checksum-file SHA256SUMS rescueusb verify disc.iso --sha256 dbbf3898b5dc6f...c202f6 rescueusb boot disc.iso rescueusb boot disc.iso --json | jq .uefi_bootable rescueusb preflight disc.iso --target-size 8G rescueusb preflight disc.iso --json WHAT IS IMPLEMENTED ------------------- - SHA-256 and MD5 hashing of an image, in a single streaming pass. - Comparison against a hash given on the command line, or against a published checksum file in GNU coreutils or BSD tagged format. - ISO 9660 volume descriptor reading: volume identifier, system identifier, logical block size, declared volume space size. - El Torito Boot Record Volume Descriptor location and decoding. - Full boot catalog parsing: validation entry with genuine 16-bit checksum verification, default/initial entry, section headers, section entries, and section entry extensions. - Platform identification including EFI (0xEF), and a BIOS/UEFI verdict. - Truncation and alignment detection. - Target-device capacity check. - JSON output for all three commands. WHAT IS NOT IMPLEMENTED ----------------------- - Writing to USB devices. RescueUSB does not write to any device, ever. Raw-device writing needs privileged access and is deliberately out of scope. - Creating, modifying, repairing or remastering images. The tool is strictly read-only. - Verifying GPG or PGP signatures on checksum files. RescueUSB checks that the image matches the hash in the file; it does NOT check that the file itself is authentic. A checksum file an attacker replaced will happily match an image the same attacker replaced. Verify the signature on SHA256SUMS with gpg yourself before trusting it. - Listing or extracting files from inside an image. That is ISOPilot's job. - Hybrid MBR / GPT partition table analysis of isohybrid images. - Rock Ridge, Joliet, UDF, and multi-session/multi-track layouts. - Checking whether the destination USB device exists or is writable; the --target-size check is arithmetic on a number you supply, nothing more. ROADMAP ------- - Actually writing an image to removable media, with a progress indicator and a read-back verification pass. - Hybrid MBR/GPT ISO analysis: isohybrid partition tables, the protective MBR, and the EFI system partition an image carries for UEFI boot. - GPG signature verification of published checksum files, closing the gap between "matches the hash" and "is authentic". - Multi-boot USB creation: several rescue images on one stick with a boot menu. BUILDING -------- Go standard library only, no third-party dependencies, no network access needed: go build -o rescueusb . Pre-built binaries for Windows, macOS (Intel and Apple Silicon) and Linux are in dist/.