mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 05:32:44 +00:00
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:
5 files changed
+125
-43
No files matched your search
@@ -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
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
@@ -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],
|
||||
};
|
||||
};
|
||||
@@ -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 }) => {
|
||||
|
||||
Reference in new issue
Block a user