diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index ea36e445c3..eea93ea39e 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1848,7 +1848,7 @@ Each line is `addresskind[name]`, where kind is `function`, `code` or Label seeds can name mapped uninitialized storage such as `.bss`; function and code seeds require initialized bytes. -When Ghidra has no function for a requested procedure, the error's remediation names this seed recovery. A `resolve_containing_procedure` result of `not_in_procedure` carries it as a limitation. Neither establishes that the address holds code. Seeds apply only to a fresh import, so a session with `REA_GHIDRA_PROJECT_PATH` or `REA_GHIDRA_CHECKPOINT_DIR` names the setting to unset first. +When Ghidra has no function for a requested procedure, the error's remediation names this seed recovery. A `resolve_containing_procedure` result of `not_in_procedure` carries it as a limitation, and an `inspect_native_instruction` result with status `not-in-listing` carries the `code` seed variant. None of these establishes that the address holds code. Seeds apply only to a fresh import, so a session with `REA_GHIDRA_PROJECT_PATH` or `REA_GHIDRA_CHECKPOINT_DIR` names the setting to unset first. To skip a named Ghidra auto-analyzer (for example, when default auto-analysis stalls in one analyzer on a Swift/Objective-C arm64 Mach-O): diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts index 5a60537c62..9a8c511882 100644 --- a/src/ghidra/GhidraProvider.behavior.test.ts +++ b/src/ghidra/GhidraProvider.behavior.test.ts @@ -22,6 +22,7 @@ import { ghidraEmptyOutgoingReferencesLimitation, ghidraEmptyXrefsLimitation, ghidraFunctionSeedRecovery, + ghidraNotInListingLimitation, ghidraNotInProcedureLimitation, limitationsFor, type GhidraSessionSource, @@ -4144,6 +4145,31 @@ describe("Ghidra empty instruction reference facets", () => { expect(limitations).not.toContain(ghidraEmptyXrefsLimitation); expect(limitations).not.toContain(ghidraEmptyInstructionOutgoingLimitation); }); + + it("names the code seed recovery when the address is not in Ghidra's listing", async () => { + const limitations = await executeInspect({ + ...compactInstruction(), + status: "not-in-listing", + bytes: null, + length: null, + mnemonic: null, + raw_disassembly: null, + incoming_references: [compactReference()], + }); + expect( + limitations.filter((item) => item.includes("REA_GHIDRA_SEED_FILE")), + ).toEqual([ghidraNotInListingLimitation("fresh-import")]); + }); + + it.each([ + ["decoded", instruction([compactReference()], [compactReference()])], + ["data", definedData([compactReference()])], + ])("adds no seed recovery to a %s instruction answer", async (_, result) => { + const limitations = await executeInspect(result); + expect( + limitations.some((item) => item.includes("REA_GHIDRA_SEED_FILE")), + ).toBe(false); + }); }); describe("Ghidra containing-procedure absence", () => { diff --git a/src/ghidra/GhidraProviderCapabilities.ts b/src/ghidra/GhidraProviderCapabilities.ts index fe7ff893ac..13b79f6295 100644 --- a/src/ghidra/GhidraProviderCapabilities.ts +++ b/src/ghidra/GhidraProviderCapabilities.ts @@ -123,6 +123,15 @@ export const ghidraNotInProcedureLimitation = ( ): string => `Ghidra has no function at or containing this address in this session. This reflects the current function inventory, not proof that the address holds no code. ${ghidraFunctionSeedRecovery(source)}`; +/** + * Attached to a not-in-listing instruction: Ghidra attempted no decode, so the + * answer does not show the bytes are data. Names the `code` seed recovery. + */ +export const ghidraNotInListingLimitation = ( + source: GhidraSessionSource, +): string => + `Ghidra's listing has no instruction or defined data at this address in this session, so no decode was attempted; this is not proof that the bytes are not code. If they are initialized code that auto-analysis did not reach, declare the address as a \`code\` seed, or a \`function\` seed for an entry point, in REA_GHIDRA_SEED_FILE for a new REA process${seedSessionRestriction[source]}; that session's seed outcome limitation counts decoded, failed and unmapped seeds.`; + /** Limitation text for one admitted operation, including the common base. */ export const limitationsFor = ( operation: string, diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts index 7846c02644..885e86d2f1 100644 --- a/src/ghidra/GhidraProviderClient.ts +++ b/src/ghidra/GhidraProviderClient.ts @@ -143,6 +143,7 @@ import { ghidraEmptyInstructionOutgoingLimitation, ghidraEmptyOutgoingReferencesLimitation, ghidraFunctionSeedRecovery, + ghidraNotInListingLimitation, ghidraNotInProcedureLimitation, windowsP0Limitations, limitationsFor, @@ -346,6 +347,22 @@ const containingProcedureAbsenceCaveat = ( : []; }; +/** + * Caveat for an instruction query in mapped memory that Ghidra's listing does + * not cover: no decode was attempted, so code there remains possible. + */ +const instructionListingAbsenceCaveat = ( + operation: GhidraFunctionOperation, + normalized: JsonValue, + source: GhidraSessionSource, +): readonly string[] => { + if (operation !== "inspect_native_instruction") return []; + const record = referenceObservationRecord(normalized); + return record?.status === "not-in-listing" + ? [ghidraNotInListingLimitation(source)] + : []; +}; + /** Build one AnalysisClient for an admitted Ghidra target and profile. */ export const createGhidraProviderClient = (input: { readonly config: AppConfig; @@ -1139,7 +1156,14 @@ export const createGhidraProviderClient = (input: { let { value: normalized, ...observation } = result.value; let executionMetadata: GhidraExecutionMetadata = observation; const absenceCaveats = isGhidraFunctionOperation(operation) - ? emptyReferenceCaveat(operation, normalized) + ? [ + ...emptyReferenceCaveat(operation, normalized), + ...instructionListingAbsenceCaveat( + operation, + normalized, + projection.source, + ), + ] : containingProcedureAbsenceCaveat( operation, normalized,