* feat(ghidra): admit RISC-V ELF analysis through a pinned generic lane Refs #2063. Recognize `EM_RISCV` (243) as a provider-neutral family that carries its own ELF facts, and bound the first Ghidra lane to little-endian `ET_EXEC` images that declare the double-float ABI, pinned to `RISCV:LE:32:default` or `RISCV:LE:64:default` with the `gcc` compiler specification. Ghidra 12.1.4 is not reliable without the pin: its `riscv.opinion` pins `variant="default"` for the 64-bit constraint and leaves the 32-bit constraint with the comment that the loader "must choose between 'default' and 'AndeStar' variants". Measured on the installed release tree, a source-owned generic RV32 ELF with no Andes declaration imports as `RISCV:LE:32:AndeStar_v5:gcc`, while RV64 resolves to `RISCV:LE:64:default:gcc`. The lane therefore states the language per width and refuses any caller-selected processor outside it instead of inheriting the header guess. Refusals name the declaration rather than falling back to a guessed profile: big-endian images (Ghidra 12.1.4 ships no big-endian RISC-V language), non-`ET_EXEC` images, `EF_RISCV_RVE`, `EF_RISCV_TSO`, and every float ABI other than double, which the pinned generic compiler specifications model. The raw e_flags bits stay in Evidence as declarations, not as instruction semantics. Family recognition now has one owner for the ELF-metadata families: `ELF_METADATA_ARCHITECTURES`, `isElfMetadataArchitecture`, and `HeaderArchitecture` replace ten `Exclude<BinaryArchitecture, "mips">` sites that would each have needed a second hand-edited member. `ghidraPinnedLanguage` is that owner for the import commitment: the session readback previously re-derived only the MIPS pin, so a profile committing any second pinned language failed with a language-mismatch error before the bridge started. Hopper and IDA refuse RISC-V by name, matching the MIPS wording. Caller-supplied raw-binary entry keeps its existing four-family list; this lane is ELF-header admission only. Verification on macOS 15.7.7 arm64, Node 24.18.0, Ghidra 12.1.4 PUBLIC and JDK 21.0.12.1, with the host decompiler built from the release sources for `os/mac_arm_64`: `npm run check` passes; `npm run test:fast` passes 396 test files; `npm run verify:test-discovery` discovers all 917 test files exactly once. Source-owned RV32 and RV64 double-float `ET_EXEC` fixtures complete `rea analyze --provider ghidra` and `rea decompile rea_riscv_entry`, committing `RISCV:LE:32:default` and `RISCV:LE:64:default` with `language_selection: provider-pinned-v1`; the soft-float RV64 shape is refused with the named float-ABI reason, and the full refusal matrix including the RV32 and width-mismatch shapes is covered by unit tests. No `verify:ghidra:riscv` lane script is included in this change; the runs above were performed manually against the installed engine. Fork pull requests receive no CI check runs, so the real-provider scope above is the evidence available for review. * fix(ghidra): bound the RISC-V lane by declared flags and document it Address review feedback on #2151. `e_flags` bits outside `EF_RISCV_RVC | EF_RISCV_FLOAT_ABI` are now refused with the offending value named, so a reserved or newer producer declaration cannot enter the verified generic lane by falling through the RVE, TSO and float-ABI checks. Admission reads `e_type` only, so the refusal text no longer calls `ET_EXEC` static: a fixed-address declaration does not establish static linkage, and `PT_INTERP` and dynamic dependencies are not inspected. The session records that boundary as a limitation rather than inferring a load model. Add `docs/ghidra-riscv.md` in the shape of the MIPS lane guide (admission boundary, refusal table, why the language is pinned per class, Evidence fields, and what the fixtures do not establish), and correct `docs/firmware-analysis.md`, which still told users that MIPS and RISC-V decompilation had not been added. Verification after the change: `npm run check` and `npm run docs:check` pass; the RISC-V module tests pass (17 lane cases plus 9 parser cases); on Ghidra 12.1.4 with JDK 21.0.12.1 the RV32 and RV64 double-float fixtures still analyze and decompile with `RISCV:LE:32:default` / `RISCV:LE:64:default` and `language_selection: provider-pinned-v1`, the soft-float fixture is still refused by name, and the new linkage limitation appears in the emitted Evidence. * fix(ghidra): align RISC-V pinning with admission Reuse the complete lane admission boundary when selecting a language, retain unsigned unsupported flag bits in diagnostics, and derive float ABI metadata from the source declaration. * test(ghidra): verify RISC-V CLI and MCP workflows Build source-owned RV32/RV64 fixtures with Clang and LLD, establish independent ELF and symbol facts with LLVM readelf, and verify real provider evidence, instruction bytes, calls, decompilation, schema projections, snapshot replay, refusal diagnostics, source immutability and cleanup. Verified on macOS ARM64 with Ghidra 12.1.4, JDK 21 and LLVM/LLD 23.1.2. Dynamic linkage, big-endian, Andes and RVE/TSO workflows remain unverified; ISA attributes are not inspected. --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
248 lines
7.9 KiB
TypeScript
248 lines
7.9 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
import { createReadStream } from "node:fs";
|
|
|
|
import type {
|
|
AnalysisProfileResolution,
|
|
ProviderIdentity,
|
|
} from "../application/AnalysisProvider.js";
|
|
import { createAnalysisProfile } from "../domain/analysisProfile.js";
|
|
import {
|
|
isMachOFormat,
|
|
isElfMetadataArchitecture,
|
|
type BinaryTarget,
|
|
type ElfMetadataArchitecture,
|
|
type HeaderArchitecture,
|
|
} from "../domain/binaryTargetTypes.js";
|
|
import {
|
|
AnalysisCancelledError,
|
|
AnalysisCapabilityUnavailableError,
|
|
} from "../domain/analysisErrorCore.js";
|
|
import { BinaryTargetError } from "../domain/configurationErrors.js";
|
|
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
|
|
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
|
|
import {
|
|
resolveHopperMachOImage,
|
|
type HopperMachOImage,
|
|
} from "./HopperMachOImage.js";
|
|
|
|
interface HopperProfileOptions {
|
|
readonly launcherPath: string;
|
|
readonly loaderArgsOverride: readonly string[];
|
|
readonly provider: ProviderIdentity;
|
|
readonly signal?: AbortSignal;
|
|
}
|
|
|
|
/** Resolve Hopper open semantics without placing its CLI flags in BinaryTarget. */
|
|
export const resolveHopperAnalysisProfile = async (
|
|
target: BinaryTarget,
|
|
options: HopperProfileOptions,
|
|
): Promise<Result<AnalysisProfileResolution, AnalysisError>> => {
|
|
if (target.kind !== "executable" && target.kind !== "database")
|
|
return ok({ profile: null });
|
|
let machoContainer: "thin" | "fat32" | "fat64" | undefined;
|
|
if (target.kind === "executable" && isMachOFormat(target.format)) {
|
|
const header = await readMachoMagic(target.path, options.signal);
|
|
if (!header.ok) return header;
|
|
machoContainer = [0xcafebabf, 0xbfbafeca].includes(header.value)
|
|
? "fat64"
|
|
: [0xcafebabe, 0xbebafeca].includes(header.value)
|
|
? "fat32"
|
|
: "thin";
|
|
}
|
|
let preparedImage: HopperMachOImage | undefined;
|
|
if (
|
|
target.kind === "executable" &&
|
|
machoContainer === "fat64" &&
|
|
options.loaderArgsOverride.length === 0
|
|
) {
|
|
const resolved = await resolveHopperMachOImage(target, options.signal);
|
|
if (!resolved.ok) return resolved;
|
|
preparedImage = resolved.value;
|
|
}
|
|
const derived = hopperLoaderArgsForTarget(
|
|
target,
|
|
preparedImage === undefined ? machoContainer : "thin",
|
|
);
|
|
if (!derived.ok) return derived;
|
|
const loaderArgs =
|
|
options.loaderArgsOverride.length === 0
|
|
? derived.value
|
|
: [...options.loaderArgsOverride];
|
|
const launcherDigest = await sha256File(options.launcherPath, options.signal);
|
|
if (!launcherDigest.ok) return launcherDigest;
|
|
if (launcherDigest.value === undefined) return ok({ profile: null });
|
|
const provider = {
|
|
id: options.provider.id,
|
|
name: options.provider.name,
|
|
version: `launcher-sha256:${launcherDigest.value}`,
|
|
};
|
|
return ok({
|
|
profile: createAnalysisProfile(provider, {
|
|
target_kind: target.kind,
|
|
target_format: target.format,
|
|
architecture: target.architecture ?? null,
|
|
available_architectures: [
|
|
...(target.availableArchitectures ?? []),
|
|
].sort(),
|
|
...(machoContainer === undefined
|
|
? {}
|
|
: { macho_container: machoContainer }),
|
|
...(preparedImage === undefined
|
|
? {}
|
|
: { prepared_image: { ...preparedImage } }),
|
|
loader: {
|
|
source:
|
|
options.loaderArgsOverride.length === 0
|
|
? "derived"
|
|
: "configured_override",
|
|
arguments: [...loaderArgs],
|
|
},
|
|
}),
|
|
});
|
|
};
|
|
|
|
/** Ghidra owns these lanes; Hopper names the family it declines rather than guessing. */
|
|
const HOPPER_DECLINED_ARCHITECTURE_LABELS: Record<
|
|
ElfMetadataArchitecture,
|
|
string
|
|
> = {
|
|
mips: "MIPS",
|
|
riscv: "RISC-V",
|
|
};
|
|
|
|
/** Derive Hopper's complete non-interactive CLI loader selection. */
|
|
export const hopperLoaderArgsForTarget = (
|
|
target: BinaryTarget,
|
|
machoContainer?: "thin" | "fat32" | "fat64",
|
|
): Result<
|
|
readonly string[],
|
|
ProviderAdapterError | AnalysisCapabilityUnavailableError
|
|
> => {
|
|
if (target.kind === "database") return ok([]);
|
|
if (target.kind !== "executable")
|
|
return err(new ProviderAdapterError("hopper", "resolve_analysis_profile"));
|
|
const architecture = target.architecture;
|
|
if (isElfMetadataArchitecture(architecture))
|
|
return err(
|
|
new AnalysisCapabilityUnavailableError(
|
|
"hopper",
|
|
"resolve_analysis_profile",
|
|
`REA's Hopper adapter does not admit ${HOPPER_DECLINED_ARCHITECTURE_LABELS[architecture]} targets. Select a verified Ghidra ${HOPPER_DECLINED_ARCHITECTURE_LABELS[architecture]} profile instead.`,
|
|
),
|
|
);
|
|
const flag = hopperArchitectureFlag(architecture);
|
|
if (isMachOFormat(target.format)) {
|
|
if (machoContainer === undefined)
|
|
return err(
|
|
new AnalysisCapabilityUnavailableError(
|
|
"hopper",
|
|
"resolve_analysis_profile",
|
|
"Mach-O container kind is unknown; resolve the Hopper analysis profile before starting its client.",
|
|
),
|
|
);
|
|
return ok(
|
|
machoContainer === "fat32" || machoContainer === "fat64"
|
|
? ["-l", "FAT", flag, "-l", "Mach-O"]
|
|
: ["-l", "Mach-O", flag],
|
|
);
|
|
}
|
|
switch (target.format) {
|
|
case "elf":
|
|
return ok(["-l", "ELF", flag]);
|
|
case "pe":
|
|
return ok(["-l", "WinPE", flag]);
|
|
case "dos-mz":
|
|
case "dos-com":
|
|
case "raw-binary":
|
|
return err(
|
|
new ProviderAdapterError("hopper", "resolve_analysis_profile"),
|
|
);
|
|
}
|
|
};
|
|
|
|
const hopperArchitectureFlag = (architecture: HeaderArchitecture): string => {
|
|
switch (architecture) {
|
|
case "x86":
|
|
return "--intel-32";
|
|
case "x86_64":
|
|
return "--intel-64";
|
|
case "arm":
|
|
return "--armv7";
|
|
case "arm64":
|
|
return "--aarch64";
|
|
}
|
|
};
|
|
|
|
const readMachoMagic = async (
|
|
path: string,
|
|
signal?: AbortSignal,
|
|
): Promise<Result<number, AnalysisError>> => {
|
|
if (signalIsAborted(signal))
|
|
return err(new AnalysisCancelledError("open_binary"));
|
|
const stream = createReadStream(path, { start: 0, end: 3 });
|
|
const onAbort = (): void => {
|
|
stream.destroy();
|
|
};
|
|
signal?.addEventListener("abort", onAbort, { once: true });
|
|
try {
|
|
const chunks: Buffer[] = [];
|
|
for await (const chunk of stream) chunks.push(Buffer.from(chunk));
|
|
if (signalIsAborted(signal))
|
|
return err(new AnalysisCancelledError("open_binary"));
|
|
const bytes = Buffer.concat(chunks);
|
|
return bytes.length === 4
|
|
? ok(bytes.readUInt32BE(0))
|
|
: err(
|
|
new BinaryTargetError(
|
|
path,
|
|
"Mach-O header became truncated before Hopper loader selection",
|
|
),
|
|
);
|
|
} catch (cause: unknown) {
|
|
return signalIsAborted(signal)
|
|
? err(new AnalysisCancelledError("open_binary"))
|
|
: err(
|
|
new BinaryTargetError(
|
|
path,
|
|
`Cannot read the Mach-O container header: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
{ cause },
|
|
),
|
|
);
|
|
} finally {
|
|
signal?.removeEventListener("abort", onAbort);
|
|
}
|
|
};
|
|
|
|
const sha256File = async (
|
|
path: string,
|
|
signal: AbortSignal | undefined,
|
|
): Promise<Result<string | undefined, AnalysisCancelledError>> => {
|
|
if (signalIsAborted(signal))
|
|
return err(new AnalysisCancelledError("open_binary"));
|
|
const stream = createReadStream(path);
|
|
const onAbort = (): void => {
|
|
stream.destroy();
|
|
};
|
|
signal?.addEventListener("abort", onAbort, { once: true });
|
|
try {
|
|
const hash = createHash("sha256");
|
|
for await (const chunk of stream) hash.update(chunk);
|
|
return signalIsAborted(signal)
|
|
? err(new AnalysisCancelledError("open_binary"))
|
|
: ok(hash.digest("hex"));
|
|
} catch (cause: unknown) {
|
|
// best-effort cleanup: unreadable targets mean no digest; abort still cancels.
|
|
void cause;
|
|
return signalIsAborted(signal)
|
|
? err(new AnalysisCancelledError("open_binary"))
|
|
: ok(undefined);
|
|
} finally {
|
|
signal?.removeEventListener("abort", onAbort);
|
|
}
|
|
};
|
|
|
|
const signalIsAborted = (signal: AbortSignal | undefined): boolean =>
|
|
signal?.aborted === true;
|