Files
rea/src/server/registerEnhancedTools.ts
T
morlutoandGitHub ed933d1893 feat(native): add investigation features (#486)
* feat(native): add UI and dispatch investigation workflows

* feat(ghidra): support macOS host validation

* docs: update native investigation capabilities

* feat(artifacts): decode compiled Interface Builder archives

* feat(ghidra): expose bounded p-code value flow

* test(ghidra): split host and cross-format verification

* fix(verify): follow complete result contracts

* refactor: remove unused authorization and schema helpers

* refactor: remove unused evidence result alias

* fix(ghidra): report jump-table evidence precisely

* fix(verify): align browser scenario fixture schema

* fix(setup): compare parsed client config structurally

* test(ghidra): verify AArch64 jump-table mappings

* fix(ghidra): recover AArch64 byte jump tables

* test(artifacts): verify compiled interface builder archives

* feat(native): trace UI actions through handlers

* fix(tests): update native trace and shutdown fixtures

* fix(verification): diagnose browser scenario failures

* fix(browser): wrap scenario snapshots in capture state

* fix(native): bind and bound investigation workflows

* fix(artifacts): preserve bounded interface builder evidence

* fix(ghidra): enforce admitted hosts and preflight tools

* fix(native): preserve trace cancellation and bounds

* test(application): expect bound analysis target evidence

* fix(native): preserve investigation bounds and cancellation

* fix(application): preserve bundle and unresolved trace evidence

* style(test): format artifact subject fixture
2026-09-30 00:41:05 +08:00

337 lines
10 KiB
TypeScript

import type {
CallToolResult,
McpServer,
ServerContext,
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
EnhancedTools,
type ValidatedEnhancedCall,
} from "../application/EnhancedTools.js";
import {
REA_WORKFLOW_PROVIDER,
workflowAnalysisProfile,
} from "../application/InvestigationProviders.js";
import {
ENHANCED_TOOL_CONTRACTS,
type ToolContract,
} from "../contracts/toolContracts.js";
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { UnknownRegistryError } from "../domain/errors.js";
import { createEvidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Logger } from "../logger.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
/** Optional session services used by enhanced tool registration. */
export interface EnhancedToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly analysisProfile:
| (() => AnalysisProfileCommitment | undefined)
| undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
}
/** Register composed workflows against the same port as direct bridge tools. */
// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
export const registerEnhancedTools = (
server: McpServer,
analysis: AnalysisOperationPort,
options: EnhancedToolRegistration,
): void => {
const [
nativeDispatchMetadata,
objcClasses,
objcProtocols,
batchDecompile,
callGraph,
swiftTypes,
xrefsToName,
binaryOverview,
analyzeFunction,
inspectNativeApi,
traceFeature,
codeForString,
traceCallPath,
traceNativeUiAction,
] = ENHANCED_TOOL_CONTRACTS;
server.registerTool(
nativeDispatchMetadata.name,
toolRegistrationOptions(nativeDispatchMetadata),
(input, context) =>
executeEnhancedTool(analysis, options, nativeDispatchMetadata, {
validatedCall: { name: "inspect_native_dispatch_metadata", input },
context,
}),
);
server.registerTool(
objcClasses.name,
toolRegistrationOptions(objcClasses),
(input, context) =>
executeEnhancedTool(analysis, options, objcClasses, {
validatedCall: { name: "get_objc_classes", input },
context,
}),
);
server.registerTool(
objcProtocols.name,
toolRegistrationOptions(objcProtocols),
(input, context) =>
executeEnhancedTool(analysis, options, objcProtocols, {
validatedCall: { name: "get_objc_protocols", input },
context,
}),
);
server.registerTool(
batchDecompile.name,
toolRegistrationOptions(batchDecompile),
(input, context) =>
executeEnhancedTool(analysis, options, batchDecompile, {
validatedCall: { name: "batch_decompile", input },
context,
}),
);
server.registerTool(
callGraph.name,
toolRegistrationOptions(callGraph),
(input, context) =>
executeEnhancedTool(analysis, options, callGraph, {
validatedCall: { name: "get_call_graph", input },
context,
}),
);
server.registerTool(
swiftTypes.name,
toolRegistrationOptions(swiftTypes),
(input, context) =>
executeEnhancedTool(analysis, options, swiftTypes, {
validatedCall: { name: "analyze_swift_types", input },
context,
}),
);
server.registerTool(
xrefsToName.name,
toolRegistrationOptions(xrefsToName),
(input, context) =>
executeEnhancedTool(analysis, options, xrefsToName, {
validatedCall: { name: "find_xrefs_to_name", input },
context,
}),
);
server.registerTool(
binaryOverview.name,
toolRegistrationOptions(binaryOverview),
(input, context) =>
executeEnhancedTool(analysis, options, binaryOverview, {
validatedCall: { name: "binary_overview", input },
context,
}),
);
server.registerTool(
analyzeFunction.name,
toolRegistrationOptions(analyzeFunction),
(input, context) =>
executeEnhancedTool(analysis, options, analyzeFunction, {
validatedCall: { name: "analyze_function", input },
context,
}),
);
server.registerTool(
inspectNativeApi.name,
toolRegistrationOptions(inspectNativeApi),
(input, context) =>
executeEnhancedTool(analysis, options, inspectNativeApi, {
validatedCall: { name: "inspect_native_api", input },
context,
}),
);
server.registerTool(
traceFeature.name,
toolRegistrationOptions(traceFeature),
(input, context) =>
executeEnhancedTool(analysis, options, traceFeature, {
validatedCall: { name: "trace_feature", input },
context,
}),
);
server.registerTool(
codeForString.name,
toolRegistrationOptions(codeForString),
(input, context) =>
executeEnhancedTool(analysis, options, codeForString, {
validatedCall: { name: "find_code_for_string", input },
context,
}),
);
server.registerTool(
traceCallPath.name,
toolRegistrationOptions(traceCallPath),
(input, context) =>
executeEnhancedTool(analysis, options, traceCallPath, {
validatedCall: { name: "trace_call_path", input },
context,
}),
);
server.registerTool(
traceNativeUiAction.name,
toolRegistrationOptions(traceNativeUiAction),
(input, context) =>
executeEnhancedTool(analysis, options, traceNativeUiAction, {
validatedCall: { name: "trace_native_ui_action", input },
context,
}),
);
};
const executeEnhancedTool = async (
analysis: AnalysisOperationPort,
registration: EnhancedToolRegistration,
contract: ToolContract,
request: {
readonly validatedCall: ValidatedEnhancedCall;
readonly context: ServerContext;
},
): Promise<CallToolResult> => {
const { validatedCall, context } = request;
const name = validatedCall.name;
const progress = mcpProgressReporter(context);
await progress.report({
phase: name,
completed: 0,
total: 1,
message: "started",
});
const parsedInput = validatedCall.input;
const parameters = jsonParameters(parsedInput);
const services = new EnhancedTools({
execute: (operation, operationParameters, executionOptions) =>
analysis.execute(operation, operationParameters, {
...executionOptions,
progress,
}),
});
const result = await logToolExecution(registration.logger, name, () =>
services.executeValidated(validatedCall, context.mcpReq.signal),
);
await progress.report({
phase: name,
completed: 1,
total: 1,
message: result.ok ? "completed" : "failed",
terminal: true,
});
if (result.ok) {
const upstreamProfile = registration.analysisProfile?.();
const evidence = createEvidence(
registration.activeTarget?.(),
REA_WORKFLOW_PROVIDER,
{
operation: name,
parameters,
result: result.value,
...(upstreamProfile === undefined
? {}
: {
analysisProfile: workflowAnalysisProfile(upstreamProfile),
}),
confidence: "derived",
limitations: [
"Derived by an REA workflow from one or more provider observations.",
],
},
);
const recorded = registration.recordEvidence?.(evidence);
if (recorded !== undefined && !recorded.ok)
return toCallToolResult(recorded, contract);
const unknowns = recordWorkflowUnknowns({
name,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
});
if (!unknowns.ok) return toCallToolResult(unknowns, contract);
return toCallToolResult({ ok: true, value: evidence }, contract);
}
return toCallToolResult(result, contract);
};
const jsonParameters = (
input: Readonly<Record<string, JsonValue | undefined>>,
): Record<string, JsonValue> =>
Object.fromEntries(
Object.entries(input).filter(
(entry): entry is [string, JsonValue] => entry[1] !== undefined,
),
);
interface WorkflowUnknownInput {
readonly name: string;
readonly result: JsonValue;
readonly evidenceId: string;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
}
const recordWorkflowUnknowns = ({
name,
result,
evidenceId,
recordUnknown,
}: WorkflowUnknownInput):
| ReturnType<BinarySessionPort["recordUnknown"]>
| { readonly ok: true; readonly value: null } => {
if (
![
"trace_feature",
"find_code_for_string",
"trace_call_path",
"inspect_native_api",
].includes(name) ||
recordUnknown === undefined ||
typeof result !== "object" ||
result === null ||
Array.isArray(result) ||
!Array.isArray(result.residual_unknowns)
)
return { ok: true, value: null };
for (const question of result.residual_unknowns) {
if (typeof question !== "string") continue;
const recorded = recordUnknown({
question,
severity: "medium",
domain: name === "inspect_native_api" ? "native-api" : "control-flow",
supporting_evidence_ids: [evidenceId],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: name,
rationale:
name === "inspect_native_api"
? "Confirm the unsupported boundary with a capable provider or ABI probe."
: "Continue with a focused query or another available provider.",
},
],
relationships: [],
});
if (
!recorded.ok &&
!(
recorded.error instanceof UnknownRegistryError &&
recorded.error.reason === "already-exists"
)
)
return recorded;
}
return { ok: true, value: null };
};