mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 04:34:13 +00:00
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>
This commit is contained in:
1 parent
116f159a8a
commit
a88c0a5554
48 files changed
+4171
-79
No files matched your search
@@ -910,6 +910,15 @@ Multi-file components retain their aligned physical ranges; the full payload
|
||||
is also materialized. Unknown name text retains its original 32 bytes. See
|
||||
[U-Boot uImage](https://github.com/morluto/rea/blob/main/docs/uimage.md).
|
||||
|
||||
Android boot, init_boot, recovery, and vendor_boot images use the same
|
||||
inspection and extraction workflows. `ANDROID!` versions 0-4 and `VNDRBOOT`
|
||||
versions 3-4 expose header facts and stored component bytes. The header does
|
||||
not record whether an `ANDROID!` image is boot, init_boot, or recovery.
|
||||
Command lines and names are target-derived. gzip, lz4, and zstd payloads stay
|
||||
stored. The v4 signature and any AVB footer are reported with sizes and are
|
||||
not verified. Extract `dtb` and pass that file to `inspect_devicetree`. See
|
||||
[Android boot images](https://github.com/morluto/rea/blob/main/docs/android-boot-image.md).
|
||||
|
||||
## ESP images
|
||||
|
||||
For an ESP32-family app or bootloader image, `open_binary` then
|
||||
|
||||
@@ -910,6 +910,15 @@ Multi-file components retain their aligned physical ranges; the full payload
|
||||
is also materialized. Unknown name text retains its original 32 bytes. See
|
||||
[U-Boot uImage](https://github.com/morluto/rea/blob/main/docs/uimage.md).
|
||||
|
||||
Android boot, init_boot, recovery, and vendor_boot images use the same
|
||||
inspection and extraction workflows. `ANDROID!` versions 0-4 and `VNDRBOOT`
|
||||
versions 3-4 expose header facts and stored component bytes. The header does
|
||||
not record whether an `ANDROID!` image is boot, init_boot, or recovery.
|
||||
Command lines and names are target-derived. gzip, lz4, and zstd payloads stay
|
||||
stored. The v4 signature and any AVB footer are reported with sizes and are
|
||||
not verified. Extract `dtb` and pass that file to `inspect_devicetree`. See
|
||||
[Android boot images](https://github.com/morluto/rea/blob/main/docs/android-boot-image.md).
|
||||
|
||||
## ESP images
|
||||
|
||||
For an ESP32-family app or bootloader image, `open_binary` then
|
||||
|
||||
@@ -538,6 +538,11 @@ export const documentationSections = [
|
||||
source: "agent-environments.md",
|
||||
route: "/agent-environments",
|
||||
},
|
||||
{
|
||||
text: "Android boot and vendor_boot images",
|
||||
source: "android-boot-image.md",
|
||||
route: "/android-boot-image",
|
||||
},
|
||||
{
|
||||
text: "APK signature schemes",
|
||||
source: "apk-signature.md",
|
||||
|
||||
@@ -173,6 +173,7 @@ the exact commit messages and references from the release they describe.
|
||||
- [iNES containers](ines-containers.md)
|
||||
- [Build RL environments with REA](agent-environments-quickstart.md)
|
||||
- [Agent environments from recorded captures](agent-environments.md)
|
||||
- [Android boot and vendor_boot images](android-boot-image.md)
|
||||
- [APK signature schemes](apk-signature.md)
|
||||
- [Apple IPS crash reports](apple-ips.md)
|
||||
- [Static analysis in GitHub Actions](ci-analysis.md)
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
# Android boot and vendor_boot images
|
||||
|
||||
`inspect-artifact` and `extract-artifact` recognize `ANDROID!` boot images
|
||||
(header versions 0 through 4) and `VNDRBOOT` vendor_boot images (header
|
||||
versions 3 and 4) regardless of filename. They read local stored bytes
|
||||
without booting, executing, decompressing, or modifying the image.
|
||||
|
||||
The same header facts and artifact reader serve CLI and MCP. The root is an
|
||||
archive with unknown executable architecture. `ANDROID!` covers boot,
|
||||
init_boot, and recovery images; the header does not record which role the
|
||||
file had.
|
||||
|
||||
## Header facts
|
||||
|
||||
Versions 0 through 2 store a page size from 2048 through 65536, a power of
|
||||
two. The header occupies the first page. Kernel, ramdisk, and second stage
|
||||
follow, each padded up 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 and not checked.
|
||||
|
||||
Versions 3 and 4 use a fixed 4096-byte page. The kernel and ramdisk follow
|
||||
the header page. Version 4 can append a signature. That signature is a
|
||||
stored range with a size. It is not verified.
|
||||
|
||||
Vendor_boot versions 3 and 4 record the kernel, ramdisk, and tags load
|
||||
addresses, the board name, a 2048-byte command line, the vendor ramdisk,
|
||||
and a DTB. Version 3 exposes one `vendor_ramdisk` child when that section
|
||||
is non-empty. Version 4 exposes each ramdisk table entry as
|
||||
`vendor_ramdisk/<name>`, then the DTB, then bootconfig. The table itself
|
||||
is not a child. Each entry is at least the 108-byte v4 structure: size,
|
||||
offset, type, a 32-byte name, and 16 board-id words. A larger
|
||||
`entry_size` keeps those fields and leaves the trailing bytes undecoded.
|
||||
Entry names that are empty, `.`, `..`, or contain `/` become
|
||||
`ramdisk-<index>`. A repeated name gains `-<index>`. If that name is
|
||||
already used, the suffix gains another number until the path is unique.
|
||||
|
||||
OS version and security patch level are decoded from the packed `os_version`
|
||||
word. A month outside 1 through 12 leaves the patch level null and keeps
|
||||
the raw word. Vendor_boot has no OS version field.
|
||||
|
||||
Command line, board name, and vendor ramdisk names are target-derived and
|
||||
untrusted. Versions 0 through 2 concatenate `cmdline` and `extra_cmdline`
|
||||
with no separator. Versions 3 and 4 store one combined command line.
|
||||
Invalid UTF-8 stays null and the raw field bytes are kept as hex.
|
||||
|
||||
## Children
|
||||
|
||||
Non-empty components become children:
|
||||
|
||||
| Path | Role |
|
||||
| ----------------------- | -------------------------------- |
|
||||
| `kernel` | kernel |
|
||||
| `ramdisk` | ramdisk |
|
||||
| `second` | second stage |
|
||||
| `recovery_dtbo` | recovery DTBO |
|
||||
| `dtb` | devicetree blob |
|
||||
| `vendor_ramdisk` | version 3 vendor ramdisk section |
|
||||
| `vendor_ramdisk/<name>` | version 4 ramdisk table entry |
|
||||
| `bootconfig` | bootconfig |
|
||||
| `signature` | version 4 boot signature |
|
||||
|
||||
A child whose first bytes match 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.
|
||||
Other prefixes stay unknown, which does not prove the bytes are uncompressed.
|
||||
Nothing in this reader decompresses a payload. A kernel that starts with the
|
||||
ELF magic is classified as `elf` by the existing content check. A `dtb` child
|
||||
stays a file; extract it and run `inspect-devicetree` on the extracted file.
|
||||
|
||||
## AVB footer
|
||||
|
||||
When bytes follow the page-aligned image, the last 64 bytes are compared with
|
||||
the `AVBf` footer. A matching footer records its version, original image size,
|
||||
and vbmeta offset and size. The footer and vbmeta are not children and are not
|
||||
verified. A shorter tail, or a tail that does not start with `AVBf`, is
|
||||
reported as undecoded trailing bytes. A vbmeta range that overlaps the header,
|
||||
a component, or the footer is malformed.
|
||||
|
||||
## Bounded work
|
||||
|
||||
The reader admits at most 4,096 vendor ramdisk table entries and an entry size
|
||||
of at most 4,096 bytes. A vendor `header_size` above 1 MiB is the same kind of
|
||||
capacity limit. Those checks happen before the table is read. Unsupported
|
||||
header revisions return `unsupported_target`; truncated declared structures
|
||||
return `truncated`; malformed layouts return `invalid_request`. These refusals
|
||||
do not produce an empty successful inventory. Gaps inside a vendor ramdisk
|
||||
section, or bytes between the sequential layout and a recovery DTBO, are named
|
||||
in limitations instead of being invented as entries.
|
||||
|
||||
```sh
|
||||
rea inspect-artifact boot.img --detail summary \
|
||||
--evidence_output boot.evidence.json --json
|
||||
rea extract-artifact vendor_boot.img --json
|
||||
```
|
||||
|
||||
With MCP, `inspect_artifact` with `detail: "summary"` retains the complete
|
||||
Evidence. Use `inspect_analysis_view` and its `parent_evidence_id` for exact
|
||||
logical paths, batches of occurrence/content IDs, selected fields and pages.
|
||||
|
||||
## Verification scope
|
||||
|
||||
Source and compiled CLI/MCP tests cover stored component bytes, compression
|
||||
magics, unsupported revisions, truncation, overlapping ranges, capacity,
|
||||
cancellation, and cleanup. An independent offline check used AOSP
|
||||
`mkbootimg.py` and `unpack_bootimg.py` at commit
|
||||
`d2bb0af5ba6d3198a3e99529c97eda1be0b5a093`: boot versions 0 through 4 and
|
||||
vendor_boot versions 3 and 4 had component ranges and digests matching their
|
||||
small inert input files and official unpacked output. Version 4 vendor_boot
|
||||
extraction also matched those inputs. No device-dumped image, signature
|
||||
verification, AVB digest verification, or payload decompression was checked.
|
||||
@@ -403,6 +403,17 @@ rea extract-artifact ./boot.itb --json
|
||||
See [U-Boot FIT images](../fit-images.md) for recognition, data sources, hashes
|
||||
and limits.
|
||||
|
||||
Inspect and extract an Android boot or vendor_boot image:
|
||||
|
||||
```sh
|
||||
rea inspect-artifact ./boot.img --detail summary --evidence_output boot.json --json
|
||||
rea extract-artifact ./vendor_boot.img --json
|
||||
```
|
||||
|
||||
See [Android boot images](../android-boot-image.md) for header versions 0 through
|
||||
4, vendor ramdisk table entries, stored compression, and the unverified AVB
|
||||
footer. `ANDROID!` does not record boot versus init_boot versus recovery.
|
||||
|
||||
Inspect local model declarations without loading weights:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -375,3 +375,16 @@ images, declared load and entry addresses, configurations and verified hashes,
|
||||
then `extract-artifact` / `extract_artifact` for one raw file per image.
|
||||
Decoding is portable and requires no external tool. See
|
||||
[U-Boot FIT images](../../fit-images.md).
|
||||
|
||||
## Inspect Android boot and vendor_boot images
|
||||
|
||||
`inspect-artifact` / `extract-artifact` recognize `ANDROID!` (header versions
|
||||
0 through 4) and `VNDRBOOT` (vendor_boot versions 3 and 4) by magic. The root
|
||||
records page size, component sizes, the command line, OS version and security
|
||||
patch level when the header has them, the board name, and the header digest.
|
||||
Children are the stored kernel, ramdisk, second stage, recovery DTBO, DTB,
|
||||
vendor ramdisk table entries, bootconfig, and v4 signature. gzip, lz4, and
|
||||
zstd are recorded from leading magic and left compressed. An AVB footer is
|
||||
reported with its sizes and is not verified. `ANDROID!` does not say whether
|
||||
the file was boot, init_boot, or recovery. Extract `dtb` and pass that file
|
||||
to `inspect-devicetree`. See [Android boot images](../../android-boot-image.md).
|
||||
+13
-13
@@ -49,19 +49,19 @@ For runtime instrumentation, see the [Frida guide](guides/runtime/frida-instrume
|
||||
|
||||
The [documentation directory](README.md) lists every guide by domain.
|
||||
|
||||
| Task | Guides |
|
||||
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) |
|
||||
| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) |
|
||||
| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) |
|
||||
| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) |
|
||||
| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) |
|
||||
| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [.NET](guides/managed/managed-code-analysis.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) |
|
||||
| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) |
|
||||
| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) |
|
||||
| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) |
|
||||
| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) |
|
||||
| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) |
|
||||
| Task | Guides |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) |
|
||||
| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) |
|
||||
| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) |
|
||||
| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) |
|
||||
| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) |
|
||||
| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [Android boot images](android-boot-image.md), [.NET](guides/managed/managed-code-analysis.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) |
|
||||
| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) |
|
||||
| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) |
|
||||
| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) |
|
||||
| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) |
|
||||
| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) |
|
||||
|
||||
For development, use [testing](development/testing.md), [client verification](development/client-verification.md),
|
||||
[tool design](development/tool-design.md), [admission limits and recovery](design/limits-and-recovery.md),
|
||||
|
||||
@@ -22,6 +22,7 @@ for new work, roadmap granularity and producer-owned contracts.
|
||||
- [Core WebAssembly interface comparison (#2356)](2356-wasm-interface-comparison/spec.md) ([plan](2356-wasm-interface-comparison/plan.md), [tasks](2356-wasm-interface-comparison/tasks.md), [verification](2356-wasm-interface-comparison/verification.md))
|
||||
- [Inspect APK signature schemes (v1–v3.1)](apk-signature/spec.md)
|
||||
- [Documentation organization](documentation/organization/spec.md) ([plan](documentation/organization/plan.md), [tasks](documentation/organization/tasks.md), [verification](documentation/organization/verification.md))
|
||||
- [Android boot and vendor_boot images](firmware/android-boot-image/spec.md) ([plan](firmware/android-boot-image/plan.md), [tasks](firmware/android-boot-image/tasks.md))
|
||||
- [V8 cached-data compilation boundaries](javascript/v8-cached-data/spec.md) ([plan](javascript/v8-cached-data/plan.md), [tasks](javascript/v8-cached-data/tasks.md))
|
||||
- [Android `.note.android.ident` ELF note decoding](native/android-elf-ident-note/spec.md) ([plan](native/android-elf-ident-note/plan.md), [tasks](native/android-elf-ident-note/tasks.md))
|
||||
- [Native call source coordinates](native/call-source-locations/spec.md) ([plan](native/call-source-locations/plan.md), [tasks](native/call-source-locations/tasks.md), [verification](native/call-source-locations/verification.md))
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# 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](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.
|
||||
@@ -0,0 +1,119 @@
|
||||
# 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](../../../android-boot-image.md) 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
|
||||
|
||||
1. Classification uses the 8-byte magic `ANDROID!` or `VNDRBOOT`, independent
|
||||
of filename. `hasAndroidBootImageMagic` is the only magic owner. Target
|
||||
resolution and artifact-graph construction call it.
|
||||
2. `src/artifacts/AndroidBootImageFormat.ts` decodes 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 return `Result` with shared `ParseFailureError`
|
||||
facts. The artifact error owner preserves `malformed`, `truncated`,
|
||||
`unsupported`, and `limit` through CLI/MCP projection and cleanup retry.
|
||||
3. 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.
|
||||
4. 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_ramdisk` child when that section is
|
||||
non-empty. Version 4 exposes each ramdisk table entry as
|
||||
`vendor_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 larger `entry_size`
|
||||
keeps those fields and leaves the trailing bytes undecoded. An empty name,
|
||||
`.`, `..`, or a name containing `/` becomes `ramdisk-<index>`. A repeated
|
||||
name gains `-<index>`, then further numeric suffixes until the path is
|
||||
unique.
|
||||
5. OS version and security patch level come from the packed `os_version` word
|
||||
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 concatenate `cmdline` and `extra_cmdline` with 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. An `ANDROID!`
|
||||
image covers boot, init_boot, and recovery; the header leaves that role
|
||||
unknown.
|
||||
6. Non-empty components become children: `kernel`, `ramdisk`, `second`,
|
||||
`recovery_dtbo`, `dtb`, `vendor_ramdisk`, `vendor_ramdisk/<name>`,
|
||||
`bootconfig`, and `signature`. 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 as `elf` by the existing content
|
||||
check. A `dtb` child stays a file for a later `inspect-devicetree` on the
|
||||
extracted file.
|
||||
7. 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 with `AVBf`, is undecoded trailing
|
||||
bytes. A vbmeta range that overlaps the header, a component, or the footer
|
||||
is malformed.
|
||||
8. 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_size` of at most 1 MiB. Those checks run before the table
|
||||
is read. Truncated declared structures return `truncated`; unsupported
|
||||
revisions return `unsupported_target`; malformed layouts return
|
||||
`invalid_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.
|
||||
9. CLI and MCP return the same Evidence shape, including the untrusted-string
|
||||
limitation and the unknown boot role. `androidBootImageMetadataSchema` and
|
||||
`androidBootImageEntryMetadataSchema` are `strictObject` members of the
|
||||
kind-discriminated artifact metadata union. Summary detail retains
|
||||
Evidence. `inspect_analysis_view` pages it.
|
||||
10. The reader reuses `ArtifactFileSource`, `readArtifactFileBytes`,
|
||||
`readFileHandleChunks`, and `ArtifactResourceScope`. 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_image` tool.
|
||||
- A Binwalk or Unblob adapter.
|
||||
- Assigning boot, init_boot, or recovery from the header.
|
||||
- Executing, booting, or modifying the image.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Tasks
|
||||
|
||||
Requirement numbers refer to [spec.md](spec.md). Verification names the test
|
||||
that covers the step.
|
||||
|
||||
- [x] Record this specification, [plan](plan.md), and task list for the
|
||||
Android boot image reader. (Requirements 1-10)
|
||||
- [x] Decode `ANDROID!` versions 0-4 and `VNDRBOOT` versions 3-4 in the artifact
|
||||
parser, including safe integer ranges, packed `os_version`, UTF-8
|
||||
failure, vendor ramdisk names, and tagged parse errors.
|
||||
(Requirements 1-5, 7-8; `src/artifacts/AndroidBootImageFormat.test.ts`)
|
||||
- [x] Map non-empty components to children, record compression from the
|
||||
leading magic, stream member bytes, and enforce probe and table caps
|
||||
before the table read. (Requirements 6 and 8;
|
||||
`src/artifacts/AndroidBootImageArtifactReader.test.ts`)
|
||||
- [x] Register metadata schemas and the reader on the uImage inventory,
|
||||
extraction, and target-resolution path. (Requirement 9;
|
||||
`src/artifacts/artifactFormats.test.ts`,
|
||||
`src/application/binary/TargetFormatVocabularies.test.ts`)
|
||||
- [x] Preserve untrusted-string and unknown-role limitations through CLI and
|
||||
MCP Evidence. (Requirements 5 and 9;
|
||||
`tests/acceptance/androidBootImageCli.test.ts`,
|
||||
`tests/boundary/mcp/androidBootImageMcp.test.ts`)
|
||||
- [x] Cover close retry, cancellation during admission and paused inventory,
|
||||
cancel with buffered bytes, source change after prepare, and multi-chunk
|
||||
cancel. (Requirement 10;
|
||||
`src/artifacts/AndroidBootImageArtifactReader.boundaries.test.ts`)
|
||||
- [x] Describe current behavior and the capacity bounds in
|
||||
`docs/android-boot-image.md`, and link that guide from the documentation
|
||||
directory, CLI guide, and firmware guide. (Acceptance)
|
||||
@@ -15,6 +15,9 @@ EvidenceIntegrityError,,evidence_integrity_mismatch,integrity_mismatch,false
|
||||
ProviderAdapterError,,execution_failure,execution_failure,false
|
||||
AnalysisCapabilityUnavailableError,retryable=true,capability_unavailable,unavailable,true
|
||||
ArtifactOperationError,reason=cancelled,cancelled,cancelled,true
|
||||
ArtifactOperationError,reason=malformed,invalid_request,invalid_input,false
|
||||
ArtifactOperationError,reason=truncated,truncated,truncated,false
|
||||
ArtifactOperationError,reason=unsupported,unsupported_target,unsupported_target,false
|
||||
ArtifactOperationError,reason=format,artifact_operation_failed,execution_failure,false
|
||||
ArtifactOperationError,reason=integrity,artifact_operation_failed,integrity_mismatch,false
|
||||
ArtifactOperationError,reason=limit,truncated,truncated,false
|
||||
|
||||
|
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schemas": {
|
||||
"input compact": "706f1985ca397688",
|
||||
"output compact": "52860f8f8ed909d0"
|
||||
"output compact": "c100ceae46994f08"
|
||||
},
|
||||
"patterns": {
|
||||
"input": [
|
||||
|
||||
@@ -122,6 +122,7 @@ const TARGETS: TargetFixtures = {
|
||||
unityfs: { ...archive, format: "unityfs" },
|
||||
wxapkg: { ...archive, format: "wxapkg" },
|
||||
uimage: { ...archive, format: "uimage" },
|
||||
"android-boot-image": { ...archive, format: "android-boot-image" },
|
||||
uf2: { ...archive, format: "uf2" },
|
||||
dfuse: { ...archive, format: "dfuse" },
|
||||
dmg: { ...archive, format: "dmg" },
|
||||
|
||||
@@ -0,0 +1,245 @@
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { buffer } from "node:stream/consumers";
|
||||
|
||||
import { expect, it, vi } from "vitest";
|
||||
|
||||
import { AndroidBootImageArtifactReader } from "./AndroidBootImageArtifactReader.js";
|
||||
import {
|
||||
ArtifactReaderFailure,
|
||||
artifactFixedLimitFailure,
|
||||
} from "../resources/index.js";
|
||||
import { openRegularFile } from "../filesystem/RegularFile.js";
|
||||
import {
|
||||
buildBootImage,
|
||||
buildVendorBootImage,
|
||||
} from "../../tests/fixtures/androidBootImage.js";
|
||||
import { artifactReaderLifecycleCases } from "../../tests/fixtures/artifactReaderLifecycle.js";
|
||||
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
|
||||
|
||||
const fixture = async (bytes: Buffer): Promise<string> => {
|
||||
const path = join(
|
||||
await createTestTempDirectory("rea-android-boot-boundary-"),
|
||||
"image",
|
||||
);
|
||||
await writeFile(path, bytes);
|
||||
return path;
|
||||
};
|
||||
|
||||
const entries = async (reader: AndroidBootImageArtifactReader) => {
|
||||
const result = [];
|
||||
for await (const entry of reader.entries()) result.push(entry);
|
||||
return result;
|
||||
};
|
||||
|
||||
it("does not publish preparation metadata or coverage after carrier mutation", async () => {
|
||||
const bytes = buildBootImage({ version: 0 });
|
||||
const path = await fixture(bytes);
|
||||
class ChangedDuringPreparation extends AndroidBootImageArtifactReader {
|
||||
protected override async prepareEntries(signal?: AbortSignal) {
|
||||
const prepared = await super.prepareEntries(signal);
|
||||
await writeFile(path, Buffer.concat([bytes, Buffer.from([0])]));
|
||||
return prepared;
|
||||
}
|
||||
}
|
||||
const reader = new ChangedDuringPreparation(path);
|
||||
const onCoverage = vi.fn();
|
||||
let yielded = 0;
|
||||
try {
|
||||
await expect(
|
||||
(async () => {
|
||||
for await (const _entry of reader.entries(undefined, { onCoverage }))
|
||||
yielded += 1;
|
||||
})(),
|
||||
).rejects.toMatchObject({ reason: "integrity" });
|
||||
expect(yielded).toBe(0);
|
||||
expect(onCoverage).not.toHaveBeenCalled();
|
||||
expect(reader.formatMetadata()).toBeUndefined();
|
||||
} finally {
|
||||
await reader.close();
|
||||
}
|
||||
});
|
||||
|
||||
it.each(["invalid", "cancelled"] as const)(
|
||||
"retries a first %s preparation without publishing its metadata",
|
||||
async (mode) => {
|
||||
const path = await fixture(buildBootImage({ version: 0 }));
|
||||
const controller = new AbortController();
|
||||
let refuse = true;
|
||||
class InterruptedPreparation extends AndroidBootImageArtifactReader {
|
||||
protected override async prepareEntries(signal?: AbortSignal) {
|
||||
const prepared = await super.prepareEntries(signal);
|
||||
if (refuse) {
|
||||
refuse = false;
|
||||
if (mode === "invalid")
|
||||
throw new ArtifactReaderFailure(
|
||||
"malformed",
|
||||
"injected preparation failure",
|
||||
);
|
||||
controller.abort(new Error("cancel final preparation validation"));
|
||||
}
|
||||
return prepared;
|
||||
}
|
||||
}
|
||||
const reader = new InterruptedPreparation(path);
|
||||
try {
|
||||
const onCoverage = vi.fn();
|
||||
await expect(
|
||||
(async () => {
|
||||
for await (const _entry of reader.entries(controller.signal, {
|
||||
onCoverage,
|
||||
})) {
|
||||
throw new Error("Failed preparation yielded an entry");
|
||||
}
|
||||
})(),
|
||||
).rejects.toMatchObject({
|
||||
reason: mode === "invalid" ? "malformed" : "cancelled",
|
||||
});
|
||||
expect(onCoverage).not.toHaveBeenCalled();
|
||||
expect(reader.formatMetadata()).toBeUndefined();
|
||||
expect(await entries(reader)).toHaveLength(2);
|
||||
expect(reader.formatMetadata()).toMatchObject({
|
||||
header_version: 0,
|
||||
component_count: 2,
|
||||
});
|
||||
} finally {
|
||||
await reader.close();
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it("preserves cancellation during header admission", async () => {
|
||||
const path = await fixture(buildBootImage({ version: 0 }));
|
||||
const admitted = await openRegularFile(path, { symlinks: "reject" });
|
||||
const reader = new AndroidBootImageArtifactReader(path, admitted);
|
||||
const controller = new AbortController();
|
||||
const reason = new Error("cancel header admission");
|
||||
const nativeRead = admitted.handle.read.bind(admitted.handle);
|
||||
const reads = vi.spyOn(admitted.handle, "read").mockImplementation((async (
|
||||
...args: unknown[]
|
||||
) => {
|
||||
const result = await Reflect.apply(nativeRead, admitted.handle, args);
|
||||
if (args[3] === 0) controller.abort(reason);
|
||||
return result;
|
||||
}) as typeof admitted.handle.read);
|
||||
try {
|
||||
await expect(
|
||||
(async () => {
|
||||
for await (const _entry of reader.entries(controller.signal)) {
|
||||
/* Exhaust the admitted operation. */
|
||||
}
|
||||
})(),
|
||||
).rejects.toMatchObject({ reason: "cancelled", cause: reason });
|
||||
} finally {
|
||||
await reader.close();
|
||||
reads.mockRestore();
|
||||
await admitted.handle.close();
|
||||
}
|
||||
});
|
||||
|
||||
const vendorBootWithRamdisks = (count: number): Buffer =>
|
||||
buildVendorBootImage({
|
||||
version: 4,
|
||||
ramdisks: Array.from({ length: count }, (_, index) => ({
|
||||
name: `ramdisk${String(index)}`,
|
||||
bytes: Buffer.from([index & 0xff]),
|
||||
})),
|
||||
});
|
||||
|
||||
it("inventories a vendor ramdisk table at its 4096-entry allowance", async () => {
|
||||
const path = await fixture(vendorBootWithRamdisks(4096));
|
||||
const admitted = await openRegularFile(path, { symlinks: "reject" });
|
||||
const reader = new AndroidBootImageArtifactReader(path, admitted);
|
||||
try {
|
||||
const listed = await entries(reader);
|
||||
expect(
|
||||
listed.filter((entry) => entry.path.startsWith("vendor_ramdisk")),
|
||||
).toHaveLength(4096);
|
||||
} finally {
|
||||
await reader.close();
|
||||
await admitted.handle.close();
|
||||
}
|
||||
});
|
||||
|
||||
it("rejects an excessive vendor ramdisk count before reading the table", async () => {
|
||||
const path = await fixture(vendorBootWithRamdisks(4097));
|
||||
const admitted = await openRegularFile(path, { symlinks: "reject" });
|
||||
const reader = new AndroidBootImageArtifactReader(path, admitted);
|
||||
const reads = vi.spyOn(admitted.handle, "read");
|
||||
try {
|
||||
const failure: unknown = await entries(reader).then(
|
||||
() => undefined,
|
||||
(cause: unknown) => cause,
|
||||
);
|
||||
// The limit's facts and the recovery its owning formatter produces.
|
||||
expect(failure).toMatchObject({
|
||||
reason: "limit",
|
||||
boundary: "capacity",
|
||||
fixedAllowance: artifactFixedLimitFailure(
|
||||
{
|
||||
name: "Android vendor ramdisk table entry count",
|
||||
kind: "parser",
|
||||
limit: 4096,
|
||||
unit: "entries",
|
||||
},
|
||||
"table count",
|
||||
).fixedAllowance,
|
||||
cause: {
|
||||
kind: "limit",
|
||||
failure: { limit: { maximum: 4096 } },
|
||||
},
|
||||
});
|
||||
expect(reads).toHaveBeenCalledTimes(1);
|
||||
} finally {
|
||||
await reader.close();
|
||||
reads.mockRestore();
|
||||
await admitted.handle.close();
|
||||
}
|
||||
});
|
||||
|
||||
artifactReaderLifecycleCases({
|
||||
image: () => buildBootImage({ version: 0 }),
|
||||
createReader: (path, admitted) =>
|
||||
new AndroidBootImageArtifactReader(path, admitted),
|
||||
});
|
||||
|
||||
it("rejects a source changed after its header was prepared", async () => {
|
||||
const bytes = buildBootImage({ version: 0 });
|
||||
const path = await fixture(bytes);
|
||||
const reader = new AndroidBootImageArtifactReader(path);
|
||||
try {
|
||||
const [entry] = await entries(reader);
|
||||
await writeFile(path, Buffer.concat([bytes, Buffer.from([0])]));
|
||||
await expect(reader.open(entry!)).rejects.toMatchObject({
|
||||
reason: "integrity",
|
||||
});
|
||||
} finally {
|
||||
await reader.close();
|
||||
}
|
||||
});
|
||||
|
||||
it("checks a multi-chunk member and preserves read cancellation", async () => {
|
||||
const kernel = Buffer.alloc(128 * 1024, 0x61);
|
||||
const bytes = buildBootImage({
|
||||
version: 0,
|
||||
kernel,
|
||||
ramdisk: Buffer.alloc(0),
|
||||
});
|
||||
const reader = new AndroidBootImageArtifactReader(await fixture(bytes));
|
||||
try {
|
||||
const [entry] = await entries(reader);
|
||||
const controller = new AbortController();
|
||||
const reason = new Error("cancel member bytes");
|
||||
const stream = await reader.open(entry!, controller.signal);
|
||||
const iterator = stream[Symbol.asyncIterator]();
|
||||
await iterator.next();
|
||||
controller.abort(reason);
|
||||
await expect(iterator.next()).rejects.toMatchObject({
|
||||
reason: "cancelled",
|
||||
cause: reason,
|
||||
});
|
||||
expect((await buffer(await reader.open(entry!))).equals(kernel)).toBe(true);
|
||||
} finally {
|
||||
await reader.close();
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,330 @@
|
||||
import { readFile, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import type { Readable } from "node:stream";
|
||||
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { AndroidBootImageArtifactReader } from "./AndroidBootImageArtifactReader.js";
|
||||
import { classifyArtifactBytesAtPath } from "../../tests/fixtures/artifactClassification.js";
|
||||
import { scanCanonicalArtifactInventory } from "../../tests/fixtures/artifactInventory.js";
|
||||
import {
|
||||
appendAvbFooter,
|
||||
buildBootImage,
|
||||
buildVendorBootImage,
|
||||
osVersionRaw,
|
||||
truncateImage,
|
||||
} from "../../tests/fixtures/androidBootImage.js";
|
||||
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
|
||||
import { elf } from "../domain/binaryTarget.fixture.js";
|
||||
|
||||
const collect = async (stream: Readable): Promise<Buffer> => {
|
||||
const chunks: Buffer[] = [];
|
||||
for await (const chunk of stream) chunks.push(chunk as Buffer);
|
||||
return Buffer.concat(chunks);
|
||||
};
|
||||
|
||||
const writeCarrier = async (name: string, bytes: Buffer): Promise<string> => {
|
||||
const directory = await createTestTempDirectory("rea-android-boot-");
|
||||
const path = join(directory, name);
|
||||
await writeFile(path, bytes);
|
||||
return path;
|
||||
};
|
||||
|
||||
const openAll = async (path: string): Promise<ReadonlyMap<string, Buffer>> => {
|
||||
const reader = new AndroidBootImageArtifactReader(path);
|
||||
const out = new Map<string, Buffer>();
|
||||
try {
|
||||
const entries = [];
|
||||
for await (const entry of reader.entries()) entries.push(entry);
|
||||
for (const entry of entries)
|
||||
out.set(entry.path, await collect(await reader.open(entry)));
|
||||
return out;
|
||||
} finally {
|
||||
await reader.close();
|
||||
}
|
||||
};
|
||||
|
||||
it("classifies boot and vendor_boot bytes by content, not by suffix", () => {
|
||||
expect(
|
||||
classifyArtifactBytesAtPath("notes.txt", buildBootImage({ version: 0 })),
|
||||
).toEqual({ kind: "container", format: "android-boot-image" });
|
||||
expect(
|
||||
classifyArtifactBytesAtPath(
|
||||
"vendor.bin",
|
||||
buildVendorBootImage({ version: 4 }),
|
||||
),
|
||||
).toEqual({ kind: "container", format: "android-boot-image" });
|
||||
expect(classifyArtifactBytesAtPath("notes.txt", Buffer.from("nope"))).toEqual(
|
||||
{ kind: "resource", format: "file" },
|
||||
);
|
||||
});
|
||||
|
||||
it("inventories and extracts a v0 image", async () => {
|
||||
const kernel = Buffer.from("kernel-bytes");
|
||||
const ramdisk = Buffer.from("ramdisk-bytes");
|
||||
const path = await writeCarrier(
|
||||
"boot.img",
|
||||
buildBootImage({
|
||||
version: 0,
|
||||
kernel,
|
||||
ramdisk,
|
||||
osVersion: osVersionRaw(13, 0, 0, 2024, 11),
|
||||
}),
|
||||
);
|
||||
const snapshot = await scanCanonicalArtifactInventory(path);
|
||||
expect(snapshot.manifest.root_format).toBe("android-boot-image");
|
||||
expect(snapshot.coverage.status).toBe("complete");
|
||||
expect(snapshot.limitations.join(" ")).toContain("not decompressed");
|
||||
expect(snapshot.limitations.join(" ")).toContain("untrusted");
|
||||
const root = snapshot.occurrences.find((row) => row.logical_path === ".");
|
||||
expect(root).toMatchObject({ artifact_kind: "container" });
|
||||
expect(root?.format_metadata).toMatchObject({
|
||||
kind: "android-boot-image",
|
||||
image_kind: "boot",
|
||||
header_version: 0,
|
||||
os_version: "13.0.0",
|
||||
security_patch_level: "2024-11",
|
||||
command_line: "console=tty0 androidboot.hardware=test",
|
||||
component_count: 2,
|
||||
avb_footer_present: false,
|
||||
avb_footer_size: null,
|
||||
});
|
||||
const stored = await openAll(path);
|
||||
expect(stored.get("kernel")?.equals(kernel)).toBe(true);
|
||||
expect(stored.get("ramdisk")?.equals(ramdisk)).toBe(true);
|
||||
const carrier = await readFile(path);
|
||||
expect(carrier.subarray(2048, 2048 + kernel.length).equals(kernel)).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
|
||||
it("extracts a v2 DTB, a v4 signature, and compressed ramdisks as stored", async () => {
|
||||
const dtb = Buffer.from("dtb-payload");
|
||||
const v2 = await writeCarrier(
|
||||
"v2.img",
|
||||
buildBootImage({
|
||||
version: 2,
|
||||
// A decodable ELF64 little-endian x86-64 header, as classification requires.
|
||||
kernel: elf(2, 1, 62),
|
||||
ramdisk: Buffer.alloc(0),
|
||||
dtb,
|
||||
}),
|
||||
);
|
||||
const v2Graph = await scanCanonicalArtifactInventory(v2);
|
||||
expect(
|
||||
v2Graph.occurrences.find((row) => row.logical_path === "kernel"),
|
||||
).toMatchObject({ artifact_format: "elf" });
|
||||
expect(
|
||||
v2Graph.occurrences.find((row) => row.logical_path === "dtb"),
|
||||
).toMatchObject({
|
||||
artifact_format: "file",
|
||||
source_location: { offset: 4096, length: dtb.length },
|
||||
});
|
||||
expect((await openAll(v2)).get("dtb")?.equals(dtb)).toBe(true);
|
||||
|
||||
const signature = Buffer.from("boot-signature");
|
||||
const v4 = await writeCarrier(
|
||||
"v4.img",
|
||||
buildBootImage({
|
||||
version: 4,
|
||||
kernel: Buffer.from("kern"),
|
||||
ramdisk: Buffer.alloc(0),
|
||||
signature,
|
||||
}),
|
||||
);
|
||||
const v4Root = (await scanCanonicalArtifactInventory(v4)).occurrences.find(
|
||||
(row) => row.logical_path === ".",
|
||||
);
|
||||
expect(v4Root?.format_metadata).toMatchObject({
|
||||
header_version: 4,
|
||||
signature_size: signature.length,
|
||||
page_size: 4096,
|
||||
});
|
||||
expect((await openAll(v4)).get("signature")?.equals(signature)).toBe(true);
|
||||
|
||||
const gzip = Buffer.from([0x1f, 0x8b, 0x08, 0]);
|
||||
const lz4 = Buffer.from([0x04, 0x22, 0x4d, 0x18, 1]);
|
||||
const zstd = Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 2]);
|
||||
const compressed = await writeCarrier(
|
||||
"compressed.img",
|
||||
buildBootImage({ version: 0, kernel: lz4, ramdisk: gzip, second: zstd }),
|
||||
);
|
||||
const graph = await scanCanonicalArtifactInventory(compressed);
|
||||
expect(
|
||||
graph.occurrences.find((row) => row.logical_path === "ramdisk")
|
||||
?.format_metadata,
|
||||
).toMatchObject({ compression: "gzip" });
|
||||
expect(
|
||||
graph.occurrences.find((row) => row.logical_path === "kernel")
|
||||
?.format_metadata,
|
||||
).toMatchObject({ compression: "lz4" });
|
||||
expect(
|
||||
graph.occurrences.find((row) => row.logical_path === "second")
|
||||
?.format_metadata,
|
||||
).toMatchObject({ compression: "zstd" });
|
||||
const stored = await openAll(compressed);
|
||||
expect(stored.get("ramdisk")?.equals(gzip)).toBe(true);
|
||||
expect(stored.get("kernel")?.equals(lz4)).toBe(true);
|
||||
expect(stored.get("second")?.equals(zstd)).toBe(true);
|
||||
expect(
|
||||
graph.occurrences
|
||||
.find((row) => row.logical_path === "ramdisk")
|
||||
?.limitations.join(" "),
|
||||
).toContain("not decompressed");
|
||||
});
|
||||
|
||||
it("extracts two vendor ramdisks without inventing fragment load addresses", async () => {
|
||||
const platform = Buffer.from("platform-bytes");
|
||||
const recovery = Buffer.from("recovery-bytes");
|
||||
const dtb = Buffer.from("vendor-dtb");
|
||||
const bootconfig = Buffer.from("androidboot.hardware=test\n");
|
||||
const path = await writeCarrier(
|
||||
"vendor_boot.img",
|
||||
buildVendorBootImage({
|
||||
version: 4,
|
||||
ramdisks: [
|
||||
{ name: "platform", type: 1, bytes: platform },
|
||||
{ name: "recovery", type: 2, bytes: recovery },
|
||||
],
|
||||
dtb,
|
||||
bootconfig,
|
||||
}),
|
||||
);
|
||||
const snapshot = await scanCanonicalArtifactInventory(path);
|
||||
expect(
|
||||
snapshot.occurrences.find((row) => row.logical_path === ".")
|
||||
?.format_metadata,
|
||||
).toMatchObject({
|
||||
image_kind: "vendor-boot",
|
||||
vendor_ramdisk_table_entry_count: 2,
|
||||
component_count: 4,
|
||||
ramdisk_addr: 0x8100_0000,
|
||||
});
|
||||
const platformEntry = snapshot.occurrences.find(
|
||||
(row) => row.logical_path === "vendor_ramdisk/platform",
|
||||
);
|
||||
expect(platformEntry?.format_metadata).toMatchObject({
|
||||
role: "vendor-ramdisk",
|
||||
ramdisk_type: 1,
|
||||
ramdisk_type_name: "platform",
|
||||
load_address: null,
|
||||
});
|
||||
expect(
|
||||
snapshot.occurrences.find(
|
||||
(row) => row.logical_path === "vendor_ramdisk/recovery",
|
||||
)?.format_metadata,
|
||||
).toMatchObject({ ramdisk_type_name: "recovery", load_address: null });
|
||||
expect(platformEntry?.source_location).toEqual({
|
||||
offset: 4096,
|
||||
length: platform.length,
|
||||
});
|
||||
const stored = await openAll(path);
|
||||
expect(stored.get("vendor_ramdisk/platform")?.equals(platform)).toBe(true);
|
||||
expect(stored.get("vendor_ramdisk/recovery")?.equals(recovery)).toBe(true);
|
||||
expect(stored.get("dtb")?.equals(dtb)).toBe(true);
|
||||
expect(stored.get("bootconfig")?.equals(bootconfig)).toBe(true);
|
||||
});
|
||||
|
||||
it("keeps canonically equivalent ramdisk names distinct after normalization", async () => {
|
||||
const composed = "\u00e9";
|
||||
const decomposed = "e\u0301";
|
||||
const first = Buffer.from("composed-bytes");
|
||||
const second = Buffer.from("decomposed-bytes");
|
||||
const path = await writeCarrier(
|
||||
"vendor_boot.img",
|
||||
buildVendorBootImage({
|
||||
version: 4,
|
||||
ramdisks: [
|
||||
{ name: composed, type: 1, bytes: first },
|
||||
{ name: decomposed, type: 1, bytes: second },
|
||||
],
|
||||
}),
|
||||
);
|
||||
const snapshot = await scanCanonicalArtifactInventory(path);
|
||||
const fragments = snapshot.occurrences.filter((row) =>
|
||||
row.logical_path.startsWith("vendor_ramdisk/"),
|
||||
);
|
||||
expect(fragments.map((row) => row.logical_path)).toEqual([
|
||||
`vendor_ramdisk/${composed}`,
|
||||
`vendor_ramdisk/${composed}-1`,
|
||||
]);
|
||||
const hex = (name: string): string =>
|
||||
Buffer.concat([Buffer.from(name, "utf8"), Buffer.alloc(32)])
|
||||
.subarray(0, 32)
|
||||
.toString("hex");
|
||||
expect(
|
||||
fragments.map(
|
||||
(row) =>
|
||||
(row.format_metadata as { name_bytes_hex?: string }).name_bytes_hex,
|
||||
),
|
||||
).toEqual([hex(composed), hex(decomposed)]);
|
||||
const stored = await openAll(path);
|
||||
expect(stored.get(`vendor_ramdisk/${composed}`)?.equals(first)).toBe(true);
|
||||
expect(stored.get(`vendor_ramdisk/${composed}-1`)?.equals(second)).toBe(true);
|
||||
});
|
||||
|
||||
it("records an AVB footer without treating it as a child", async () => {
|
||||
const image = buildBootImage({ version: 3, cmdline: "console=tty0" });
|
||||
const path = await writeCarrier("avb.img", appendAvbFooter(image));
|
||||
const root = (await scanCanonicalArtifactInventory(path)).occurrences.find(
|
||||
(row) => row.logical_path === ".",
|
||||
);
|
||||
expect(root?.format_metadata).toMatchObject({
|
||||
avb_footer_present: true,
|
||||
avb_footer_size: 64,
|
||||
avb_version_major: 1,
|
||||
avb_original_image_size: image.length,
|
||||
avb_vbmeta_offset: image.length,
|
||||
command_line: "console=tty0",
|
||||
});
|
||||
const paths = (await openAll(path)).keys();
|
||||
expect([...paths]).not.toContain("vbmeta");
|
||||
const unrecognized = await writeCarrier(
|
||||
"trailing.img",
|
||||
Buffer.concat([image, Buffer.alloc(64)]),
|
||||
);
|
||||
const trailing = (
|
||||
await scanCanonicalArtifactInventory(unrecognized)
|
||||
).occurrences.find((row) => row.logical_path === ".");
|
||||
expect(trailing?.format_metadata).toMatchObject({
|
||||
avb_footer_present: false,
|
||||
avb_footer_size: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("fails closed on truncation and overlapping ranges", async () => {
|
||||
const truncated = await writeCarrier(
|
||||
"truncated.img",
|
||||
truncateImage(buildBootImage({ version: 0 })),
|
||||
);
|
||||
await expect(scanCanonicalArtifactInventory(truncated)).rejects.toThrow(
|
||||
/truncated/u,
|
||||
);
|
||||
const overlap = await writeCarrier(
|
||||
"overlap.img",
|
||||
buildBootImage({
|
||||
version: 2,
|
||||
recoveryDtbo: Buffer.from("dtbo"),
|
||||
recoveryDtboOffset: 2048,
|
||||
dtb: Buffer.from("dtb"),
|
||||
}),
|
||||
);
|
||||
await expect(scanCanonicalArtifactInventory(overlap)).rejects.toThrow(
|
||||
/overlaps an earlier component/u,
|
||||
);
|
||||
const vendor = buildVendorBootImage({
|
||||
version: 4,
|
||||
ramdisks: [
|
||||
{ name: "one", type: 1, bytes: Buffer.from("aaa") },
|
||||
{ name: "two", type: 1, bytes: Buffer.from("bbbbb") },
|
||||
],
|
||||
});
|
||||
const overlapped = Buffer.from(vendor);
|
||||
const entrySize = overlapped.readUInt32LE(2120);
|
||||
overlapped.writeUInt32LE(0, 8192 + entrySize + 4);
|
||||
await expect(
|
||||
scanCanonicalArtifactInventory(
|
||||
await writeCarrier("vendor-overlap.img", overlapped),
|
||||
),
|
||||
).rejects.toThrow(/overlaps entry/u);
|
||||
});
|
||||
@@ -0,0 +1,297 @@
|
||||
import type { FileHandle } from "node:fs/promises";
|
||||
import type { ParseFailureError } from "../domain/parseFailure.js";
|
||||
|
||||
import { readArtifactFileBytes } from "./ArtifactFileRange.js";
|
||||
import {
|
||||
ArtifactReaderFailure,
|
||||
artifactFixedLimitFailure,
|
||||
artifactParseFailure,
|
||||
} from "../resources/index.js";
|
||||
import {
|
||||
PositionalArtifactReader,
|
||||
type PositionalArtifactEntries,
|
||||
type PositionalArtifactEntry,
|
||||
} from "./PositionalArtifactReader.js";
|
||||
import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js";
|
||||
import type {
|
||||
AndroidBootImageEntryMetadata,
|
||||
AndroidBootImageMetadata,
|
||||
} from "../domain/artifactFormatMetadata.js";
|
||||
import {
|
||||
ANDROID_BOOT_HEADER_PROBE_BYTES,
|
||||
ANDROID_BOOT_FIXED_LIMITS,
|
||||
AVB_FOOTER_SIZE,
|
||||
compressionFromPrefix,
|
||||
inspectAvbFooter,
|
||||
parseAndroidBootHeader,
|
||||
parseVendorRamdiskTable,
|
||||
type AndroidBootComponentPlan,
|
||||
type AndroidBootCompression,
|
||||
type AndroidBootParse,
|
||||
type AvbFooterFacts,
|
||||
type VendorRamdiskTableParse,
|
||||
} from "./AndroidBootImageFormat.js";
|
||||
|
||||
type BootEntry = PositionalArtifactEntry & {
|
||||
readonly formatMetadata: AndroidBootImageEntryMetadata;
|
||||
};
|
||||
|
||||
const COMPRESSION_LIMITATION =
|
||||
"Compression was identified from the leading magic only and the stored bytes were not decompressed.";
|
||||
|
||||
/** Read an Android boot or vendor_boot image without unpacking or verifying it. */
|
||||
export class AndroidBootImageArtifactReader extends PositionalArtifactReader<AndroidBootImageMetadata> {
|
||||
override readonly format = "android-boot-image" as const;
|
||||
|
||||
constructor(path: string, admitted?: StableRegularFileDescriptor) {
|
||||
super(path, "Android boot image", admitted);
|
||||
}
|
||||
|
||||
formatMetadata(): AndroidBootImageMetadata | undefined {
|
||||
const metadata = this.preparedFormatMetadata;
|
||||
return metadata === undefined ? undefined : { ...metadata };
|
||||
}
|
||||
|
||||
protected override async prepareEntries(
|
||||
signal?: AbortSignal,
|
||||
): Promise<PositionalArtifactEntries<AndroidBootImageMetadata>> {
|
||||
const { handle, initial } = await this.verifyCarrier(signal);
|
||||
const headerBytes = await readArtifactFileBytes(
|
||||
handle,
|
||||
0,
|
||||
Math.min(initial.size, ANDROID_BOOT_HEADER_PROBE_BYTES),
|
||||
initial.size,
|
||||
signal,
|
||||
);
|
||||
this.assertOpen(signal);
|
||||
const parsed = parseAndroidBootHeader(headerBytes, initial.size);
|
||||
if (!parsed.ok) throw parseFailure(parsed.error);
|
||||
const header = parsed.value;
|
||||
const table = await this.#vendorTable(handle, initial.size, header, signal);
|
||||
const plans = [...(table?.components ?? []), ...header.components];
|
||||
const avb = await this.#footer(handle, initial.size, header, plans, signal);
|
||||
const compressions = await this.#compression(
|
||||
handle,
|
||||
initial.size,
|
||||
plans,
|
||||
signal,
|
||||
);
|
||||
const entries = new Map<string, BootEntry>();
|
||||
for (const plan of plans) {
|
||||
const entry = entryFor(plan, compressions.get(plan.path) ?? null);
|
||||
if (entries.has(entry.adapterKey))
|
||||
throw formatFailure(`duplicate component path ${plan.path}`);
|
||||
entries.set(entry.adapterKey, entry);
|
||||
}
|
||||
return {
|
||||
entries: [...entries.values()],
|
||||
formatMetadata: toMetadata(header, avb, plans.length),
|
||||
coverage: {
|
||||
status: "complete",
|
||||
limitations: [
|
||||
...header.limitations,
|
||||
...(table?.limitations ?? []),
|
||||
...avb.limitations,
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async #vendorTable(
|
||||
handle: Pick<FileHandle, "read">,
|
||||
fileSize: number,
|
||||
header: AndroidBootParse,
|
||||
signal?: AbortSignal,
|
||||
): Promise<VendorRamdiskTableParse | undefined> {
|
||||
const range = header.tableRange;
|
||||
if (range === null) return undefined;
|
||||
const section = header.vendorRamdiskSection;
|
||||
if (
|
||||
section === null ||
|
||||
header.vendorRamdiskTableEntryCount === null ||
|
||||
header.vendorRamdiskTableEntrySize === null
|
||||
)
|
||||
throw formatFailure("vendor ramdisk table is missing its section");
|
||||
this.assertOpen(signal);
|
||||
const bytes = await readArtifactFileBytes(
|
||||
handle,
|
||||
range.offset,
|
||||
range.size,
|
||||
fileSize,
|
||||
signal,
|
||||
);
|
||||
const table = parseVendorRamdiskTable(bytes, {
|
||||
entryCount: header.vendorRamdiskTableEntryCount,
|
||||
entrySize: header.vendorRamdiskTableEntrySize,
|
||||
sectionOffset: section.offset,
|
||||
sectionSize: section.size,
|
||||
});
|
||||
if (!table.ok) throw parseFailure(table.error);
|
||||
return table.value;
|
||||
}
|
||||
|
||||
async #footer(
|
||||
handle: Pick<FileHandle, "read">,
|
||||
fileSize: number,
|
||||
header: AndroidBootParse,
|
||||
plans: readonly AndroidBootComponentPlan[],
|
||||
signal?: AbortSignal,
|
||||
): Promise<AvbFooterFacts> {
|
||||
const trailing = fileSize - header.imageEnd;
|
||||
this.assertOpen(signal);
|
||||
const tail =
|
||||
trailing >= AVB_FOOTER_SIZE
|
||||
? await readArtifactFileBytes(
|
||||
handle,
|
||||
fileSize - AVB_FOOTER_SIZE,
|
||||
AVB_FOOTER_SIZE,
|
||||
fileSize,
|
||||
signal,
|
||||
)
|
||||
: null;
|
||||
const footer = inspectAvbFooter({
|
||||
fileSize,
|
||||
imageEnd: header.imageEnd,
|
||||
headerOccupied: header.headerOccupied,
|
||||
components: [
|
||||
...plans,
|
||||
...(header.tableRange === null ? [] : [header.tableRange]),
|
||||
...(header.vendorRamdiskSection !== null &&
|
||||
header.vendorRamdiskSection.size > 0
|
||||
? [header.vendorRamdiskSection]
|
||||
: []),
|
||||
],
|
||||
tail,
|
||||
});
|
||||
if (!footer.ok) throw parseFailure(footer.error);
|
||||
return footer.value;
|
||||
}
|
||||
|
||||
async #compression(
|
||||
handle: Pick<FileHandle, "read">,
|
||||
fileSize: number,
|
||||
plans: readonly AndroidBootComponentPlan[],
|
||||
signal?: AbortSignal,
|
||||
): Promise<ReadonlyMap<string, AndroidBootCompression | null>> {
|
||||
const observed = new Map<string, AndroidBootCompression | null>();
|
||||
for (const plan of plans) {
|
||||
this.assertOpen(signal);
|
||||
const prefix = await readArtifactFileBytes(
|
||||
handle,
|
||||
plan.offset,
|
||||
Math.min(4, plan.size),
|
||||
fileSize,
|
||||
signal,
|
||||
);
|
||||
observed.set(plan.path, compressionFromPrefix(prefix));
|
||||
}
|
||||
return observed;
|
||||
}
|
||||
}
|
||||
|
||||
const formatFailure = (
|
||||
detail: string,
|
||||
options?: ErrorOptions,
|
||||
): ArtifactReaderFailure =>
|
||||
new ArtifactReaderFailure(
|
||||
"malformed",
|
||||
`Android boot image is malformed: ${detail}`,
|
||||
options,
|
||||
);
|
||||
|
||||
const parseFailure = (failure: ParseFailureError): unknown => {
|
||||
const facts = failure.failure;
|
||||
if (facts.kind === "limit") {
|
||||
const ceiling = ANDROID_BOOT_FIXED_LIMITS.get(facts.limit.name);
|
||||
if (ceiling !== undefined)
|
||||
return artifactFixedLimitFailure(
|
||||
{
|
||||
name: ceiling.name,
|
||||
kind: "parser",
|
||||
limit: facts.limit.maximum,
|
||||
unit: ceiling.unit,
|
||||
},
|
||||
failure.message,
|
||||
"capacity",
|
||||
{ cause: failure },
|
||||
);
|
||||
}
|
||||
return artifactParseFailure(failure, undefined, () => "capacity");
|
||||
};
|
||||
|
||||
const entryFor = (
|
||||
plan: AndroidBootComponentPlan,
|
||||
compression: AndroidBootCompression | null,
|
||||
): BootEntry => ({
|
||||
path: plan.path,
|
||||
kind: "file",
|
||||
declaredSize: plan.size,
|
||||
compressedSize: null,
|
||||
executable: false,
|
||||
encrypted: false,
|
||||
byteOffset: plan.offset,
|
||||
declaredIntegrity: null,
|
||||
unpacked: false,
|
||||
limitations: compression === null ? [] : [COMPRESSION_LIMITATION],
|
||||
adapterKey: `android-boot-image:${plan.path}`,
|
||||
formatMetadata: {
|
||||
kind: "android-boot-image-entry",
|
||||
role: plan.role,
|
||||
index: plan.index,
|
||||
compression,
|
||||
ramdisk_type: plan.ramdiskType,
|
||||
ramdisk_type_name: plan.ramdiskTypeName,
|
||||
load_address: plan.loadAddress,
|
||||
name_bytes_hex: plan.nameBytesHex,
|
||||
board_id_hex: plan.boardIdHex,
|
||||
},
|
||||
sourcePath: plan.path,
|
||||
});
|
||||
|
||||
const toMetadata = (
|
||||
header: AndroidBootParse,
|
||||
avb: AvbFooterFacts,
|
||||
componentCount: number,
|
||||
): AndroidBootImageMetadata => ({
|
||||
kind: "android-boot-image",
|
||||
image_kind: header.imageKind,
|
||||
magic: header.magic,
|
||||
header_version: header.headerVersion,
|
||||
page_size: header.pageSize,
|
||||
header_size: header.headerSize,
|
||||
os_version_raw: header.osVersionRaw,
|
||||
os_version: header.osVersion,
|
||||
security_patch_level: header.securityPatchLevel,
|
||||
name: header.name,
|
||||
name_bytes_hex: header.nameBytesHex,
|
||||
cmdline: header.cmdline,
|
||||
cmdline_bytes_hex: header.cmdlineBytesHex,
|
||||
extra_cmdline: header.extraCmdline,
|
||||
extra_cmdline_bytes_hex: header.extraCmdlineBytesHex,
|
||||
command_line: header.commandLine,
|
||||
header_digest_hex: header.headerDigestHex,
|
||||
kernel_addr: header.kernelAddr,
|
||||
ramdisk_addr: header.ramdiskAddr,
|
||||
second_addr: header.secondAddr,
|
||||
tags_addr: header.tagsAddr,
|
||||
dtb_addr: header.dtbAddr,
|
||||
kernel_size: header.kernelSize,
|
||||
ramdisk_size: header.ramdiskSize,
|
||||
second_size: header.secondSize,
|
||||
recovery_dtbo_size: header.recoveryDtboSize,
|
||||
recovery_dtbo_offset: header.recoveryDtboOffset,
|
||||
dtb_size: header.dtbSize,
|
||||
signature_size: header.signatureSize,
|
||||
vendor_ramdisk_size: header.vendorRamdiskSize,
|
||||
vendor_ramdisk_table_entry_count: header.vendorRamdiskTableEntryCount,
|
||||
vendor_ramdisk_table_entry_size: header.vendorRamdiskTableEntrySize,
|
||||
bootconfig_size: header.bootconfigSize,
|
||||
avb_footer_present: avb.present,
|
||||
avb_footer_size: avb.footerSize,
|
||||
avb_version_major: avb.versionMajor,
|
||||
avb_version_minor: avb.versionMinor,
|
||||
avb_original_image_size: avb.originalImageSize,
|
||||
avb_vbmeta_offset: avb.vbmetaOffset,
|
||||
avb_vbmeta_size: avb.vbmetaSize,
|
||||
component_count: componentCount,
|
||||
});
|
||||
@@ -0,0 +1,602 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
appendAvbFooter,
|
||||
buildBootImage,
|
||||
buildVendorBootImage,
|
||||
declareVendorRamdiskCount,
|
||||
osVersionRaw,
|
||||
truncateImage,
|
||||
} from "../../tests/fixtures/androidBootImage.js";
|
||||
import {
|
||||
compressionFromPrefix,
|
||||
hasAndroidBootImageMagic,
|
||||
inspectAvbFooter,
|
||||
parseAndroidBootHeader,
|
||||
parseVendorRamdiskTable,
|
||||
} from "./AndroidBootImageFormat.js";
|
||||
|
||||
const parsed = (bytes: Buffer, fileSize = bytes.length) => {
|
||||
const result = parseAndroidBootHeader(bytes.subarray(0, 4096), fileSize);
|
||||
if (!result.ok)
|
||||
throw new Error(result.error.message, { cause: result.error });
|
||||
return result.value;
|
||||
};
|
||||
|
||||
const failed = (bytes: Buffer, fileSize = bytes.length) => {
|
||||
const result = parseAndroidBootHeader(bytes.subarray(0, 4096), fileSize);
|
||||
if (result.ok) throw new Error("Expected the header to be refused");
|
||||
return result.error;
|
||||
};
|
||||
|
||||
it("recognizes ANDROID! and VNDRBOOT and names compression from a prefix", () => {
|
||||
expect(hasAndroidBootImageMagic(Buffer.from("ANDROID!"))).toBe(true);
|
||||
expect(hasAndroidBootImageMagic(Buffer.from("VNDRBOOT"))).toBe(true);
|
||||
expect(hasAndroidBootImageMagic(Buffer.from("short"))).toBe(false);
|
||||
expect(compressionFromPrefix(Buffer.from([0x1f, 0x8b]))).toBe("gzip");
|
||||
expect(compressionFromPrefix(Buffer.from([0x04, 0x22, 0x4d, 0x18]))).toBe(
|
||||
"lz4",
|
||||
);
|
||||
expect(compressionFromPrefix(Buffer.from([0x02, 0x21, 0x4c, 0x18]))).toBe(
|
||||
"lz4",
|
||||
);
|
||||
expect(compressionFromPrefix(Buffer.from([0x28, 0xb5, 0x2f, 0xfd]))).toBe(
|
||||
"zstd",
|
||||
);
|
||||
expect(compressionFromPrefix(Buffer.from("plain"))).toBeNull();
|
||||
});
|
||||
|
||||
it("decodes a v0 command line, OS version, and page-aligned kernel", () => {
|
||||
const kernel = Buffer.from("kernel");
|
||||
const image = buildBootImage({
|
||||
version: 0,
|
||||
kernel,
|
||||
osVersion: osVersionRaw(13, 0, 0, 2024, 11),
|
||||
name: "board",
|
||||
});
|
||||
expect(image.subarray(2048, 2048 + kernel.length).equals(kernel)).toBe(true);
|
||||
const facts = parsed(image);
|
||||
expect(facts).toMatchObject({
|
||||
imageKind: "boot",
|
||||
magic: "ANDROID!",
|
||||
headerVersion: 0,
|
||||
pageSize: 2048,
|
||||
headerSize: 1632,
|
||||
osVersionRaw: 436_208_011,
|
||||
osVersion: "13.0.0",
|
||||
securityPatchLevel: "2024-11",
|
||||
name: "board",
|
||||
commandLine: "console=tty0 androidboot.hardware=test",
|
||||
kernelSize: kernel.length,
|
||||
secondSize: 0,
|
||||
recoveryDtboSize: null,
|
||||
signatureSize: null,
|
||||
headerOccupied: 2048,
|
||||
});
|
||||
expect(facts.components.map((item) => item.path)).toEqual([
|
||||
"kernel",
|
||||
"ramdisk",
|
||||
]);
|
||||
expect(facts.components[0]).toMatchObject({
|
||||
offset: 2048,
|
||||
size: kernel.length,
|
||||
loadAddress: 0x8000_8000,
|
||||
});
|
||||
expect(facts.limitations).toEqual([
|
||||
"Command line, board name, and vendor ramdisk names are target-derived and untrusted.",
|
||||
"ANDROID! covers boot, init_boot, and recovery images; the header does not record which role the file had.",
|
||||
]);
|
||||
});
|
||||
|
||||
it("keeps a split UTF-8 name as hex and a non-calendar patch month as raw", () => {
|
||||
const image = buildBootImage({
|
||||
version: 0,
|
||||
name: "测".repeat(6),
|
||||
osVersion: osVersionRaw(13, 0, 0, 2024, 13),
|
||||
});
|
||||
const facts = parsed(image);
|
||||
expect(facts.name).toBeNull();
|
||||
expect(facts.nameBytesHex).toBe(image.subarray(48, 64).toString("hex"));
|
||||
expect(facts.osVersion).toBe("13.0.0");
|
||||
expect(facts.securityPatchLevel).toBeNull();
|
||||
expect(facts.limitations.join(" ")).toContain("security patch month 13");
|
||||
});
|
||||
|
||||
it("places a v2 DTB after the recovery DTBO and rejects an overlapping offset", () => {
|
||||
const dtb = Buffer.from("dtb-bytes");
|
||||
const recovery = Buffer.from("dtbo");
|
||||
const image = buildBootImage({
|
||||
version: 2,
|
||||
kernel: Buffer.from("kernel"),
|
||||
ramdisk: Buffer.alloc(0),
|
||||
recoveryDtbo: recovery,
|
||||
dtb,
|
||||
});
|
||||
expect(image.subarray(2048, 2054).equals(Buffer.from("kernel"))).toBe(true);
|
||||
const facts = parsed(image);
|
||||
const dtbo = facts.components.find((item) => item.role === "recovery-dtbo");
|
||||
const dtbPlan = facts.components.find((item) => item.role === "dtb");
|
||||
expect(dtbo).toMatchObject({ path: "recovery_dtbo", offset: 4096 });
|
||||
expect(dtbPlan).toMatchObject({
|
||||
path: "dtb",
|
||||
offset: 6144,
|
||||
size: dtb.length,
|
||||
loadAddress: 0x8200_0000,
|
||||
});
|
||||
expect(image.subarray(6144, 6144 + dtb.length).equals(dtb)).toBe(true);
|
||||
const overlap = buildBootImage({
|
||||
version: 2,
|
||||
recoveryDtbo: recovery,
|
||||
recoveryDtboOffset: 2048,
|
||||
dtb,
|
||||
});
|
||||
expect(failed(overlap).message).toContain(
|
||||
"recovery_dtbo overlaps an earlier component",
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects an unsupported version, a bad page size, and a truncated image", () => {
|
||||
const version = buildBootImage({ version: 0 });
|
||||
version.writeUInt32LE(5, 40);
|
||||
expect(failed(version)).toMatchObject({
|
||||
kind: "unsupported",
|
||||
failure: {
|
||||
format: "android-boot-image",
|
||||
field: "header_version",
|
||||
offset: 40,
|
||||
},
|
||||
message: "header version 5 is unsupported",
|
||||
});
|
||||
const page = buildBootImage({ version: 0 });
|
||||
page.writeUInt32LE(1024, 36);
|
||||
expect(failed(page)).toMatchObject({
|
||||
kind: "malformed",
|
||||
message: expect.stringContaining("page size 1024"),
|
||||
});
|
||||
const vendor = buildVendorBootImage({ version: 4 });
|
||||
vendor.writeUInt32LE(5, 8);
|
||||
expect(failed(vendor)).toMatchObject({
|
||||
kind: "unsupported",
|
||||
failure: {
|
||||
format: "android-boot-image",
|
||||
field: "header_version",
|
||||
offset: 8,
|
||||
},
|
||||
});
|
||||
expect(failed(Buffer.from("ANDROID!"))).toMatchObject({ kind: "truncated" });
|
||||
expect(failed(truncateImage(buildBootImage({ version: 0 })))).toMatchObject({
|
||||
kind: "truncated",
|
||||
failure: { format: "android-boot-image" },
|
||||
});
|
||||
});
|
||||
|
||||
it("aligns a kernel larger than 2^31 without allocating the image", () => {
|
||||
const header = Buffer.alloc(1632);
|
||||
header.write("ANDROID!", 0, "ascii");
|
||||
header.writeUInt32LE(0x8000_0001, 8);
|
||||
header.writeUInt32LE(2048, 36);
|
||||
const result = parseAndroidBootHeader(header, Number.MAX_SAFE_INTEGER);
|
||||
expect(result.ok).toBe(true);
|
||||
if (!result.ok) return;
|
||||
expect(result.value.components).toEqual([
|
||||
expect.objectContaining({
|
||||
role: "kernel",
|
||||
path: "kernel",
|
||||
offset: 2048,
|
||||
size: 0x8000_0001,
|
||||
}),
|
||||
]);
|
||||
expect(result.value.imageEnd).toBe(0x8000_1000);
|
||||
});
|
||||
|
||||
it("decodes a legacy command line whose UTF-8 character straddles the 512-byte split", () => {
|
||||
const image = buildBootImage({ version: 0, cmdline: "", extraCmdline: "" });
|
||||
const joined = Buffer.from(`${"a".repeat(511)}\u00e9 quiet`, "utf8");
|
||||
joined.copy(image, 64, 0, 512);
|
||||
joined.copy(image, 608, 512);
|
||||
const facts = parsed(image);
|
||||
expect(facts.cmdline).toBeNull();
|
||||
expect(facts.extraCmdline).toBeNull();
|
||||
expect(facts.cmdlineBytesHex).toBe(joined.subarray(0, 512).toString("hex"));
|
||||
expect(facts.commandLine).toBe(`${"a".repeat(511)}\u00e9 quiet`);
|
||||
});
|
||||
|
||||
it("keeps a legacy command line null when the joined bytes are invalid UTF-8", () => {
|
||||
const image = buildBootImage({ version: 0, cmdline: "", extraCmdline: "" });
|
||||
Buffer.from("a".repeat(511), "utf8").copy(image, 64);
|
||||
image[575] = 0xc3;
|
||||
image[608] = 0x41;
|
||||
expect(parsed(image).commandLine).toBeNull();
|
||||
});
|
||||
|
||||
it("decodes v3 and v4 boot images with a fixed 4096-byte page", () => {
|
||||
const kernel = Buffer.from("kern");
|
||||
const v3 = parsed(
|
||||
buildBootImage({
|
||||
version: 3,
|
||||
kernel,
|
||||
ramdisk: Buffer.from([0x1f, 0x8b, 1]),
|
||||
cmdline: "console=tty0",
|
||||
}),
|
||||
);
|
||||
expect(v3).toMatchObject({
|
||||
headerVersion: 3,
|
||||
pageSize: 4096,
|
||||
headerSize: 1580,
|
||||
name: null,
|
||||
kernelAddr: null,
|
||||
extraCmdline: null,
|
||||
headerDigestHex: null,
|
||||
signatureSize: null,
|
||||
commandLine: "console=tty0",
|
||||
});
|
||||
expect(v3.components.map((item) => item.offset)).toEqual([4096, 8192]);
|
||||
expect(v3.cmdlineBytesHex).toHaveLength(3072);
|
||||
const signature = Buffer.from("sig");
|
||||
const v4 = parsed(
|
||||
buildBootImage({
|
||||
version: 4,
|
||||
kernel,
|
||||
ramdisk: Buffer.alloc(0),
|
||||
signature,
|
||||
}),
|
||||
);
|
||||
expect(v4.signatureSize).toBe(signature.length);
|
||||
expect(v4.components.map((item) => item.role)).toEqual([
|
||||
"kernel",
|
||||
"signature",
|
||||
]);
|
||||
expect(v4.components[1]).toMatchObject({ offset: 8192, path: "signature" });
|
||||
});
|
||||
|
||||
it("splits a v4 vendor ramdisk table and a v3 section", () => {
|
||||
const first = Buffer.from("aaa");
|
||||
const second = Buffer.from("bbbbb");
|
||||
const dtb = Buffer.from("dtb");
|
||||
const bootconfig = Buffer.from("androidboot.serialno=abc\n");
|
||||
const boardId = Buffer.alloc(64, 0x11);
|
||||
boardId.writeUInt32LE(0x11223344, 0);
|
||||
const longName = "platform-ramdisk-name-exceeds-32b";
|
||||
const storedName = longName.slice(0, 32);
|
||||
const image = buildVendorBootImage({
|
||||
version: 4,
|
||||
ramdisks: [
|
||||
{ name: longName, type: 1, bytes: first, boardId },
|
||||
{ name: "platform", type: 2, bytes: second },
|
||||
],
|
||||
dtb,
|
||||
bootconfig,
|
||||
});
|
||||
expect(image.subarray(4096, 4099).equals(first)).toBe(true);
|
||||
const facts = parsed(image);
|
||||
expect(facts).toMatchObject({
|
||||
imageKind: "vendor-boot",
|
||||
magic: "VNDRBOOT",
|
||||
headerVersion: 4,
|
||||
pageSize: 4096,
|
||||
osVersion: null,
|
||||
vendorRamdiskSize: 8,
|
||||
vendorRamdiskTableEntryCount: 2,
|
||||
vendorRamdiskTableEntrySize: 108,
|
||||
bootconfigSize: bootconfig.length,
|
||||
});
|
||||
expect(facts.cmdlineBytesHex).toHaveLength(4096);
|
||||
expect(facts.tableRange).toEqual({ offset: 12288, size: 216 });
|
||||
const table = facts.tableRange;
|
||||
const section = facts.vendorRamdiskSection;
|
||||
if (table === null || section === null) throw new Error("missing table");
|
||||
expect(
|
||||
image.subarray(table.offset + 12, table.offset + 44).toString("utf8"),
|
||||
).toBe(storedName);
|
||||
expect(
|
||||
image.subarray(table.offset + 44, table.offset + 108).equals(boardId),
|
||||
).toBe(true);
|
||||
const rows = parseVendorRamdiskTable(
|
||||
image.subarray(table.offset, table.offset + table.size),
|
||||
{
|
||||
entryCount: 2,
|
||||
entrySize: 108,
|
||||
sectionOffset: section.offset,
|
||||
sectionSize: section.size,
|
||||
},
|
||||
);
|
||||
expect(rows.ok, JSON.stringify(rows)).toBe(true);
|
||||
if (!rows.ok) return;
|
||||
expect(rows.value.components.map((item) => item.path)).toEqual([
|
||||
`vendor_ramdisk/${storedName}`,
|
||||
"vendor_ramdisk/platform",
|
||||
]);
|
||||
expect(rows.value.components[0]?.nameBytesHex).toHaveLength(64);
|
||||
expect(rows.value.components[0]?.boardIdHex).toBe(boardId.toString("hex"));
|
||||
expect(rows.value.components[0]).toMatchObject({
|
||||
ramdiskType: 1,
|
||||
ramdiskTypeName: "platform",
|
||||
offset: 4096,
|
||||
size: first.length,
|
||||
});
|
||||
expect(rows.value.components.map((item) => item.loadAddress)).toEqual([
|
||||
null,
|
||||
null,
|
||||
]);
|
||||
const v3 = buildVendorBootImage({
|
||||
version: 3,
|
||||
pageSize: 2048,
|
||||
ramdisk: Buffer.from("ram"),
|
||||
});
|
||||
expect(v3.subarray(4096, 4099).equals(Buffer.from("ram"))).toBe(true);
|
||||
expect(parsed(v3).components).toEqual([
|
||||
expect.objectContaining({
|
||||
path: "vendor_ramdisk",
|
||||
offset: 4096,
|
||||
size: 3,
|
||||
loadAddress: 0x8100_0000,
|
||||
}),
|
||||
]);
|
||||
});
|
||||
|
||||
it("rejects vendor table overlap, overrun, and an excessive entry count", () => {
|
||||
const image = buildVendorBootImage({
|
||||
version: 4,
|
||||
ramdisks: [
|
||||
{ name: "one", type: 1, bytes: Buffer.from("aaa") },
|
||||
{ name: "two", type: 1, bytes: Buffer.from("bbbbb") },
|
||||
],
|
||||
});
|
||||
const facts = parsed(image);
|
||||
const table = facts.tableRange;
|
||||
const section = facts.vendorRamdiskSection;
|
||||
const entrySize = facts.vendorRamdiskTableEntrySize;
|
||||
if (
|
||||
table === null ||
|
||||
section === null ||
|
||||
entrySize === null ||
|
||||
facts.vendorRamdiskTableEntryCount === null
|
||||
)
|
||||
throw new Error("missing table");
|
||||
const input = {
|
||||
entryCount: facts.vendorRamdiskTableEntryCount,
|
||||
entrySize,
|
||||
sectionOffset: section.offset,
|
||||
sectionSize: section.size,
|
||||
};
|
||||
const rows = (source: Buffer) =>
|
||||
parseVendorRamdiskTable(
|
||||
source.subarray(table.offset, table.offset + table.size),
|
||||
input,
|
||||
);
|
||||
const overlap = Buffer.from(image);
|
||||
const short = rows(image.subarray(0, table.offset + table.size - 1));
|
||||
if (short.ok) throw new Error("Expected a truncated ramdisk table");
|
||||
expect(short.error).toMatchObject({
|
||||
kind: "truncated",
|
||||
failure: { field: "vendor ramdisk table" },
|
||||
});
|
||||
overlap.writeUInt32LE(0, table.offset + entrySize + 4);
|
||||
const overlapped = rows(overlap);
|
||||
expect(overlapped.ok).toBe(false);
|
||||
if (overlapped.ok) return;
|
||||
expect(overlapped.error.message).toContain("overlaps entry");
|
||||
const overrun = Buffer.from(image);
|
||||
overrun.writeUInt32LE(100, table.offset);
|
||||
const overran = rows(overrun);
|
||||
expect(overran.ok).toBe(false);
|
||||
if (overran.ok) return;
|
||||
expect(overran.error.message).toContain("overruns the vendor ramdisk");
|
||||
const capacity = failed(
|
||||
declareVendorRamdiskCount(buildVendorBootImage({ version: 4 }), 4097),
|
||||
);
|
||||
expect(capacity).toMatchObject({
|
||||
kind: "limit",
|
||||
failure: {
|
||||
format: "android-boot-image",
|
||||
limit: {
|
||||
name: "Android vendor ramdisk table entry count",
|
||||
maximum: 4096,
|
||||
},
|
||||
},
|
||||
});
|
||||
expect(capacity.message).toContain("4096");
|
||||
expect(
|
||||
failed(
|
||||
buildVendorBootImage({
|
||||
version: 4,
|
||||
entrySize: 107,
|
||||
ramdisks: [{ name: "short", bytes: Buffer.from("abcd") }],
|
||||
}),
|
||||
).message,
|
||||
).toContain("smaller than the 108-byte");
|
||||
});
|
||||
|
||||
it("names unsafe vendor ramdisk paths and reports an uncovered section", () => {
|
||||
const entry = (name: string, offset: number): Buffer => {
|
||||
const row = Buffer.alloc(108);
|
||||
row.writeUInt32LE(4, 0);
|
||||
row.writeUInt32LE(offset, 4);
|
||||
Buffer.from(name, "utf8").copy(row, 12);
|
||||
return row;
|
||||
};
|
||||
const table = Buffer.concat([
|
||||
entry("a/b", 0),
|
||||
entry(".", 4),
|
||||
entry("same", 8),
|
||||
entry("same", 12),
|
||||
]);
|
||||
const result = parseVendorRamdiskTable(table, {
|
||||
entryCount: 4,
|
||||
entrySize: 108,
|
||||
sectionOffset: 4096,
|
||||
sectionSize: 16,
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
if (!result.ok) return;
|
||||
expect(result.value.components.map((item) => item.path)).toEqual([
|
||||
"vendor_ramdisk/ramdisk-0",
|
||||
"vendor_ramdisk/ramdisk-1",
|
||||
"vendor_ramdisk/same",
|
||||
"vendor_ramdisk/same-3",
|
||||
]);
|
||||
const uncovered = parsed(
|
||||
buildVendorBootImage({
|
||||
version: 4,
|
||||
section: Buffer.from("uncovered-section"),
|
||||
}),
|
||||
);
|
||||
expect(uncovered.components).toEqual([]);
|
||||
expect(uncovered.limitations.join(" ")).toContain(
|
||||
"outside the ramdisk table",
|
||||
);
|
||||
const wide = Buffer.alloc(208);
|
||||
wide.writeUInt32LE(4, 0);
|
||||
const wideRows = parseVendorRamdiskTable(wide, {
|
||||
entryCount: 1,
|
||||
entrySize: 208,
|
||||
sectionOffset: 4096,
|
||||
sectionSize: 4,
|
||||
});
|
||||
expect(wideRows.ok, JSON.stringify(wideRows)).toBe(true);
|
||||
if (!wideRows.ok) return;
|
||||
expect(wideRows.value.limitations.join(" ")).toContain("108-byte");
|
||||
expect(wideRows.value.components[0]?.nameBytesHex).toHaveLength(64);
|
||||
expect(wideRows.value.components[0]?.boardIdHex).toHaveLength(128);
|
||||
});
|
||||
|
||||
it("omits empty vendor ramdisk fragments instead of rejecting the table", () => {
|
||||
const entry = (name: string, size: number, offset: number): Buffer => {
|
||||
const row = Buffer.alloc(108);
|
||||
row.writeUInt32LE(size, 0);
|
||||
row.writeUInt32LE(offset, 4);
|
||||
Buffer.from(name, "utf8").copy(row, 12);
|
||||
return row;
|
||||
};
|
||||
const input = {
|
||||
entryCount: 3,
|
||||
entrySize: 108,
|
||||
sectionOffset: 4096,
|
||||
sectionSize: 8,
|
||||
};
|
||||
const result = parseVendorRamdiskTable(
|
||||
Buffer.concat([entry("one", 4, 0), entry("gap", 0, 4), entry("two", 4, 4)]),
|
||||
input,
|
||||
);
|
||||
expect(result.ok, JSON.stringify(result)).toBe(true);
|
||||
if (!result.ok) return;
|
||||
expect(result.value.components.map((item) => item.path)).toEqual([
|
||||
"vendor_ramdisk/one",
|
||||
"vendor_ramdisk/two",
|
||||
]);
|
||||
expect(result.value.limitations.join(" ")).toContain(
|
||||
"entries 1 declare no bytes",
|
||||
);
|
||||
const outside = parseVendorRamdiskTable(
|
||||
Buffer.concat([entry("one", 4, 0), entry("gap", 0, 9), entry("two", 4, 4)]),
|
||||
input,
|
||||
);
|
||||
expect(outside.ok).toBe(false);
|
||||
if (outside.ok) return;
|
||||
expect(outside.error.message).toContain("overruns the vendor ramdisk");
|
||||
});
|
||||
|
||||
it("keeps colliding vendor ramdisk names unique", () => {
|
||||
const entry = (name: string, offset: number): Buffer => {
|
||||
const row = Buffer.alloc(108);
|
||||
row.writeUInt32LE(4, 0);
|
||||
row.writeUInt32LE(offset, 4);
|
||||
Buffer.from(name, "utf8").copy(row, 12);
|
||||
return row;
|
||||
};
|
||||
const paths = (names: readonly string[]) => {
|
||||
const table = Buffer.concat(
|
||||
names.map((name, index) => entry(name, index * 4)),
|
||||
);
|
||||
const result = parseVendorRamdiskTable(table, {
|
||||
entryCount: names.length,
|
||||
entrySize: 108,
|
||||
sectionOffset: 4096,
|
||||
sectionSize: names.length * 4,
|
||||
});
|
||||
if (!result.ok)
|
||||
throw new Error(result.error.message, { cause: result.error });
|
||||
return result.value.components.map((item) => item.path);
|
||||
};
|
||||
expect(paths(["x", "x-2", "x"])).toEqual([
|
||||
"vendor_ramdisk/x",
|
||||
"vendor_ramdisk/x-2",
|
||||
"vendor_ramdisk/x-2-2",
|
||||
]);
|
||||
expect(paths(["ramdisk-1", ""])).toEqual([
|
||||
"vendor_ramdisk/ramdisk-1",
|
||||
"vendor_ramdisk/ramdisk-1-1",
|
||||
]);
|
||||
expect(paths(["ramdisk-2", "ramdisk-2-2", "a/b"])).toEqual([
|
||||
"vendor_ramdisk/ramdisk-2",
|
||||
"vendor_ramdisk/ramdisk-2-2",
|
||||
"vendor_ramdisk/ramdisk-2-2-2",
|
||||
]);
|
||||
});
|
||||
|
||||
it("records an AVB footer and rejects vbmeta that overlaps a component", () => {
|
||||
const image = buildBootImage({
|
||||
version: 0,
|
||||
kernel: Buffer.alloc(64, 1),
|
||||
ramdisk: Buffer.alloc(0),
|
||||
});
|
||||
const facts = parsed(image);
|
||||
const happy = appendAvbFooter(image);
|
||||
const footer = inspectAvbFooter({
|
||||
fileSize: happy.length,
|
||||
imageEnd: facts.imageEnd,
|
||||
headerOccupied: facts.headerOccupied,
|
||||
components: facts.components,
|
||||
tail: happy.subarray(happy.length - 64),
|
||||
});
|
||||
expect(footer).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
present: true,
|
||||
footerSize: 64,
|
||||
versionMajor: 1,
|
||||
versionMinor: 0,
|
||||
originalImageSize: image.length,
|
||||
vbmetaOffset: image.length,
|
||||
limitations: [],
|
||||
},
|
||||
});
|
||||
const bare = inspectAvbFooter({
|
||||
fileSize: image.length,
|
||||
imageEnd: facts.imageEnd,
|
||||
headerOccupied: facts.headerOccupied,
|
||||
components: facts.components,
|
||||
tail: null,
|
||||
});
|
||||
expect(bare).toMatchObject({
|
||||
ok: true,
|
||||
value: { present: false, limitations: [] },
|
||||
});
|
||||
const short = Buffer.concat([image, Buffer.alloc(10)]);
|
||||
const shortFooter = inspectAvbFooter({
|
||||
fileSize: short.length,
|
||||
imageEnd: facts.imageEnd,
|
||||
headerOccupied: facts.headerOccupied,
|
||||
components: facts.components,
|
||||
tail: null,
|
||||
});
|
||||
expect(shortFooter.ok).toBe(true);
|
||||
if (!shortFooter.ok) return;
|
||||
expect(shortFooter.value.limitations[0]).toContain("10 trailing bytes");
|
||||
const colliding = appendAvbFooter(image, {
|
||||
vbmetaOffset: 2048,
|
||||
vbmeta: Buffer.alloc(16),
|
||||
});
|
||||
const collision = inspectAvbFooter({
|
||||
fileSize: colliding.length,
|
||||
imageEnd: facts.imageEnd,
|
||||
headerOccupied: facts.headerOccupied,
|
||||
components: facts.components,
|
||||
tail: colliding.subarray(colliding.length - 64),
|
||||
});
|
||||
expect(collision.ok).toBe(false);
|
||||
if (collision.ok) return;
|
||||
expect(collision.error.message).toContain(
|
||||
"AVB vbmeta overlaps a component at offset 2048",
|
||||
);
|
||||
});
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1122,7 +1122,7 @@ it("confirms SEA naming before rejecting an unrelated cyclic PE resource branch"
|
||||
try {
|
||||
await expect(
|
||||
locateNodeSea(handle, fixture.bytes.length),
|
||||
).rejects.toMatchObject({ reason: "format" });
|
||||
).rejects.toMatchObject({ reason: "malformed" });
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
|
||||
@@ -17,6 +17,8 @@ import {
|
||||
import { ownArtifactStream } from "./OwnedArtifactStream.js";
|
||||
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
|
||||
import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js";
|
||||
import type { ArtifactFormatMetadata } from "../domain/artifactFormatMetadata.js";
|
||||
import { invariantViolation } from "../domain/internalInvariant.js";
|
||||
|
||||
/** An entry whose bytes are one range of the carrier. */
|
||||
export type PositionalArtifactEntry = ArtifactEntry & {
|
||||
@@ -25,10 +27,11 @@ export type PositionalArtifactEntry = ArtifactEntry & {
|
||||
};
|
||||
|
||||
/** The entries one preparation established and the coverage to report. */
|
||||
export interface PositionalArtifactEntries {
|
||||
export interface PositionalArtifactEntries<Metadata = never> {
|
||||
readonly entries: readonly PositionalArtifactEntry[];
|
||||
/** The coverage the preparation established, including complete coverage. */
|
||||
readonly coverage: ArtifactReaderTraversal;
|
||||
readonly formatMetadata?: Metadata;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -37,15 +40,22 @@ export interface PositionalArtifactEntries {
|
||||
* carrier's identity, and close retires open streams before the carrier.
|
||||
* Encrypted entries are listed but never opened.
|
||||
*/
|
||||
export abstract class PositionalArtifactReader implements ArtifactReader {
|
||||
export abstract class PositionalArtifactReader<
|
||||
Metadata extends ArtifactFormatMetadata = never,
|
||||
> implements ArtifactReader {
|
||||
abstract readonly format: ArtifactReader["format"];
|
||||
readonly #scope = new ArtifactResourceScope();
|
||||
readonly #entries = new Map<string, PositionalArtifactEntry>();
|
||||
readonly #streams = new Set<Readable>();
|
||||
readonly #label: string;
|
||||
readonly #source: ArtifactFileSource;
|
||||
readonly #preparation = new ArtifactPreparation();
|
||||
#coverage: ArtifactReaderTraversal | undefined;
|
||||
#prepared:
|
||||
| {
|
||||
readonly entries: ReadonlyMap<string, PositionalArtifactEntry>;
|
||||
readonly coverage: ArtifactReaderTraversal;
|
||||
readonly formatMetadata: Metadata | undefined;
|
||||
}
|
||||
| undefined;
|
||||
#closing = false;
|
||||
|
||||
constructor(
|
||||
@@ -60,7 +70,12 @@ export abstract class PositionalArtifactReader implements ArtifactReader {
|
||||
/** Read the carrier once and describe its entries. */
|
||||
protected abstract prepareEntries(
|
||||
signal?: AbortSignal,
|
||||
): Promise<PositionalArtifactEntries>;
|
||||
): Promise<PositionalArtifactEntries<Metadata>>;
|
||||
|
||||
/** Metadata from the same validated preparation that established entries and coverage. */
|
||||
protected get preparedFormatMetadata(): Metadata | undefined {
|
||||
return this.#prepared?.formatMetadata;
|
||||
}
|
||||
|
||||
async prepareContainer(
|
||||
expectedSha256: string,
|
||||
@@ -78,22 +93,27 @@ export abstract class PositionalArtifactReader implements ArtifactReader {
|
||||
): AsyncIterable<ArtifactEntry> {
|
||||
await this.#scope.run(async () => {
|
||||
this.assertOpen(signal);
|
||||
// The first preparation validates before publishing; cached traversals
|
||||
// still need their own freshness admission.
|
||||
if (this.#prepared !== undefined) await this.#source.read(signal);
|
||||
await this.#preparation.run(
|
||||
signal,
|
||||
() => this.#prepare(signal),
|
||||
() => this.assertOpen(signal),
|
||||
);
|
||||
await this.#source.read(signal);
|
||||
});
|
||||
this.assertOpen(signal);
|
||||
// An unprepared reader declares nothing, which consumers read as unknown.
|
||||
if (this.#coverage !== undefined)
|
||||
options?.onCoverage?.({
|
||||
...this.#coverage,
|
||||
limitations: [...this.#coverage.limitations],
|
||||
});
|
||||
const prepared = this.#prepared;
|
||||
if (prepared === undefined)
|
||||
throw invariantViolation(
|
||||
"Positional artifact preparation did not complete",
|
||||
);
|
||||
options?.onCoverage?.({
|
||||
...prepared.coverage,
|
||||
limitations: [...prepared.coverage.limitations],
|
||||
});
|
||||
let index = 0;
|
||||
for (const entry of this.#entries.values()) {
|
||||
for (const entry of prepared.entries.values()) {
|
||||
// Yield between batches so a large inventory does not hold the loop.
|
||||
if (index++ % 256 === 0) await setImmediate();
|
||||
this.assertOpen(signal);
|
||||
@@ -105,7 +125,7 @@ export abstract class PositionalArtifactReader implements ArtifactReader {
|
||||
async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
|
||||
return this.#scope.run(async () => {
|
||||
this.assertOpen(signal);
|
||||
const stored = this.#entries.get(entry.adapterKey);
|
||||
const stored = this.#prepared?.entries.get(entry.adapterKey);
|
||||
assertProducedEntry(
|
||||
entry,
|
||||
stored,
|
||||
@@ -159,7 +179,8 @@ export abstract class PositionalArtifactReader implements ArtifactReader {
|
||||
);
|
||||
await this.#scope.close();
|
||||
await this.#source.close();
|
||||
this.#entries.clear();
|
||||
this.#prepared = undefined;
|
||||
this.#preparation.clear();
|
||||
}
|
||||
|
||||
provenance(): readonly [] {
|
||||
@@ -184,9 +205,17 @@ export abstract class PositionalArtifactReader implements ArtifactReader {
|
||||
}
|
||||
|
||||
async #prepare(signal?: AbortSignal): Promise<void> {
|
||||
const { entries, coverage } = await this.prepareEntries(signal);
|
||||
for (const entry of entries) this.#entries.set(entry.adapterKey, entry);
|
||||
this.#coverage = coverage;
|
||||
const prepared = await this.prepareEntries(signal);
|
||||
const entries = new Map(
|
||||
prepared.entries.map((entry) => [entry.adapterKey, entry] as const),
|
||||
);
|
||||
await this.#source.read(signal);
|
||||
this.assertOpen(signal);
|
||||
this.#prepared = {
|
||||
entries,
|
||||
coverage: prepared.coverage,
|
||||
formatMetadata: prepared.formatMetadata,
|
||||
};
|
||||
}
|
||||
|
||||
#entryStream(
|
||||
|
||||
@@ -30,6 +30,7 @@ type FormatsWithReaders =
|
||||
| "unityfs"
|
||||
| "wxapkg"
|
||||
| "uimage"
|
||||
| "android-boot-image"
|
||||
| "mach-o-universal"
|
||||
| "directory"
|
||||
| "pyinstaller"
|
||||
|
||||
@@ -17,6 +17,7 @@ import {
|
||||
ZipArtifactReader,
|
||||
} from "../resources/index.js";
|
||||
import type { ArtifactReaderAdmission } from "./ArtifactReaderAdmission.js";
|
||||
import { AndroidBootImageArtifactReader } from "./AndroidBootImageArtifactReader.js";
|
||||
import { AsarArtifactReader } from "./AsarArtifactReader.js";
|
||||
import type { BunStandaloneAdmission } from "./bun/BunStandaloneAdmission.js";
|
||||
import { BunStandaloneArtifactReader } from "./BunStandaloneArtifactReader.js";
|
||||
@@ -349,6 +350,16 @@ const NON_ZIP_FORMATS = {
|
||||
createReader: (path, options) =>
|
||||
new UImageArtifactReader(path, sourceOf(options)),
|
||||
}),
|
||||
"android-boot-image": container("android-boot-image", {
|
||||
roleContainer: true,
|
||||
retainClassifiedSource: true,
|
||||
extractable: true,
|
||||
absentInventory: "unavailable",
|
||||
readerLimitation:
|
||||
"Android boot image inventory establishes header facts and stored component bytes. Payloads are not decompressed, the v4 signature and AVB footer are not verified, and the image is not executed.",
|
||||
createReader: (path, options) =>
|
||||
new AndroidBootImageArtifactReader(path, sourceOf(options)),
|
||||
}),
|
||||
"javascript-bundle": described("javascript-bundle", plain),
|
||||
"source-map": described("source-map", plain),
|
||||
"mach-o-universal": described("mach-o-universal", {
|
||||
|
||||
@@ -1363,7 +1363,7 @@ it("fails closed when a readable D3N0L4ND resource sits beside an unreadable RT_
|
||||
locateDenoStandalone(bytesHandle(fixture.bytes), fixture.bytes.length),
|
||||
).resolves.toMatchObject({
|
||||
status: "present",
|
||||
failure: { reason: "format" },
|
||||
failure: { reason: "malformed" },
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1388,7 +1388,7 @@ it("fails closed when a readable D3N0L4ND resource sits beside a non-directory R
|
||||
locateDenoStandalone(bytesHandle(fixture.bytes), fixture.bytes.length),
|
||||
).resolves.toMatchObject({
|
||||
status: "present",
|
||||
failure: { reason: "format" },
|
||||
failure: { reason: "malformed" },
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1401,7 +1401,7 @@ it("fails closed when a D3N0L4ND payload is not file-backed", async () => {
|
||||
locateDenoStandalone(bytesHandle(fixture.bytes), fixture.bytes.length),
|
||||
).resolves.toMatchObject({
|
||||
status: "present",
|
||||
failure: { reason: "format" },
|
||||
failure: { reason: "malformed" },
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -150,7 +150,11 @@ export const locateDenoStandalone = async (
|
||||
} catch (cause) {
|
||||
if (
|
||||
cause instanceof ArtifactReaderFailure &&
|
||||
(cause.reason === "format" || cause.reason === "limit")
|
||||
(cause.reason === "format" ||
|
||||
cause.reason === "malformed" ||
|
||||
cause.reason === "truncated" ||
|
||||
cause.reason === "unsupported" ||
|
||||
cause.reason === "limit")
|
||||
)
|
||||
return { status: "present", failure: cause };
|
||||
throw cause;
|
||||
|
||||
@@ -42,6 +42,9 @@ it.each([
|
||||
|
||||
it.each([
|
||||
"cancelled",
|
||||
"malformed",
|
||||
"truncated",
|
||||
"unsupported",
|
||||
"format",
|
||||
"integrity",
|
||||
"path",
|
||||
|
||||
@@ -98,6 +98,9 @@ const RETRYABLE_CAPABILITY_UNAVAILABLE = classified(
|
||||
|
||||
const ARTIFACT_OPERATION_CLASSIFICATIONS = {
|
||||
cancelled: classified("cancelled", "cancelled"),
|
||||
malformed: classified("invalid_request", "invalid_input"),
|
||||
truncated: classified("truncated", "truncated"),
|
||||
unsupported: classified("unsupported_target", "unsupported_target"),
|
||||
format: classified("artifact_operation_failed", "execution_failure"),
|
||||
integrity: classified("artifact_operation_failed", "integrity_mismatch"),
|
||||
limit: classified("truncated", "truncated"),
|
||||
|
||||
@@ -545,6 +545,12 @@ const artifactMessage = ({
|
||||
detail ??
|
||||
"Artifact processing reached a resource limit. Select an artifact within the reported limits and retry."
|
||||
);
|
||||
if (reason === "unsupported")
|
||||
return "Artifact structure uses an unsupported format or revision. Use a decoder that supports the reported form.";
|
||||
if (reason === "truncated")
|
||||
return "A declared artifact structure is truncated. Select a complete copy and retry; do not pad or truncate required bytes.";
|
||||
if (reason === "malformed")
|
||||
return "Artifact bytes contain malformed format structure. Review the reported field and select a valid copy.";
|
||||
if (reason === "path")
|
||||
return (
|
||||
detail ??
|
||||
|
||||
@@ -91,6 +91,7 @@ const formatSchema = z.enum([
|
||||
"javascript",
|
||||
"source-map",
|
||||
"uimage",
|
||||
"android-boot-image",
|
||||
]);
|
||||
const kindSchema = z.enum(["executable", "database", "archive", "artifact"]);
|
||||
type SnapshotFormat = z.infer<typeof formatSchema>;
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
/** Android boot image magic values; the header parser lives with its reader. */
|
||||
export const ANDROID_BOOT_MAGIC = "ANDROID!";
|
||||
export const VENDOR_BOOT_MAGIC = "VNDRBOOT";
|
||||
const ANDROID_BOOT_MAGIC_BYTES = Buffer.from(ANDROID_BOOT_MAGIC);
|
||||
const VENDOR_BOOT_MAGIC_BYTES = Buffer.from(VENDOR_BOOT_MAGIC);
|
||||
|
||||
/** True when the first eight bytes are ANDROID! or VNDRBOOT. */
|
||||
export const hasAndroidBootImageMagic = (prefix: Buffer): boolean =>
|
||||
prefix.length >= 8 &&
|
||||
(prefix.subarray(0, 8).equals(ANDROID_BOOT_MAGIC_BYTES) ||
|
||||
prefix.subarray(0, 8).equals(VENDOR_BOOT_MAGIC_BYTES));
|
||||
@@ -847,6 +847,106 @@ export type BunStandaloneEntryMetadata = z.infer<
|
||||
typeof bunStandaloneEntryMetadataSchema
|
||||
>;
|
||||
|
||||
/**
|
||||
* Android boot and vendor_boot header facts. Addresses, names, and the
|
||||
* command line are declarations from the image. The digest, v4 signature,
|
||||
* and AVB footer are recorded and not verified.
|
||||
*/
|
||||
export const androidBootImageMetadataSchema = z.strictObject({
|
||||
kind: z.literal("android-boot-image"),
|
||||
image_kind: z.enum(["boot", "vendor-boot"]),
|
||||
magic: z.enum(["ANDROID!", "VNDRBOOT"]),
|
||||
header_version: z.number().int().min(0).max(4),
|
||||
page_size: z.number().int().min(2048).max(65536),
|
||||
header_size: offset,
|
||||
os_version_raw: uint32.nullable(),
|
||||
os_version: z
|
||||
.string()
|
||||
.regex(/^\d{1,3}\.\d{1,3}\.\d{1,3}$/u)
|
||||
.nullable(),
|
||||
security_patch_level: z
|
||||
.string()
|
||||
.regex(/^\d{4}-\d{2}$/u)
|
||||
.nullable(),
|
||||
name: z.string().nullable(),
|
||||
name_bytes_hex: z
|
||||
.string()
|
||||
.regex(/^[0-9a-f]{32}$/u)
|
||||
.nullable(),
|
||||
cmdline: z.string().nullable(),
|
||||
cmdline_bytes_hex: z
|
||||
.string()
|
||||
.regex(/^(?:[0-9a-f]{1024}|[0-9a-f]{3072}|[0-9a-f]{4096})$/u),
|
||||
extra_cmdline: z.string().nullable(),
|
||||
extra_cmdline_bytes_hex: z
|
||||
.string()
|
||||
.regex(/^[0-9a-f]{2048}$/u)
|
||||
.nullable(),
|
||||
command_line: z.string().nullable(),
|
||||
header_digest_hex: z
|
||||
.string()
|
||||
.regex(/^[0-9a-f]{64}$/u)
|
||||
.nullable(),
|
||||
kernel_addr: uint32.nullable(),
|
||||
ramdisk_addr: uint32.nullable(),
|
||||
second_addr: uint32.nullable(),
|
||||
tags_addr: uint32.nullable(),
|
||||
dtb_addr: offset.nullable(),
|
||||
kernel_size: uint32.nullable(),
|
||||
ramdisk_size: uint32.nullable(),
|
||||
second_size: uint32.nullable(),
|
||||
recovery_dtbo_size: uint32.nullable(),
|
||||
recovery_dtbo_offset: offset.nullable(),
|
||||
dtb_size: uint32.nullable(),
|
||||
signature_size: uint32.nullable(),
|
||||
vendor_ramdisk_size: uint32.nullable(),
|
||||
vendor_ramdisk_table_entry_count: uint32.nullable(),
|
||||
vendor_ramdisk_table_entry_size: uint32.nullable(),
|
||||
bootconfig_size: uint32.nullable(),
|
||||
avb_footer_present: z.boolean(),
|
||||
avb_footer_size: z.literal(64).nullable(),
|
||||
avb_version_major: uint32.nullable(),
|
||||
avb_version_minor: uint32.nullable(),
|
||||
avb_original_image_size: offset.nullable(),
|
||||
avb_vbmeta_offset: offset.nullable(),
|
||||
avb_vbmeta_size: offset.nullable(),
|
||||
component_count: uint32,
|
||||
});
|
||||
export type AndroidBootImageMetadata = z.infer<
|
||||
typeof androidBootImageMetadataSchema
|
||||
>;
|
||||
|
||||
/** One stored boot-image component. Compression is a leading-magic observation. */
|
||||
export const androidBootImageEntryMetadataSchema = z.strictObject({
|
||||
kind: z.literal("android-boot-image-entry"),
|
||||
role: z.enum([
|
||||
"kernel",
|
||||
"ramdisk",
|
||||
"second",
|
||||
"recovery-dtbo",
|
||||
"dtb",
|
||||
"vendor-ramdisk",
|
||||
"bootconfig",
|
||||
"signature",
|
||||
]),
|
||||
index: uint32,
|
||||
compression: z.enum(["gzip", "lz4", "zstd"]).nullable(),
|
||||
ramdisk_type: uint32.nullable(),
|
||||
ramdisk_type_name: z.string().nullable(),
|
||||
load_address: offset.nullable(),
|
||||
name_bytes_hex: z
|
||||
.string()
|
||||
.regex(/^[0-9a-f]{64}$/u)
|
||||
.nullable(),
|
||||
board_id_hex: z
|
||||
.string()
|
||||
.regex(/^[0-9a-f]{128}$/u)
|
||||
.nullable(),
|
||||
});
|
||||
export type AndroidBootImageEntryMetadata = z.infer<
|
||||
typeof androidBootImageEntryMetadataSchema
|
||||
>;
|
||||
|
||||
const denoListingSchema = z.enum(["listed", "unsupported"]);
|
||||
|
||||
const denoEnvVarSchema = z.strictObject({
|
||||
@@ -959,6 +1059,8 @@ export const artifactFormatMetadataSchema = z.discriminatedUnion("kind", [
|
||||
espFlashPartitionMetadataSchema,
|
||||
fitMetadataSchema,
|
||||
fitImageMetadataSchema,
|
||||
androidBootImageMetadataSchema,
|
||||
androidBootImageEntryMetadataSchema,
|
||||
]);
|
||||
export type ArtifactFormatMetadata = z.infer<
|
||||
typeof artifactFormatMetadataSchema
|
||||
@@ -1077,6 +1179,14 @@ const declarationsByKind: {
|
||||
notCompared:
|
||||
"role and index restate the entry's path; its stored bytes are compared by content.",
|
||||
},
|
||||
"android-boot-image": {
|
||||
notCompared:
|
||||
"Its header facts come from the image's own bytes, which content comparison covers.",
|
||||
},
|
||||
"android-boot-image-entry": {
|
||||
notCompared:
|
||||
"role and index restate the entry's path, compression is observed from its bytes, and load addresses, names and board IDs come from the image header or vendor ramdisk table, which the image's content comparison covers.",
|
||||
},
|
||||
"esp-image": {
|
||||
notCompared:
|
||||
"Its fields come from the image's own bytes, which content comparison covers.",
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { ArtifactFormatId } from "./artifactGraph.js";
|
||||
import { hasAndroidBootImageMagic } from "./androidBootImageFormat.js";
|
||||
import { hasBinaryPlistSignature } from "./apple/appleArchiveFormat.js";
|
||||
import { hasDfuSePrefix, isDfuSeFile } from "./firmware/dfuse.js";
|
||||
import { ESP8266_REFUSAL, recognizeEspImage } from "./firmware/espImage.js";
|
||||
@@ -22,6 +23,7 @@ export type RecognizedArtifactFormat = Extract<
|
||||
| "unityfs"
|
||||
| "wxapkg"
|
||||
| "uimage"
|
||||
| "android-boot-image"
|
||||
| "intel-hex"
|
||||
| "srec"
|
||||
| "uf2"
|
||||
@@ -102,6 +104,7 @@ export const ARTIFACT_FORMAT_RECOGNIZERS: readonly ArtifactFormatRecognizer[] =
|
||||
(prefix) => hasWxapkgEncryptedMagic(prefix) || hasWxapkgHeader(prefix),
|
||||
),
|
||||
when("uimage", hasUImageMagic),
|
||||
when("android-boot-image", hasAndroidBootImageMagic),
|
||||
({ prefix }) => {
|
||||
const format = detectHexRecordEncoding(prefix);
|
||||
return format === undefined ? undefined : { state: "recognized", format };
|
||||
|
||||
@@ -72,6 +72,7 @@ export const ARTIFACT_FORMAT_IDS = [
|
||||
"unityfs",
|
||||
"wxapkg",
|
||||
"uimage",
|
||||
"android-boot-image",
|
||||
"javascript-bundle",
|
||||
"source-map",
|
||||
"mach-o-universal",
|
||||
@@ -120,6 +121,7 @@ const artifactContentFormatSchema = artifactFormatSchema.extract([
|
||||
"unityfs",
|
||||
"wxapkg",
|
||||
"uimage",
|
||||
"android-boot-image",
|
||||
"intel-hex",
|
||||
"srec",
|
||||
"esp-image",
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
} from "./analysisErrorBase.js";
|
||||
import type { ArtifactReaderLimitFact } from "./artifactReaderLimits.js";
|
||||
import type { FixedAllowance } from "./fixedAllowanceRemediation.js";
|
||||
import type { ParseFailureKind } from "./parseFailure.js";
|
||||
|
||||
/** The resource class that refused an artifact operation. */
|
||||
export type ArtifactLimitBoundary = "file-size" | "capacity" | "memory";
|
||||
@@ -99,10 +100,10 @@ export class ArtifactOperationError extends AnalysisError {
|
||||
| "trace_web_source_location"
|
||||
| "analyze_javascript_application",
|
||||
readonly reason:
|
||||
| ParseFailureKind
|
||||
| "cancelled"
|
||||
| "format"
|
||||
| "integrity"
|
||||
| "limit"
|
||||
| "path"
|
||||
| "unavailable"
|
||||
| "io",
|
||||
|
||||
@@ -316,6 +316,7 @@ export type BinaryTarget =
|
||||
| "unityfs"
|
||||
| "wxapkg"
|
||||
| "uimage"
|
||||
| "android-boot-image"
|
||||
| "dmg"
|
||||
| "pkg"
|
||||
| "intel-hex"
|
||||
@@ -371,6 +372,7 @@ export const BINARY_TARGET_FORMAT_KINDS = {
|
||||
unityfs: "archive",
|
||||
wxapkg: "archive",
|
||||
uimage: "archive",
|
||||
"android-boot-image": "archive",
|
||||
dmg: "archive",
|
||||
pkg: "archive",
|
||||
"intel-hex": "archive",
|
||||
|
||||
@@ -29,6 +29,7 @@ export const evidenceSubjectFormatSchema = z.enum([
|
||||
"unityfs",
|
||||
"wxapkg",
|
||||
"uimage",
|
||||
"android-boot-image",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -72,6 +72,7 @@ export const liveBinaryTargetSummaryVariants = [
|
||||
"unityfs",
|
||||
"wxapkg",
|
||||
"uimage",
|
||||
"android-boot-image",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"intel-hex",
|
||||
|
||||
@@ -1,9 +1,8 @@
|
||||
import { BinaryFormatFailure } from "../../domain/binaryContainer.js";
|
||||
import {
|
||||
projectSelectedArtifactFileFailure,
|
||||
projectOwnedArtifactIdentityFailure,
|
||||
projectOwnedArtifactInputFailure,
|
||||
projectStableArtifactFailure,
|
||||
stableArtifactInputFailure,
|
||||
projectArtifactCloseFailure,
|
||||
ArtifactReaderFailure,
|
||||
type StableArtifactSnapshot,
|
||||
@@ -18,7 +17,6 @@ import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
|
||||
import {
|
||||
AnalysisInputError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisUnsupportedTargetError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import {
|
||||
MAX_INSPECT_PE_CERTIFICATE_ENTRIES,
|
||||
@@ -146,20 +144,18 @@ const peCertificatesFailurePrimary = (
|
||||
input: InspectPeCertificatesInput,
|
||||
) => {
|
||||
const { cause, origin } = facts;
|
||||
if (cause instanceof BinaryFormatFailure && cause.kind === "unsupported")
|
||||
return new AnalysisUnsupportedTargetError(
|
||||
OPERATION,
|
||||
input.path,
|
||||
cause.message,
|
||||
{ cause },
|
||||
);
|
||||
|
||||
const identityFailure = projectOwnedArtifactIdentityFailure(
|
||||
facts,
|
||||
OPERATION,
|
||||
input.path,
|
||||
);
|
||||
if (identityFailure !== undefined) return identityFailure;
|
||||
const inputFailure = projectOwnedArtifactInputFailure(
|
||||
facts,
|
||||
OPERATION,
|
||||
input.path,
|
||||
);
|
||||
if (inputFailure !== undefined) return inputFailure;
|
||||
if (
|
||||
origin === "owned-or-classified" &&
|
||||
cause instanceof PeCertificateAsn1Failure &&
|
||||
@@ -192,8 +188,6 @@ const peCertificatesFailurePrimary = (
|
||||
}),
|
||||
},
|
||||
);
|
||||
if (cause.reason === "path" || cause.reason === "format")
|
||||
return stableArtifactInputFailure(cause, OPERATION);
|
||||
}
|
||||
const fileFailure = projectSelectedArtifactFileFailure(
|
||||
cause,
|
||||
|
||||
@@ -1,10 +1,9 @@
|
||||
import { BinaryFormatFailure } from "../../domain/binaryContainer.js";
|
||||
import {
|
||||
imageFileSizeRemediation,
|
||||
projectSelectedArtifactFileFailure,
|
||||
projectOwnedArtifactIdentityFailure,
|
||||
projectOwnedArtifactInputFailure,
|
||||
projectStableArtifactFailure,
|
||||
stableArtifactInputFailure,
|
||||
projectArtifactCloseFailure,
|
||||
ArtifactReaderFailure,
|
||||
type StableArtifactSnapshot,
|
||||
@@ -21,7 +20,6 @@ import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
|
||||
import {
|
||||
AnalysisInputError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisUnsupportedTargetError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import {
|
||||
MAX_INSPECT_PE_DIRECTORY_ENTRIES,
|
||||
@@ -109,14 +107,6 @@ const peResourcesFailurePrimary = (
|
||||
) => {
|
||||
const { cause, origin } = facts;
|
||||
const operation = "inspect_pe_resources";
|
||||
if (cause instanceof BinaryFormatFailure && cause.kind === "unsupported")
|
||||
return new AnalysisUnsupportedTargetError(
|
||||
operation,
|
||||
input.path,
|
||||
cause.message,
|
||||
{ cause },
|
||||
);
|
||||
|
||||
const identityFailure = projectOwnedArtifactIdentityFailure(
|
||||
facts,
|
||||
operation,
|
||||
@@ -124,6 +114,13 @@ const peResourcesFailurePrimary = (
|
||||
);
|
||||
if (identityFailure !== undefined) return identityFailure;
|
||||
|
||||
const inputFailure = projectOwnedArtifactInputFailure(
|
||||
facts,
|
||||
operation,
|
||||
input.path,
|
||||
);
|
||||
if (inputFailure !== undefined) return inputFailure;
|
||||
|
||||
if (
|
||||
origin === "owned-or-classified" &&
|
||||
cause instanceof ArtifactReaderFailure
|
||||
@@ -166,8 +163,6 @@ const peResourcesFailurePrimary = (
|
||||
},
|
||||
);
|
||||
}
|
||||
if (cause.reason === "path" || cause.reason === "format")
|
||||
return stableArtifactInputFailure(cause, operation);
|
||||
}
|
||||
|
||||
const fileFailure = projectSelectedArtifactFileFailure(
|
||||
|
||||
@@ -248,9 +248,8 @@ export const assertArtifactReadActive = (
|
||||
/**
|
||||
* Project a failure raised by a domain byte parser over artifact bytes onto the
|
||||
* reader's reasons: the caller's cancellation (`signal.reason`) becomes
|
||||
* `cancelled`, malformed or truncated structure `format`, and a decode budget
|
||||
* `limit` bounded by `limitBoundary`. Unsupported forms and every other cause
|
||||
* pass through unchanged.
|
||||
* `cancelled`, parser failure kinds stay distinct, and a decode budget is
|
||||
* bounded by `limitBoundary`. Every other cause passes through unchanged.
|
||||
*/
|
||||
export const artifactParseFailure = (
|
||||
cause: unknown,
|
||||
@@ -263,8 +262,6 @@ export const artifactParseFailure = (
|
||||
});
|
||||
if (!(cause instanceof ParseFailureError)) return cause;
|
||||
const { failure } = cause;
|
||||
if (failure.kind === "malformed" || failure.kind === "truncated")
|
||||
return new ArtifactReaderFailure("format", cause.message, { cause });
|
||||
if (failure.kind === "limit") {
|
||||
const boundary = limitBoundary?.(failure.limit);
|
||||
return new ArtifactReaderFailure("limit", cause.message, {
|
||||
@@ -272,7 +269,7 @@ export const artifactParseFailure = (
|
||||
...(boundary === undefined ? {} : { boundary }),
|
||||
});
|
||||
}
|
||||
return cause;
|
||||
return new ArtifactReaderFailure(failure.kind, cause.message, { cause });
|
||||
};
|
||||
|
||||
/** Recognize only the originating caller's cancellation without discarding cleanup ownership. */
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { expect, it } from "vitest";
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import {
|
||||
ArtifactReaderFailure,
|
||||
@@ -9,13 +10,179 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
import { constants as bufferConstants } from "node:buffer";
|
||||
import {
|
||||
imageFileSizeRemediation,
|
||||
projectOwnedArtifactInputFailure,
|
||||
projectStableArtifactFailure,
|
||||
readerIntegrityFailure,
|
||||
} from "./StableArtifactFailure.js";
|
||||
import { artifactIntegrityDetails } from "../domain/artifactIntegrity.js";
|
||||
import { ArtifactFileCleanupFailure } from "./ArtifactFileOperation.js";
|
||||
import {
|
||||
ArtifactFileCleanupFailure,
|
||||
artifactFilePrimaryFacts,
|
||||
artifactParseFailure,
|
||||
} from "./ArtifactFileOperation.js";
|
||||
import { AnalysisCleanupLease } from "./AnalysisCleanupLease.js";
|
||||
import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
|
||||
import { artifactReaderLimitFailure } from "./index.js";
|
||||
import {
|
||||
malformedInput,
|
||||
truncatedInput,
|
||||
unsupportedInput,
|
||||
} from "../domain/parseFailure.js";
|
||||
|
||||
it.each([
|
||||
malformedInput("pe", "bad field"),
|
||||
truncatedInput("pe", "short field"),
|
||||
unsupportedInput("pe", "unsupported image"),
|
||||
])(
|
||||
"preserves selected input projection and partial identity through cleanup retry: $kind",
|
||||
async (cause) => {
|
||||
const path = "/selected/./program.exe";
|
||||
const operation = "inspect_pe_resources";
|
||||
const failure = artifactParseFailure(cause, undefined);
|
||||
expect(failure).toMatchObject({ cause });
|
||||
let attempts = 0;
|
||||
const lease = new AnalysisCleanupLease(async () => {
|
||||
if (attempts++ === 0) throw new Error("cleanup retry failed");
|
||||
}, [path]);
|
||||
const wrapped = new ArtifactFileCleanupFailure(
|
||||
new RegularFileCleanupFailure({
|
||||
path,
|
||||
owner: { close: async () => undefined } as never,
|
||||
outcome: { kind: "failed", cause: failure },
|
||||
cleanupCause: new Error("close failed"),
|
||||
}),
|
||||
lease,
|
||||
);
|
||||
const primary = projectOwnedArtifactInputFailure(
|
||||
artifactFilePrimaryFacts(wrapped),
|
||||
operation,
|
||||
path,
|
||||
);
|
||||
if (primary === undefined)
|
||||
throw new Error("Expected a selected-input projection");
|
||||
expect(primary.cause).toBe(failure);
|
||||
const bytes = Buffer.from("inert snapshot");
|
||||
const sha256 = createHash("sha256").update(bytes).digest("hex");
|
||||
const projected = projectStableArtifactFailure(
|
||||
wrapped,
|
||||
primary,
|
||||
path,
|
||||
"pe-fixture",
|
||||
operation,
|
||||
{ bytes, sha256 },
|
||||
);
|
||||
expect(projectAnalysisError(projected)).toMatchObject({
|
||||
code: "cleanup_incomplete",
|
||||
});
|
||||
await expect(lease.release()).rejects.toThrow("cleanup retry failed");
|
||||
expect(projectAnalysisError(projected)).toMatchObject({
|
||||
code: "cleanup_incomplete",
|
||||
});
|
||||
await lease.release();
|
||||
expect(projectAnalysisError(projected)).toMatchObject({
|
||||
code:
|
||||
cause.kind === "unsupported" ? "unsupported_target" : "invalid_request",
|
||||
details:
|
||||
cause.kind === "unsupported"
|
||||
? { operation, path, reason: cause.message }
|
||||
: {
|
||||
operation,
|
||||
issues: [
|
||||
{
|
||||
path: ["path"],
|
||||
reason: "invalid_format",
|
||||
message: cause.message,
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
expect(projected.partialObservation).toEqual({
|
||||
kind: "file-snapshot-hash",
|
||||
path,
|
||||
sha256,
|
||||
bytes: bytes.length,
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
it("leaves opaque operation errors and decode limits with their owning projection", () => {
|
||||
const unsupported = artifactParseFailure(
|
||||
unsupportedInput("pe", "unsupported"),
|
||||
undefined,
|
||||
);
|
||||
expect(
|
||||
projectOwnedArtifactInputFailure(
|
||||
{ cause: unsupported, origin: "opaque-operation" },
|
||||
"inspect_pe_resources",
|
||||
"/selected.exe",
|
||||
),
|
||||
).toBeUndefined();
|
||||
expect(
|
||||
projectOwnedArtifactInputFailure(
|
||||
{
|
||||
cause: new ArtifactReaderFailure("limit", "budget"),
|
||||
origin: "owned-or-classified",
|
||||
},
|
||||
"inspect_pe_resources",
|
||||
"/selected.exe",
|
||||
),
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it.each([
|
||||
{
|
||||
cause: malformedInput("fixture", "bad field"),
|
||||
code: "invalid_request",
|
||||
category: "invalid_input",
|
||||
},
|
||||
{
|
||||
cause: truncatedInput("fixture", "short field"),
|
||||
code: "truncated",
|
||||
category: "truncated",
|
||||
},
|
||||
{
|
||||
cause: unsupportedInput("fixture", "new revision"),
|
||||
code: "unsupported_target",
|
||||
category: "unsupported_target",
|
||||
},
|
||||
])(
|
||||
"preserves $cause.kind parser facts after cleanup retry",
|
||||
async ({ cause, code, category }) => {
|
||||
const readerFailure = artifactParseFailure(cause, undefined);
|
||||
if (!(readerFailure instanceof ArtifactReaderFailure))
|
||||
throw new Error(
|
||||
"Parser failure did not become an artifact reader failure",
|
||||
);
|
||||
expect(readerFailure).toMatchObject({ reason: cause.kind, cause });
|
||||
const lease = new AnalysisCleanupLease(async () => {}, [
|
||||
"fixture descriptor",
|
||||
]);
|
||||
const wrapped = ArtifactReaderFailure.withCleanup(
|
||||
readerFailure,
|
||||
{ reason: "close failed", resources: ["fixture descriptor"] },
|
||||
undefined,
|
||||
[lease],
|
||||
);
|
||||
const projectedOwner = translateArtifactFailure(
|
||||
"inspect_artifact",
|
||||
wrapped,
|
||||
);
|
||||
expect(projectAnalysisError(projectedOwner)).toMatchObject({
|
||||
code: "cleanup_incomplete",
|
||||
details: {
|
||||
reason: cause.kind,
|
||||
detail: cause.message,
|
||||
cleanup: "incomplete",
|
||||
},
|
||||
});
|
||||
await lease.release();
|
||||
expect(projectAnalysisError(projectedOwner)).toMatchObject({
|
||||
code,
|
||||
category,
|
||||
details: { reason: cause.kind, detail: cause.message },
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
// The provider ceiling test uses a sparse file and is skipped on Windows.
|
||||
it.skipIf(process.platform !== "win32")(
|
||||
|
||||
@@ -4,6 +4,7 @@ import type {
|
||||
ArtifactAdmissionLimit,
|
||||
ArtifactIntegrityCheck,
|
||||
ArtifactLimitBoundary,
|
||||
ArtifactOperationError,
|
||||
} from "../domain/artifactOperationError.js";
|
||||
import type {
|
||||
ArtifactContainerIntegrityPair,
|
||||
@@ -233,6 +234,7 @@ export interface ArtifactReader {
|
||||
| "unityfs"
|
||||
| "wxapkg"
|
||||
| "uimage"
|
||||
| "android-boot-image"
|
||||
| "pyinstaller"
|
||||
| "dotnet-bundle"
|
||||
| "bun-standalone"
|
||||
@@ -271,14 +273,7 @@ export type CleanupFailedRead = ArtifactReaderFailure & {
|
||||
};
|
||||
|
||||
/** Why an artifact reader failed. */
|
||||
export type ArtifactReaderFailureReason =
|
||||
| "cancelled"
|
||||
| "format"
|
||||
| "integrity"
|
||||
| "io"
|
||||
| "limit"
|
||||
| "path"
|
||||
| "unavailable";
|
||||
export type ArtifactReaderFailureReason = ArtifactOperationError["reason"];
|
||||
|
||||
export class ArtifactReaderFailure extends Error {
|
||||
readonly userMessage: string | undefined;
|
||||
@@ -469,8 +464,10 @@ export const artifactFixedLimitFailure = (
|
||||
allowance: ArtifactFixedLimit,
|
||||
outcome: string,
|
||||
boundary: ArtifactLimitBoundary = "capacity",
|
||||
options?: ErrorOptions,
|
||||
): ArtifactReaderFailure =>
|
||||
new ArtifactReaderFailure("limit", outcome, {
|
||||
...options,
|
||||
boundary,
|
||||
userMessage: outcome,
|
||||
fixedAllowance: allowance,
|
||||
|
||||
@@ -17,6 +17,7 @@ import {
|
||||
AnalysisAccessDeniedError,
|
||||
AnalysisArtifactChangedError,
|
||||
AnalysisInputError,
|
||||
AnalysisUnsupportedTargetError,
|
||||
cancelledBy,
|
||||
carriedReason,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
@@ -63,6 +64,32 @@ export const projectOwnedArtifactIdentityFailure = (
|
||||
/** The request field that selected a file: a name, or a path into the request. */
|
||||
export type RequestField = string | readonly (string | number)[];
|
||||
|
||||
/** Keep a selected parser refusal's established path and structured input projection. */
|
||||
export const projectOwnedArtifactInputFailure = (
|
||||
{ cause, origin }: ArtifactFilePrimaryFacts,
|
||||
operation: string,
|
||||
path: string,
|
||||
field: RequestField = "path",
|
||||
): AnalysisError | undefined => {
|
||||
if (
|
||||
origin !== "owned-or-classified" ||
|
||||
!(cause instanceof ArtifactReaderFailure)
|
||||
)
|
||||
return undefined;
|
||||
if (cause.reason === "unsupported")
|
||||
return new AnalysisUnsupportedTargetError(operation, path, cause.message, {
|
||||
cause,
|
||||
});
|
||||
if (
|
||||
cause.reason === "malformed" ||
|
||||
cause.reason === "truncated" ||
|
||||
cause.reason === "format" ||
|
||||
cause.reason === "path"
|
||||
)
|
||||
return stableArtifactInputFailure(cause, operation, field);
|
||||
return undefined;
|
||||
};
|
||||
|
||||
const requestFieldPath = (field: RequestField): (string | number)[] =>
|
||||
typeof field === "string" ? [field] : [...field];
|
||||
|
||||
|
||||
@@ -88,6 +88,7 @@ export {
|
||||
imageFileSizeRemediation,
|
||||
projectArtifactCloseFailure,
|
||||
projectOwnedArtifactIdentityFailure,
|
||||
projectOwnedArtifactInputFailure,
|
||||
projectSelectedArtifactFileFailure,
|
||||
projectStableArtifactFailure,
|
||||
readerIntegrityFailure,
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
import { readFile, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { expect } from "vitest";
|
||||
|
||||
import { parseEvidence } from "../../src/domain/evidence.js";
|
||||
import { artifactInspectionResultSchema } from "../../src/domain/artifactInspection.js";
|
||||
import {
|
||||
artifactExtractionResultSchema,
|
||||
artifactInventoryResultSchema,
|
||||
} from "../../src/domain/artifactGraph.js";
|
||||
import {
|
||||
androidBootImageRefusals,
|
||||
buildVendorBootImage,
|
||||
} from "../fixtures/androidBootImage.js";
|
||||
import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
|
||||
import { cliTest } from "../support/cli/cliFixture.js";
|
||||
|
||||
cliTest(
|
||||
"inspects and extracts a vendor_boot image through the compiled CLI",
|
||||
async ({ cli }) => {
|
||||
const root = await createTestTempDirectory("rea-android-boot-cli-");
|
||||
const platform = Buffer.from("platform-bytes");
|
||||
const recovery = Buffer.from("recovery-bytes");
|
||||
const dtb = Buffer.from("vendor-dtb");
|
||||
const bootconfig = Buffer.from("androidboot.hardware=test\n");
|
||||
const source = join(root, "vendor_boot.img");
|
||||
const callerPath = `${root}/./vendor_boot.img`;
|
||||
await writeFile(
|
||||
source,
|
||||
buildVendorBootImage({
|
||||
version: 4,
|
||||
name: "board",
|
||||
cmdline: "console=tty0",
|
||||
ramdisks: [
|
||||
{ name: "platform", type: 1, bytes: platform },
|
||||
{ name: "recovery", type: 2, bytes: recovery },
|
||||
],
|
||||
dtb,
|
||||
bootconfig,
|
||||
}),
|
||||
);
|
||||
const inspected = await cli.run({
|
||||
arguments: ["inspect-artifact", callerPath, "--json"],
|
||||
});
|
||||
expect(inspected.exitCode, inspected.stdout + inspected.stderr).toBe(0);
|
||||
const evidence = parseEvidence(inspected.json);
|
||||
expect(evidence.caller_input_path).toBe(callerPath);
|
||||
const inspection = artifactInspectionResultSchema.parse(
|
||||
evidence.normalized_result,
|
||||
);
|
||||
const graph = artifactInventoryResultSchema.parse(
|
||||
inspection.substeps[0]?.evidence.normalized_result,
|
||||
);
|
||||
expect(graph.manifest.root_format).toBe("android-boot-image");
|
||||
expect(graph.coverage.status).toBe("complete");
|
||||
expect(
|
||||
graph.occurrences.find((row) => row.logical_path === ".")
|
||||
?.format_metadata,
|
||||
).toMatchObject({
|
||||
kind: "android-boot-image",
|
||||
image_kind: "vendor-boot",
|
||||
magic: "VNDRBOOT",
|
||||
header_version: 4,
|
||||
name: "board",
|
||||
command_line: "console=tty0",
|
||||
vendor_ramdisk_table_entry_count: 2,
|
||||
component_count: 4,
|
||||
});
|
||||
const extracted = await cli.run({
|
||||
arguments: ["extract-artifact", callerPath, "--json"],
|
||||
environment: { TMPDIR: root, TMP: root, TEMP: root },
|
||||
});
|
||||
expect(extracted.exitCode, extracted.stdout + extracted.stderr).toBe(0);
|
||||
const extractedEvidence = parseEvidence(extracted.json);
|
||||
expect(extractedEvidence.caller_input_path).toBe(callerPath);
|
||||
const result = artifactExtractionResultSchema.parse(
|
||||
extractedEvidence.normalized_result,
|
||||
);
|
||||
expect(result.containment_verified).toBe(true);
|
||||
expect(
|
||||
(
|
||||
await readFile(join(result.output_root, "vendor_ramdisk/platform"))
|
||||
).equals(platform),
|
||||
).toBe(true);
|
||||
expect(
|
||||
(
|
||||
await readFile(join(result.output_root, "vendor_ramdisk/recovery"))
|
||||
).equals(recovery),
|
||||
).toBe(true);
|
||||
expect((await readFile(join(result.output_root, "dtb"))).equals(dtb)).toBe(
|
||||
true,
|
||||
);
|
||||
expect(
|
||||
(await readFile(join(result.output_root, "bootconfig"))).equals(
|
||||
bootconfig,
|
||||
),
|
||||
).toBe(true);
|
||||
},
|
||||
);
|
||||
|
||||
cliTest(
|
||||
"keeps Android parser refusal kinds through the compiled CLI",
|
||||
async ({ cli }) => {
|
||||
const root = await createTestTempDirectory(
|
||||
"rea-android-boot-cli-refusals-",
|
||||
);
|
||||
for (const fixture of androidBootImageRefusals()) {
|
||||
const path = join(root, `${fixture.name}.img`);
|
||||
await writeFile(path, fixture.bytes);
|
||||
const result = await cli.run({
|
||||
arguments: ["inspect-artifact", path, "--json"],
|
||||
});
|
||||
expect(result.exitCode, result.stdout + result.stderr).toBe(1);
|
||||
expect(result.json).toMatchObject({
|
||||
code: fixture.code,
|
||||
category: fixture.category,
|
||||
details: { operation: "inspect_artifact", reason: fixture.kind },
|
||||
});
|
||||
expect((await readFile(path)).equals(fixture.bytes)).toBe(true);
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,145 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { artifactInspectionResultSchema } from "../../../src/domain/artifactInspection.js";
|
||||
import { artifactExtractionResultSchema } from "../../../src/domain/artifactGraph.js";
|
||||
import { parseEvidence } from "../../../src/domain/evidence.js";
|
||||
import {
|
||||
appendAvbFooter,
|
||||
androidBootImageRefusals,
|
||||
buildBootImage,
|
||||
osVersionRaw,
|
||||
} from "../../fixtures/androidBootImage.js";
|
||||
import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
|
||||
|
||||
it("retains Android boot image facts through compiled MCP", async () => {
|
||||
const root = await createTestTempDirectory("rea-android-boot-mcp-");
|
||||
const path = join(root, "boot.img");
|
||||
const kernel = Buffer.from([0x7f, 0x45, 0x4c, 0x46, 2, 1, 1, 0]);
|
||||
const ramdisk = Buffer.from([0x1f, 0x8b, 0x08, 0, 0x61]);
|
||||
const signature = Buffer.from("boot-signature");
|
||||
const image = buildBootImage({
|
||||
version: 4,
|
||||
kernel,
|
||||
ramdisk,
|
||||
signature,
|
||||
cmdline: "console=tty0",
|
||||
osVersion: osVersionRaw(13, 0, 0, 2024, 11),
|
||||
});
|
||||
const bytes = appendAvbFooter(image);
|
||||
await writeFile(path, bytes);
|
||||
const { call } = await connectLocalToolsMcp({
|
||||
REA_MCP_INPUT_SCHEMA_PROFILE: "compact",
|
||||
});
|
||||
let outputRoot: string | undefined;
|
||||
try {
|
||||
const opened = await call("open_binary", { path });
|
||||
expect(opened.isError, JSON.stringify(opened)).not.toBe(true);
|
||||
expect(opened.structuredContent).toMatchObject({
|
||||
result: {
|
||||
kind: "archive",
|
||||
format: "android-boot-image",
|
||||
architecture: null,
|
||||
},
|
||||
});
|
||||
const reply = await call("inspect_artifact", {});
|
||||
expect(reply.isError, JSON.stringify(reply)).not.toBe(true);
|
||||
const inspection = artifactInspectionResultSchema.parse(
|
||||
parseEvidence(reply.structuredContent).normalized_result,
|
||||
);
|
||||
const inventory = inspection.substeps[0]!.evidence.normalized_result;
|
||||
expect(inventory.coverage.status).toBe("complete");
|
||||
expect(inventory.occurrences).toContainEqual(
|
||||
expect.objectContaining({
|
||||
logical_path: ".",
|
||||
format_metadata: expect.objectContaining({
|
||||
kind: "android-boot-image",
|
||||
header_version: 4,
|
||||
os_version: "13.0.0",
|
||||
security_patch_level: "2024-11",
|
||||
command_line: "console=tty0",
|
||||
signature_size: signature.length,
|
||||
avb_footer_present: true,
|
||||
avb_footer_size: 64,
|
||||
}),
|
||||
}),
|
||||
);
|
||||
expect(inventory.occurrences).toContainEqual(
|
||||
expect.objectContaining({
|
||||
logical_path: "ramdisk",
|
||||
format_metadata: expect.objectContaining({ compression: "gzip" }),
|
||||
source_location: { offset: 8192, length: ramdisk.length },
|
||||
}),
|
||||
);
|
||||
expect(inventory.occurrences).toContainEqual(
|
||||
expect.objectContaining({
|
||||
logical_path: "signature",
|
||||
source_location: { offset: 12288, length: signature.length },
|
||||
}),
|
||||
);
|
||||
expect(inventory.nodes).toContainEqual(
|
||||
expect.objectContaining({
|
||||
sha256: createHash("sha256").update(ramdisk).digest("hex"),
|
||||
}),
|
||||
);
|
||||
const extracted = await call("extract_artifact", {});
|
||||
expect(extracted.isError, JSON.stringify(extracted)).not.toBe(true);
|
||||
const result = artifactExtractionResultSchema.parse(
|
||||
parseEvidence(extracted.structuredContent).normalized_result,
|
||||
);
|
||||
outputRoot = result.output_root;
|
||||
expect(result.containment_verified).toBe(true);
|
||||
expect(result.cleanup).toMatchObject({
|
||||
verified: true,
|
||||
residual_paths: [],
|
||||
});
|
||||
expect((await readFile(join(outputRoot, "kernel"))).equals(kernel)).toBe(
|
||||
true,
|
||||
);
|
||||
expect((await readFile(join(outputRoot, "ramdisk"))).equals(ramdisk)).toBe(
|
||||
true,
|
||||
);
|
||||
expect(
|
||||
(await readFile(join(outputRoot, "signature"))).equals(signature),
|
||||
).toBe(true);
|
||||
expect((await readFile(path)).equals(bytes)).toBe(true);
|
||||
await call("close_binary", {});
|
||||
} finally {
|
||||
if (outputRoot !== undefined)
|
||||
await rm(outputRoot, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps Android parser refusal kinds and recovers through compiled MCP", async () => {
|
||||
const root = await createTestTempDirectory("rea-android-boot-mcp-refusals-");
|
||||
const { call } = await connectLocalToolsMcp({
|
||||
REA_MCP_INPUT_SCHEMA_PROFILE: "compact",
|
||||
});
|
||||
try {
|
||||
for (const fixture of androidBootImageRefusals()) {
|
||||
const path = join(root, `${fixture.name}.img`);
|
||||
await writeFile(path, fixture.bytes);
|
||||
const opened = await call("open_binary", { path });
|
||||
expect(opened.isError, JSON.stringify(opened)).not.toBe(true);
|
||||
const { error } = parseMcpToolError(await call("inspect_artifact", {}));
|
||||
expect(error).toMatchObject({
|
||||
code: fixture.code,
|
||||
category: fixture.category,
|
||||
details: { operation: "inspect_artifact", reason: fixture.kind },
|
||||
});
|
||||
expect((await readFile(path)).equals(fixture.bytes)).toBe(true);
|
||||
expect((await call("close_binary", {})).isError).not.toBe(true);
|
||||
}
|
||||
const path = join(root, "valid.img");
|
||||
await writeFile(path, buildBootImage({ version: 0 }));
|
||||
expect((await call("open_binary", { path })).isError).not.toBe(true);
|
||||
expect((await call("inspect_artifact", {})).isError).not.toBe(true);
|
||||
} finally {
|
||||
await call("close_binary", {});
|
||||
}
|
||||
});
|
||||
Vendored
+438
@@ -0,0 +1,438 @@
|
||||
/**
|
||||
* Synthetic Android boot and vendor_boot images.
|
||||
* Field offsets follow the v0-v4 and vendor v3/v4 layouts directly.
|
||||
*/
|
||||
|
||||
const BOOT_V3_PAGE = 4096;
|
||||
const LEGACY_V1 = 1648;
|
||||
const LEGACY_V2 = 1660;
|
||||
const MODERN_V3 = 1580;
|
||||
const MODERN_V4 = 1584;
|
||||
const VENDOR_V3 = 2112;
|
||||
const VENDOR_V4 = 2128;
|
||||
/** `vendor_ramdisk_table_entry_v4`: 12-byte prefix, 32-byte name, 16 board ids. */
|
||||
const VENDOR_ENTRY = 108;
|
||||
const VENDOR_RAMDISK_NAME_SIZE = 32;
|
||||
const VENDOR_RAMDISK_BOARD_ID_OFFSET = 44;
|
||||
|
||||
export interface BootImageOptions {
|
||||
readonly version: 0 | 1 | 2 | 3 | 4;
|
||||
readonly pageSize?: number;
|
||||
readonly headerSize?: number;
|
||||
readonly kernel?: Buffer;
|
||||
readonly ramdisk?: Buffer;
|
||||
readonly second?: Buffer;
|
||||
readonly recoveryDtbo?: Buffer;
|
||||
/** File offset. Omit to place the DTBO on the sequential page cursor. */
|
||||
readonly recoveryDtboOffset?: number;
|
||||
readonly dtb?: Buffer;
|
||||
readonly signature?: Buffer;
|
||||
readonly name?: string;
|
||||
readonly cmdline?: string;
|
||||
readonly extraCmdline?: string;
|
||||
readonly osVersion?: number;
|
||||
readonly kernelAddr?: number;
|
||||
readonly ramdiskAddr?: number;
|
||||
readonly secondAddr?: number;
|
||||
readonly tagsAddr?: number;
|
||||
readonly dtbAddr?: number;
|
||||
readonly headerDigest?: Buffer;
|
||||
}
|
||||
|
||||
export interface VendorRamdiskFixture {
|
||||
readonly name?: string;
|
||||
readonly type?: number;
|
||||
readonly bytes: Buffer;
|
||||
readonly boardId?: Buffer;
|
||||
}
|
||||
|
||||
export interface VendorBootImageOptions {
|
||||
readonly version: 3 | 4;
|
||||
readonly pageSize?: number;
|
||||
readonly headerSize?: number;
|
||||
readonly name?: string;
|
||||
readonly cmdline?: string;
|
||||
readonly kernelAddr?: number;
|
||||
readonly ramdiskAddr?: number;
|
||||
readonly tagsAddr?: number;
|
||||
readonly dtbAddr?: number;
|
||||
readonly dtb?: Buffer;
|
||||
/** Version 3 section bytes. Empty omits the vendor_ramdisk child. */
|
||||
readonly ramdisk?: Buffer;
|
||||
/** Version 4 table entries. Their bytes are concatenated into the section. */
|
||||
readonly ramdisks?: readonly VendorRamdiskFixture[];
|
||||
/** Section bytes with no table entries. Use to leave the section uncovered. */
|
||||
readonly section?: Buffer;
|
||||
readonly bootconfig?: Buffer;
|
||||
readonly entrySize?: number;
|
||||
}
|
||||
|
||||
interface Placement {
|
||||
readonly offset: number;
|
||||
readonly bytes: Buffer;
|
||||
}
|
||||
|
||||
/** Pack the boot header os_version word. `year` is the calendar year. */
|
||||
export const osVersionRaw = (
|
||||
major: number,
|
||||
minor: number,
|
||||
patch: number,
|
||||
year: number,
|
||||
month: number,
|
||||
): number =>
|
||||
((major & 0x7f) << 25) |
|
||||
((minor & 0x7f) << 18) |
|
||||
((patch & 0x7f) << 11) |
|
||||
(((year - 2000) & 0x7f) << 4) |
|
||||
(month & 0xf);
|
||||
|
||||
const alignUp = (value: number, page: number): number => {
|
||||
const remainder = value % page;
|
||||
return remainder === 0 ? value : value + (page - remainder);
|
||||
};
|
||||
|
||||
const writeU32 = (buffer: Buffer, offset: number, value: number): void => {
|
||||
buffer.writeUInt32LE(value >>> 0, offset);
|
||||
};
|
||||
|
||||
const writeU64 = (buffer: Buffer, offset: number, value: number): void => {
|
||||
writeU32(buffer, offset, value >>> 0);
|
||||
writeU32(buffer, offset + 4, Math.floor(value / 2 ** 32));
|
||||
};
|
||||
|
||||
const writeU64be = (buffer: Buffer, offset: number, value: number): void => {
|
||||
buffer.writeUInt32BE(Math.floor(value / 2 ** 32), offset);
|
||||
buffer.writeUInt32BE(value >>> 0, offset + 4);
|
||||
};
|
||||
|
||||
const writeText = (
|
||||
buffer: Buffer,
|
||||
offset: number,
|
||||
length: number,
|
||||
text: string,
|
||||
): void => {
|
||||
Buffer.from(text, "utf8").copy(buffer, offset, 0, length);
|
||||
};
|
||||
|
||||
const place = (
|
||||
placed: Placement[],
|
||||
cursor: number,
|
||||
page: number,
|
||||
bytes: Buffer | undefined,
|
||||
): number => {
|
||||
if (bytes === undefined || bytes.length === 0) return cursor;
|
||||
placed.push({ offset: cursor, bytes });
|
||||
return alignUp(cursor + bytes.length, page);
|
||||
};
|
||||
|
||||
const writeLegacyHeader = (
|
||||
image: Buffer,
|
||||
options: BootImageOptions,
|
||||
version: 0 | 1 | 2,
|
||||
page: number,
|
||||
sizes: {
|
||||
readonly kernel: number;
|
||||
readonly ramdisk: number;
|
||||
readonly second: number;
|
||||
readonly recovery: number;
|
||||
readonly recoveryOffset: number;
|
||||
readonly dtb: number;
|
||||
},
|
||||
): void => {
|
||||
writeU32(image, 8, sizes.kernel);
|
||||
writeU32(image, 12, options.kernelAddr ?? 0x8000_8000);
|
||||
writeU32(image, 16, sizes.ramdisk);
|
||||
writeU32(image, 20, options.ramdiskAddr ?? 0x8100_0000);
|
||||
writeU32(image, 24, sizes.second);
|
||||
writeU32(image, 28, options.secondAddr ?? 0x8110_0000);
|
||||
writeU32(image, 32, options.tagsAddr ?? 0x8000_0100);
|
||||
writeU32(image, 36, page);
|
||||
writeU32(image, 40, version);
|
||||
writeU32(image, 44, options.osVersion ?? 0);
|
||||
writeText(image, 48, 16, options.name ?? "board");
|
||||
writeText(image, 64, 512, options.cmdline ?? "console=tty0");
|
||||
(options.headerDigest ?? Buffer.alloc(32)).copy(image, 576, 0, 32);
|
||||
writeText(
|
||||
image,
|
||||
608,
|
||||
1024,
|
||||
options.extraCmdline ?? " androidboot.hardware=test",
|
||||
);
|
||||
if (version === 0) return;
|
||||
writeU32(image, 1632, sizes.recovery);
|
||||
writeU64(image, 1636, sizes.recoveryOffset);
|
||||
writeU32(
|
||||
image,
|
||||
1644,
|
||||
options.headerSize ?? (version === 1 ? LEGACY_V1 : LEGACY_V2),
|
||||
);
|
||||
if (version < 2) return;
|
||||
writeU32(image, LEGACY_V1, sizes.dtb);
|
||||
writeU64(image, LEGACY_V1 + 4, options.dtbAddr ?? 0x8200_0000);
|
||||
};
|
||||
|
||||
const writeModernHeader = (
|
||||
image: Buffer,
|
||||
options: BootImageOptions,
|
||||
version: 3 | 4,
|
||||
sizes: {
|
||||
readonly kernel: number;
|
||||
readonly ramdisk: number;
|
||||
readonly signature: number;
|
||||
},
|
||||
): void => {
|
||||
writeU32(image, 8, sizes.kernel);
|
||||
writeU32(image, 12, sizes.ramdisk);
|
||||
writeU32(image, 16, options.osVersion ?? 0);
|
||||
writeU32(
|
||||
image,
|
||||
20,
|
||||
options.headerSize ?? (version === 4 ? MODERN_V4 : MODERN_V3),
|
||||
);
|
||||
writeU32(image, 40, version);
|
||||
writeText(
|
||||
image,
|
||||
44,
|
||||
1536,
|
||||
`${options.cmdline ?? "console=tty0"}${options.extraCmdline ?? ""}`,
|
||||
);
|
||||
if (version === 4) writeU32(image, MODERN_V3, sizes.signature);
|
||||
};
|
||||
|
||||
/** Build a page-padded ANDROID! image. Zero-length components are omitted. */
|
||||
export const buildBootImage = (options: BootImageOptions): Buffer => {
|
||||
const version = options.version;
|
||||
const modern = version >= 3;
|
||||
const page = modern ? BOOT_V3_PAGE : (options.pageSize ?? 2048);
|
||||
const kernel = options.kernel ?? Buffer.from("kernel");
|
||||
const ramdisk = options.ramdisk ?? Buffer.from("ramdisk");
|
||||
const second = options.second ?? Buffer.alloc(0);
|
||||
const recovery = !modern && version >= 1 ? options.recoveryDtbo : undefined;
|
||||
const dtb = !modern && version >= 2 ? options.dtb : undefined;
|
||||
const signature = version === 4 ? options.signature : undefined;
|
||||
const placed: Placement[] = [];
|
||||
let cursor = page;
|
||||
cursor = place(placed, cursor, page, kernel);
|
||||
cursor = place(placed, cursor, page, ramdisk);
|
||||
if (!modern) cursor = place(placed, cursor, page, second);
|
||||
let recoveryOffset = 0;
|
||||
if (recovery !== undefined && recovery.length > 0) {
|
||||
recoveryOffset = options.recoveryDtboOffset ?? cursor;
|
||||
placed.push({ offset: recoveryOffset, bytes: recovery });
|
||||
cursor = Math.max(cursor, alignUp(recoveryOffset + recovery.length, page));
|
||||
}
|
||||
if (!modern && version >= 2) cursor = place(placed, cursor, page, dtb);
|
||||
if (version === 4) cursor = place(placed, cursor, page, signature);
|
||||
const image = Buffer.alloc(cursor);
|
||||
image.write("ANDROID!", 0, "ascii");
|
||||
const sizes = {
|
||||
kernel: kernel.length,
|
||||
ramdisk: ramdisk.length,
|
||||
second: second.length,
|
||||
recovery: recovery?.length ?? 0,
|
||||
recoveryOffset,
|
||||
dtb: dtb?.length ?? 0,
|
||||
signature: signature?.length ?? 0,
|
||||
};
|
||||
switch (version) {
|
||||
case 0:
|
||||
case 1:
|
||||
case 2:
|
||||
writeLegacyHeader(image, options, version, page, sizes);
|
||||
break;
|
||||
case 3:
|
||||
case 4:
|
||||
writeModernHeader(image, options, version, sizes);
|
||||
break;
|
||||
}
|
||||
for (const item of placed) item.bytes.copy(image, item.offset);
|
||||
return image;
|
||||
};
|
||||
|
||||
const vendorRamdiskTable = (
|
||||
ramdisks: readonly VendorRamdiskFixture[],
|
||||
entrySize: number,
|
||||
): Buffer => {
|
||||
const table = Buffer.alloc(ramdisks.length * entrySize);
|
||||
let offset = 0;
|
||||
for (const [index, ramdisk] of ramdisks.entries()) {
|
||||
const base = index * entrySize;
|
||||
writeU32(table, base, ramdisk.bytes.length);
|
||||
writeU32(table, base + 4, offset);
|
||||
writeU32(table, base + 8, ramdisk.type ?? 0);
|
||||
writeText(table, base + 12, VENDOR_RAMDISK_NAME_SIZE, ramdisk.name ?? "");
|
||||
ramdisk.boardId?.copy(table, base + VENDOR_RAMDISK_BOARD_ID_OFFSET, 0, 64);
|
||||
offset += ramdisk.bytes.length;
|
||||
}
|
||||
return table;
|
||||
};
|
||||
|
||||
const writeVendorHeader = (
|
||||
image: Buffer,
|
||||
options: VendorBootImageOptions,
|
||||
facts: {
|
||||
readonly version: 3 | 4;
|
||||
readonly page: number;
|
||||
readonly headerSize: number;
|
||||
readonly sectionSize: number;
|
||||
readonly dtbSize: number;
|
||||
readonly tableSize: number;
|
||||
readonly entryCount: number;
|
||||
readonly entrySize: number;
|
||||
readonly bootconfigSize: number;
|
||||
},
|
||||
): void => {
|
||||
image.write("VNDRBOOT", 0, "ascii");
|
||||
writeU32(image, 8, facts.version);
|
||||
writeU32(image, 12, facts.page);
|
||||
writeU32(image, 16, options.kernelAddr ?? 0x8000_8000);
|
||||
writeU32(image, 20, options.ramdiskAddr ?? 0x8100_0000);
|
||||
writeU32(image, 24, facts.sectionSize);
|
||||
writeText(image, 28, 2048, options.cmdline ?? "console=tty0");
|
||||
writeU32(image, 2076, options.tagsAddr ?? 0x8000_0100);
|
||||
writeText(image, 2080, 16, options.name ?? "board");
|
||||
writeU32(image, 2096, facts.headerSize);
|
||||
writeU32(image, 2100, facts.dtbSize);
|
||||
writeU64(image, 2104, options.dtbAddr ?? 0x8200_0000);
|
||||
if (facts.version < 4) return;
|
||||
writeU32(image, VENDOR_V3, facts.tableSize);
|
||||
writeU32(image, VENDOR_V3 + 4, facts.entryCount);
|
||||
writeU32(image, VENDOR_V3 + 8, facts.entrySize);
|
||||
writeU32(image, VENDOR_V3 + 12, facts.bootconfigSize);
|
||||
};
|
||||
|
||||
/** Build a page-padded VNDRBOOT image. The v4 table is not a child. */
|
||||
export const buildVendorBootImage = (
|
||||
options: VendorBootImageOptions,
|
||||
): Buffer => {
|
||||
const version = options.version;
|
||||
const page = options.pageSize ?? 4096;
|
||||
const headerSize =
|
||||
options.headerSize ?? (version === 4 ? VENDOR_V4 : VENDOR_V3);
|
||||
const ramdisks = options.ramdisks ?? [];
|
||||
const entrySize = options.entrySize ?? VENDOR_ENTRY;
|
||||
const section =
|
||||
options.section ??
|
||||
(version === 3
|
||||
? (options.ramdisk ?? Buffer.alloc(0))
|
||||
: Buffer.concat(ramdisks.map((item) => item.bytes)));
|
||||
const dtb = options.dtb ?? Buffer.alloc(0);
|
||||
const bootconfig =
|
||||
version === 4 ? (options.bootconfig ?? Buffer.alloc(0)) : Buffer.alloc(0);
|
||||
const table =
|
||||
version === 4 && ramdisks.length > 0
|
||||
? vendorRamdiskTable(ramdisks, entrySize)
|
||||
: Buffer.alloc(0);
|
||||
const placed: Placement[] = [];
|
||||
let cursor = alignUp(headerSize, page);
|
||||
const sectionOffset = cursor;
|
||||
if (section.length > 0)
|
||||
cursor = alignUp(sectionOffset + section.length, page);
|
||||
cursor = place(placed, cursor, page, dtb);
|
||||
cursor = place(placed, cursor, page, table);
|
||||
cursor = place(placed, cursor, page, bootconfig);
|
||||
const image = Buffer.alloc(cursor);
|
||||
writeVendorHeader(image, options, {
|
||||
version,
|
||||
page,
|
||||
headerSize,
|
||||
sectionSize: section.length,
|
||||
dtbSize: dtb.length,
|
||||
tableSize: table.length,
|
||||
entryCount: ramdisks.length,
|
||||
entrySize,
|
||||
bootconfigSize: bootconfig.length,
|
||||
});
|
||||
if (section.length > 0) section.copy(image, sectionOffset);
|
||||
for (const item of placed) item.bytes.copy(image, item.offset);
|
||||
return image;
|
||||
};
|
||||
|
||||
/** Append an AVBf footer. Sizes are written; nothing is signed. */
|
||||
export const appendAvbFooter = (
|
||||
image: Buffer,
|
||||
options: {
|
||||
readonly vbmeta?: Buffer;
|
||||
readonly vbmetaOffset?: number;
|
||||
readonly originalImageSize?: number;
|
||||
readonly partitionSize?: number;
|
||||
} = {},
|
||||
): Buffer => {
|
||||
const vbmeta = options.vbmeta ?? Buffer.from("vbmeta-test");
|
||||
const vbmetaOffset = options.vbmetaOffset ?? image.length;
|
||||
const originalImageSize = options.originalImageSize ?? image.length;
|
||||
const minimum = Math.max(image.length, vbmetaOffset + vbmeta.length) + 64;
|
||||
const partitionSize = options.partitionSize ?? minimum;
|
||||
if (partitionSize < minimum)
|
||||
throw new Error("partition is shorter than the image, vbmeta, and footer");
|
||||
if (vbmetaOffset + vbmeta.length > partitionSize - 64)
|
||||
throw new Error("vbmeta does not fit before the footer");
|
||||
const out = Buffer.alloc(partitionSize);
|
||||
image.copy(out, 0, 0, Math.min(image.length, out.length));
|
||||
vbmeta.copy(out, vbmetaOffset);
|
||||
const footerAt = partitionSize - 64;
|
||||
out.write("AVBf", footerAt, "ascii");
|
||||
out.writeUInt32BE(1, footerAt + 4);
|
||||
out.writeUInt32BE(0, footerAt + 8);
|
||||
writeU64be(out, footerAt + 12, originalImageSize);
|
||||
writeU64be(out, footerAt + 20, vbmetaOffset);
|
||||
writeU64be(out, footerAt + 28, vbmeta.length);
|
||||
return out;
|
||||
};
|
||||
|
||||
/** Drop the final byte. The view is a copy, so the source image stays intact. */
|
||||
export const truncateImage = (image: Buffer): Buffer =>
|
||||
Buffer.from(image.subarray(0, Math.max(0, image.length - 1)));
|
||||
|
||||
/**
|
||||
* Rewrite a v4 vendor table count. `entry_size` stays 108 and `table_size`
|
||||
* becomes `count * 108`.
|
||||
*/
|
||||
export const declareVendorRamdiskCount = (
|
||||
image: Buffer,
|
||||
count: number,
|
||||
): Buffer => {
|
||||
const copy = Buffer.from(image);
|
||||
writeU32(copy, VENDOR_V3, count * VENDOR_ENTRY);
|
||||
writeU32(copy, VENDOR_V3 + 4, count);
|
||||
return copy;
|
||||
};
|
||||
/** Small byte-format refusals for the public artifact adapters. */
|
||||
export const androidBootImageRefusals = () => {
|
||||
const unsupportedBoot = buildBootImage({ version: 0 });
|
||||
unsupportedBoot.writeUInt32LE(5, 40);
|
||||
const unsupportedVendor = buildVendorBootImage({ version: 4 });
|
||||
unsupportedVendor.writeUInt32LE(5, 8);
|
||||
const malformed = buildBootImage({ version: 0 });
|
||||
malformed.writeUInt32LE(1024, 36);
|
||||
return [
|
||||
{
|
||||
name: "boot-version",
|
||||
bytes: unsupportedBoot,
|
||||
kind: "unsupported",
|
||||
code: "unsupported_target",
|
||||
category: "unsupported_target",
|
||||
},
|
||||
{
|
||||
name: "vendor-version",
|
||||
bytes: unsupportedVendor,
|
||||
kind: "unsupported",
|
||||
code: "unsupported_target",
|
||||
category: "unsupported_target",
|
||||
},
|
||||
{
|
||||
name: "short-image",
|
||||
bytes: truncateImage(buildBootImage({ version: 0 })),
|
||||
kind: "truncated",
|
||||
code: "truncated",
|
||||
category: "truncated",
|
||||
},
|
||||
{
|
||||
name: "bad-page",
|
||||
bytes: malformed,
|
||||
kind: "malformed",
|
||||
code: "invalid_request",
|
||||
category: "invalid_input",
|
||||
},
|
||||
] as const;
|
||||
};
|
||||
Reference in new issue
Block a user