Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ghidra): preserve source failures and snapshot ownership
morluto704fa7699ca1
diff --git a/docs/native-investigation.md b/docs/native-investigation.mdindex eea5a8d7d..6255d5e4e 100644--- a/docs/native-investigation.md+++ b/docs/native-investigation.md@@ -110,6 +110,16 @@ After metadata edits, snapshot saves and imports remain unavailable in thatsession. Use `export_evidence_bundle` to retain the observations, close without`snapshot_path`, and reopen the target before importing or saving a snapshot.+Ghidra checks its private import copy against the artifact digest selected by+`open_binary`. If the source changes before that copy is acquired, the query+reports `artifact_changed` with the selected path and both digests. Reopen the+stable target to acquire its current identity. An already imported database+continues to describe its captured bytes even if the original path is changed+or removed; this identity failure does not mark the Ghidra installation unavailable.+On Linux and macOS, an unreadable source reports `access_denied`; a removed or+nonregular replacement reports `artifact_changed`. Source copying is cancellable+and never replaces an existing private snapshot.+```bashrea inspect-native-instruction <binary> <address> --provider ghidrarea resolve-native-call-targets <binary> <call-site> --provider ghidradiff --git a/docs/testing.md b/docs/testing.mdindex e0ffb7370..3dad3fd7a 100644--- a/docs/testing.md+++ b/docs/testing.md@@ -308,6 +308,18 @@ snapshot is written by an independent real CLI session.They also start a real annotation and snapshot close concurrently: the editmust succeed, the snapshot must be rejected without creating a file, and theedited session must remain usable until explicitly closed.+Source-admission probes change a caller-owned fixture after `open_binary` but+before the first Ghidra query. They require an actionable `artifact_changed`+error preserving both digests and the selected path, unchanged provider+availability, failed-copy cleanup, and successful recovery after reopening.+After import, deleting that source must preserve the captured database identity.+Instruction inspection and containing-function lookup also agree across+hexadecimal case, leading zeros, and encoded default address-space spellings.+The same source-acquisition workflow exercises missing and directory-replaced+inputs, plus real read-permission denial on a non-root host. Root runs report+that permission-denial check as unverified. A focused filesystem integration+check retains selected-platform routing and exclusive creation; two copy/digest+checks duplicated by the real workflow have been removed.Malformed annotation readback, memory completeness, and inventory data remain separateSDK/provider integration cases; success from a realprovider cannot establish rejection of a contradictory provider response.diff --git a/scripts/lib/real-ghidra-boundaries.mjs b/scripts/lib/real-ghidra-boundaries.mjsindex 8ba6974a3..0de391002 100644--- a/scripts/lib/real-ghidra-boundaries.mjs+++ b/scripts/lib/real-ghidra-boundaries.mjs@@ -10,6 +10,7 @@ import addFormats from "ajv-formats";import { mcpTextValue, requireMcpResult } from "./mcp-verifier-results.mjs";import { verifyLegacyGhidraReferenceSnapshot } from "./ghidra-reference-snapshot-e2e.mjs";import { verifyGhidraSnapshotLifecycle } from "./real-ghidra-snapshot-lifecycle.mjs";+import { verifyGhidraTargetAdmission } from "./real-ghidra-target-admission.mjs";/** Probe real Ghidra location, annotation and error contracts through public adapters. */export async function verifyGhidraBoundaries(@@ -648,6 +649,13 @@ export async function verifyGhidraBoundaries();successfulCalls += snapshotLifecycle.successfulCalls;rejectedCalls += snapshotLifecycle.rejectedCalls;+ const targetAdmission = await verifyGhidraTargetAdmission({+ call,+ reject: invalid,+ target,+ entry: address,+ runtimeRoot: env.TMPDIR,+ });await assert.rejects(access(socketRoot), { code: "ENOENT" });await assert.rejects(access(runtimeRoot), { code: "ENOENT" });assert.equal(await call("procedure_address", { procedure: name }), address);@@ -683,6 +691,11 @@ export async function verifyGhidraBoundaries(legacy_reference_snapshot_rejected: true,mutation_snapshot_lifecycle: true,concurrent_annotation_snapshot_close: true,+ changed_source_admission_and_recovery: true,+ source_permission_denial_verified: targetAdmission.permissionDenied,+ missing_and_nonregular_source_rejected: true,+ imported_source_identity_retained: true,+ equivalent_instruction_address_spellings: true,source_immutable: true,reopen_discards_edits: true,long_tmpdir_private_socket_cleanup: true,diff --git a/scripts/lib/real-ghidra-target-admission.mjs b/scripts/lib/real-ghidra-target-admission.mjsnew file mode 100644index 000000000..2c256c154--- /dev/null+++ b/scripts/lib/real-ghidra-target-admission.mjs@@ -0,0 +1,191 @@+import assert from "node:assert/strict";+import { createHash } from "node:crypto";+import {+ chmod,+ mkdir,+ mkdtemp,+ readFile,+ realpath,+ readdir,+ rm,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";++/** Verify changed-source admission and retained private database identity through MCP. */+export async function verifyGhidraTargetAdmission({+ call,+ reject,+ target,+ entry,+ runtimeRoot,+}) {+ const workspace = await mkdtemp(+ join(tmpdir(), "rea-ghidra-source-admission-"),+ );+ const source = join(workspace, "caller-selected.%PATH%");+ try {+ const original = await readFile(target.path);+ await writeFile(source, original);+ await call("close_binary");+ const opened = await call("open_binary", {+ path: source,+ provider_id: "ghidra",+ });+ assert.equal(opened.sha256, target.sha256);+ const selectedPath = await realpath(source);+ assert.equal(opened.path, selectedPath);+ const before = await call("binary_session");+ const changed = Buffer.concat([+ original,+ Buffer.from("REA_SOURCE_CHANGED_AFTER_OPEN"),+ ]);+ const changedSha256 = createHash("sha256").update(changed).digest("hex");+ await writeFile(source, changed);+ const failure = await reject("analyze_function", { procedure: entry });+ assert.equal(failure.code, "artifact_changed");+ assert.equal(failure.category, "integrity_mismatch");+ assert.equal(failure.details.operation, "analyze_function");+ assert.equal(failure.details.path, selectedPath);+ assert.ok(failure.details.reason.includes(target.sha256));+ assert.ok(failure.details.reason.includes(changedSha256));+ assert.match(failure.remediation.action, /open_binary/u);+ assert.doesNotMatch(failure.remediation.action, /doctor/u);+ const after = await call("binary_session");+ assert.equal(after.analysis_run.run_id, before.analysis_run.run_id);+ assert.equal(after.sha256, target.sha256);+ assert.equal(+ after.capabilities.find(+ ({ operation }) => operation === "analyze_function",+ )?.available,+ true,+ "An artifact identity mismatch must not mark the installed provider unavailable",+ );+ assert.deepEqual(+ (await readdir(runtimeRoot)).filter((name) =>+ name.startsWith("rea-ghidra-"),+ ),+ [],+ "Failed admission must remove the private snapshot without launching Ghidra",+ );+ assert.deepEqual(await readFile(source), changed);+ const permissionDenied = await verifySourceReadFailures({+ call,+ reject,+ source,+ bytes: changed,+ entry,+ runtimeRoot,+ });++ const reopened = await call("open_binary", {+ path: source,+ provider_id: "ghidra",+ });+ assert.equal(reopened.sha256, changedSha256);+ assert.notEqual(+ (await call("binary_session")).analysis_run.run_id,+ before.analysis_run.run_id,+ );+ const dossier = await call("analyze_function", { procedure: entry });+ const instruction = await call("inspect_native_instruction", {+ address: entry,+ });+ assert.equal(dossier.procedure.address, entry);+ assert.equal(instruction.status, "decoded");+ for (const address of [+ entry.toUpperCase(),+ entry.slice(2),+ `0x0000${entry.slice(2)}`,+ `ram:${entry}`,+ `%72%61%6D:${entry}`,+ ]) {+ assert.deepEqual(+ await call("inspect_native_instruction", { address }),+ instruction,+ );+ assert.equal(+ (await call("resolve_containing_procedure", { address })).procedure+ .address,+ entry,+ );+ }+ // Imported facts belong to the captured bytes even if the caller's path disappears.+ await rm(source);+ assert.deepEqual(+ await call("analyze_function", { procedure: entry }),+ dossier,+ );+ assert.deepEqual(+ await call("inspect_native_instruction", { address: entry }),+ instruction,+ );+ assert.equal((await call("binary_session")).sha256, changedSha256);+ await call("close_binary");+ await call("open_binary", { path: target.path, provider_id: "ghidra" });+ return { permissionDenied };+ } finally {+ await rm(workspace, { recursive: true, force: true });+ }+}++async function verifySourceReadFailures({+ call,+ reject,+ source,+ bytes,+ entry,+ runtimeRoot,+}) {+ const permissionDenied =+ typeof process.getuid === "function" && process.getuid() !== 0;+ const scenarios = [+ "missing",+ "directory",+ ...(permissionDenied ? ["permission"] : []),+ ];+ for (const scenario of scenarios) {+ await call("open_binary", { path: source, provider_id: "ghidra" });+ const before = await call("binary_session");+ if (scenario === "permission") await chmod(source, 0);+ else {+ await rm(source);+ if (scenario === "directory") await mkdir(source);+ }+ try {+ const failure = await reject("analyze_function", { procedure: entry });+ assert.equal(+ failure.code,+ scenario === "permission" ? "access_denied" : "artifact_changed",+ );+ assert.equal(failure.details.path, before.path);+ assert.equal(failure.details.operation, "analyze_function");+ if (scenario === "permission") {+ assert.ok(["EACCES", "EPERM"].includes(failure.details.system_code));+ assert.match(failure.remediation.action, /read access/u);+ } else assert.match(failure.remediation.action, /open_binary/u);+ assert.doesNotMatch(failure.remediation.action, /doctor/u);+ const after = await call("binary_session");+ assert.equal(after.analysis_run.run_id, before.analysis_run.run_id);+ assert.equal(after.sha256, before.sha256);+ assert.equal(+ after.capabilities.find(+ ({ operation }) => operation === "analyze_function",+ )?.available,+ true,+ );+ assert.deepEqual(+ (await readdir(runtimeRoot)).filter((name) =>+ name.startsWith("rea-ghidra-"),+ ),+ [],+ );+ } finally {+ if (scenario === "permission") await chmod(source, 0o600);+ await rm(source, { recursive: true, force: true });+ await writeFile(source, bytes);+ }+ }+ return permissionDenied;+}diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.tsindex ff1823897..56b0ad273 100644--- a/src/domain/analysisErrorPresentation.ts+++ b/src/domain/analysisErrorPresentation.ts@@ -75,7 +75,7 @@ export const analysisErrorRemediationAction = (if (error instanceof AnalysisAccessDeniedError)return "Check the current process's read access to the selected path. Retry with a readable local file.";if (error instanceof AnalysisArtifactChangedError)- return "Wait until the selected file is stable, then retry this operation.";+ return "Wait until the selected file is stable. For an active binary session, reopen the target with open_binary before retrying so REA acquires its current identity; for a CLI command or target-free tool, rerun the operation.";if (error instanceof AnalysisInputError)return "Correct the listed arguments and retry.";if (error instanceof UnknownRegistryError && error.reason === "not-found")diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.tsindex 00a1cfa87..aed08e04b 100644--- a/src/ghidra/GhidraProviderClient.ts+++ b/src/ghidra/GhidraProviderClient.ts@@ -11,6 +11,8 @@ import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";import type { BinaryTarget } from "../domain/binaryTarget.js";import {AnalysisCancelledError,+ AnalysisArtifactChangedError,+ AnalysisAccessDeniedError,AnalysisCapabilityUnavailableError,AnalysisInputError,AnalysisResourceConstraintError,@@ -319,6 +321,20 @@ const projectSessionError = (operation: AnalysisOperation,failure: GhidraSessionError,): AnalysisError => {+ if (failure.cause instanceof AnalysisAccessDeniedError)+ return new AnalysisAccessDeniedError(+ operation,+ failure.cause.path,+ failure.cause.systemCode,+ { cause: failure },+ );+ if (failure.cause instanceof AnalysisArtifactChangedError)+ return new AnalysisArtifactChangedError(+ operation,+ failure.cause.path,+ failure.cause.reason,+ { cause: failure },+ );if (operation === "annotate_native_function" &&failure.kind === "remote" &&diff --git a/src/ghidra/GhidraTargetSnapshot.ts b/src/ghidra/GhidraTargetSnapshot.tsindex d30618d0f..b6447bc75 100644--- a/src/ghidra/GhidraTargetSnapshot.ts+++ b/src/ghidra/GhidraTargetSnapshot.ts@@ -1,9 +1,15 @@import { createHash } from "node:crypto";-import { constants, createReadStream } from "node:fs";-import { chmod, copyFile, rm } from "node:fs/promises";+import { constants } from "node:fs";+import { open, rm, type FileHandle } from "node:fs/promises";import { extname, join } from "node:path";+import { Transform } from "node:stream";+import { pipeline } from "node:stream/promises";import type { JsonValue } from "../domain/jsonValue.js";+import {+ AnalysisArtifactChangedError,+ AnalysisAccessDeniedError,+} from "../domain/analysisErrorCore.js";import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";/** Immutable target copy admitted to one ephemeral Ghidra import. */@@ -37,7 +43,9 @@ export const createGhidraTargetSnapshot = async (options.signal,);if (observed.sha256 !== expectedSha256)- throw new Error(+ throw new AnalysisArtifactChangedError(+ "open_binary",+ sourcePath,`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`,);return {@@ -46,23 +54,71 @@ export const createGhidraTargetSnapshot = async (admission: { source: observed.source, snapshot: observed.snapshot },};}+ let source: FileHandle | undefined;+ let destination: FileHandle | undefined;try {- await copyFile(sourcePath, snapshotPath, constants.COPYFILE_EXCL);- await chmod(snapshotPath, 0o600);+ source = await openSnapshotSource(sourcePath);+ if (!(await source.stat()).isFile())+ throw new AnalysisArtifactChangedError(+ "open_binary",+ sourcePath,+ "The selected Ghidra source is no longer a regular file",+ );+ destination = await open(snapshotPath, "wx", 0o600);+ await destination.chmod(0o600);const hash = createHash("sha256");- for await (const chunk of createReadStream(snapshotPath))- hash.update(chunk);+ const digest = new Transform({+ transform(chunk: unknown, _encoding, done) {+ if (!Buffer.isBuffer(chunk)) {+ done(new TypeError("Ghidra snapshot stream must contain bytes"));+ return;+ }+ hash.update(chunk);+ done(null, chunk);+ },+ });+ await pipeline(+ source.createReadStream(),+ digest,+ destination.createWriteStream(),+ options.signal === undefined ? {} : { signal: options.signal },+ );const observedSha256 = hash.digest("hex");if (observedSha256 !== expectedSha256)- throw new Error(+ throw new AnalysisArtifactChangedError(+ "open_binary",+ sourcePath,`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`,);return { path: snapshotPath, sha256: observedSha256 };} catch (cause: unknown) {- await rm(snapshotPath, { force: true }).catch((cause: unknown) => {- // best-effort cleanup: snapshot removal must not mask the copy failure.- void cause;- });+ if (destination !== undefined)+ await rm(snapshotPath, { force: true }).catch((cause: unknown) => {+ // best-effort cleanup: snapshot removal must not mask the copy failure.+ void cause;+ });+ throw cause;+ } finally {+ await Promise.all([source?.close(), destination?.close()]);+ }+};++const openSnapshotSource = async (path: string): Promise<FileHandle> => {+ try {+ // A path replaced by a FIFO must not block startup before its type is checked.+ return await open(path, constants.O_RDONLY | constants.O_NONBLOCK);+ } catch (cause: unknown) {+ const code =+ cause instanceof Error && "code" in cause ? cause.code : undefined;+ if (code === "EACCES" || code === "EPERM")+ throw new AnalysisAccessDeniedError("open_binary", path, code, { cause });+ if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")+ throw new AnalysisArtifactChangedError(+ "open_binary",+ path,+ `The selected Ghidra source could not be opened (${code})`,+ { cause },+ );throw cause;}};diff --git a/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts b/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.tsindex 30e796d15..13660b944 100644--- a/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts+++ b/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts@@ -1,20 +1,16 @@import { createHash } from "node:crypto";-import { access, readFile, rm, writeFile } from "node:fs/promises";+import { readFile, rm, writeFile } from "node:fs/promises";import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";-import { createGhidraTestRuntime } from "../../../fixtures/ghidraRuntime.js";-import type { PrivateRuntimeRoot } from "../../../../src/process/PrivateRuntimeRoot.js";import { createGhidraTargetSnapshot } from "../../../../src/ghidra/GhidraTargetSnapshot.js";const roots: string[] = [];-const runtimes: PrivateRuntimeRoot[] = [];afterEach(async () => {- await Promise.all(runtimes.splice(0).map((runtime) => runtime.close()));await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),);@@ -34,51 +30,11 @@ describe("Ghidra target snapshot", () => {expect(snapshot.admission).toBeUndefined();await expect(readFile(snapshot.path)).resolves.toEqual(bytes);await expect(- createGhidraTargetSnapshot(source, root, sha256, { platform: "win32" }),- ).rejects.toThrow(/No native private runtime owns/u);- });- it("copies an exact digest-bound target into the private runtime", async () => {- const root = await createTestTempDirectory("rea-ghidra-snapshot-");- roots.push(root);- const source = join(root, "source.exe");- const bytes = Buffer.from("native PE fixture");- const sha256 = createHash("sha256").update(bytes).digest("hex");- await writeFile(source, bytes);- const runtime = await createGhidraTestRuntime(root);- runtimes.push(runtime);-- const snapshot = await createGhidraTargetSnapshot(- source,- runtime.path,- sha256,- );-- expect(snapshot).toMatchObject({- path: join(runtime.path, `target-${sha256.slice(0, 12)}.exe`),- sha256,- });+ createGhidraTargetSnapshot(source, root, sha256, { platform: "linux" }),+ ).rejects.toMatchObject({ code: "EEXIST" });await expect(readFile(snapshot.path)).resolves.toEqual(bytes);- });-- it("rejects a mismatched digest and removes the failed runtime snapshot", async () => {- const root = await createTestTempDirectory("rea-ghidra-snapshot-");- roots.push(root);- const source = join(root, "source with unsafe extension.%PATH%");- await writeFile(source, "changed target");- const runtime = await createGhidraTestRuntime(root);- runtimes.push(runtime);- const expected = "a".repeat(64);- const snapshotPath = join(- runtime.path,- `target-${expected.slice(0, 12)}.bin`,- );-await expect(- createGhidraTargetSnapshot(source, runtime.path, expected),- ).rejects.toThrow(/digest mismatch/u);- await runtime.close();- await expect(access(snapshotPath)).rejects.toMatchObject({- code: "ENOENT",- });+ createGhidraTargetSnapshot(source, root, sha256, { platform: "win32" }),+ ).rejects.toThrow(/No native private runtime owns/u);});});