Skip to content

feat(native): expose typed incoming references at exact addresses - #1715

Merged
morluto merged 1 commit into
morluto:mainfrom
bugstan:fix/typed-incoming-native-references
Oct 11, 2026
Merged

morluto merged 1 commit into
morluto:mainfrom
bugstan:fix/typed-incoming-native-references

Conversation

@bugstan

@bugstan bugstan commented Oct 11, 2026

Copy link
Copy Markdown
Contributor

Closes #1245. Completes the typed incoming-reference portion left open after #1438.

inspect_native_instruction now returns incoming_references for the exact queried code or data address. Ghidra preserves each source/target, operand index, access kind, primary status and provider/source provenance, using deterministic address ordering and excluding synthetic entry-point references. Existing outgoing references and bare-address xrefs keep their meanings. Call-target resolution skips the incoming scan.

An empty array means the address was examined and no references were found; omitted/null coverage remains unavailable for historical Evidence or other providers. The Ghidra profile versions the new coverage, so older snapshots must be rebuilt instead of replaying results without it. Analyzer references remain static observations, not proof of literal addressing or runtime access.

Validation on Windows 11 x64 with Node 24.18.0 and npm 11.16.0:

  • Regression observed failing before the schema change, then passing; 43 focused function-value/snapshot tests pass.
  • 10 MCP reference, schema-validity and presentation tests pass.
  • npm run check, npm run check:fast, npm run docs:check, and npm run verify:test-discovery pass. The full format check used an LF checkout on NTFS; the original Windows clone uses CRLF.
  • Real Ghidra 12.1.4 and Temurin JDK 21.0.12.1: the source-owned x86 and x86_64 PE fixtures pass verifyGhidraCompactReferences through a focused real stdio MCP/CLI harness. This covers DATA/READ/WRITE, non-primary analyzer references, incoming/outgoing/full-dossier agreement, xrefs ordering, entry-point filtering, empty and targetless cases, CLI/MCP parity, and completed runtime cleanup.

Existing verification limitations: the general Windows verifier stops at its capability-list assertion because it excludes only annotate_native_function while the read-only bridge also omits naming mutations. A broader provider test run passes 39/40; its unchanged test expecting unavailable Windows native controls fails when the built addon is present. Neither unrelated assertion was changed. The complete deterministic suite and real Linux/macOS providers were not run.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T05:33:32.847507Z 1de1681 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@CassieFox23

Copy link
Copy Markdown
Contributor

TL;DR: I ran PR 1715 against real Ghidra 12.1.4 on Linux with a small C program. Every call, pointer, read and write I expected came back with the right type and source address. Two things differ from my objdump list: Ghidra types a tail jump as a call, and it adds one computed call.

Results

I built a small x86-64 ELF with gcc. I wrote the expected references from objdump -d and readelf first. Then I called inspect_native_instruction over MCP and the CLI on head (1de1681) and on base (13e03e9, the merge-base). The patch also applies to current main (2165045).

Address Expected Base Head
0x400480 call from 0x400490 no field CALL from 0x400490, match
0x400480 pointer at 0x403008 no field DATA from 0x403008, match
0x400480 jmp at 0x4004c3 no field CALL there, type differs
0x400480 nothing more no field extra COMPUTED_CALL from 0x400380
0x403010 read at 0x400480 no field READ, match
0x403010 read at 0x4004a0 no field READ, match
0x403010 write at 0x4004b0 no field WRITE, match
0x403008 read at 0x400380 no field READ, match
0x400490 call from 0x400361 no field CALL, match
0x4004a0 call from 0x400368 no field CALL, match
0x4004b0 call from 0x400371 no field CALL, match
0x4004c0 call from 0x400376 no field CALL, match
0x401124 no refs no field [], undecodable
0x400481 no refs no field [], not-instruction-boundary
0x500000 outside any section no field [], outside-memory
0x0 outside any section no field [], outside-memory
zzz bad address invalid_format error same as base

In the table, CALL stands for UNCONDITIONAL_CALL. Every row has primary set to true. Every source is default, except the computed call.

Before the PR, base xrefs gave the same source addresses as bare strings. At 0x400480 that is four, at 0x403010 three, at 0x403008 one. Head adds the type, operand and source for each.

  • Tail jump: Ghidra's flow type for that jmp is CALL_TERMINATOR. The bridge copies Ghidra's type as is. Base shows UNCONDITIONAL_CALL on the outgoing side too. So the call type is Ghidra's choice, not the PR's.
  • Extra computed call: the call at 0x400380 runs through a stored pointer. Ghidra follows it. The row has source set to analysis. Base already lists 0x400380 in xrefs for that address.

Base and head agree on every other field, over MCP and the CLI. The three changed test files pass on Node 22, 24 and 26. An old snapshot is refused on head.

I also put a data pointer in the middle of an instruction, in a second build. readelf -x .data shows it. Ghidra holds no reference there, so head returns []. That means "Ghidra holds none", not "no pointer exists".

Not run

  • The PR's own real-Ghidra check, verifyGhidraCompactReferences. Its caller only runs on Windows x64.
  • macOS, PE files, other CPUs and other providers.
  • The full test suite, npm run check and the docs checks.
  • Two of the four references on _start: 0x401168 and .gnu.build.attributes:0x40502c. I did not check them against readelf.

Thanks, bugstan, for the PR.

Details
  • Old output: I compared 34 MCP calls on base and head. I dropped three things first: the new field, evidence_id and analysis_profile. Every result then matched, including xrefs and resolve_native_call_targets. The new field never shows up in resolve_native_call_targets. The evidence_id and the profile digest do change on every tool, because the PR versions the profile.
  • CLI and MCP: the 12 CLI results equal the MCP results. CLI xrefs equals base at three addresses.
  • Old snapshot: I saved a snapshot on base and opened it on head. It fails at open_binary with evidence_integrity_mismatch. The exact text is in the fold below. Base opens its own snapshot.
  • Tests: the three changed test files pass on Node 22.23.1, 24.18.0 and 26.11.1. That is 45 of 45 each time. On base, the four new tests fail, as the PR says.
  • Entry point: _start at 0x400390 has four incoming references. One is the ELF entry field. One is an .eh_frame_hdr table entry, which I checked with readelf. None is a synthetic entry reference. The filter is the old isEntryPointReference check in addReference. I did not see the filtered reference itself.
fixture.c
volatile int g_counter = 5;
typedef int (*fn_t)(int);
__attribute__((noinline)) int target_fn(int x) { return x * 3 + (int)g_counter * 0 + 1; }
__attribute__((noinline)) int via_call(int a) { int r = target_fn(a); return r + 1; }
fn_t volatile g_fnptr = target_fn;
__attribute__((noinline)) int read_global(void) { return g_counter; }
__attribute__((noinline)) void write_global(int v) { g_counter = v; }
__attribute__((noinline)) int jump_into(int a) { return target_fn(a + 7); }
int main(int argc, char **argv) {
  (void)argv;
  int r = via_call(argc);
  r += read_global();
  write_global(r);
  r += jump_into(r);
  r += g_fnptr(r);
  return r;
}

Built with gcc -O2 -fno-pie -no-pie -fno-asynchronous-unwind-tables -fcf-protection=none. The second build adds char *volatile g_mid = (char *)target_fn + 1;.

Commands
gcc -O2 -fno-pie -no-pie -fno-asynchronous-unwind-tables -fcf-protection=none -o fixture fixture.c
objdump -d --no-show-raw-insn -M intel fixture
readelf -S -h -x .data fixture

# head and base, one MCP stdio session each:
#   open_binary {path, provider_id: "ghidra"}
#   inspect_native_instruction {address} and xrefs {address}, per address
#   resolve_native_call_targets {address}, then close_binary

# CLI, one run per address
node <rea-root>/scripts/rea.mjs inspect-native-instruction fixture 0x400480 --provider ghidra --format json
node <rea-root>/scripts/rea.mjs xrefs fixture 0x400480 --provider ghidra --format json

# snapshot test: on base, open_binary, inspect_native_instruction, then
#   close_binary {snapshot_path}; on head, open_binary {path, provider_id, snapshot_path}

# tests, once per Node
node node_modules/vitest/vitest.mjs run src/ghidra/GhidraFunctionValues.test.ts \
  src/ghidra/GhidraSnapshotCache.test.ts tests/boundary/mcp/ghidraCompactReferencesMcp.test.ts
Exact error text

Old snapshot opened on head, open_binary:

{"error":{"code":"evidence_integrity_mismatch","category":"integrity_mismatch","message":"Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the requested binary","retryable":false,"remediation":{"action":"Run analysis without this snapshot, then save a fresh snapshot using the intended artifact, provider, and analysis profile."}}}

Address zzz, inspect_native_instruction and xrefs, same on base and head:

{"error":{"code":"invalid_request","category":"invalid_input","message":"Analysis input is invalid. Check the arguments and try again.","retryable":true,"details":{"operation":"inspect_native_instruction","issues":[{"path":["address"],"reason":"invalid_format","message":"Use hexadecimal digits, optionally prefixed with 0x, or an encoded address-space name followed by :0x and hexadecimal digits","expected":"regex"}]}}}

The other four edge addresses raise no error. They return a normal result with the status shown in the table.

Test setup
  • Box: Nobara 44 (Fedora 44 base), Linux 7.2.9
  • CPU: AMD Ryzen 9 5900X, 12 cores / 24 threads
  • RAM: 32 GB DDR4-3600
  • Node: 22.23.1, 24.18.0, 26.11.1
  • Head: 1de1681
  • Base: 13e03e9
  • Other: Ghidra 12.1.4 (Apache-2.0)
  • Other: Temurin JDK 21.0.12.1 (GPL-2.0-only WITH Classpath-exception-2.0)
  • Other: GCC 16.2.1 (GPL-3.0-or-later, first entry of the Fedora package license field)
  • Other agents used the box too. I ran one Ghidra job at a time.

🤖 Generated with Claude Code (Sonnet 5.5, verified by Opus 5.5) 🦊

@morluto

morluto commented Oct 11, 2026

Copy link
Copy Markdown
Owner

Thank you @bugstan for completing typed incoming references! Preserving exact addresses, access kinds, primary status, and provenance makes the compact inspection much more useful, and the unavailable-versus-empty distinction and snapshot versioning keep the evidence semantics clear. I reviewed the change with no actionable findings; all 53 focused tests passed and CI is green. Thanks also @CassieFox23 for the independent Linux verification. Squash-merging this now.

@morluto
morluto merged commit cdd9fe7 into morluto:main Oct 11, 2026
31 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 11, 2026
3 tasks done
@morluto morluto added enhancement New feature or request area: native Native analysis and decompilation, including Ghidra, IDA, and Hopper analysis behavior labels Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: native Native analysis and decompilation, including Ghidra, IDA, and Hopper analysis behavior enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(native): preserve access kind and inference provenance in compact xrefs

3 participants