* feat(ghidra): edit function annotations atomically Return annotation readback and refreshed function analysis through CLI and MCP. Own each database transaction, invalidate caches and immutable snapshots, preserve executable bytes, and retain the Windows mutation boundary. Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering) * fix(ghidra): preserve qualified function annotation identity Preserve namespaces during local name writes and match qualified readback to the refreshed dossier. Add a producer-shaped regression and verify a real namespaced C++ function through the CLI. Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering) * test(ghidra): align verification with annotation authority Keep strict capability and profile checks while admitting the explicit session metadata operation. Verify packaged transport authority and atomic transaction commitments and preserve a read-only Windows expectation. Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
290 lines
9.5 KiB
TypeScript
290 lines
9.5 KiB
TypeScript
import { fileURLToPath } from "node:url";
|
|
import { accessSync, constants } 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.js";
|
|
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
|
import type { Logger } from "../logger.js";
|
|
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
|
|
import { err } from "../domain/result.js";
|
|
import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
|
|
import { HopperApplicationLauncher } from "./BridgeLauncher.js";
|
|
import {
|
|
hopperLoaderArgsForTarget,
|
|
resolveHopperAnalysisProfile,
|
|
} from "./HopperAnalysisProfile.js";
|
|
import { HopperClient } from "./HopperClient.js";
|
|
|
|
/** Public identity committed by every Hopper-backed observation. */
|
|
export const HOPPER_PROVIDER_IDENTITY: ProviderIdentity = Object.freeze({
|
|
id: "hopper",
|
|
name: "Hopper Disassembler",
|
|
version: null,
|
|
});
|
|
const IDENTITY = HOPPER_PROVIDER_IDENTITY;
|
|
const MUTATING_OPERATIONS = new Set([
|
|
"set_address_name",
|
|
"set_addresses_names",
|
|
"set_bookmark",
|
|
"set_comment",
|
|
"set_inline_comment",
|
|
"unset_bookmark",
|
|
]);
|
|
|
|
/** Tool contracts implemented directly by the Hopper adapter. */
|
|
export const HOPPER_PROVIDER_TOOL_CONTRACTS = Object.freeze([
|
|
...GENERATED_MCP_TOOL_CATALOG.filter(
|
|
({ kind, name }) =>
|
|
kind === "official-proxy" &&
|
|
name !== "annotate_native_function" &&
|
|
name !== "inspect_native_load_image" &&
|
|
name !== "inspect_native_data_type" &&
|
|
name !== "inspect_native_instruction" &&
|
|
name !== "resolve_native_call_targets",
|
|
),
|
|
...GENERATED_MCP_TOOL_CATALOG.filter(
|
|
({ name }) => name === "analyze_function",
|
|
),
|
|
]);
|
|
|
|
const CAPABILITIES: readonly CapabilityDescriptor[] = Object.freeze(
|
|
HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract) => {
|
|
const operation = contract.analysisOperation;
|
|
if (operation === null)
|
|
throw new TypeError(`Missing analysis operation for ${contract.name}`);
|
|
return Object.freeze({
|
|
provider: IDENTITY,
|
|
operation,
|
|
available: true,
|
|
reason: null,
|
|
effects: Object.freeze({
|
|
mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
|
|
launchesProcess: true,
|
|
mayShowUi: true,
|
|
mayAccessNetwork: false,
|
|
mayWriteFilesystem: MUTATING_OPERATIONS.has(contract.name),
|
|
changesPermissions: false,
|
|
requiresRoot: false,
|
|
}),
|
|
limitations: Object.freeze([
|
|
"Results depend on Hopper's completed static analysis.",
|
|
]),
|
|
});
|
|
}),
|
|
);
|
|
|
|
/** Concrete analysis provider backed by REA's private Hopper bridge. */
|
|
export class HopperProvider implements AnalysisProviderCandidate {
|
|
/**
|
|
* 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,
|
|
private readonly platform: NodeJS.Platform = process.platform,
|
|
) {}
|
|
|
|
identity(): ProviderIdentity {
|
|
return 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);
|
|
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.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: 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(
|
|
IDENTITY.id,
|
|
operation,
|
|
`Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`,
|
|
),
|
|
),
|
|
),
|
|
close: () => Promise.resolve(),
|
|
};
|
|
const derivedLoaderArgs = hopperLoaderArgsForTarget(target);
|
|
if (!derivedLoaderArgs.ok)
|
|
return {
|
|
execute: () => Promise.resolve(err(derivedLoaderArgs.error)),
|
|
close: () => Promise.resolve(),
|
|
};
|
|
const executionProvider = profile?.provider ?? IDENTITY;
|
|
const client = new HopperClient({
|
|
launcher: new HopperApplicationLauncher({
|
|
launcherPath: this.config.hopperLauncherPath,
|
|
targetPath: target.path,
|
|
targetKind: target.kind,
|
|
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"),
|
|
});
|
|
return {
|
|
execute: async (operation, parameters, options) => {
|
|
const result = await client.callTool(operation, parameters, options);
|
|
return result.ok
|
|
? {
|
|
ok: true,
|
|
value: createAnalysisExecution(result.value, executionProvider, {
|
|
...(profile === undefined ? {} : { analysisProfile: profile }),
|
|
limitations: [
|
|
"Results depend on Hopper's completed static analysis.",
|
|
...(operation === "procedure_references"
|
|
? [
|
|
"Hopper's public Python API does not expose flow classification for calls without resolved targets; unresolved_calls is empty and its coverage is unknown.",
|
|
]
|
|
: []),
|
|
],
|
|
}),
|
|
}
|
|
: result;
|
|
},
|
|
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,
|
|
},
|
|
];
|
|
},
|
|
closeWithOutcome: (options) => client.closeWithOutcome(options),
|
|
close: () => client.close(),
|
|
};
|
|
}
|
|
}
|