mirror of
https://github.com/morluto/rea.git
synced 2026-11-10 00:36:35 +00:00
f21fda0fc0
* feat(elf): report a Linux kernel image's version banner and embedded build config inspect_kernel_build_config and inspect-kernel-build-config read one local vmlinux, raw arm64 Image, gzip bzImage or zImage, or configs.ko and report its Linux version banner and the IKCONFIG .config embedded between IKCFG_ST and IKCFG_ED, without executing it. A config is present only when a gzip member ends exactly at IKCFG_ED, passes its CRC-32 and ISIZE checks and parses as .config text; framing that fails is reported malformed, never absent. bzImage gzip payloads are inflated within a budget and other codecs are named as unsupported, using codec detection now shared with the kernel module parser. The config search, inflate sizes and option counts are bounded, scans honor cancellation, and target-derived text is marked untrusted. * fix(elf): reject a gzip member whose header checksum fails When FHCRC is set, compare the low 16 bits of the header CRC-32 before inflating, so a damaged header no longer yields a present config or an inflated bzImage payload. * fix(elf): detect the bzImage codec inside the declared payload Codec detection now reads the same payload_offset/payload_length slice that is inflated, so bytes past a short payload cannot name its codec. * fix(elf): report a framed config that does not decode as malformed A damaged or cut-off deflate stream between IKCFG_ST and IKCFG_ED was skipped and could end as an absent config with complete coverage. It is now malformed with config_gzip_invalid, and a later valid config still wins. * fix(elf): scan config lines in place and accept long string values Config text is read one line at a time instead of split into an array, and a quoted value is validated before it is decoded once. The 4096-character string cap is removed: Kconfig has no such limit and max_config_bytes already bounds every line, so a long CONFIG_EXTRA_FIRMWARE list is no longer reported as malformed. * fix(elf): let a live cancellation reach the kernel config parser The parser ran synchronously, so an abort raised during parsing could not change the signal before it returned. Inflation now runs on the zlib thread pool and each scan yields to the event loop once per MiB, so the existing cancellation checks observe a real abort. * refactor(elf): carry the refused kernel config budget as a typed fact Budget failures are now KernelBuildConfigBudgetFailure with a knob field, and the provider builds its recovery advice from that field instead of searching the diagnostic message for an option name. * docs(elf): move the kernel build config guide under docs/guides/native The documentation guide assigns analyst workflows to docs/guides/<domain>/. Move the guide there, place its navigation and directory entries in the Native binaries group, and update links from the docs index, CLI guide, spec and authored skill. The public /kernel-build-config route is unchanged. * fix(elf): yield while checking one long config line A config made of one long quoted value never reached the per-line yield, so the control-byte check, value validation and SHA-256 ran in one synchronous block. Each now works one MiB window per event-loop turn, and the line patterns match only a bounded name prefix instead of the whole value. * fix(elf): return paged config entries that do not pin the decoded text Entry names and values were V8 slices of the whole decoded config, so a one-entry page kept the full text alive. Entries in the returned page are now standalone copies, so retained memory follows the page size. * fix(elf): yield while kernel marker searches find nothing IKCFG_ST, IKCFG_ED and banner searches used one Buffer.indexOf over the rest of the image, so a large image with no marker never yielded. They now search overlapping one MiB windows and yield after each window without a match. * fix(elf): preserve long kernel config names * fix(elf): frame kernel configs by gzip member boundaries --------- Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
76 lines
3.9 KiB
Markdown
76 lines
3.9 KiB
Markdown
# Linux kernel build config
|
|
|
|
## Problem and outcome
|
|
|
|
Analysing a Linux kernel image usually starts with two questions: which kernel
|
|
version is this, and how was it configured. A kernel built with
|
|
`CONFIG_IKCONFIG` embeds its `.config` as a gzip blob between `IKCFG_ST` and
|
|
`IKCFG_ED`. REA reports kernel modules and ELF notes, but it cannot read the
|
|
version banner or the embedded config, so an agent needs a Linux host and
|
|
`scripts/extract-ikconfig`.
|
|
|
|
This feature adds `inspect_kernel_build_config` and
|
|
`inspect-kernel-build-config`. They read one selected local kernel image and
|
|
report its `Linux version` banner and embedded build config, without
|
|
executing or booting it.
|
|
|
|
[Linux kernel build config](../../../guides/native/kernel-build-config.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. Accepted inputs are a `vmlinux` ELF, a raw arm64 `Image`, an x86 `bzImage`
|
|
or `zImage` whose payload is gzip, and a `configs.ko` module. The file is
|
|
read through the stable artifact read and never executed.
|
|
2. The banner is the first printable `Linux version ` string followed by a
|
|
version token that starts with a digit and ends at a NUL or newline within
|
|
512 bytes. Version, builder and compiler are split from it. The scan is
|
|
linear in the searched bytes.
|
|
3. A config is `present` only when `IKCFG_ST` is followed by a gzip member that
|
|
ends exactly at the next `IKCFG_ED`, inflates within `max_config_bytes`,
|
|
passes its CRC-32 and ISIZE checks, and parses as `.config` text. Inflation
|
|
reads only the bytes up to that marker.
|
|
4. Framing that fails its checks or grammar, including a framed deflate stream
|
|
that does not decode or is cut off by `IKCFG_ED`, is `malformed`, never
|
|
`absent`. An unframed `IKCFG_ST` string is skipped. A valid config later in the bytes
|
|
still wins.
|
|
5. Entries report name, kind (`y`, `m`, `number`, `string`, `not_set`) and
|
|
value, with an exact `name` filter and `offset`/`limit` paging.
|
|
6. A bzImage setup header from boot protocol 2.08 locates the payload. A gzip
|
|
payload is inflated within `max_payload_bytes` and searched, with locations
|
|
marked `inflated_payload`. Other payload codecs, and a file that is itself a
|
|
compressed stream such as `Image.gz`, are `unsupported` and name the codec,
|
|
using the codec detection shared with the kernel module parser.
|
|
7. Budgets bound file size, config and payload inflate size, option count and
|
|
page size. The config search inflates at most 16 candidates and at most
|
|
four times `max_config_bytes` in total, charging a stream that fails
|
|
partway through its full per-candidate allowance. Exhausting the search budget is
|
|
`incomplete` with `config_search_exhausted`. A member past
|
|
`max_config_bytes` fails the budget only when no later candidate is
|
|
accepted.
|
|
8. Cancellation is checked between candidates, between banner hits, while
|
|
scanning long text and while parsing config lines. Inflation runs off the
|
|
event loop and each scan, including marker searches that find nothing, text
|
|
checks, validation of a single long value and hashing, yields to it at least once per MiB, so a live
|
|
cancellation reaches those checks.
|
|
9. Banner text and config values are marked target-derived and untrusted.
|
|
10. MCP requires an absolute path. The CLI resolves relative paths against the
|
|
working directory.
|
|
|
|
## Acceptance
|
|
|
|
- Unit tests cover banner parsing, config framing, grammar, malformed and
|
|
truncated members, decoy candidates, search budgets, cancellation, and
|
|
bzImage payload handling.
|
|
- Service tests cover each status and reason.
|
|
- CLI acceptance, filesystem boundary and MCP boundary tests exercise the
|
|
public contract.
|
|
|
|
## Non-goals
|
|
|
|
- Decompressing xz, lz4, lzma, zstd, bzip2 or lzo payloads.
|
|
- Comparing the config with a source tree or evaluating Kconfig dependencies.
|
|
- Executing or booting the image.
|