Files
rea/src/hopper/HopperProvider.ts
T
Jay-Alexander ElliotGitHubgithub-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
bddddccdee feat(native): admit bounded MIPS ELF analysis through Ghidra (#1362)
* feat(native): admit bounded MIPS ELF analysis through Ghidra

Retain MIPS ELF identity and interpretation through Evidence and snapshots.
Keep provider admission bounded to ELF32 ET_EXEC o32 MIPS32r2, without
implicitly widening Hopper, IDA or Windows P0 coverage. Add source-owned
fixtures and an optional real-provider verifier; real Ghidra verification
remains pending in this contribution environment.

Refs #718

* fix(ghidra): bound MIPS floating-point mode admission

Reject explicit EF_MIPS_FP64 and EF_MIPS_NAN2008 declarations until their
semantics have a real-provider verification lane. Add PSP PRX/Allegrex,
o64/EABI and floating-point-mode refusal regressions. Document that the
header gate is not a full .MIPS.abiflags check and advance the profile lane
identity to invalidate older interpretation bindings.

Validation: 24 standalone checks against the transpiled production profile
module passed; the two new flag cases failed before this change. Clang 17
and LLD compiled the source-owned fixture for both endian targets. The
complete Vitest/typecheck suite and real Ghidra verification remain pending.

Refs morluto/rea#718; PSP support remains follow-up morluto/rea#1330.

* fix(native): validate MIPS ABI records before Ghidra admission

Read bounded ELF32 PT_MIPS_ABIFLAGS and SHT_MIPS_ABIFLAGS records through
the already-open target handle. Preserve declared ABI fields, reject
conflicting/duplicate/truncated records, and keep missing records unknown.
Wire inspection into target resolution before provider selection. Require
compatible declarations for the deliberately narrow Ghidra lane and bind
all ABI fields into profile identity (v3) for snapshot invalidation.

Clang 17 produced eight source-owned fixtures spanning both byte orders
and FPXX/FP32/FP64/soft-float modes with identical ELF header flags. The
new reader and policy distinguish them. 24 focused regression test bodies
passed after TypeScript transpilation using node:test in place of Vitest;
strict isolated TypeScript checking of the reader and target/result types
passed. These are limited checks, not full Vitest/project typechecking or
real-Ghidra verification, which remain pending.

Advances morluto/rea#718. PSP/Allegrex remains morluto/rea#1330 follow-up.

* fix(native): repair MIPS integration boundaries and test resolver behavior

Keep ELF targets out of Hopper Mach-O preparation and scope existing PE fixture types correctly. Move ABI tests into the filesystem boundary lane, use shared cleanup, add resolver regressions, apply the pinned formatter, and register the real MIPS verifier through the existing package-command pattern. Validated with repository-pinned Node/npm, check:ci, actual focused Vitest, discovery and docs:check. Real Ghidra conformance remains pending.

* fix(test): honor caller-selected JDK in real MIPS verification

* test(native): strengthen MIPS Ghidra conformance

Cross-check the source-owned fixture with bounded GNU readelf inspection, compare production ELF/ABI interpretation and independent symbol addresses, and verify effective Ghidra language/compiler identity through existing public operations. Add a source-owned fixed-encoding probe for immediate and conditional branch checks plus global/string byte assertions.

Add 16 assertion/producer-boundary regression cases without widening production admission, changing provider contracts, or introducing proprietary dependencies. Local focused suite: 99 passed, one existing root-permission test skipped. Typecheck, lint/module boundaries, formatting and 700-file discovery pass; full hosted checks and real Ghidra verification remain pending for this checkpoint.

* fix(ghidra): preserve native-tool architecture checks after MIPS integration

The conflict-free upstream merge failed TypeScript compilation because includes on the union of MIPS-only and other architecture arrays requires never. Use equality-based membership without casts or changing accepted native hosts. Extend the existing native-decompiler rejection table with a MIPS executable at a Linux x64 tool path; retain upstream FAT and unknown-header behavior. Hosted verification follows this commit; no success is claimed yet.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-10 23:04:27 +08:00

321 lines
11 KiB
TypeScript

import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import { fileURLToPath } from "node:url";
import { accessSync, constants, statSync } from "node:fs";
import { createAnalysisExecution } from "../application/AnalysisProvider.js";
import type {
AnalysisClient,
AnalysisClientContext,
AnalysisProfileResolutionOptions,
AnalysisProviderCandidate,
CapabilityDescriptor,
ProviderAvailability,
ProviderIdentity,
ProviderTargetSupport,
} from "../application/AnalysisProvider.js";
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import type { AppConfig } from "../config/types.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import type { Logger } from "pino";
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
import { err, ok } from "../domain/result.js";
import { HopperApplicationLauncher } from "./BridgeLauncher.js";
import {
hopperLoaderArgsForTarget,
resolveHopperAnalysisProfile,
} from "./HopperAnalysisProfile.js";
import { mapHopperFileOffset } from "./HopperFileOffset.js";
import { HopperRegexSearch } from "./HopperRegexSearch.js";
import { HopperClient } from "./HopperClient.js";
import { hopperMachOImageSchema } from "./HopperMachOImage.js";
import {
CAPABILITIES,
HOPPER_PROVIDER_IDENTITY,
} from "./HopperProviderCapabilities.js";
/** Concrete analysis provider backed by REA's private Hopper bridge. */
export class HopperProvider implements AnalysisProviderCandidate {
private readonly environment: Readonly<NodeJS.ProcessEnv>;
/**
* Host platform, injected so availability and launch-mode decisions can be
* exercised for any host rather than only the machine running the suite.
* Mirrors `GhidraProvider`, which already threads its installation host's
* platform the same way.
*/
constructor(
private readonly config: AppConfig,
private readonly logger: Logger,
environment: Readonly<NodeJS.ProcessEnv>,
private readonly platform: NodeJS.Platform = process.platform,
) {
this.environment = snapshotEnvironment(environment, platform);
}
identity(): ProviderIdentity {
return HOPPER_PROVIDER_IDENTITY;
}
capabilities(): readonly CapabilityDescriptor[] {
return CAPABILITIES;
}
inspectAvailability(): ProviderAvailability {
const diagnostics = {
launcher_path: this.config.hopperLauncherPath,
platform: this.platform,
};
if (this.platform !== "darwin" && this.platform !== "linux")
return {
status: "unavailable",
code: "unsupported_host",
reason: `Hopper integration is not supported on ${this.platform}.`,
diagnostics,
};
try {
accessSync(this.config.hopperLauncherPath, constants.X_OK);
// A searchable directory, such as an .app bundle, also passes X_OK.
if (!statSync(this.config.hopperLauncherPath).isFile())
throw new TypeError("Hopper launcher is not a regular file");
return {
status: "available",
code: null,
reason: null,
diagnostics,
};
} catch (cause: unknown) {
// best-effort cleanup: optional launcher probing; failure means unavailable.
void cause;
return {
status: "unavailable",
code: "executable_missing",
reason: `Hopper launcher is missing or not executable: ${this.config.hopperLauncherPath}`,
diagnostics,
};
}
}
inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport {
const diagnostics = {
target_kind: target.kind,
target_format: target.format,
architecture: target.architecture ?? null,
};
if (target.kind !== "executable" && target.kind !== "database")
return {
status: "unsupported",
code: "target_kind_unsupported",
reason: `Hopper cannot directly analyze ${target.kind} targets.`,
diagnostics,
};
if (target.kind === "database")
return {
status: "supported",
code: null,
reason: null,
diagnostics,
};
if (target.architecture === "mips")
return {
status: "unsupported",
code: "architecture_unsupported",
reason: "REA's Hopper adapter does not admit MIPS targets.",
diagnostics,
};
if (target.format === "dos-mz" || target.format === "dos-com")
return {
status: "unsupported",
code: "target_format_unsupported",
reason:
"DOS MZ/COM analysis requires the Ghidra 16-bit real-mode adapter.",
diagnostics,
};
return {
status: "supported",
code: null,
reason: null,
diagnostics,
};
}
resolveAnalysisProfile(
target: BinaryTarget,
options?: AnalysisProfileResolutionOptions,
) {
return resolveHopperAnalysisProfile(target, {
launcherPath: this.config.hopperLauncherPath,
loaderArgsOverride: this.config.hopperLoaderArgs,
provider: HOPPER_PROVIDER_IDENTITY,
...(options?.signal === undefined ? {} : { signal: options.signal }),
});
}
createClient(
target: BinaryTarget,
profile?: AnalysisProfileCommitment,
context?: AnalysisClientContext,
): AnalysisClient {
if (target.kind !== "executable" && target.kind !== "database")
return {
execute: (operation) =>
Promise.resolve(
err(
new AnalysisCapabilityUnavailableError(
HOPPER_PROVIDER_IDENTITY.id,
operation,
`Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`,
),
),
),
close: () => Promise.resolve(ok(null)),
};
const preparation = profile?.parameters.prepared_image;
const parsedImage =
preparation === undefined
? undefined
: hopperMachOImageSchema.safeParse(preparation);
if (parsedImage?.success === false)
return {
execute: (operation) =>
Promise.resolve(
err(
new AnalysisCapabilityUnavailableError(
HOPPER_PROVIDER_IDENTITY.id,
operation,
"Hopper prepared-image profile is malformed; resolve the analysis profile again.",
),
),
),
close: () => Promise.resolve(ok(null)),
};
const preparedImage = parsedImage?.data;
const container =
preparedImage === undefined
? profile?.parameters.macho_container
: "thin";
const derivedLoaderArgs = hopperLoaderArgsForTarget(
target,
container === "thin" || container === "fat32" || container === "fat64"
? container
: undefined,
);
if (!derivedLoaderArgs.ok)
return {
execute: () => Promise.resolve(err(derivedLoaderArgs.error)),
close: () => Promise.resolve(ok(null)),
};
const executionProvider = profile?.provider ?? HOPPER_PROVIDER_IDENTITY;
const client = new HopperClient({
launcher: new HopperApplicationLauncher({
environment: this.environment,
launcherPath: this.config.hopperLauncherPath,
targetPath: target.path,
targetKind: target.kind,
...(preparedImage === undefined
? {}
: {
preparedImage: {
image: preparedImage,
sourceSha256: target.sha256,
},
}),
loaderArgs:
this.config.hopperLoaderArgs.length > 0
? this.config.hopperLoaderArgs
: derivedLoaderArgs.value,
bridgeScriptPath: fileURLToPath(
new URL("../../bridge/hopper_bridge.py", import.meta.url),
),
...(this.platform === "linux"
? {
launchMode: "verified_linux_demo" as const,
demoHelperPath: fileURLToPath(
new URL("../../scripts/hopper-demo-x11.py", import.meta.url),
),
}
: { launchMode: "native" as const }),
}),
...(context === undefined ? {} : { runId: context.runId }),
logger: this.logger.child({ layer: "bridge" }),
onDiagnostic: (diagnostic) =>
this.logger.info(diagnostic, "Hopper bridge reported a diagnostic"),
});
const regexSearch = new HopperRegexSearch(client);
return {
execute: async (operation, parameters, options) => {
const result =
(operation === "search_strings" ||
operation === "search_procedures") &&
parameters.mode === "regex"
? await regexSearch.execute(operation, parameters, options)
: await client.callTool(operation, parameters, options);
if (!result.ok) return result;
const mapped =
operation === "address_to_file_offset"
? await mapHopperFileOffset(target, result.value, options?.signal)
: result;
return mapped.ok
? {
ok: true,
value: createAnalysisExecution(mapped.value, executionProvider, {
// Only the file-offset mapping differs from Hopper's reply.
rawResult: mapped === result ? null : result.value,
...(profile === undefined ? {} : { analysisProfile: profile }),
limitations: [
...(preparedImage === undefined
? []
: [
"REA loaded a verified thin Mach-O slice from the original FAT64 source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",
]),
...(CAPABILITIES.find(
(descriptor) => descriptor.operation === operation,
)?.limitations ?? []),
...(operation === "read_bytes"
? [
"Hopper byte reads stop at the containing segment's exclusive end; a readable prefix is returned with complete=false when the requested range crosses it.",
]
: []),
...(operation === "procedure_references"
? [
"Native CallReference classifications and unresolved targets are preserved. Detailed reference flags and coverage beyond reported CallReference objects remain unknown.",
]
: []),
],
}),
}
: mapped;
},
runtimeLineageSnapshots: () => {
const observation = client.runtimeLineage();
return observation === null
? []
: [{ provider: executionProvider, observation }];
},
requestActivitySnapshots: () => {
const activity = client.requestActivity();
return [
{
provider: executionProvider,
active:
activity === null
? null
: {
requestId: activity.requestId,
operation: activity.operation,
elapsedMs: activity.elapsedMs,
callerState: activity.callerState,
},
queuedRequests: activity?.queuedRequests ?? 0,
},
];
},
operationHealthSnapshot: () => client.operationHealth(),
close: async (options) => {
await regexSearch.close();
return client.close(options);
},
};
}
}