Files
reverse-engineering-anything/src/il2cpp/Il2cppGhidraSeeds.ts
T
morluto 680c83f88c feat(errors): carry the value of Go, Rust, IL2CPP, sigrok, Electron fuse, CDP, projection and assetutil allowances (#11645)
Each of these fixed allowances now passes limit and unit, traced to the constant or parse refusal that produced it. The Electron fuse, CDP runtime retention and assetutil names no longer embed the value.
2026-11-16 09:40:58 +08:00

274 lines
9.2 KiB
TypeScript

import {
AnalysisInputError,
AnalysisResourceConstraintError,
} from "../domain/analysisErrorCore.js";
import {
fixedAllowanceOptions,
type FixedAllowance,
} from "../domain/fixedAllowanceRemediation.js";
const OPERATION = "inspect_il2cpp_metadata";
/** Each Ghidra seed admission ceiling, with the value that refuses a seed. */
const SEED_ALLOWANCES = {
name: {
name: "The IL2CPP Ghidra seed-name allowance",
kind: "count",
limit: MAX_GHIDRA_SEED_NAME_LENGTH,
unit: "characters",
},
file: {
name: "The IL2CPP Ghidra seed-file allowance",
kind: "bytes",
limit: MAX_GHIDRA_SEED_BYTES,
unit: "bytes",
},
entry: {
name: "The IL2CPP Ghidra seed-entry allowance",
kind: "count",
limit: MAX_GHIDRA_SEED_ENTRIES,
unit: "entries",
},
} as const satisfies Record<string, FixedAllowance>;
const capacity = (message: string, allowance: keyof typeof SEED_ALLOWANCES) => {
const { name, kind, limit, unit } = SEED_ALLOWANCES[allowance];
return new AnalysisResourceConstraintError(
OPERATION,
"capacity",
message,
{
maximum_seed_bytes: MAX_GHIDRA_SEED_BYTES,
maximum_seed_entries: MAX_GHIDRA_SEED_ENTRIES,
maximum_seed_name_characters: MAX_GHIDRA_SEED_NAME_LENGTH,
},
fixedAllowanceOptions(name, kind, { limit, unit }),
);
};
import type { Il2cppMetadata } from "../domain/il2cpp/il2cppMetadata.js";
import {
MAX_GHIDRA_SEED_BYTES,
MAX_GHIDRA_SEED_ENTRIES,
MAX_GHIDRA_SEED_NAME_LENGTH,
} from "../domain/native/ghidraSeedFile.js";
/** A linked metadata report reduced to Ghidra function seeds. */
export interface Il2cppGhidraSeeds {
/** `address<TAB>function<TAB>name` lines in the REA_GHIDRA_SEED_FILE format. */
readonly text: string;
readonly functions: number;
/** Methods whose code address another method already seeded (identical code folding). */
readonly folded: number;
/** Each folded address with the name its function seed kept and the names it shares. */
readonly folded_groups: readonly {
readonly address: string;
readonly kept: string;
readonly also: readonly string[];
}[];
/** Methods without native code: abstract, interface, or generic definitions. */
readonly without_address: number;
readonly no_body: number;
readonly unknown: number;
/** Generic instance rows seeded or folded; null when the report did not link them. */
readonly generic_instances: number | null;
/** Generic instance rows left unseeded (no code or no name); null as above. */
readonly generic_without_seed: number | null;
}
/**
* Where Ghidra's default loaders place the binary: an ELF linked at 0 goes to
* 0x100000, while Mach-O and PE images keep their link base.
*/
export const ghidraDefaultBase = (
binary: NonNullable<Il2cppMetadata["binary"]>,
): bigint => {
const linked = BigInt(binary.image_base);
return binary.format === "elf" && linked === 0n ? 0x100000n : linked;
};
/** `Namespace.Outer.Inner` for a type, following declaring_type to the outermost type. */
const typeName = (report: Il2cppMetadata, index: number): string => {
const parts: string[] = [];
let namespace = "";
const seen = new Set<number>();
let length = 0;
for (let at = index; at !== -1;) {
if (seen.has(at))
throw new AnalysisInputError(OPERATION, undefined, [
{
path: ["types", at],
reason: "invalid_format",
message: "Cyclic type ancestry cannot name a seed.",
},
]);
seen.add(at);
const type = report.types[at];
if (type === undefined)
throw new AnalysisInputError(OPERATION, undefined, [
{
path: ["types", at],
reason: "invalid_format",
message: "Seed type owner is unavailable.",
},
]);
length += type.name.length + 1;
if (length > MAX_GHIDRA_SEED_NAME_LENGTH)
throw capacity(
"Qualified seed type name exceeds the Ghidra name limit.",
"name",
);
parts.unshift(type.name);
namespace = type.namespace;
if (length + namespace.length > MAX_GHIDRA_SEED_NAME_LENGTH)
throw capacity(
"Qualified seed type name exceeds the Ghidra name limit.",
"name",
);
at = type.declaring_type;
}
return namespace === "" ? parts.join(".") : `${namespace}.${parts.join(".")}`;
};
/**
* Name every linked method `Type$$Method`, the Il2CppDumper convention, at
* `base + rva`. Whitespace becomes `_` because seed names cannot contain it.
* The first method at an address names its function, since a seed file holds
* one function seed per address. The other methods at that address are listed
* in `#` comment lines after the seeds, so a reader of the file or the
* decompilation can see that the kept name is one of several.
*/
export const il2cppGhidraSeeds = (
report: Il2cppMetadata,
base: bigint,
): Il2cppGhidraSeeds => {
if (report.binary === null)
throw new AnalysisInputError(OPERATION, undefined, [
{
path: ["binary_path"],
reason: "invalid_value",
message: "Ghidra seeds need a report linked with binary_path.",
},
]);
const seeded = new Map<bigint, { kept: string; also: string[] }>();
const lines: string[] = [];
let folded = 0;
let withoutAddress = 0,
noBody = 0,
unknown = 0,
bytes = 0;
const typeNames = new Map<number, string>();
const reserve = (length: number) => {
if (length > MAX_GHIDRA_SEED_BYTES - bytes)
throw capacity("Seed file exceeds Ghidra byte admission.", "file");
bytes += length;
};
const emit = (text: string) => {
reserve(Buffer.byteLength(text));
lines.push(text);
};
/** Seed `name` at base + rva, or fold it under the name already there. */
const seed = (rva: string, raw: string, path: (string | number)[]) => {
const address = base + BigInt(rva);
if (address < 0n || address > 0xffffffffffffffffn)
throw new AnalysisInputError(OPERATION, undefined, [
{
path: ["seed_base"],
reason: "invalid_value",
message: "Rebased seed address exceeds 64 bits.",
},
]);
if (raw.length > MAX_GHIDRA_SEED_NAME_LENGTH)
throw capacity(
"Qualified method seed name exceeds Ghidra character admission.",
"name",
);
const name = raw.replace(/\s/gu, "_");
if (name.includes("\0"))
throw new AnalysisInputError(OPERATION, undefined, [
{
path,
reason: "invalid_format",
message: "Seed names cannot contain NUL.",
},
]);
const group = seeded.get(address);
if (group !== undefined) {
folded++;
if (group.also.length === 0)
reserve(
Buffer.byteLength(
`# folded 0x${address.toString(16)} ${group.kept} also\n`,
),
);
reserve(Buffer.byteLength(` ${name}`));
group.also.push(name);
return;
}
seeded.set(address, { kept: name, also: [] });
if (seeded.size > MAX_GHIDRA_SEED_ENTRIES)
throw capacity(
"Seed function count exceeds Ghidra entry admission.",
"entry",
);
emit(`0x${address.toString(16)}\tfunction\t${name}\n`);
};
report.methods.forEach((method, index) => {
const rva = report.method_addresses[index]?.rva ?? null;
if (rva === null) {
withoutAddress++;
if (report.method_addresses[index]?.state === "no-body") noBody++;
else unknown++;
return;
}
let ownerName = typeNames.get(method.declaring_type);
if (ownerName === undefined) {
ownerName = typeName(report, method.declaring_type);
typeNames.set(method.declaring_type, ownerName);
}
if (ownerName.length + 2 + method.name.length > MAX_GHIDRA_SEED_NAME_LENGTH)
throw capacity(
"Qualified method seed name exceeds Ghidra character admission.",
"name",
);
seed(rva, `${ownerName}$$${method.name}`, ["methods", index, "name"]);
});
// Generic instances follow the definitions, so an instance sharing a
// definition's code is folded under the definition's name.
let genericInstances = 0,
genericWithoutSeed = 0;
report.generic_method_instances?.forEach((row, index) => {
if (row.rva === null || row.name === null) {
genericWithoutSeed++;
return;
}
genericInstances++;
seed(row.rva, row.name, ["generic_method_instances", index, "name"]);
});
const foldedGroups = [...seeded]
.filter(([, group]) => group.also.length > 0)
.map(([address, group]) => ({
address: `0x${address.toString(16)}`,
kept: group.kept,
also: group.also,
}));
for (const group of foldedGroups) {
lines.push(`# folded ${group.address} ${group.kept} also`);
for (const name of group.also) lines.push(` ${name}`);
lines.push("\n");
}
emit(
`# metadata_sha256 ${report.artifact.sha256}\n# binary_sha256 ${report.binary.artifact.sha256}\n# link_base ${report.binary.image_base}\n# seed_base 0x${base.toString(16)}\n`,
);
return {
text: lines.join(""),
functions: seeded.size,
folded,
folded_groups: foldedGroups,
without_address: withoutAddress,
no_body: noBody,
unknown,
generic_instances:
report.generic_method_instances == null ? null : genericInstances,
generic_without_seed:
report.generic_method_instances == null ? null : genericWithoutSeed,
};
};