Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(ghidra): qualify defined-string search coverage

morluto4733fc810a8b
diff --git a/docs/ghidra-provider.md b/docs/ghidra-provider.md
index 3151ccbb7..af95d0ab4 100644
--- a/docs/ghidra-provider.md
+++ b/docs/ghidra-provider.md
@@ -29,9 +29,15 @@ not equivalence with another engine's pseudocode or analysis database.
| Strings | Only Ghidra-defined string `Data` is observed. Items report charset, byte length, and whether a required null terminator is missing. The API cannot distinguish a present terminator from fixed/Pascal layouts when no terminator is missing, so that state is named `present_or_not_required`. |
| Memory | Memory-block end addresses are exclusive. Read/write/execute, initialization, overlay, address space, and image base are direct Ghidra observations. |
| Inventory | Procedure, symbol, and string listings plus searches return the complete matching collection in one response; callers do not provide offsets or result-count limits. |
-| Search | Literal and Java-regex searches scan the complete immutable inventory and return all matching entries inline. Search waits for a reply or caller cancellation; there are no caller-supplied offsets or result-count limits. |
+| Search | Literal and Java-regex searches return every match in the immutable provider-defined inventory; string search does not cover every text sequence in artifact bytes. Search waits for a reply or caller cancellation; there are no caller-supplied offsets or result-count limits. |
| Analysis state | The socket is exposed only after default auto-analysis completes. Established operations wait for their reply or caller cancellation; there is no fixed response-size ceiling. |
+String-search completeness applies only to Ghidra-defined string `Data`. Packed
+or undefined literals, including Rust strings, may be absent; an empty result
+does not prove text is absent. Both list and search Evidence carry this
+limitation. When an address is known, use `read_bytes` and `xrefs` to inspect
+bytes and references.
+
## Admitted function-analysis semantics
| Concern | Ghidra contract |
diff --git a/scripts/lib/real-ghidra-boundaries.mjs b/scripts/lib/real-ghidra-boundaries.mjs
index 849815b84..83cc74b22 100644
--- a/scripts/lib/real-ghidra-boundaries.mjs
+++ b/scripts/lib/real-ghidra-boundaries.mjs
@@ -58,6 +58,15 @@ export async function verifyGhidraBoundaries(
`${name}: ${JSON.stringify(validate.errors)}`,
);
assert.deepEqual(reply.structuredContent, JSON.parse(mcpTextValue(reply)));
+ if (name === "list_strings" || name === "search_strings")
+ assert.ok(
+ reply.structuredContent.limitations.some((limitation) =>
+ /Only Ghidra-defined string Data.*empty search does not establish/u.test(
+ limitation,
+ ),
+ ),
+ `${name} omitted defined-string coverage`,
+ );
successfulCalls++;
return result;
};
@@ -378,6 +387,12 @@ export async function verifyGhidraBoundaries(
).some((item) => item.address === marker.address),
false,
);
+ assert.deepEqual(
+ await call("search_strings", {
+ pattern: `REA_GHIDRA_ABSENT_${randomUUID()}`,
+ }),
+ [],
+ );
assert.equal(
(await call("inspect_native_instruction", { address: strings[0].address }))
.status,
diff --git a/src/contracts/officialToolContracts.ts b/src/contracts/officialToolContracts.ts
index 73ca89e48..811b66c90 100644
--- a/src/contracts/officialToolContracts.ts
+++ b/src/contracts/officialToolContracts.ts
@@ -196,7 +196,7 @@ export const OFFICIAL_TOOL_CONTRACTS = [
),
official(
"search_strings",
- "Search every analyzed string object using literal matching by default or regex when requested. Results are deterministic and complete over the native inventory. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.",
+ "Search every provider-defined string object using literal matching by default or regex when requested. Results are deterministic and complete over those defined objects, not every text sequence in artifact bytes. Ghidra may omit packed or undefined literals, including Rust strings; an empty result does not prove text is absent. If an address is known, read_bytes and xrefs inspect its bytes and references. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.",
z.object(analysisSearchInput),
),
official(
diff --git a/src/ghidra/GhidraAnalysisProfile.ts b/src/ghidra/GhidraAnalysisProfile.ts
index 84677fb5f..59113b3b8 100644
--- a/src/ghidra/GhidraAnalysisProfile.ts
+++ b/src/ghidra/GhidraAnalysisProfile.ts
@@ -67,6 +67,7 @@ export const resolveGhidraAnalysisProfile = (
load_image_observations: "source-mappings-entry-context-v2",
function_body_evidence: "complete-inclusive-ranges-v1",
function_references: "complete-body-and-entry-reference-manager-v2",
+ string_inventory_evidence: "defined-data-coverage-v1",
location_resolution: "explicit-address-exact-entry-symbol-first-v3",
instruction_flow_evidence: "decoded-return-pcode-v1",
process_launch:
diff --git a/src/ghidra/GhidraProviderCapabilities.ts b/src/ghidra/GhidraProviderCapabilities.ts
index 943380789..b64b49d7f 100644
--- a/src/ghidra/GhidraProviderCapabilities.ts
+++ b/src/ghidra/GhidraProviderCapabilities.ts
@@ -37,6 +37,12 @@ export const windowsP0Limitations = Object.freeze([
"Windows sessions require the matching packaged Windows x64 native addon, local NTFS targets and runtimes, and Windows 10 or later. Native handles enforce path admission, private DACLs, and Job Object ownership automatically.",
]);
+const stringInventoryLimitation =
+ "Only Ghidra-defined string Data is observed; packed or undefined string bytes may be absent. Completeness applies to that inventory, and an empty search does not establish that text is absent from the artifact. If an address is known, use read_bytes and xrefs to inspect bytes and references.";
+
+const searchLimitation =
+ "Regex mode uses Java Pattern semantics. Matcher or compiler stack exhaustion returns a resource constraint without closing the session; literal mode avoids regex recursion and returns complete matching values.";
+
/** Limitation text for one admitted operation, including the common base. */
export const limitationsFor = (operation: string): readonly string[] => {
const common = [
@@ -93,7 +99,8 @@ export const limitationsFor = (operation: string): readonly string[] => {
case "list_strings":
return [
...common,
- "Only Ghidra-defined string Data is observed; charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
+ stringInventoryLimitation,
+ "Charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
];
case "resolve_containing_procedure":
return [
@@ -106,11 +113,9 @@ export const limitationsFor = (operation: string): readonly string[] => {
"Memory-block end addresses are exclusive; permissions come from Ghidra MemoryBlock flags rather than inference from section names.",
];
case "search_procedures":
+ return [...common, searchLimitation];
case "search_strings":
- return [
- ...common,
- "Regex mode uses Java Pattern semantics. Matcher or compiler stack exhaustion returns a resource constraint without closing the session; literal mode avoids regex recursion and returns complete matching values.",
- ];
+ return [...common, stringInventoryLimitation, searchLimitation];
case "procedure_pseudo_code":
return [
...common,
diff --git a/tests/boundary/mcp/ghidraInventoryMcp.test.ts b/tests/boundary/mcp/ghidraInventoryMcp.test.ts
index 23bb6035f..b24dac153 100644
--- a/tests/boundary/mcp/ghidraInventoryMcp.test.ts
+++ b/tests/boundary/mcp/ghidraInventoryMcp.test.ts
@@ -3,7 +3,66 @@ import { expect, it } from "vitest";
import { jsonValueSchema } from "../../../src/domain/jsonValue.js";
import { ok } from "../../../src/domain/result.js";
import { ghidraFunctionIdentity } from "../../../src/domain/ghidraValues.fixture.js";
-import { connectGhidraMcp } from "./ghidraMcpHarness.js";
+import { connectGhidraMcp, sessionEvidence } from "./ghidraMcpHarness.js";
+
+it("retains defined-string coverage in empty and matching search Evidence", async () => {
+ let output = jsonValueSchema.parse([]);
+ const harness = await connectGhidraMcp("ghidra-string-coverage", () =>
+ Promise.resolve(ok(output)),
+ );
+ try {
+ for (const request of [
+ { name: "list_strings", arguments: {} },
+ { name: "search_strings", arguments: { pattern: "projection" } },
+ {
+ name: "search_strings",
+ arguments: { pattern: "projection.*", mode: "regex" },
+ },
+ ]) {
+ const reply = await harness.mcp.callTool(request);
+ expect(reply.isError).not.toBe(true);
+ const evidence = sessionEvidence(
+ harness.session,
+ reply.structuredContent,
+ );
+ expect(evidence.normalized_result).toEqual([]);
+ expect(evidence.analysis_profile?.parameters).toMatchObject({
+ string_inventory_evidence: "defined-data-coverage-v1",
+ });
+ expect(evidence.limitations).toContainEqual(
+ expect.stringMatching(
+ /Only Ghidra-defined string Data.*empty search does not establish/u,
+ ),
+ );
+ }
+ output = jsonValueSchema.parse([
+ { address: "0x401000", value: "projection cache ignored" },
+ ]);
+ const matched = await harness.mcp.callTool({
+ name: "search_strings",
+ arguments: { pattern: "projection" },
+ });
+ const evidence = sessionEvidence(
+ harness.session,
+ matched.structuredContent,
+ );
+ expect(evidence.normalized_result).toEqual(output);
+ expect(evidence.limitations).toContainEqual(
+ expect.stringContaining("Completeness applies to that inventory"),
+ );
+ output = jsonValueSchema.parse([]);
+ const procedures = await harness.mcp.callTool({
+ name: "search_procedures",
+ arguments: { pattern: "projection" },
+ });
+ expect(
+ sessionEvidence(harness.session, procedures.structuredContent)
+ .limitations,
+ ).not.toContainEqual(expect.stringContaining("Ghidra-defined string Data"));
+ } finally {
+ await harness.close();
+ }
+});
it("rejects contradictory provider output before emitting MCP Evidence", async () => {
const bytes = {