isoinspect

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 22, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package isoinspect inspects, validates, and manipulates Windows installation ISO images. It parses the three on-disc structures that matter for a bootable Windows install medium — the ISO9660 primary volume descriptor, the El Torito boot catalog, and the UDF file system — and reports correctness problems that keep media from booting even though lenient readers (e.g. macOS) accept it.

Its headline check is the UDF allocation-descriptor validation: a file larger than ~1 GiB (boot.wim, install.wim) must be split across several block-aligned short allocation descriptors, because a single short_ad's length field is only 30 bits. Media that records one oversized descriptor mounts on macOS but the Windows boot manager cannot read boot.wim from it — the medium starts then hangs. This package detects exactly that class of defect.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractElToritoEFIImage

func ExtractElToritoEFIImage(isoPath, destPath string) error

ExtractElToritoEFIImage writes the FAT EFI System Partition image referenced by the El Torito UEFI boot entry (efisys.bin's contents) of the ISO at isoPath to destPath. It is the volume the firmware mounts to launch \EFI\BOOT\ BOOTAA64.EFI, useful for inspecting the boot image in isolation.

func SetElToritoUEFIOnly

func SetElToritoUEFIOnly(isoPath string) error

SetElToritoUEFIOnly rewrites the El Torito boot catalog of the ISO at isoPath in place so the UEFI boot image becomes the validation/default entry with the validation platform set to UEFI (0xEF), dropping any BIOS (x86) entry. This matches the layout of Microsoft's UEFI-only ARM64 media and removes the "Image type X64 can't be loaded" firmware error caused by a stray etfsboot.com BIOS entry. The image's UDF/El Torito boot image data are untouched.

It is a no-op (returning nil) when the catalog is already UEFI-only with the UEFI image as the default entry.

Types

type BootEntry

type BootEntry struct {
	// Section is true for an entry introduced by a section header; false for the
	// initial/default entry.
	Section bool
	// PlatformID is the entry's platform: 0x00 BIOS, 0xEF UEFI. For the default
	// entry this is the validation entry's platform.
	PlatformID uint8
	Bootable   bool
	MediaType  uint8 // 0 = no emulation
	// SectorCount is the El Torito "sector count": the number of 512-byte virtual
	// sectors of the boot image. For a UEFI entry this is the size of the FAT EFI
	// System Partition image the firmware exposes.
	SectorCount uint16
	// LoadRBA is the logical block (2048-byte) where the boot image begins.
	LoadRBA uint32
	// ImageIsFAT/ImageIsX86Boot describe the bytes at LoadRBA.
	ImageIsFAT     bool
	ImageIsX86Boot bool
}

BootEntry is one El Torito boot-catalog entry (the default/initial entry or a section entry).

func (BootEntry) SizeBytes

func (e BootEntry) SizeBytes() int64

SizeBytes returns the boot image size implied by SectorCount (512-byte units).

type ElToritoInfo

type ElToritoInfo struct {
	// Present is false when the image has no El Torito boot record.
	Present              bool
	CatalogSector        uint32
	ValidationPlatform   uint8
	ValidationChecksumOK bool
	Entries              []BootEntry
	// UEFI and BIOS point to the resolved boot entries of each kind, if present.
	UEFI *BootEntry
	BIOS *BootEntry
}

ElToritoInfo describes a parsed El Torito boot catalog.

type ISO9660Info

type ISO9660Info struct {
	Present      bool
	VolumeID     string
	VolumeBlocks uint32
	RootEntries  []string
	HasJoliet    bool
}

ISO9660Info describes the ISO9660 primary volume descriptor.

type Issue

type Issue struct {
	Severity Severity
	// Area is the structure the issue concerns: "iso9660", "eltorito", or "udf".
	Area string
	// Path is the file path within the UDF tree the issue concerns, when
	// applicable (otherwise empty).
	Path    string
	Message string
}

Issue is a single validation finding.

func (Issue) String

func (i Issue) String() string

type Report

type Report struct {
	Path     string
	Size     int64
	ISO9660  *ISO9660Info
	ElTorito *ElToritoInfo
	UDF      *UDFInfo
	Issues   []Issue
}

Report is the result of inspecting an ISO.

func Inspect

func Inspect(path string) (*Report, error)

Inspect opens the ISO at path and returns a full Report. A non-nil error is returned only for I/O failures; structural defects are reported as Issues so a caller can inspect a malformed image without the call failing.

func InspectReaderAt

func InspectReaderAt(ra io.ReaderAt, size int64, path string) *Report

InspectReaderAt inspects an ISO available through ra (size bytes). path is used only for reporting.

func (*Report) Errors

func (r *Report) Errors() []Issue

Errors returns only the error-severity issues.

func (*Report) OK

func (r *Report) OK() bool

OK reports whether the ISO has no error-severity issues.

func (*Report) Summary

func (r *Report) Summary() string

Summary returns a human-readable multi-line summary of the report: the parsed ISO9660 / El Torito / UDF structure followed by every issue.

func (*Report) Warnings

func (r *Report) Warnings() []Issue

Warnings returns only the warning-severity issues.

type Severity

type Severity string

Severity classifies a validation Issue.

const (
	// SeverityError marks a defect that prevents the medium from booting.
	SeverityError Severity = "error"
	// SeverityWarning marks a deviation from Microsoft's media that is unusual
	// or wasteful but not necessarily fatal.
	SeverityWarning Severity = "warning"
)

type UDFFile

type UDFFile struct {
	Path    string
	Size    int64
	Extents int // number of allocation descriptors describing the data
}

UDFFile is a regular file discovered in the UDF tree.

type UDFInfo

type UDFInfo struct {
	Present         bool
	UDFRevision     uint16 // e.g. 0x0102 for UDF 1.02
	VolumeID        string
	PartitionStart  uint32 // absolute sector of partition logical block 0
	PartitionBlocks uint32
	RootFEBlock     uint32 // partition-relative block of the root File Entry
	Files           []UDFFile
	FileCount       int
	DirCount        int
}

UDFInfo describes a parsed UDF file system.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL