fix(erlang): report unexamined BEAM table tails (#12267)

* fix(erlang): report unexamined BEAM table tails

* refactor(erlang): own coverage in BEAM table framing

---------

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-19 12:15:01 +00:00
1 parent 9bf500016b
commit a21a5db09d
5 files changed
+125 -43

No files matched your search

+5
View File
@@ -31,6 +31,11 @@ The BEAM form size bounds the parsed chunks. Bytes after the form remain part
of the artifact's byte length and SHA-256. They are unexamined by the chunk
reader, so the report sets `coverage.status` to `partial` and gives their exact
count in `coverage.trailing_bytes`. Older retained Evidence may omit the count.
When a selected atom, export, import, or lambda table has bytes left after its
declared entries, coverage is also `partial`. A limitation names the table and
counts its unexamined bytes. The report retains the decoded entries and the
full chunk range. `coverage.trailing_bytes` counts only bytes outside the FOR1
form, so it can be zero when a table leaves bytes unexamined.
When a selected `AtU8` or `Atom` table is decoded, `atoms` is the 1-based name table and
`module` is atom 1. Both the pre-OTP 28 table and the OTP 28+ compact table
+1 -1
View File
@@ -118,7 +118,7 @@ export const erlangBeamSchema = z.strictObject({
.nullable(),
module: z.string().nullable(),
coverage: z.strictObject({
// "partial" when bytes trail the declared FOR1 form and go unexamined.
// "partial" when bytes trail the declared FOR1 form or a decoded table.
status: knownCoverageStatusSchema,
examined_chunks: uint,
atoms: uint,
+26
View File
@@ -447,3 +447,29 @@ it.each([
}
},
);
it.each([
["Atom", Buffer.from([0, 0, 0, 1, 1, 0x61])],
["AtU8", Buffer.from([0, 0, 0, 1, 1, 0x61])],
["AtU8", Buffer.from([0xff, 0xff, 0xff, 0xff, 0x10, 0x61])],
["ExpT", Buffer.alloc(4)],
["ImpT", Buffer.alloc(4)],
["FunT", Buffer.alloc(4)],
] as const)(
"reports unexamined bytes inside a selected %s table",
(name, payload) => {
const control = parse(erlangBeamChunksFixture([[name, payload]]));
const extended = Buffer.concat([payload, Buffer.from([0x61])]);
const report = parse(erlangBeamChunksFixture([[name, extended]]));
expect(control.coverage.status).toBe("complete");
expect(report.coverage).toMatchObject({
status: "partial",
trailing_bytes: 0,
});
expect(report.limitations).toContain(
`The selected ${name} table has 1 trailing byte that was not examined.`,
);
for (const field of ["atoms", "exports", "imports", "lambdas"] as const)
expect(report[field]).toEqual(control[field]);
},
);
+59 -42
View File
@@ -123,7 +123,10 @@ const parseAtoms = (
payload: Buffer,
maxAtoms: number,
format: "Atom" | "AtU8",
): ErlangBeam["atoms"] => {
): {
readonly atoms: NonNullable<ErlangBeam["atoms"]>;
readonly trailingBytes: number;
} => {
if (payload.length < 4) fail("BEAM atom table is truncated.");
// Only AtU8 supports OTP 28+'s negated count and compact name lengths.
// Historical Atom uses an unsigned count and single-byte lengths.
@@ -156,30 +159,30 @@ const parseAtoms = (
});
at += length;
}
if (at > payload.length) fail("BEAM atom table is truncated.");
return atoms;
return { atoms, trailingBytes: payload.length - at };
};
const tableCount = (payload: Buffer, width: number, label: string): number => {
const frameRows = (payload: Buffer, width: number, label: string) => {
if (payload.length < 4) fail(`BEAM ${label} table is truncated.`);
const count = new BinaryReader(payload, false, "beam").u32(0);
if (count > Math.floor((payload.length - 4) / (width * 4)))
fail(`BEAM ${label} table is truncated.`);
return count;
const reader = new BinaryReader(payload, false, "beam");
const count = reader.u32(0);
const rowBytes = width * 4;
const bytesRead = 4 + count * rowBytes;
if (bytesRead > payload.length) fail(`BEAM ${label} table is truncated.`);
return { reader, count, rowBytes, trailingBytes: payload.length - bytesRead };
};
const parseRows = (
payload: Buffer,
width: number,
count: number,
): number[][] => {
const reader = new BinaryReader(payload, false, "beam");
const parseRows = ({
reader,
count,
rowBytes,
}: ReturnType<typeof frameRows>): number[][] => {
const rows: number[][] = [];
for (let index = 0; index < count; index += 1) {
const row: number[] = [];
const start = 4 + index * width * 4;
for (let field = 0; field < width; field += 1)
row.push(reader.u32(start + field * 4));
const start = 4 + index * rowBytes;
for (let fieldOffset = 0; fieldOffset < rowBytes; fieldOffset += 4)
row.push(reader.u32(start + fieldOffset));
rows.push(row);
}
return rows;
@@ -275,28 +278,31 @@ export const parseErlangBeam = (
atomChunk === undefined ? null : useUtf8Atoms ? "AtU8" : "Atom";
const atomEncoding =
atomFormat === null ? null : atomFormat === "AtU8" ? "utf8" : "latin1";
const atoms =
const atomTable =
atomChunk === undefined || atomFormat === null
? null
: parseAtoms(atomChunk.payload, input.max_atoms, atomFormat);
const atoms = atomTable?.atoms ?? null;
const exportChunk = payloads.get("ExpT");
const importChunk = payloads.get("ImpT");
const lambdaChunk = payloads.get("FunT");
const exportCount =
const exportTable =
exportChunk === undefined
? 0
: tableCount(exportChunk.payload, 3, "export");
const importCount =
? null
: frameRows(exportChunk.payload, 3, "export");
const importTable =
importChunk === undefined
? 0
: tableCount(importChunk.payload, 3, "import");
? null
: frameRows(importChunk.payload, 3, "import");
// OTP skips the optional lambda parser for a zero-byte selected chunk.
const lambdaCount =
const lambdaTable =
lambdaChunk === undefined || lambdaChunk.payload.length === 0
? 0
: tableCount(lambdaChunk.payload, 6, "lambda");
? null
: frameRows(lambdaChunk.payload, 6, "lambda");
if (
exportCount + importCount + lambdaCount >
(exportTable?.count ?? 0) +
(importTable?.count ?? 0) +
(lambdaTable?.count ?? 0) >
MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS
)
throw new BeamCapacityFailure(
@@ -305,18 +311,18 @@ export const parseErlangBeam = (
`BEAM tables exceed the ${String(MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS)}-row budget.`,
);
const exports =
exportChunk === undefined
exportTable === null
? null
: parseRows(exportChunk.payload, 3, exportCount).map((row) => ({
: parseRows(exportTable).map((row) => ({
function_index: row[0]!,
function: atomAt(atoms, row[0]!),
arity: row[1]!,
label: row[2]!,
}));
const imports =
importChunk === undefined
importTable === null
? null
: parseRows(importChunk.payload, 3, importCount).map((row) => ({
: parseRows(importTable).map((row) => ({
module_index: row[0]!,
module: atomAt(atoms, row[0]!),
function_index: row[1]!,
@@ -325,9 +331,9 @@ export const parseErlangBeam = (
}));
// A four-byte zero count remains a decoded, explicitly empty table.
const lambdas =
lambdaChunk === undefined || lambdaChunk.payload.length === 0
lambdaTable === null
? null
: parseRows(lambdaChunk.payload, 6, lambdaCount).map((row) => ({
: parseRows(lambdaTable).map((row) => ({
function_index: row[0]!,
function: atomAt(atoms, row[0]!),
arity: row[1]!,
@@ -344,6 +350,23 @@ export const parseErlangBeam = (
// A conformant FOR1 form sizes itself to the file; any surplus bytes trail an
// unexamined region. Disclose them instead of reporting complete coverage.
const trailingBytes = bytes.length - formEnd;
const unexamined: string[] = [];
if (trailingBytes > 0)
unexamined.push(
`The declared FOR1 form ends at offset ${String(formEnd)}; ${String(trailingBytes)} trailing ${trailingBytes === 1 ? "byte was" : "bytes were"} not examined.`,
);
const tableTails = [
[atomFormat, atomTable?.trailingBytes ?? 0],
["ExpT", exportTable?.trailingBytes ?? 0],
["ImpT", importTable?.trailingBytes ?? 0],
["FunT", lambdaTable?.trailingBytes ?? 0],
] as const;
for (const [name, extra] of tableTails) {
if (extra > 0)
unexamined.push(
`The selected ${name} table has ${String(extra)} trailing ${extra === 1 ? "byte that was" : "bytes that were"} not examined.`,
);
}
return {
artifact,
form: { location: { offset: 0, bytes: formEnd }, size: formSize },
@@ -356,17 +379,11 @@ export const parseErlangBeam = (
code,
module: atoms?.[0]?.name ?? null,
coverage: {
status: trailingBytes > 0 ? "partial" : "complete",
status: unexamined.length > 0 ? "partial" : "complete",
examined_chunks: chunks.length,
atoms: atoms?.length ?? 0,
trailing_bytes: trailingBytes,
},
limitations:
trailingBytes > 0
? [
...LIMITATIONS,
`The declared FOR1 form ends at offset ${String(formEnd)}; ${String(trailingBytes)} trailing ${trailingBytes === 1 ? "byte was" : "bytes were"} not examined.`,
]
: [...LIMITATIONS],
limitations: [...LIMITATIONS, ...unexamined],
};
};
+34
View File
@@ -365,6 +365,40 @@ cliTest(
},
);
cliTest(
"reports a selected BEAM table tail through CLI and MCP",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-beam-table-tail-");
const path = join(root, "table-tail.beam");
const bytes = oneAtomBeam(0xab);
// Move one byte of alignment padding into the AtU8 payload.
bytes.writeUInt32BE(7, 16);
await writeFile(path, bytes);
const result = await cli.run({
arguments: ["inspect-erlang-beam", path, "--json"],
});
expect(result.exitCode, result.stderr).toBe(0);
const report = completeBeamEvidenceSchema.parse(
result.json,
).normalized_result;
expect(report).toMatchObject({
module: "m",
chunks: [{ name: "AtU8", payload: { location: { bytes: 7 } } }],
coverage: { status: "partial", trailing_bytes: 0 },
});
expect(report.limitations).toContain(
"The selected AtU8 table has 1 trailing byte that was not examined.",
);
const { call } = await connectLocalToolsMcp();
const reply = await call("inspect_erlang_beam", { path });
expect(reply.isError, JSON.stringify(reply)).not.toBe(true);
expect(
completeBeamEvidenceSchema.parse(reply.structuredContent)
.normalized_result,
).toEqual(report);
},
);
cliTest(
"inspects the declared BEAM form while retaining trailing bytes in artifact identity",
async ({ cli }) => {