Files
reverse-engineering-anything/src/domain/native/kernelBuildConfig.ts
T
morluto acb10754c1 refactor(native)!: report kernel build config coverage as partial or unknown instead of incomplete (#11486)
inspect_kernel_build_config coverage.status was `incomplete` for a config cut by the
searched bytes or a budget-stopped search (known gaps), for a malformed framed
config, and for a payload that was never searched (examined_bytes 0). Coverage
now uses the shared status: `partial` for the known gaps, `unknown` when a
config's existence or contents cannot be determined; `unsupported` is
unchanged. config.status keeps its own values, and the service's consistency
check pairs each config state with its coverage.

BREAKING CHANGE: inspect_kernel_build_config `coverage.status` reports `partial`
(config_gzip_truncated, config_search_exhausted) or `unknown` (malformed config,
payload not searched) instead of `incomplete`.
2026-11-16 05:01:36 +08:00

238 lines
7.3 KiB
TypeScript

import { z } from "zod";
import { coverageStatusSchema } from "../coverage.js";
import { digestSchema } from "../digests.js";
import { absoluteLocalPathStringSchema } from "../localPath.js";
const uint = z.number().int().min(0).max(0xffffffff);
/** Hard ceiling on the caller-selected input read budget. */
export const MAX_INSPECT_KERNEL_BUILD_CONFIG_FILE_BYTES = 536870912;
/** Hard ceiling on CONFIG_* options examined from one embedded config. */
export const MAX_INSPECT_KERNEL_BUILD_CONFIG_ENTRIES = 65536;
/** Hard ceiling on the inflated IKCFG gzip member. */
export const MAX_INSPECT_KERNEL_BUILD_CONFIG_CONFIG_BYTES = 33554432;
/** Hard ceiling on an inflated bzImage payload searched for the banner and config. */
export const MAX_INSPECT_KERNEL_BUILD_CONFIG_PAYLOAD_BYTES = 536870912;
/** Hard ceiling on one page of CONFIG_* entries. */
export const MAX_INSPECT_KERNEL_BUILD_CONFIG_PAGE = 4096;
export const KERNEL_BUILD_CONFIG_CODECS = [
"gzip",
"xz",
"lz4",
"lzma",
"zstd",
"bzip2",
"lzo",
] as const;
export const KERNEL_BUILD_CONFIG_VALUE_KINDS = [
"y",
"m",
"string",
"number",
"not_set",
] as const;
/** Reasons a framed `IKCFG_ST` ... `IKCFG_ED` blob is reported as malformed. */
export const KERNEL_BUILD_CONFIG_MALFORMED_REASONS = [
"config_gzip_invalid",
"config_text_invalid",
] as const;
export const KERNEL_BUILD_CONFIG_REASONS = [
...KERNEL_BUILD_CONFIG_MALFORMED_REASONS,
"config_gzip_truncated",
"config_search_exhausted",
"payload_truncated",
"payload_gzip_invalid",
"payload_codec_unsupported",
"unrecognized_payload_codec",
"setup_header_payload_unavailable",
] as const;
const range = z.strictObject({
/** `file` is a range in the selected image. `inflated_payload` is a range in the inflated bzImage payload. */
space: z.enum(["file", "inflated_payload"]),
offset: uint,
bytes: uint,
});
/** Matches a Kconfig `int` or `hex` value as written to `.config`. */
export const KERNEL_BUILD_CONFIG_NUMBER =
/^(?:-?(?:0|[1-9][0-9]*)|0[xX][0-9A-Fa-f]+)$/u;
/** Length of the `IKCFG_ST` and `IKCFG_ED` markers. */
export const KERNEL_BUILD_CONFIG_MARKER_BYTES = 8;
const entrySchema = z.strictObject({
name: z.string().regex(/^CONFIG_[A-Za-z0-9_]+$/u),
kind: z.enum(KERNEL_BUILD_CONFIG_VALUE_KINDS),
/** Null only for `not_set`. Strings are the decoded quoted text. */
value: z.string().nullable(),
trust: z.literal("target-derived-untrusted"),
});
const bannerSchema = z.strictObject({
status: z.enum(["present", "absent", "unknown"]),
text: z.string().nullable(),
version: z.string().nullable(),
builder: z.string().nullable(),
compiler: z.string().nullable(),
location: range.nullable(),
trust: z.literal("target-derived-untrusted"),
});
const payloadSchema = z.strictObject({
container: z.enum(["file", "bzimage"]),
codec: z.enum(KERNEL_BUILD_CONFIG_CODECS).nullable(),
status: z.enum([
"uncompressed",
"inflated",
"unsupported",
"truncated",
"malformed",
"unavailable",
]),
/** File offset of a bzImage payload, or 0 for a whole-file codec. Null when the file itself was searched. */
offset: uint.nullable(),
bytes: uint.nullable(),
inflated_bytes: uint.nullable(),
});
/** One bounded read of a kernel image's version banner and embedded `.config`. */
export const inspectKernelBuildConfigInputSchema = z.strictObject({
path: absoluteLocalPathStringSchema.describe(
"Absolute filesystem path to a vmlinux ELF, raw arm64 Image, x86 bzImage/zImage, or configs.ko module",
),
max_file_bytes: z
.number()
.int()
.min(64)
.max(MAX_INSPECT_KERNEL_BUILD_CONFIG_FILE_BYTES)
.default(67108864)
.describe("Maximum stable artifact bytes to read (default 64 MiB)"),
max_entries: z
.number()
.int()
.min(1)
.max(MAX_INSPECT_KERNEL_BUILD_CONFIG_ENTRIES)
.default(16384)
.describe(
"Maximum CONFIG_* options to examine; exceeding the budget fails without partial success",
),
max_config_bytes: z
.number()
.int()
.min(64)
.max(MAX_INSPECT_KERNEL_BUILD_CONFIG_CONFIG_BYTES)
.default(4194304)
.describe(
"Maximum inflated bytes of one IKCFG gzip member (default 4 MiB)",
),
max_payload_bytes: z
.number()
.int()
.min(64)
.max(MAX_INSPECT_KERNEL_BUILD_CONFIG_PAYLOAD_BYTES)
.default(134217728)
.describe(
"Maximum inflated bytes of a bzImage gzip payload (default 128 MiB)",
),
offset: z
.number()
.int()
.min(0)
.max(MAX_INSPECT_KERNEL_BUILD_CONFIG_ENTRIES)
.default(0)
.describe("Number of matching CONFIG_* options to skip"),
limit: z
.number()
.int()
.min(1)
.max(MAX_INSPECT_KERNEL_BUILD_CONFIG_PAGE)
.default(256)
.describe("Maximum CONFIG_* options to return in this page"),
name: z
.string()
.regex(/^CONFIG_[A-Za-z0-9_]+$/u)
.optional()
.describe(
"Exact CONFIG_* name to return. Omitted returns every option in the page",
),
});
/**
* Version banner and embedded build config. A config is present only when
* `IKCFG_ST` is immediately followed by a gzip member whose inflated text is
* a config and whose next bytes are `IKCFG_ED`. A framed blob whose member does
* not decode, fails its trailer check, or whose text fails the grammar is
* `malformed`.
* Malformed, truncated, or unsupported input is never an absent config.
*/
export const kernelBuildConfigSchema = z.strictObject({
artifact: z.strictObject({
path: z.string().min(1),
sha256: digestSchema,
bytes: uint,
}),
format: z.enum(["elf", "file"]),
payload: payloadSchema,
next_probe: z
.strictObject({
operation: z
.literal("external_decompression")
.describe(
"External decompression with a codec utility, not a REA tool",
),
rationale: z.string().min(1),
})
.nullable(),
banner: bannerSchema,
config: z.strictObject({
status: z.enum([
"present",
"absent",
"malformed",
"incomplete",
"unsupported",
]),
reason: z.enum(KERNEL_BUILD_CONFIG_REASONS).nullable(),
marker: range.nullable(),
end_marker: range.nullable(),
gzip: range.nullable(),
sha256: digestSchema.nullable(),
/** CONFIG_* options in the accepted config, before the name filter and page. */
option_count: uint,
/** Options selected by the name filter, before the page. */
matched_count: uint,
offset: uint,
limit: uint,
name: z
.string()
.regex(/^CONFIG_[A-Za-z0-9_]+$/u)
.nullable(),
entries: z.array(entrySchema),
}),
coverage: z.strictObject({
/**
* `partial` when the config is known to extend past what was examined (a
* gzip member cut by the searched bytes, or the candidate budget stopping
* the search); `unknown` when whether a config exists or what it holds
* cannot be determined (an unreadable payload that was not searched, or a
* malformed config); `unsupported` for a payload codec REA does not inflate.
*/
status: z.enum([...coverageStatusSchema.options, "unsupported"]),
examined_bytes: uint,
examined_entries: uint,
}),
limitations: z.array(z.string()),
});
export type KernelBuildConfig = z.infer<typeof kernelBuildConfigSchema>;
export type InspectKernelBuildConfigInput = z.infer<
typeof inspectKernelBuildConfigInputSchema
>;
export type KernelBuildConfigEntry =
KernelBuildConfig["config"]["entries"][number];