feat(elf): inspect Linux kernel module metadata (#7010)

* feat(elf): inspect Linux kernel module metadata

Adds inspect-kernel-module and inspect_kernel_module for ELF32/ELF64
ET_REL Linux kernel modules, read statically without executing them.
Reports ordered .modinfo entries with duplicates preserved, __versions
symbol CRCs, the presence of .gnu.linkonce.this_module and __ksymtab,
.init.text and .exit.text sizes, and an appended module signature
trailer with its PKCS#7 byte range and SHA-256. gzip, xz and zstd
containers are reported unsupported with external decompression as the
next probe. Malformed headers and exhausted entry budgets return no
partial success.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016y53PdpyMAp9RSW65fatHe

* fix(elf): bound kernel module ksymtab listing and tighten contracts

Charge listed __ksymtab* sections against max_entries, omit section names
longer than 256 bytes with ksymtab_name_exceeds_limit, and aggregate the
non-file-backed limitation so repeated huge names cannot inflate Evidence.
Use fixedTupleSchema for the signature pad bytes with projection parity
tests, and assert the late-cancellation reason and retained observation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016y53PdpyMAp9RSW65fatHe

* fix: resolve merge integration errors

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-10-24 22:35:20 +08:00
1 parent de088fcec6
commit dba8a31978
57 files changed
+3160 -14

No files matched your search

+451
View File
@@ -0,0 +1,451 @@
import { createHash } from "node:crypto";
import { expect, it } from "vitest";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import {
inspectKernelModuleInputSchema,
kernelModuleSchema,
MODULE_SIGNATURE_MAGIC,
} from "../../domain/native/kernelModule.js";
import { BinaryFormatFailure } from "../metadata/BinaryContainer.js";
import {
compressedKernelModuleContainer,
kernelModuleFixture,
modversionEntry,
moduleSignatureTrailer,
} from "./KernelModule.fixture.js";
import { parseKernelModule } from "./KernelModuleParser.js";
const artifactPath = "/artifacts/demo.ko";
const parse = (bytes: Buffer, extra: { readonly max_entries?: number } = {}) =>
kernelModuleSchema.parse(
parseKernelModule(
bytes,
{
path: artifactPath,
sha256: "ab".repeat(32),
bytes: bytes.length,
},
inspectKernelModuleInputSchema.parse({
path: artifactPath,
...extra,
}),
),
);
const pkcs7 = Buffer.from("fake-pkcs7-bytes", "latin1");
const pkcs7Sha256 = createHash("sha256").update(pkcs7).digest("hex");
it("preserves parameter duplicates, embedded equals, and original entry bytes", () => {
const records = [
"parm=level:verbosity=a",
"parmtype=level:int",
"parm=level:again",
];
const report = parse(
kernelModuleFixture({ modinfo: Buffer.from(`${records.join("\0")}\0`) }),
);
expect(
report.modinfo?.entries.map(({ key, value, raw_hex }) => ({
key,
value,
raw_hex,
})),
).toEqual(
records.map((record) => ({
key: record.slice(0, record.indexOf("=")),
value: record.slice(record.indexOf("=") + 1),
raw_hex: Buffer.from(`${record}\0`).toString("hex"),
})),
);
});
it("distinguishes absent metadata from unavailable section names", () => {
const absent = parse(kernelModuleFixture({ modinfo: null, versions: null }));
expect(absent.modinfo?.status).toBe("absent");
expect(absent.versions?.status).toBe("absent");
const bytes = kernelModuleFixture();
bytes.writeUInt16LE(0, 62);
const unknown = parse(bytes);
expect(unknown.modinfo?.status).toBe("unknown");
expect(unknown.versions?.status).toBe("unknown");
});
it.each([
[64, true],
[64, false],
[32, true],
[32, false],
] as const)("reports an ET_REL ELF%s %s module", (bits, little) => {
const report = parse(kernelModuleFixture({ bits, little }));
const width = bits === 64 ? 16 : 8;
expect(report).toMatchObject({
format: bits === 64 ? "elf64" : "elf32",
byte_order: little ? "little" : "big",
machine: bits === 64 ? 62 : 20,
type: 1,
type_name: "relocatable",
applicability: "applicable",
compression: null,
next_probe: null,
coverage: { status: "complete", examined_entries: 9 },
});
expect(
report.modinfo?.entries.map((entry) => [entry.key, entry.value]),
).toEqual([
["license", "GPL"],
["vermagic", "5.15.0 SMP mod_unload"],
["alias", "pci:v1"],
["alias", "pci:v2"],
["name", "demo"],
["depends", ""],
]);
expect(
report.modinfo?.entries.every((entry) => entry.status === "observed"),
).toBe(true);
expect(report.versions?.layout).toBe(
bits === 64 ? "elf64_unsigned_long_name56" : "elf32_unsigned_long_name60",
);
expect(
report.versions?.entries.map((entry) => [entry.crc_hex, entry.name]),
).toEqual([
["12345678".padStart(width, "0"), "printk"],
["90abcdef".padStart(width, "0"), "module_layout"],
]);
expect(report.this_module).toMatchObject({
status: "present",
layout: "unknown",
location: { bytes: 8 },
});
expect(report.ksymtab?.sections.map((section) => section.name)).toEqual([
"__ksymtab",
]);
expect(report.init_text).toMatchObject({ status: "present", bytes: 4 });
expect(report.exit_text).toMatchObject({ status: "present", bytes: 1 });
expect(report.signature).toMatchObject({
status: "present",
reason: null,
pkcs7: {
location: { bytes: pkcs7.length },
sha256: pkcs7Sha256,
},
info: { algo: 0, hash: 0, id_type: 2, sig_len: pkcs7.length },
});
});
it("keeps earlier .modinfo entries when the last span is unterminated", () => {
const report = parse(
kernelModuleFixture({
modinfo: Buffer.from("license=GPL\0alias=pci:v3", "latin1"),
}),
);
expect(report.modinfo?.status).toBe("present");
expect(report.modinfo?.entries.map((entry) => entry.reason)).toEqual([
null,
"unterminated_modinfo_entry",
]);
expect(report.modinfo?.entries[1]).toMatchObject({
status: "malformed",
key: "alias",
value: "pci:v3",
});
});
it("reports a missing separator, an empty key, and an over-long field per entry", () => {
const report = parse(
kernelModuleFixture({
modinfo: Buffer.concat([
Buffer.from("license\0=GPL\0", "latin1"),
Buffer.from(`${"k".repeat(257)}=x\0`, "latin1"),
Buffer.from(`name=${"v".repeat(4097)}\0`, "latin1"),
]),
}),
);
expect(report.modinfo?.entries.map((entry) => entry.reason)).toEqual([
"modinfo_missing_separator",
"modinfo_empty_key",
"modinfo_field_exceeds_limit",
"modinfo_field_exceeds_limit",
]);
expect(report.modinfo?.entries[1]).toMatchObject({
key: null,
value: "GPL",
});
expect(report.modinfo?.entries[2]).toMatchObject({ key: null, value: "x" });
expect(report.modinfo?.entries[3]).toMatchObject({
key: "name",
value: null,
});
});
it("closes __versions when the section size is not a multiple of 64", () => {
const report = parse(kernelModuleFixture({ versions: Buffer.alloc(63) }));
expect(report.versions).toMatchObject({
status: "malformed",
entries: [],
reason: "versions_size_not_multiple",
layout: "elf64_unsigned_long_name56",
entry_bytes: 64,
});
expect(report.coverage.examined_entries).toBe(
(report.modinfo?.entries.length ?? 0) +
(report.ksymtab?.sections.length ?? 0),
);
});
it("observes a version name with nonzero padding and rejects a missing NUL", () => {
const padded = modversionEntry(0x12345678, "printk", 64, true);
padded[8 + "printk".length + 1] = 0x7f;
const unterminated = Buffer.alloc(64, 0x41);
unterminated.writeBigUInt64LE(0x11n, 0);
const report = parse(
kernelModuleFixture({
versions: Buffer.concat([padded, unterminated]),
}),
);
expect(report.versions?.entries[0]).toMatchObject({
status: "observed",
name: "printk",
reason: null,
crc_hex: "0000000012345678",
});
expect(report.versions?.entries[1]).toMatchObject({
status: "malformed",
name: null,
reason: "version_name_unterminated",
crc_hex: "0000000000000011",
});
});
it("reports an inconsistent signature length without a PKCS#7 range", () => {
const report = parse(
kernelModuleFixture({
signature: moduleSignatureTrailer(Buffer.from("abcd"), 50_000),
}),
);
expect(report.signature).toMatchObject({
status: "malformed",
reason: "signature_length_inconsistent",
pkcs7: null,
info: { sig_len: 50_000, id_type: 2 },
});
expect(report.modinfo?.entries[0]?.key).toBe("license");
});
it("withholds PKCS#7 bytes for nonzero signature parameters and a non-PKCS7 id", () => {
const nonzero = Buffer.alloc(12);
nonzero[0] = 1;
nonzero[2] = 2;
nonzero.writeUInt32BE(4, 8);
const otherId = Buffer.alloc(12);
otherId[0] = 1;
otherId[3] = 2;
otherId[2] = 1;
otherId.writeUInt32BE(4, 8);
const magic = Buffer.from(MODULE_SIGNATURE_MAGIC, "latin1");
const payload = Buffer.from("abcd");
expect(
parse(
kernelModuleFixture({
signature: Buffer.concat([payload, nonzero, magic]),
}),
).signature,
).toMatchObject({
status: "malformed",
reason: "signature_parameters_nonzero",
pkcs7: null,
});
expect(
parse(
kernelModuleFixture({
signature: Buffer.concat([payload, otherId, magic]),
}),
).signature,
).toMatchObject({
status: "unsupported",
reason: "signature_id_type_not_pkcs7",
pkcs7: null,
info: { id_type: 1 },
});
});
it("does not examine kernel metadata on a non-relocatable ELF", () => {
const report = parse(kernelModuleFixture({ type: 2 }));
expect(report).toMatchObject({
applicability: "not_applicable",
type: 2,
type_name: "executable",
modinfo: null,
versions: null,
signature: null,
coverage: { status: "not_applicable", examined_entries: 0 },
});
});
it.each(["gzip", "xz", "zstd"] as const)(
"recommends external decompression for a %s container",
(codec) => {
const report = parse(compressedKernelModuleContainer(codec));
expect(report).toMatchObject({
applicability: "unsupported",
format: null,
compression: { codec, status: "unsupported" },
next_probe: { operation: "external_decompression" },
modinfo: null,
coverage: { status: "unsupported", examined_entries: 0 },
});
expect(report.next_probe?.rationale).toContain(codec);
expect(report.next_probe?.rationale).toContain("external");
expect(report.next_probe?.rationale).toContain(
"call inspect_kernel_module on the decompressed file",
);
expect(
kernelModuleSchema.safeParse({
...report,
next_probe: { ...report.next_probe, operation: "extract_artifact" },
}).success,
).toBe(false);
},
);
it("fails closed when the combined entry budget is exhausted", () => {
expect(() => parse(kernelModuleFixture(), { max_entries: 7 })).toThrow(
ArtifactReaderFailure,
);
try {
parse(kernelModuleFixture(), { max_entries: 7 });
} catch (error) {
expect(error).toBeInstanceOf(ArtifactReaderFailure);
expect(error).toMatchObject({ reason: "limit", boundary: "capacity" });
}
});
it("examines the first of two .modinfo sections and records the duplicate", () => {
const report = parse(kernelModuleFixture({ repeatModinfo: true }));
expect(report.modinfo?.entries).toHaveLength(6);
expect(report.limitations.join("\n")).toContain(
"Multiple .modinfo sections are declared; the first is examined.",
);
});
it("does not decode compressed, nobits, or out-of-file metadata sections", () => {
const compressed = kernelModuleFixture();
compressed.writeBigUInt64LE(0x800n, 64 + 64 + 8);
expect(parse(compressed).modinfo).toMatchObject({
status: "unsupported",
entries: [],
reason: "modinfo_section_compressed",
});
const nobits = kernelModuleFixture();
nobits.writeUInt32LE(8, 64 + 64 + 4);
expect(parse(nobits).modinfo).toMatchObject({
status: "malformed",
location: null,
entries: [],
reason: "modinfo_section_not_file_backed",
});
const outside = kernelModuleFixture();
outside.writeBigUInt64LE(1_000_000n, 64 + 64 + 24);
expect(parse(outside).modinfo).toMatchObject({
status: "malformed",
reason: "modinfo_section_not_file_backed",
});
const versionsOutside = kernelModuleFixture();
versionsOutside.writeBigUInt64LE(1_000_000n, 64 + 64 * 2 + 24);
expect(parse(versionsOutside).versions).toMatchObject({
status: "malformed",
entries: [],
reason: "versions_section_not_file_backed",
});
const versionsCompressed = kernelModuleFixture();
versionsCompressed.writeBigUInt64LE(0x800n, 64 + 64 * 2 + 8);
expect(parse(versionsCompressed).versions).toMatchObject({
status: "unsupported",
entries: [],
reason: "versions_section_compressed",
});
const versionsNobits = kernelModuleFixture();
versionsNobits.writeUInt32LE(8, 64 + 64 * 2 + 4);
expect(parse(versionsNobits).versions).toMatchObject({
status: "malformed",
location: null,
entries: [],
reason: "versions_section_not_file_backed",
});
const moduleSection = kernelModuleFixture();
moduleSection.writeUInt32LE(8, 64 + 64 * 3 + 4);
expect(parse(moduleSection).this_module).toMatchObject({
status: "present",
location: null,
layout: "unknown",
});
});
it("rejects a non-ELF file that is not a recognized container", () => {
expect(() => parse(Buffer.from("not an elf"))).toThrow(BinaryFormatFailure);
});
it("rejects ELF bytes preceding a bare signature magic as an inconsistent trailer", () => {
const report = parse(
kernelModuleFixture({
signature: Buffer.from(MODULE_SIGNATURE_MAGIC, "latin1"),
}),
);
expect(report.signature).toMatchObject({
status: "malformed",
reason: "signature_length_inconsistent",
pkcs7: null,
});
expect(report.modinfo?.entries[0]?.key).toBe("license");
});
it("records a missing trailer as observed absence", () => {
const report = parse(kernelModuleFixture({ signature: null }));
expect(report.signature).toMatchObject({
status: "absent",
magic: null,
info: null,
pkcs7: null,
reason: null,
});
expect(report.limitations.join("\n")).toContain(
"not proof the module is unsigned",
);
});
it("names a non-file-backed __ksymtab section without dropping the module", () => {
const bytes = kernelModuleFixture();
bytes.writeUInt32LE(8, 64 + 64 * 4 + 4);
const report = parse(bytes);
expect(report.ksymtab?.sections).toEqual([]);
expect(report.limitations.join("\n")).toContain(
"1 __ksymtab* section(s) are declared but not file-backed",
);
expect(report.modinfo?.entries[0]?.key).toBe("license");
});
it("charges many sections sharing one huge __ksymtab name to the entry budget", () => {
const name = `__ksymtab_${"x".repeat(65_490)}`;
const bytes = kernelModuleFixture({
sharedNameSections: { name, count: 8192 },
});
const started = performance.now();
expect(() => parse(bytes)).toThrow(ArtifactReaderFailure);
const report = parse(bytes, { max_entries: 65_536 });
expect(performance.now() - started).toBeLessThan(5_000);
const huge = report.ksymtab?.sections.slice(1) ?? [];
expect(huge).toHaveLength(8192);
expect(
huge.every(
(section) =>
section.name === null &&
section.reason === "ksymtab_name_exceeds_limit",
),
).toBe(true);
expect(report.ksymtab?.sections[0]).toMatchObject({
name: "__ksymtab",
reason: null,
});
expect(report.coverage.examined_entries).toBe(6 + 2 + 1 + 8192);
expect(JSON.stringify(report).length).toBeLessThan(2 * 1024 * 1024);
});