diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts index f015b4f920..c1e67d3227 100644 --- a/src/application/DirectAnalysis.ts +++ b/src/application/DirectAnalysis.ts @@ -2,7 +2,7 @@ import { admitOneShotOperation, type DirectAnalysisTool, } from "./oneShotOperationInput.js"; -import { admitCompletedAnalysis } from "./investigation/admitCompletedAnalysis.js"; +import { completedOperationEvidence } from "./binary/SessionEvidenceReuse.js"; import type { EspFlashSelection } from "../domain/firmware/espFlashLocation.js"; import type { ExecutableFormatHint } from "../domain/dosCom.js"; import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js"; @@ -794,27 +794,17 @@ const executeAnalysisTool = async (input: { ); } if (!result.ok) return result; - const observation = { - ...result.value, - subject: - result.value.subject === undefined - ? input.openedTarget - : result.value.subject, - }; - const admitted = admitCompletedAnalysis( + const evidence = completedOperationEvidence( tool, input.evidenceParameters, - observation, - session.admitRecoveryObservation.bind(session), + result.value, + { + target: input.openedTarget, + admitRecovery: session.admitRecoveryObservation.bind(session), + evidenceById: (id) => session.evidenceForAnalysis(id), + }, ); - if (!admitted.ok) return admitted; - const evidence = createAnalysisExecutionEvidence( - tool, - input.evidenceParameters, - observation, - "observed", - ); - return ok({ evidence }); + return evidence.ok ? ok({ evidence: evidence.value }) : evidence; }; const withProcessCancellation = async ( diff --git a/src/application/binary/SessionEvidenceReuse.ts b/src/application/binary/SessionEvidenceReuse.ts index e5d5415698..8e6a77b292 100644 --- a/src/application/binary/SessionEvidenceReuse.ts +++ b/src/application/binary/SessionEvidenceReuse.ts @@ -4,6 +4,12 @@ import type { AnalysisExecution } from "../../ports/AnalysisProvider.js"; import type { Evidence } from "../../domain/evidence.js"; import type { JsonValue } from "../../domain/jsonValue.js"; import { equalJsonText } from "../../domain/jsonSerialization.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import { createAnalysisExecutionEvidence } from "../../domain/analysisObservation.js"; +import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; +import { ok, type Result } from "../../domain/result.js"; +import { admitCompletedAnalysis } from "../investigation/admitCompletedAnalysis.js"; +import type { RecoveryAdmission } from "../investigation/InvestigationRetention.js"; // Proof belongs to the exact object issued by the session. A wrapper that // copies or transforms the observation cannot carry it forward. @@ -54,7 +60,7 @@ export const bindSessionEvidenceExecution = ( return result; }; -export const sessionEvidenceForExecution = ( +const sessionEvidenceForExecution = ( execution: AnalysisExecution, operation: string, parameters: Readonly>, @@ -70,3 +76,56 @@ export const sessionEvidenceForExecution = ( return undefined; return evidence; }; + +/** How one completed session execution becomes Evidence. */ +export interface CompletedOperationEvidenceOptions { + /** The subject when the provider names none. */ + readonly target: BinaryTarget | null; + readonly admitRecovery?: RecoveryAdmission | undefined; + /** The session's records, to reuse the record it issued for this call. */ + readonly evidenceById?: ((id: string) => Evidence | undefined) | undefined; +} + +/** + * The Evidence of one completed provider operation, built once for every + * adapter: the record the session issued for this exact execution and + * parameters when it holds one, else a new record admitted against the + * completed analysis. + */ +export const completedOperationEvidence = ( + operation: string, + parameters: Readonly>, + execution: AnalysisExecution, + options: CompletedOperationEvidenceOptions, +): Result => { + const reusable = + options.evidenceById === undefined + ? undefined + : sessionEvidenceForExecution( + execution, + operation, + parameters, + options.evidenceById, + ); + if (reusable !== undefined) return ok(reusable); + const observation = { + ...execution, + subject: + execution.subject === undefined ? options.target : execution.subject, + }; + const admitted = admitCompletedAnalysis( + operation, + parameters, + observation, + options.admitRecovery, + ); + if (!admitted.ok) return admitted; + return ok( + createAnalysisExecutionEvidence( + operation, + parameters, + observation, + "observed", + ), + ); +}; diff --git a/src/server/providerOperationToolHandler.ts b/src/server/providerOperationToolHandler.ts index 83fd10ea97..aa0dcb51a9 100644 --- a/src/server/providerOperationToolHandler.ts +++ b/src/server/providerOperationToolHandler.ts @@ -4,7 +4,7 @@ import type { } from "@modelcontextprotocol/server"; import type { Logger } from "pino"; -import { sessionEvidenceForExecution } from "../application/binary/SessionEvidenceReuse.js"; +import { completedOperationEvidence } from "../application/binary/SessionEvidenceReuse.js"; import type { EvidenceLookup } from "../application/EvidenceInputResolver.js"; import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; import { @@ -17,10 +17,8 @@ import type { } from "../ports/AnalysisProvider.js"; import type { ToolContract } from "../contracts/toolContractTypes.js"; import { ok } from "../domain/result.js"; -import { admitCompletedAnalysis } from "../application/investigation/admitCompletedAnalysis.js"; import type { RecoveryAdmission } from "../application/investigation/InvestigationRetention.js"; import type { BinaryTarget } from "../domain/binaryTargetTypes.js"; -import { createAnalysisExecutionEvidence } from "../domain/analysisObservation.js"; import { jsonObjectSchema, type JsonValue } from "../domain/jsonValue.js"; import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; import { mcpProgressReporter } from "./mcpProgress.js"; @@ -131,42 +129,21 @@ export const createProviderOperationToolHandler = contract.retainedSummary?.evidenceParameters === "omit-detail" ? providerParameters : parameters; - const observation = { - ...execution.value, - subject: - execution.value.subject === undefined - ? (options.activeTarget?.() ?? null) - : execution.value.subject, - }; - const reusable = - dependencies.evidenceById === undefined - ? undefined - : sessionEvidenceForExecution( - execution.value, - operation, - evidenceParameters, - dependencies.evidenceById, - ); - if (reusable === undefined) { - const admitted = admitCompletedAnalysis( - operation, - evidenceParameters, - observation, - options.admitRecovery, - ); - if (!admitted.ok) - return server.delivery.toCallToolResult(admitted, contract); - } - const evidence = - reusable ?? - createAnalysisExecutionEvidence( - operation, - evidenceParameters, - observation, - "observed", - ); + const evidence = completedOperationEvidence( + operation, + evidenceParameters, + execution.value, + { + target: options.activeTarget?.() ?? null, + admitRecovery: options.admitRecovery, + evidenceById: dependencies.evidenceById, + }, + ); + if (!evidence.ok) + return server.delivery.toCallToolResult(evidence, contract); const projected = - delivery?.projectEvidence(parameters, evidence) ?? ok(evidence); + delivery?.projectEvidence(parameters, evidence.value) ?? + ok(evidence.value); if (!projected.ok) return server.delivery.toCallToolResult(projected, contract); const recorded = dependencies.recordEvidence?.(projected.value); diff --git a/tests/composition/directAnalysisEvidenceReuse.test.ts b/tests/composition/directAnalysisEvidenceReuse.test.ts new file mode 100644 index 0000000000..a4748d1232 --- /dev/null +++ b/tests/composition/directAnalysisEvidenceReuse.test.ts @@ -0,0 +1,91 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect, it, vi } from "vitest"; + +import { runDirectAnalysis } from "../../src/application/DirectAnalysis.js"; +import type { DirectAnalysisDependencies } from "../../src/application/DirectAnalysisDependencies.js"; +import { BinarySession } from "../../src/application/binary/BinarySession.js"; +import { parseConfig } from "../../src/config/parseConfig.js"; +import { createAnalysisProfile } from "../../src/domain/analysisProfile.js"; +import { ok } from "../../src/domain/result.js"; +import { + createAnalysisExecution, + type AnalysisProvider, +} from "../../src/ports/AnalysisProvider.js"; +import { createTestProviderRouter } from "../fixtures/binarySession.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; + +// `rea decompile --snapshot` with Ghidra: the session retains the one-shot +// pseudocode as Evidence, so the CLI has a record to reuse. +const GHIDRA = { id: "ghidra", name: "Ghidra", version: "1" } as const; + +const ghidraFixture: AnalysisProvider = { + identity: () => GHIDRA, + capabilities: () => [ + { + provider: GHIDRA, + operation: "procedure_pseudo_code", + available: true, + reason: null, + cachePolicy: "snapshot", + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limitations: [], + }, + ], + createClient: () => ({ + execute: async () => ok(createAnalysisExecution("int main(void);", GHIDRA)), + close: async () => ok(null), + }), +}; + +it("delivers the record a profiled one-shot session issued and admits it once", async () => { + const directory = await createTestTempDirectory("rea-direct-reuse-"); + const path = join(directory, "fixture.com"); + await writeFile(path, Buffer.from([0xb8, 0, 0x4c, 0xcd, 0x21])); + const session = new BinarySession( + createTestProviderRouter(ghidraFixture, { + resolveAnalysisProfile: async () => + ok({ profile: createAnalysisProfile(GHIDRA, {}) }), + }), + ); + const admit = vi.spyOn(session, "admitRecoveryObservation"); + let issued: string | undefined; + const record = session.recordEvidence.bind(session); + vi.spyOn(session, "recordEvidence").mockImplementation((evidence) => { + issued ??= evidence.evidence_id; + return record(evidence); + }); + const create = () => session; + const dependencies: DirectAnalysisDependencies = { + readConfiguration: () => parseConfig({}), + createBinarySession: create, + createNativeDispatchBinarySession: create, + createArtifactBinarySession: create, + createNativeBinarySession: create, + createManagedBinarySession: create, + }; + + const result = await runDirectAnalysis( + dependencies, + path, + "procedure_pseudo_code", + { procedure: "0x100" }, + { formatHint: "dos-com", snapshotPath: join(directory, "snapshot.json") }, + ); + + if (!result.ok) throw new Error(JSON.stringify(result.error)); + // The CLI delivers the session's record with its own path, not a copy. + expect(issued).toBeDefined(); + expect(result.value.evidence_id).toBe(issued); + expect(result.value.caller_input_path).toBe(path); + expect(admit).toHaveBeenCalledTimes(1); +});