From a21a5db09dbaaa7961a12d0947ffc4f0de91d8cb Mon Sep 17 00:00:00 2001 From: ShuaixinHuang <1836656514@qq.com> Date: Thu, 19 Nov 2026 20:15:01 +0800 Subject: [PATCH] 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> --- docs/erlang-beam.md | 5 ++ src/domain/erlang/beam.ts | 2 +- src/erlang/BeamParser.test.ts | 26 +++++++ src/erlang/BeamParser.ts | 101 +++++++++++++++---------- tests/acceptance/erlangBeamCli.test.ts | 34 +++++++++ 5 files changed, 125 insertions(+), 43 deletions(-) diff --git a/docs/erlang-beam.md b/docs/erlang-beam.md index e697db5c79..309aac655c 100644 --- a/docs/erlang-beam.md +++ b/docs/erlang-beam.md @@ -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 diff --git a/src/domain/erlang/beam.ts b/src/domain/erlang/beam.ts index 11ba6e5663..5bd4bf27d6 100644 --- a/src/domain/erlang/beam.ts +++ b/src/domain/erlang/beam.ts @@ -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, diff --git a/src/erlang/BeamParser.test.ts b/src/erlang/BeamParser.test.ts index 83acf8dcf5..de722942af 100644 --- a/src/erlang/BeamParser.test.ts +++ b/src/erlang/BeamParser.test.ts @@ -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]); + }, +); diff --git a/src/erlang/BeamParser.ts b/src/erlang/BeamParser.ts index 0e897f79a4..74ee22a2d8 100644 --- a/src/erlang/BeamParser.ts +++ b/src/erlang/BeamParser.ts @@ -123,7 +123,10 @@ const parseAtoms = ( payload: Buffer, maxAtoms: number, format: "Atom" | "AtU8", -): ErlangBeam["atoms"] => { +): { + readonly atoms: NonNullable; + 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): 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], }; }; diff --git a/tests/acceptance/erlangBeamCli.test.ts b/tests/acceptance/erlangBeamCli.test.ts index 421f230677..ef9add7ff3 100644 --- a/tests/acceptance/erlangBeamCli.test.ts +++ b/tests/acceptance/erlangBeamCli.test.ts @@ -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 }) => {