mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
refactor(domain): give the Ghidra seed file format a domain owner shared with il2cpp (#11515)
This commit is contained in:
1 parent
062b3835f9
commit
76117c04f3
7 files changed
+132
-104
No files matched your search
@@ -22,7 +22,6 @@
|
||||
"desktop -> electron": 1,
|
||||
"flutter -> artifacts": 1,
|
||||
"gpu -> artifacts": 2,
|
||||
"il2cpp -> ghidra": 1,
|
||||
"model -> artifacts": 1,
|
||||
"native -> artifacts": 2
|
||||
},
|
||||
|
||||
@@ -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("");
|
||||
@@ -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();
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in new issue
Block a user