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(cli): resolve xrefs symbol selectors after address validation (#1209)
Ysopwnable7e9c91199ecd
diff --git a/scripts/lib/real-ghidra-entry-aliases.mjs b/scripts/lib/real-ghidra-entry-aliases.mjsindex 3230ed6d1..5a38c7061 100644--- a/scripts/lib/real-ghidra-entry-aliases.mjs+++ b/scripts/lib/real-ghidra-entry-aliases.mjs@@ -45,6 +45,21 @@ export async function verifyGhidraEntryAliases({({ address }) => address === alias.address,);assert.ok(canonical, "Fixture alias is not at a function entry");+ const xrefsSelectors = [];+ for (const value of [+ canonical.value,+ alias.value,+ `${prefix}rea_xrefs_data`,+ `${prefix}rea_xrefs_unreferenced`,+ ]) {+ const symbol = names.find((item) => item.value === value);+ assert.ok(symbol, `Missing xrefs selector ${value}`);+ const expected = await call("xrefs", { address: symbol.address });+ if (value === `${prefix}rea_xrefs_unreferenced`)+ assert.deepEqual(expected, []);+ else assert.ok(expected.length > 0, `Missing references for ${value}`);+ xrefsSelectors.push({ symbol, expected });+ }for (const procedure of [alias.value,"dead",@@ -118,6 +133,55 @@ export async function verifyGhidraEntryAliases({JSON.parse(stdout).normalized_result.procedure.address,alias.address,);+ for (const { symbol, expected } of xrefsSelectors) {+ for (const selector of [+ [symbol.value],+ ["--address", symbol.value],+ [symbol.address],+ ]) {+ const { stdout } = await exec(+ process.execPath,+ [+ entrypoint,+ "xrefs",+ path,+ ...selector,+ "--provider",+ "ghidra",+ "--json",+ ],+ { env, timeout: 240000, maxBuffer: 16 * 1024 * 1024 },+ );+ const evidence = JSON.parse(stdout);+ assert.deepEqual(evidence.normalized_result, expected);+ assert.equal(evidence.parameters.address, selector.at(-1));+ }+ }+ await assert.rejects(+ exec(+ process.execPath,+ [+ entrypoint,+ "xrefs",+ path,+ "rea_missing_symbol",+ "--provider",+ "ghidra",+ "--json",+ ],+ { env, timeout: 240000, maxBuffer: 16 * 1024 * 1024 },+ ),+ (error) => {+ const failure = JSON.parse(error.stdout);+ assert.equal(failure.code, "invalid_request");+ assert.equal(failure.details.operation, "xrefs");+ assert.match(+ JSON.stringify(failure.details.issues),+ /Unknown analyzed symbol name.*rea_missing_symbol/u,+ );+ return true;+ },+ );assert.deepEqual(await readFile(path), bytes);await call("open_binary", { path: target.path, provider_id: "ghidra" });} finally {diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.tsindex f9f15244f..1f66ec8c8 100644--- a/src/application/DirectAnalysis.ts+++ b/src/application/DirectAnalysis.ts@@ -48,6 +48,8 @@ import {} from "./WorkflowEvidence.js";import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";+import { resolveXrefsAddress } from "./XrefsAddressResolution.js";+import { AnalysisInputError } from "../domain/analysisErrorCore.js";type DirectAnalysisTool =| "annotate_native_function"@@ -356,7 +358,34 @@ const executeAnalysisTool = async (input: {});return { output: evidence, evidence };}- const result = await session.execute(tool, input.arguments, { signal });+ let result = await session.execute(tool, input.arguments, { signal });+ if (+ tool === "xrefs" &&+ typeof input.arguments.address === "string" &&+ !result.ok &&+ result.error instanceof AnalysisInputError &&+ !result.error.cleanupIncomplete &&+ result.error.issues.length > 0 &&+ result.error.issues.every(+ ({ path, reason }) =>+ path.length === 1 &&+ path[0] === "address" &&+ reason === "invalid_format",+ )+ ) {+ const address = await resolveXrefsAddress(+ session,+ input.arguments.address,+ signal,+ );+ if (!address.ok) return { output: cliError(address.error) };+ if (address.value !== input.arguments.address)+ result = await session.execute(+ tool,+ { ...input.arguments, address: address.value },+ { signal },+ );+ }if (!result.ok) return { output: cliError(result.error) };const evidence = createEvidence(result.value.subject ?? input.openedTarget,diff --git a/src/application/XrefsAddressResolution.ts b/src/application/XrefsAddressResolution.tsnew file mode 100644index 000000000..c7eef8bdc--- /dev/null+++ b/src/application/XrefsAddressResolution.ts@@ -0,0 +1,81 @@+import { addressedValue } from "../contracts/toolOutputSchemaPrimitives.js";+import type { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCapabilityUnavailableError,+ AnalysisInputError,+ AnalysisOutputError,+} from "../domain/analysisErrorCore.js";+import { err, ok, type Result } from "../domain/result.js";+import type { AnalysisOperationPort } from "./AnalysisProvider.js";+import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";++/** Resolve a CLI symbol selector without changing existing address spellings. */+export const resolveXrefsAddress = async (+ analysis: AnalysisOperationPort,+ selector: string,+ signal: AbortSignal,+): Promise<Result<string, AnalysisError>> => {+ if (+ selector.length === 0 ||+ /^[0-9a-f]+$/iu.test(selector) ||+ /^0x/iu.test(selector) ||+ /:0x/iu.test(selector)+ )+ return ok(selector);++ const inventory = await analysis.execute("list_names", {}, { signal });+ if (!inventory.ok) {+ if (+ inventory.error instanceof AnalysisCapabilityUnavailableError &&+ inventory.error.operation === "list_names" &&+ !inventory.error.cleanupIncomplete+ )+ return resolveProcedureAddress(+ async (operation, parameters, signal) => {+ const result = await analysis.execute(+ operation,+ parameters,+ signal === undefined ? {} : { signal },+ );+ return result.ok ? ok(result.value.result) : result;+ },+ selector,+ signal,+ );+ return inventory;+ }+ if (!Array.isArray(inventory.value.result))+ return err(+ new AnalysisOutputError(+ "list_names",+ "Expected a symbol inventory array",+ ),+ );++ const addresses = new Set<string>();+ for (const [index, item] of inventory.value.result.entries()) {+ const parsed = addressedValue.safeParse(item);+ if (!parsed.success || parsed.data.address.length === 0)+ return err(+ new AnalysisOutputError(+ "list_names",+ `Invalid symbol inventory entry at index ${index}`,+ ),+ );+ if (parsed.data.value === selector) addresses.add(parsed.data.address);+ }+ const [address] = addresses;+ if (addresses.size === 1 && address !== undefined) return ok(address);+ return err(+ new AnalysisInputError("xrefs", undefined, [+ {+ path: ["address"],+ reason: "invalid_value",+ message:+ addresses.size === 0+ ? `Unknown analyzed symbol name ${JSON.stringify(selector)}. Use an exact analyzed name or a hexadecimal address.`+ : `Analyzed symbol name ${JSON.stringify(selector)} is ambiguous at ${[...addresses].join(", ")}. Select an exact address.`,+ },+ ]),+ );+};diff --git a/tests/composition/directAnalysisXrefs.test.ts b/tests/composition/directAnalysisXrefs.test.tsnew file mode 100644index 000000000..5e1d998a6--- /dev/null+++ b/tests/composition/directAnalysisXrefs.test.ts@@ -0,0 +1,238 @@+import { describe, expect, it } from "vitest";+import { runDirectAnalysis } from "../../src/application/DirectAnalysis.js";+import type { DirectAnalysisDependencies } from "../../src/application/DirectAnalysisDependencies.js";+import type { AnalysisError } from "../../src/domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisCapabilityUnavailableError,+ AnalysisInputError,+} from "../../src/domain/analysisErrorCore.js";+import { parseEvidence } from "../../src/domain/evidence.js";+import { err } from "../../src/domain/result.js";+import { observed } from "../fixtures/analysisExecution.js";+import {+ createBinarySessionTargets,+ createTestBinarySession,+} from "../fixtures/binarySession.js";++const inventory = [+ { address: "0x1000", value: "table_only" },+ { address: "0x1000", value: "entry_alias" },+ { address: "0x1000", value: "namespace::function" },+ { address: "0x2000", value: "data_symbol" },+ { address: "0x3000", value: "unreferenced" },+ { address: "0x1000", value: "same_address" },+ { address: "0x1000", value: "same_address" },+ { address: "0x1000", value: "ambiguous" },+ { address: "0x2000", value: "ambiguous" },+];++const fixture = (+ options: {+ readonly inventoryError?: AnalysisError;+ readonly malformedInventory?: boolean;+ readonly acceptsNamedSelectors?: boolean;+ readonly xrefsError?: AnalysisInputError;+ } = {},+) => {+ let closed = 0;+ const createSession = () =>+ createTestBinarySession(() => ({+ execute: (operation, parameters) => {+ if (operation === "list_names")+ return Promise.resolve(+ options.inventoryError !== undefined+ ? err(options.inventoryError)+ : observed(+ options.malformedInventory ? "not an inventory" : inventory,+ ),+ );+ if (operation === "procedure_address")+ return Promise.resolve(observed("0x1000"));+ if (operation === "xrefs") {+ if (options.xrefsError !== undefined)+ return Promise.resolve(err(options.xrefsError));+ const address = parameters.address;+ if (+ !options.acceptsNamedSelectors &&+ (typeof address !== "string" ||+ !/^(?:(?:0[xX])?[0-9a-fA-F]+|space%20name:0[xX][0-9a-fA-F]+)$/u.test(+ address,+ ))+ )+ return Promise.resolve(+ err(+ new AnalysisInputError("xrefs", undefined, [+ { path: ["address"], reason: "invalid_format" },+ ]),+ ),+ );+ return Promise.resolve(+ observed(address === "0x3000" ? [] : ["0x4000"]),+ );+ }+ return Promise.resolve(observed(null));+ },+ close: () => {+ closed += 1;+ return Promise.resolve();+ },+ }));+ const dependencies: DirectAnalysisDependencies = {+ createBinarySession: createSession,+ createManagedBinarySession: createSession,+ };+ return { dependencies, closed: () => closed };+};++describe("direct CLI cross-reference selectors", () => {+ it("retains validation issues unrelated to symbol resolution", async () => {+ const [path] = await createBinarySessionTargets();+ const issues = [+ { path: ["address"], reason: "invalid_format" },+ { path: ["extra"], reason: "unknown_argument" },+ ] as const;+ const provider = fixture({+ xrefsError: new AnalysisInputError("xrefs", undefined, issues),+ });+ const result = await runDirectAnalysis(+ provider.dependencies,+ path,+ "xrefs",+ { address: "table_only", extra: true },+ );+ expect(result).toMatchObject({+ code: "invalid_request",+ details: { operation: "xrefs", issues },+ });+ expect(provider.closed()).toBe(1);+ });+ it.each(["hidden_alias", "dead"])(+ "retains the provider's existing interpretation of %s",+ async (address) => {+ const [path] = await createBinarySessionTargets();+ const provider = fixture({+ acceptsNamedSelectors: true,+ malformedInventory: true,+ });+ const evidence = parseEvidence(+ await runDirectAnalysis(provider.dependencies, path, "xrefs", {+ address,+ }),+ );+ expect(evidence.parameters).toEqual({ address });+ expect(evidence.normalized_result).toEqual(["0x4000"]);+ expect(provider.closed()).toBe(1);+ },+ );+ it.each([+ "table_only",+ "entry_alias",+ "namespace::function",+ "data_symbol",+ "same_address",+ "0x1000",+ "1000",+ "0X1000",+ "space%20name:0x1000",+ ])(+ "inspects %s and retains the original selector in Evidence",+ async (address) => {+ const [path] = await createBinarySessionTargets();+ const provider = fixture();+ const evidence = parseEvidence(+ await runDirectAnalysis(provider.dependencies, path, "xrefs", {+ address,+ }),+ );+ expect(evidence.parameters).toEqual({ address });+ expect(evidence.normalized_result).toEqual(["0x4000"]);+ expect(provider.closed()).toBe(1);+ },+ );++ it("distinguishes a resolved unreferenced symbol from an unknown name", async () => {+ const [path] = await createBinarySessionTargets();+ const provider = fixture();+ const empty = parseEvidence(+ await runDirectAnalysis(provider.dependencies, path, "xrefs", {+ address: "unreferenced",+ }),+ );+ expect(empty.normalized_result).toEqual([]);+ const missing = await runDirectAnalysis(+ provider.dependencies,+ path,+ "xrefs",+ {+ address: "missing_symbol",+ },+ );+ expect(missing).toMatchObject({+ code: "invalid_request",+ details: { operation: "xrefs", issues: [{ path: ["address"] }] },+ });+ expect(JSON.stringify(missing)).toContain("missing_symbol");+ expect(provider.closed()).toBe(2);+ });++ it("reports every candidate for an ambiguous exact name", async () => {+ const [path] = await createBinarySessionTargets();+ const provider = fixture();+ const result = await runDirectAnalysis(+ provider.dependencies,+ path,+ "xrefs",+ {+ address: "ambiguous",+ },+ );+ expect(result).toMatchObject({ code: "invalid_request" });+ expect(JSON.stringify(result)).toContain("0x1000");+ expect(JSON.stringify(result)).toContain("0x2000");+ expect(provider.closed()).toBe(1);+ });++ it("uses procedure resolution when the provider has no symbol inventory", async () => {+ const [path] = await createBinarySessionTargets();+ const provider = fixture({+ inventoryError: new AnalysisCapabilityUnavailableError(+ "fixture",+ "list_names",+ "only procedure inventory is supported",+ ),+ });+ const evidence = parseEvidence(+ await runDirectAnalysis(provider.dependencies, path, "xrefs", {+ address: "table_only",+ }),+ );+ expect(evidence.parameters).toEqual({ address: "table_only" });+ expect(evidence.normalized_result).toEqual(["0x4000"]);+ expect(provider.closed()).toBe(1);+ });++ it.each([+ {+ options: { inventoryError: new AnalysisCancelledError("list_names") },+ code: "cancelled",+ },+ { options: { malformedInventory: true }, code: "unreadable_output" },+ ])(+ "preserves $code from inventory resolution and releases the session",+ async ({ options, code }) => {+ const [path] = await createBinarySessionTargets();+ const provider = fixture(options);+ const result = await runDirectAnalysis(+ provider.dependencies,+ path,+ "xrefs",+ {+ address: "table_only",+ },+ );+ expect(result).toMatchObject({ code });+ expect(provider.closed()).toBe(1);+ },+ );+});diff --git a/tests/conformance/ghidra/entry-aliases.c b/tests/conformance/ghidra/entry-aliases.cindex 3f9982044..25493f737 100644--- a/tests/conformance/ghidra/entry-aliases.c+++ b/tests/conformance/ghidra/entry-aliases.c@@ -5,10 +5,13 @@#define REA_SYMBOL(name) name#endif+volatile int rea_xrefs_data = 17;+__attribute__((used)) volatile int rea_xrefs_unreferenced = 41;+__attribute__((noinline, used)) int rea_alias_target(void) {__asm__ volatile(".globl " REA_SYMBOL("rea_interior") "\n"REA_SYMBOL("rea_interior") ":");- return 17;+ return rea_xrefs_data;}__asm__(".globl " REA_SYMBOL("rea_entry_alias") "\n"