From 76117c04f3b6814dbf8d2615769865f8ea80a0a6 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 06:16:09 +0800 Subject: [PATCH] refactor(domain): give the Ghidra seed file format a domain owner shared with il2cpp (#11515) --- scripts/lib/module-layers.baseline.json | 1 - src/domain/native/ghidraSeedFile.ts | 112 ++++++++++++++++++ src/ghidra/GhidraAnalysisSeeds.test.ts | 2 +- src/ghidra/GhidraAnalysisSeeds.ts | 107 ++--------------- src/il2cpp/Il2cppGhidraSeeds.ts | 10 +- .../ghidraProfileArtifactOwnership.test.ts | 2 +- .../boundary/il2cpp/il2cppGhidraSeeds.test.ts | 2 +- 7 files changed, 132 insertions(+), 104 deletions(-) create mode 100644 src/domain/native/ghidraSeedFile.ts diff --git a/scripts/lib/module-layers.baseline.json b/scripts/lib/module-layers.baseline.json index 67f20e9dec..af8f0e395b 100644 --- a/scripts/lib/module-layers.baseline.json +++ b/scripts/lib/module-layers.baseline.json @@ -22,7 +22,6 @@ "desktop -> electron": 1, "flutter -> artifacts": 1, "gpu -> artifacts": 2, - "il2cpp -> ghidra": 1, "model -> artifacts": 1, "native -> artifacts": 2 }, diff --git a/src/domain/native/ghidraSeedFile.ts b/src/domain/native/ghidraSeedFile.ts new file mode 100644 index 0000000000..85d2db1289 --- /dev/null +++ b/src/domain/native/ghidraSeedFile.ts @@ -0,0 +1,112 @@ +import { ConfigurationError } from "../configurationErrors.js"; +import { err, ok, type Result } from "../result.js"; + +/** + * The `REA_GHIDRA_SEED_FILE` text format: `addresskind[name]` + * lines that Ghidra applies before analysis. il2cpp writes these files and + * the Ghidra provider reads them, so the format and its limits live here. + */ +export const MAX_GHIDRA_SEED_BYTES = 32 * 1024 * 1024; +export const MAX_GHIDRA_SEED_ENTRIES = 1_000_000; +export const MAX_GHIDRA_SEED_NAME_LENGTH = 2000; + +export type GhidraSeedKind = "function" | "code" | "label"; +export interface GhidraSeedEntry { + readonly address: bigint; + readonly kind: GhidraSeedKind; + readonly name?: string; +} + +/** A configuration error naming one seed file line. */ +export const ghidraSeedLineError = (line: number, constraint: string) => + new ConfigurationError("Invalid REA environment configuration", { + settings: [ + { + setting: "REA_GHIDRA_SEED_FILE", + constraint: `line ${line}: ${constraint}`, + }, + ], + }); + +/** + * Parse `addresskind[name]` lines. Blank lines and `#` comments are + * ignored. Addresses are hexadecimal offsets in the default address space. + */ +export const parseGhidraSeeds = ( + text: string, +): Result => { + const entries: GhidraSeedEntry[] = []; + const seen = new Set(); + const lines = text.split("\n"); + for (const [index, raw] of lines.entries()) { + const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw; + if (line.trim() === "" || line.startsWith("#")) continue; + const number = index + 1; + const fields = line.split("\t"); + if (fields.length < 2 || fields.length > 3) + return err( + ghidraSeedLineError(number, "expected addresskind[name]"), + ); + const [address, kind, name] = fields; + if (address === undefined || !/^0x[0-9a-fA-F]{1,16}$/u.test(address)) + return err( + ghidraSeedLineError(number, "address must be 0x-prefixed hex"), + ); + if (kind !== "function" && kind !== "code" && kind !== "label") + return err( + ghidraSeedLineError(number, "kind must be function, code or label"), + ); + if ( + name !== undefined && + (name.length === 0 || + name.length > MAX_GHIDRA_SEED_NAME_LENGTH || + /[\s\0]/u.test(name)) + ) + return err( + ghidraSeedLineError( + number, + `name must be 1..${MAX_GHIDRA_SEED_NAME_LENGTH} characters without whitespace`, + ), + ); + if (kind === "label" && name === undefined) + return err(ghidraSeedLineError(number, "a label seed requires a name")); + if (kind === "code" && name !== undefined) + return err( + ghidraSeedLineError( + number, + "a code seed takes no name; add a label seed", + ), + ); + const value = BigInt(address); + const key = `${value.toString(16)}:${kind}`; + if (seen.has(key)) + return err( + ghidraSeedLineError(number, `duplicate ${kind} seed at ${address}`), + ); + seen.add(key); + entries.push({ + address: value, + kind, + ...(name === undefined ? {} : { name }), + }); + if (entries.length > MAX_GHIDRA_SEED_ENTRIES) + return err( + ghidraSeedLineError( + number, + `more than ${MAX_GHIDRA_SEED_ENTRIES} seed entries`, + ), + ); + } + return ok(entries); +}; + +/** Canonical script input: lowercase addresses, fixed field order, LF endings. */ +export const normalizedGhidraSeeds = ( + entries: readonly GhidraSeedEntry[], +): string => + entries + .map( + (entry) => + `0x${entry.address.toString(16)}\t${entry.kind}${entry.name === undefined ? "" : `\t${entry.name}`}\n`, + ) + .join(""); diff --git a/src/ghidra/GhidraAnalysisSeeds.test.ts b/src/ghidra/GhidraAnalysisSeeds.test.ts index 9590dcd830..a5e3f0b97a 100644 --- a/src/ghidra/GhidraAnalysisSeeds.test.ts +++ b/src/ghidra/GhidraAnalysisSeeds.test.ts @@ -25,7 +25,6 @@ import { ghidraSeedFailure, ghidraSeedReportSchema, ghidraSeedLimitations, - parseGhidraSeeds, resolveGhidraAnalysisSeeds, snapshotGhidraAnalysisSeeds, type GhidraSeedCommitment, @@ -33,6 +32,7 @@ import { } from "./GhidraAnalysisSeeds.js"; import { ghidraProfileInstallationHost as host } from "./GhidraInstallation.fixture.js"; import { GhidraProvider } from "./GhidraProvider.js"; +import { parseGhidraSeeds } from "../domain/native/ghidraSeedFile.js"; const directories: string[] = []; let resources = new ArtifactResourceScope(); diff --git a/src/ghidra/GhidraAnalysisSeeds.ts b/src/ghidra/GhidraAnalysisSeeds.ts index 876544ea1f..c05d5157c6 100644 --- a/src/ghidra/GhidraAnalysisSeeds.ts +++ b/src/ghidra/GhidraAnalysisSeeds.ts @@ -17,12 +17,16 @@ import { import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; import { err, ok, type Result } from "../domain/result.js"; import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; +import { + MAX_GHIDRA_SEED_BYTES, + normalizedGhidraSeeds, + parseGhidraSeeds, + ghidraSeedLineError, + type GhidraSeedEntry, +} from "../domain/native/ghidraSeedFile.js"; /** Seed file format admitted by this adapter. */ export const GHIDRA_SEED_FORMAT = "rea-ghidra-seeds-v1"; -export const MAX_GHIDRA_SEED_BYTES = 32 * 1024 * 1024; -export const MAX_GHIDRA_SEED_ENTRIES = 1_000_000; -export const MAX_GHIDRA_SEED_NAME_LENGTH = 2000; const digest = z.string().regex(/^[a-f0-9]{64}$/u); const count = z.int().nonnegative(); @@ -67,93 +71,6 @@ export const ghidraSeedReportSchema = z ); export type GhidraSeedReport = z.infer; -type SeedKind = "function" | "code" | "label"; -interface SeedEntry { - readonly address: bigint; - readonly kind: SeedKind; - readonly name?: string; -} - -const seedLineError = (line: number, constraint: string) => - new ConfigurationError("Invalid REA environment configuration", { - settings: [ - { - setting: "REA_GHIDRA_SEED_FILE", - constraint: `line ${line}: ${constraint}`, - }, - ], - }); - -/** - * Parse `addresskind[name]` lines. Blank lines and `#` comments are - * ignored. Addresses are hexadecimal offsets in the default address space. - */ -export const parseGhidraSeeds = ( - text: string, -): Result => { - const entries: SeedEntry[] = []; - const seen = new Set(); - const lines = text.split("\n"); - for (const [index, raw] of lines.entries()) { - const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw; - if (line.trim() === "" || line.startsWith("#")) continue; - const number = index + 1; - const fields = line.split("\t"); - if (fields.length < 2 || fields.length > 3) - return err(seedLineError(number, "expected addresskind[name]")); - const [address, kind, name] = fields; - if (address === undefined || !/^0x[0-9a-fA-F]{1,16}$/u.test(address)) - return err(seedLineError(number, "address must be 0x-prefixed hex")); - if (kind !== "function" && kind !== "code" && kind !== "label") - return err(seedLineError(number, "kind must be function, code or label")); - if ( - name !== undefined && - (name.length === 0 || - name.length > MAX_GHIDRA_SEED_NAME_LENGTH || - /[\s\0]/u.test(name)) - ) - return err( - seedLineError( - number, - `name must be 1..${MAX_GHIDRA_SEED_NAME_LENGTH} characters without whitespace`, - ), - ); - if (kind === "label" && name === undefined) - return err(seedLineError(number, "a label seed requires a name")); - if (kind === "code" && name !== undefined) - return err( - seedLineError(number, "a code seed takes no name; add a label seed"), - ); - const value = BigInt(address); - const key = `${value.toString(16)}:${kind}`; - if (seen.has(key)) - return err(seedLineError(number, `duplicate ${kind} seed at ${address}`)); - seen.add(key); - entries.push({ - address: value, - kind, - ...(name === undefined ? {} : { name }), - }); - if (entries.length > MAX_GHIDRA_SEED_ENTRIES) - return err( - seedLineError( - number, - `more than ${MAX_GHIDRA_SEED_ENTRIES} seed entries`, - ), - ); - } - return ok(entries); -}; - -/** Canonical script input: lowercase addresses, fixed field order, LF endings. */ -const normalizedSeeds = (entries: readonly SeedEntry[]): string => - entries - .map( - (entry) => - `0x${entry.address.toString(16)}\t${entry.kind}${entry.name === undefined ? "" : `\t${entry.name}`}\n`, - ) - .join(""); - const sha256 = (bytes: Buffer | string): string => createHash("sha256").update(bytes).digest("hex"); @@ -162,7 +79,7 @@ const readSeeds = ( path: string, resources: ArtifactResourceScope, signal?: AbortSignal, -): Promise => +): Promise => readGhidraProfileArtifact( path, MAX_GHIDRA_SEED_BYTES, @@ -174,7 +91,7 @@ const readSeeds = ( // A user-authored seed file may start with a BOM signature. text = decodeStrictUtf8(bytes, "strip-signature"); } catch { - throw seedLineError(0, "file is not valid UTF-8"); + throw ghidraSeedLineError(0, "file is not valid UTF-8"); } const parsed = parseGhidraSeeds(text); if (!parsed.ok) throw parsed.error; @@ -200,7 +117,7 @@ export const resolveGhidraAnalysisSeeds = async ( resources .run(async () => { if (configured === undefined) return ok(undefined); - let entries: readonly SeedEntry[]; + let entries: readonly GhidraSeedEntry[]; let path: string; try { path = await resolveSeedPath(configured); @@ -213,7 +130,7 @@ export const resolveGhidraAnalysisSeeds = async ( }), ); } - const normalized = normalizedSeeds(entries); + const normalized = normalizedGhidraSeeds(entries); const tally = { function: 0, code: 0, label: 0 }; for (const entry of entries) tally[entry.kind] += 1; return ok({ @@ -247,7 +164,7 @@ export const snapshotGhidraAnalysisSeeds = async ( ) throw new GhidraAdmissionError("seed_path_differs"); const entries = await readSeeds(commitment.path, resources, signal); - const normalized = normalizedSeeds(entries); + const normalized = normalizedGhidraSeeds(entries); if (sha256(normalized) !== commitment.sha256) throw new GhidraAdmissionError("seed_changed", { path: commitment.path, diff --git a/src/il2cpp/Il2cppGhidraSeeds.ts b/src/il2cpp/Il2cppGhidraSeeds.ts index e20b2d7feb..9f2a24b1b0 100644 --- a/src/il2cpp/Il2cppGhidraSeeds.ts +++ b/src/il2cpp/Il2cppGhidraSeeds.ts @@ -1,8 +1,3 @@ -import { - MAX_GHIDRA_SEED_BYTES, - MAX_GHIDRA_SEED_ENTRIES, - MAX_GHIDRA_SEED_NAME_LENGTH, -} from "../ghidra/GhidraAnalysisSeeds.js"; import { AnalysisInputError, AnalysisResourceConstraintError, @@ -26,6 +21,11 @@ const capacity = ( fixedAllowanceOptions(allowance, kind), ); 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 { diff --git a/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts b/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts index 11b8c973a1..cf9ed91d9c 100644 --- a/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts +++ b/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts @@ -21,13 +21,13 @@ import { parseConfig } from "../../../src/config/parseConfig.js"; import { resolveGhidraAnalysisSeeds, snapshotGhidraAnalysisSeeds, - MAX_GHIDRA_SEED_BYTES, } from "../../../src/ghidra/GhidraAnalysisSeeds.js"; import { resolveGhidraExtensions, snapshotGhidraExtensions, } from "../../../src/ghidra/extensions/GhidraExtensions.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { MAX_GHIDRA_SEED_BYTES } from "../../../src/domain/native/ghidraSeedFile.js"; const controls = vi.hoisted(() => ({ realpath: undefined as ((path: string) => Promise) | undefined, diff --git a/tests/boundary/il2cpp/il2cppGhidraSeeds.test.ts b/tests/boundary/il2cpp/il2cppGhidraSeeds.test.ts index 887c1cca83..b86fe5c753 100644 --- a/tests/boundary/il2cpp/il2cppGhidraSeeds.test.ts +++ b/tests/boundary/il2cpp/il2cppGhidraSeeds.test.ts @@ -3,7 +3,6 @@ import { AnalysisResourceConstraintError, } from "../../../src/domain/analysisErrorCore.js"; import { expect, it } from "vitest"; -import { parseGhidraSeeds } from "../../../src/ghidra/GhidraAnalysisSeeds.js"; import { ghidraDefaultBase, il2cppGhidraSeeds, @@ -14,6 +13,7 @@ import { type Il2cppMetadata, } from "../../../src/domain/il2cpp/il2cppMetadata.js"; import { analysisErrorRemediationAction } from "../../../src/domain/analysisErrorPresentation.js"; +import { parseGhidraSeeds } from "../../../src/domain/native/ghidraSeedFile.js"; const type = ( name: string,