refactor(domain): give the Ghidra seed file format a domain owner shared with il2cpp (#11515)

This commit is contained in:
morluto authored and GitHub committed 2026-11-16 06:16:09 +08:00
1 parent 062b3835f9
commit 76117c04f3
7 files changed
+132 -104

No files matched your search

-1
View File
@@ -22,7 +22,6 @@
"desktop -> electron": 1,
"flutter -> artifacts": 1,
"gpu -> artifacts": 2,
"il2cpp -> ghidra": 1,
"model -> artifacts": 1,
"native -> artifacts": 2
},
+112
View File
@@ -0,0 +1,112 @@
import { ConfigurationError } from "../configurationErrors.js";
import { err, ok, type Result } from "../result.js";
/**
* The `REA_GHIDRA_SEED_FILE` text format: `address<TAB>kind[<TAB>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 `address<TAB>kind[<TAB>name]` lines. Blank lines and `#` comments are
* ignored. Addresses are hexadecimal offsets in the default address space.
*/
export const parseGhidraSeeds = (
text: string,
): Result<readonly GhidraSeedEntry[], ConfigurationError> => {
const entries: GhidraSeedEntry[] = [];
const seen = new Set<string>();
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 address<TAB>kind[<TAB>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("");
+1 -1
View File
@@ -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();
+12 -95
View File
@@ -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<typeof ghidraSeedReportSchema>;
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 `address<TAB>kind[<TAB>name]` lines. Blank lines and `#` comments are
* ignored. Addresses are hexadecimal offsets in the default address space.
*/
export const parseGhidraSeeds = (
text: string,
): Result<readonly SeedEntry[], ConfigurationError> => {
const entries: SeedEntry[] = [];
const seen = new Set<string>();
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 address<TAB>kind[<TAB>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<readonly SeedEntry[]> =>
): Promise<readonly GhidraSeedEntry[]> =>
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<GhidraSeedCommitment>({
@@ -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,
+5 -5
View File
@@ -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 {
@@ -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<void>) | undefined,
@@ -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,