Files
reverse-engineering-anything/src/domain/native/kernelModule.ts
T
morluto 62d6cfac92 refactor(domain): name known coverage once and derive local coverage enums from it (#11428)
* refactor(domain): name known coverage once and derive six native coverage enums from it

knownCoverageStatusSchema in src/domain/coverage.ts replaces the four per-domain coverageStatusSchema.exclude(["unknown"]) copies (Android, Flutter, GPU, model) and six plain ["complete", "partial"] enums in native reports (Apple IPS, PE certificates and imports, Windows shortcuts, native call observation, NativeAOT metadata recovery). Advertised schemas are unchanged. local-completeness-enum: 91 -> 85.

* refactor(domain): use the shared known coverage schema for ADB device analysis

* refactor(domain): derive pcap, firmware, Apktool, JEB and WASM interface coverage from known coverage (#11430)

Each producer decides coverage from what it examined (dissected-field gaps, unpublished firmware entries, string-table facts, a short JEB unit page, a WABT budget stop), so none reports unknown. Advertised schemas are unchanged. local-completeness-enum: 85 -> 79.

* refactor(domain): derive eleven checked coverage enums from known coverage (#11438)

* refactor(domain): derive eleven checked coverage enums from known coverage

* refactor(domain): derive coverage-plus-outcome enums from the coverage owner (#11440)
2026-11-16 04:15:59 +08:00

295 lines
9.3 KiB
TypeScript

import { z } from "zod";
import { knownCoverageStatusSchema } from "../coverage.js";
import { digestSchema } from "../digests.js";
import { fixedTupleSchema } from "../fixedTupleSchema.js";
import { absoluteLocalPathStringSchema } from "../localPath.js";
import { ELF_OBJECT_TYPE_NAMES } from "./elfNotes.js";
const uint = z.number().int().min(0).max(0xffffffff);
const uint8 = z.number().int().min(0).max(255);
const range = z.strictObject({ offset: uint, bytes: uint });
const hex = z.string().regex(/^[0-9a-f]*$/u);
/** Hard ceiling on the caller-selected input read budget. */
export const MAX_INSPECT_KERNEL_MODULE_FILE_BYTES = 536870912;
/**
* Hard ceiling on decoded .modinfo and __versions entries plus listed
* file-backed __ksymtab* sections combined.
*/
export const MAX_INSPECT_KERNEL_MODULE_ENTRIES = 65536;
/** Default per-field retention budgets; omission does not establish malformed syntax. */
export const DEFAULT_KERNEL_MODULE_KEY_BYTES = 256;
export const DEFAULT_KERNEL_MODULE_VALUE_BYTES = 4096;
/**
* Retained __ksymtab* section-name length. Longer names stay listed with a
* null name and are not copied into the result.
*/
export const MAX_KERNEL_MODULE_SECTION_NAME_BYTES = 256;
/** Inline raw-entry hex ceiling. Longer entries keep only their SHA-256. */
export const MAX_KERNEL_MODULE_RAW_BYTES = 4096;
/**
* `struct modversion_info` is `unsigned long crc` plus
* `char name[64 - sizeof(unsigned long)]`, so every entry is 64 bytes.
* ELF32 stores a u32 CRC and a 60-byte name. ELF64 stores a u64
* unsigned long and a 56-byte name.
*/
export const KERNEL_MODULE_VERSION_ENTRY_BYTES = 64;
/** `struct module_signature` is 12 bytes, with sig_len big-endian. */
export const MODULE_SIGNATURE_INFO_BYTES = 12;
/** Trailer magic, including the trailing newline, from MODULE_SIG_STRING. */
export const MODULE_SIGNATURE_MAGIC = "~Module signature appended~\n";
/** `PKEY_ID_PKCS7` from the kernel public-key identifier enum. */
export const MODULE_SIGNATURE_PKCS7_ID_TYPE = 2;
export const KERNEL_MODULE_APPLICABILITY = [
"applicable",
"not_applicable",
"unsupported",
] as const;
export const KERNEL_MODULE_MODINFO_ENTRY_REASONS = [
"unterminated_modinfo_entry",
"modinfo_missing_separator",
"modinfo_empty_key",
] as const;
export const KERNEL_MODULE_MODINFO_SECTION_REASONS = [
"modinfo_section_compressed",
"modinfo_section_not_file_backed",
] as const;
export const KERNEL_MODULE_VERSION_ENTRY_REASONS = [
"version_name_unterminated",
] as const;
export const KERNEL_MODULE_VERSION_SECTION_REASONS = [
"versions_size_not_multiple",
"versions_section_compressed",
"versions_section_not_file_backed",
] as const;
export const KERNEL_MODULE_KSYMTAB_SECTION_REASONS = [
"ksymtab_name_exceeds_limit",
] as const;
export const KERNEL_MODULE_SIGNATURE_REASONS = [
"signature_trailer_truncated",
"signature_length_inconsistent",
"signature_parameters_nonzero",
"signature_id_type_not_pkcs7",
] as const;
export const KERNEL_MODULE_VERSION_LAYOUTS = [
"elf32_unsigned_long_name60",
"elf64_unsigned_long_name56",
] as const;
const sectionStatus = z.enum([
"present",
"absent",
"unknown",
"malformed",
"unsupported",
]);
const entryStatus = z.enum(["observed", "malformed"]);
const modinfoEntrySchema = z.strictObject({
index: uint,
location: range,
key: z.string().nullable(),
value: z.string().nullable(),
raw_sha256: digestSchema,
raw_hex: hex.nullable(),
status: entryStatus,
reason: z.enum(KERNEL_MODULE_MODINFO_ENTRY_REASONS).nullable(),
omitted_fields: z
.array(z.enum(["key", "value"]))
.max(2)
.default([])
.describe(
"Fields omitted by retention policy, independently of structural status/reason",
),
});
const modinfoSchema = z.strictObject({
status: sectionStatus,
location: range.nullable(),
sha256: digestSchema.nullable(),
entries: z.array(modinfoEntrySchema),
reason: z.enum(KERNEL_MODULE_MODINFO_SECTION_REASONS).nullable(),
});
const versionEntrySchema = z.strictObject({
index: uint,
location: range,
crc_hex: z.string().regex(/^(?:[0-9a-f]{8}|[0-9a-f]{16})$/u),
name: z.string().nullable(),
status: entryStatus,
reason: z.enum(KERNEL_MODULE_VERSION_ENTRY_REASONS).nullable(),
});
const versionsSchema = z.strictObject({
status: sectionStatus,
layout: z.enum(KERNEL_MODULE_VERSION_LAYOUTS).nullable(),
entry_bytes: z.literal(KERNEL_MODULE_VERSION_ENTRY_BYTES).nullable(),
location: range.nullable(),
sha256: digestSchema.nullable(),
entries: z.array(versionEntrySchema),
reason: z.enum(KERNEL_MODULE_VERSION_SECTION_REASONS).nullable(),
});
const thisModuleSchema = z.strictObject({
status: z.enum(["present", "absent", "unknown", "unsupported"]),
location: range.nullable(),
/** `struct module` changes with the kernel version and is not decoded. */
layout: z.literal("unknown"),
});
const sizedSectionSchema = z.strictObject({
status: z.enum(["present", "absent", "unknown"]),
location: range.nullable(),
/** Observed file-backed size. Null when the section is not file-backed. */
bytes: uint.nullable(),
compressed: z.boolean().nullable(),
});
const ksymtabSchema = z.strictObject({
status: z.enum(["observed", "unknown"]),
sections: z.array(
z.strictObject({
name: z
.string()
.min(1)
.max(MAX_KERNEL_MODULE_SECTION_NAME_BYTES)
.nullable(),
location: range,
compressed: z.boolean(),
reason: z.enum(KERNEL_MODULE_KSYMTAB_SECTION_REASONS).nullable(),
}),
),
});
const signatureInfoSchema = z.strictObject({
location: range,
algo: uint8,
hash: uint8,
id_type: uint8,
signer_len: uint8,
key_id_len: uint8,
pad: fixedTupleSchema([uint8, uint8, uint8]),
sig_len: uint,
});
const signatureSchema = z.strictObject({
status: z.enum(["absent", "present", "malformed", "unsupported"]),
magic: range.nullable(),
info: signatureInfoSchema.nullable(),
pkcs7: z
.strictObject({
location: range,
sha256: digestSchema,
})
.nullable(),
reason: z.enum(KERNEL_MODULE_SIGNATURE_REASONS).nullable(),
});
/** Complete bounded inspection of one relocatable Linux kernel module. */
export const inspectKernelModuleInputSchema = z.strictObject({
path: absoluteLocalPathStringSchema.describe(
"Absolute filesystem path to an ELF kernel module or a compressed .ko container",
),
max_file_bytes: z
.number()
.int()
.min(64)
.max(MAX_INSPECT_KERNEL_MODULE_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_MODULE_ENTRIES)
.default(8192)
.describe(
"Maximum .modinfo and __versions entries plus file-backed __ksymtab* sections to examine; exceeding the budget fails without partial success",
),
max_modinfo_key_bytes: z
.int()
.min(1)
.max(MAX_INSPECT_KERNEL_MODULE_FILE_BYTES)
.default(DEFAULT_KERNEL_MODULE_KEY_BYTES)
.describe(
"Maximum bytes retained per .modinfo key (default 256). Larger keys stay valid when their syntax is valid, with key null and omitted_fields naming key. Raise on the next call to retain them; no restart. Does not raise input, entry or raw-hex budgets.",
),
max_modinfo_value_bytes: z
.int()
.min(1)
.max(MAX_INSPECT_KERNEL_MODULE_FILE_BYTES)
.default(DEFAULT_KERNEL_MODULE_VALUE_BYTES)
.describe(
"Maximum bytes retained per .modinfo value (default 4096). Larger values stay valid when their syntax is valid, with value null and omitted_fields naming value. Raise on the next call to retain them; no restart. Does not raise input, entry or raw-hex budgets.",
),
});
/**
* Observed kernel-module metadata. ET_REL images are applicable. Other ELF
* types are not applicable. gzip, xz, and zstd containers are unsupported.
*/
export const kernelModuleSchema = z.strictObject({
artifact: z.strictObject({
path: z.string().min(1),
sha256: digestSchema,
bytes: uint,
}),
format: z.enum(["elf32", "elf64"]).nullable(),
byte_order: z.enum(["little", "big"]).nullable(),
machine: uint.nullable(),
type: uint.nullable(),
type_name: z.enum(ELF_OBJECT_TYPE_NAMES).nullable(),
applicability: z.enum(KERNEL_MODULE_APPLICABILITY),
compression: z
.strictObject({
codec: z.enum(["gzip", "xz", "zstd"]),
status: z.literal("unsupported"),
})
.nullable(),
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(),
modinfo: modinfoSchema.nullable(),
versions: versionsSchema.nullable(),
this_module: thisModuleSchema.nullable(),
ksymtab: ksymtabSchema.nullable(),
init_text: sizedSectionSchema.nullable(),
exit_text: sizedSectionSchema.nullable(),
signature: signatureSchema.nullable(),
coverage: z.strictObject({
status: z
.enum([
...knownCoverageStatusSchema.options,
"not_applicable",
"unsupported",
])
.describe(
"Whether the supported inspection examined the declared facts; omitted or undecodable facts make coverage partial.",
),
examined_entries: uint,
}),
limitations: z.array(z.string()),
});
export type KernelModule = z.infer<typeof kernelModuleSchema>;
export type InspectKernelModuleInput = z.infer<
typeof inspectKernelModuleInputSchema
>;