Files
reverse-engineering-anything/docs/specs/firmware/android-boot-image/plan.md
T
Matt Van Hornandgensokyo-dev a88c0a5554 feat(artifacts): inspect Android boot image components
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>
2026-11-17 12:08:42 +00:00

3.0 KiB

Implementation plan

One format-aware parser normalizes the header, vendor ramdisk table, and AVB footer. The artifact reader consumes that result. Registration follows the uImage reader. Requirements are numbered in spec.md.

Boundary and contract

  1. Keep parsing in src/artifacts/AndroidBootImageFormat.ts, using shared Result, ParseFailureError, and bounded BinaryReader primitives. Keep magic recognition in src/domain/androidBootImageFormat.ts. Export parseAndroidBootHeader, parseVendorRamdiskTable, inspectAvbFooter, and compressionFromPrefix from the parser. Preserve parser failure kinds through the shared artifact failure owner.
  2. Add AndroidBootImageArtifactReader with format android-boot-image. It probes at most 4096 header bytes, reads a 64-byte tail for the AVB check, and streams member bytes on demand. Table admission uses the 4096-entry, 4096-byte entry, and 1 MiB header caps before any table read.
  3. Add androidBootImageMetadataSchema and androidBootImageEntryMetadataSchema as strictObject members of the kind-discriminated artifact metadata union. Catalog order does not select the schema.
  4. Add android-boot-image to ARTIFACT_FORMATS with the same container flags as uImage: roleContainer, retainClassifiedSource, extractable, and absentInventory: "unavailable". createArtifactReader, inventory classification, and extraction follow that registry. ArtifactGraphConstruction and BinaryTargetResolver call hasAndroidBootImageMagic. Add the kind to ArtifactReader, the artifact graph, evidence subject, analysis snapshot, live target summary, and binary target types.
  5. Carry untrusted target-derived strings and the unknown boot, init_boot, or recovery role in reader limitations. CLI and MCP preserve that Evidence. Summary detail keeps the full Evidence and uses inspect_analysis_view for paging.
  6. Reuse ArtifactFileSource, ranged reads, chunk reads, and ArtifactResourceScope. A failed close stays owned so a later close can retry. Cancellation covers admission, paused inventory, buffered bytes, and multi-chunk reads.

Validation

Synthetic fixtures live in tests/fixtures/androidBootImage.ts: version 0, version 2 with a DTB, versions 3 and 4 boot, version 4 vendor_boot with two ramdisk table entries, and truncated and overlapping-range negatives. Cover the parser, the reader, filesystem boundaries, CLI acceptance, and MCP boundary output, including matching Evidence limitations and unsupported, truncated, and malformed refusals. Use pinned AOSP generation and unpacking with small inert component inputs as an independent byte oracle. State that no device-dumped image was checked.

Effects and compatibility

The reader only reads an admitted local file. It introduces no execution, boot, decompression, digest check, or signature check. The new metadata kinds are additive. Other artifact formats keep their existing schemas.