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> => { 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")); if (target.format === "raw-binary") 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": 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> => { 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> => { 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;