Inventory Android boot and vendor_boot images through shared artifact workflows. Preserve parser failure kinds and bounded stored-component extraction. Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning) Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
7.0 KiB
Android boot and vendor_boot images
Problem and outcome
Android firmware inspection starts from boot.img, init_boot.img,
recovery.img, and vendor_boot.img. REA inventories APKs, devicetree blobs,
legacy uImage containers, and FIT images. It has no reader for an Android boot
image, so inspect_artifact and extract_artifact cannot expose the kernel,
ramdisk, or DTB stored in one.
This feature adds a provider-less artifact reader for ANDROID! headers
(versions 0 through 4) and VNDRBOOT headers (versions 3 and 4). Header facts
and component children use the existing artifact inventory, extraction, CLI,
and MCP path.
Android boot and vendor_boot images describes the current behavior and limitations. This directory is the feature specification, implementation plan, and task list. The guide does not replace these files.
Requirements
- Classification uses the 8-byte magic
ANDROID!orVNDRBOOT, independent of filename.hasAndroidBootImageMagicis the only magic owner. Target resolution and artifact-graph construction call it. src/artifacts/AndroidBootImageFormat.tsdecodes the header, the vendor ramdisk table, and the AVB footer once. The reader consumes those facts. Header multi-byte fields are little-endian. AVB footer sizes and versions are big-endian.u64,alignUp, and range ends reject values that are not safe integers. Parse failures returnResultwith sharedParseFailureErrorfacts. The artifact error owner preservesmalformed,truncated,unsupported, andlimitthrough CLI/MCP projection and cleanup retry.- Boot versions 0 through 2 take a power-of-two page size from 2048 through 65536. The header occupies the first page. Kernel, ramdisk, and second stage follow, each padded to the next page. Version 1 adds a recovery DTBO at a page-aligned file offset. Version 2 adds a DTB after that offset. The 32-byte header digest is recorded. Boot versions 3 and 4 use a fixed 4096-byte page. Kernel and ramdisk follow the header page. Version 4 can append a signature as a stored range with a size.
- Vendor_boot versions 3 and 4 record kernel, ramdisk, and tags load
addresses, the board name, a 2048-byte command line, the vendor ramdisk,
and a DTB. The vendor page size is a power of two from 2048 through 65536.
Version 3 exposes one
vendor_ramdiskchild when that section is non-empty. Version 4 exposes each ramdisk table entry asvendor_ramdisk/<name>, then the DTB, then bootconfig. The table itself stays metadata. Each entry is at least the 108-byte v4 structure: size, offset, type, a 32-byte name, and 16 board-id words. A largerentry_sizekeeps those fields and leaves the trailing bytes undecoded. An empty name,.,.., or a name containing/becomesramdisk-<index>. A repeated name gains-<index>, then further numeric suffixes until the path is unique. - OS version and security patch level come from the packed
os_versionword on a boot image. A month outside 1 through 12 leaves the patch level null and keeps the raw word. Vendor_boot has no OS version field. Versions 0 through 2 concatenatecmdlineandextra_cmdlinewith no separator. Versions 3 and 4 store one combined command line. Invalid UTF-8 leaves the text null and keeps the raw field bytes as hex. Command line, board name, and vendor ramdisk names are target-derived and untrusted. AnANDROID!image covers boot, init_boot, and recovery; the header leaves that role unknown. - Non-empty components become children:
kernel,ramdisk,second,recovery_dtbo,dtb,vendor_ramdisk,vendor_ramdisk/<name>,bootconfig, andsignature. A prefix of gzip (1f 8b), an lz4 frame (04 22 4d 18), legacy lz4 (02 21 4c 18), or zstd (28 b5 2f fd) records that compression. Any other prefix leaves compression null. Null means none of those magics matched. Stored bytes stay compressed. A kernel that starts with ELF magic is classified aselfby the existing content check. Adtbchild stays a file for a laterinspect-devicetreeon the extracted file. - When bytes follow the page-aligned image, the last 64 bytes are compared
with
AVBf. A match records footer version, original image size, and vbmeta offset and size. The footer and vbmeta stay header facts. A shorter tail, or a tail that does not start withAVBf, is undecoded trailing bytes. A vbmeta range that overlaps the header, a component, or the footer is malformed. - The header probe is at most 4096 bytes. The reader admits at most 4096
vendor ramdisk table entries, an entry size of at most 4096 bytes, and a
vendor
header_sizeof at most 1 MiB. Those checks run before the table is read. Truncated declared structures returntruncated; unsupported revisions returnunsupported_target; malformed layouts returninvalid_request. Gaps inside a vendor ramdisk section, and bytes between the sequential layout and a recovery DTBO, are named in limitations. Member bytes stream on demand. - CLI and MCP return the same Evidence shape, including the untrusted-string
limitation and the unknown boot role.
androidBootImageMetadataSchemaandandroidBootImageEntryMetadataSchemaarestrictObjectmembers of the kind-discriminated artifact metadata union. Summary detail retains Evidence.inspect_analysis_viewpages it. - The reader reuses
ArtifactFileSource,readArtifactFileBytes,readFileHandleChunks, andArtifactResourceScope. Close rethrows a scope or source close failure and keeps the handle for retry. Cancellation applies during admission, paused inventory, buffered reads, and multi-chunk reads. A source change after prepare fails closed.
Acceptance
Synthetic fixtures cover a version 0 image, a version 2 image with a DTB,
version 3 and version 4 boot images, and a version 4 vendor_boot image with
two ramdisk table entries, plus truncated and overlapping-range inputs.
Parser tests, reader tests, boundary tests, the CLI acceptance test, and the
MCP boundary test cover those images, compression magics, capacity limits,
cancellation, and cleanup retry. CLI and MCP tests assert the same Evidence
limitations. Temp directories use createTestTempDirectory without an
afterEach root removal. The MCP extraction cleanup removes the extraction
output root.
Fixtures are synthetic headers and stored payloads. An independent offline
check also generates boot v0-v4 and vendor_boot v3-v4 images with pinned AOSP
mkbootimg.py, then compares REA ranges and digests with the known inputs and
official unpack_bootimg.py output. This feature includes no device-dumped
image. No signature check, AVB digest check, or payload decompressor runs.
Non-goals
- Decompressing ramdisk, kernel, or bootconfig bytes.
- Checking the header digest, the version 4 boot signature, or the AVB footer.
- A separate
inspect_android_boot_imagetool. - A Binwalk or Unblob adapter.
- Assigning boot, init_boot, or recovery from the header.
- Executing, booting, or modifying the image.