Repository navigation
feat(ida): resolve containing procedures and report the admitted program as the document - #2374
Conversation
…ncated A provider that reports a capped xrefs read makes the trace truncated with a residual unknown for that target. An explicit complete report and a provider that reports nothing leave the trace as before.
Executions gain an optional flag for a capped xrefs read, set by the IDA adapter from the upstream cap. trace_feature marks the trace truncated with a residual unknown for that target only when the provider reports a truncation; a provider that reports nothing keeps its previous result. The trace_feature workflow profile is revised so earlier results are not replayed.
… and failures of the trace coverage
…lookups and segment facts Cover positive and negative containment, segment boundaries including addresses above 2^53, failures of the lookup and of the segment survey, cancellation, input validation and the admitted program as the only document.
…less IDA Run trace_feature, including a capped reference read, and inspect_address_context with and without an explicit document through the IDA session client.
…ram as the document The modern headless profile resolves an address through the function lookup and, when no function contains it, tells a mapped address from an unmapped one using the database-scoped minimal survey. A survey that is missing, truncated or inconsistent fails the read. list_documents reports the single admitted program. The attached profiles do not declare either operation.
…truncated feature traces
…ature tracing on real IDA
…ached refusals and each trace_feature prerequisite
…m its facts in the real lane
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
Technical Review & Findings1. Inconsistent Cache Invalidation for
|
|
@greptileai review |
|
This PR is set for a Plus review. TREX isn't supported with Plus or Apex reviews yet, so Greptile reviews this PR at Base while TREX is on. |
|
…xref-coverage # Conflicts: # src/application/AnalysisProvider.ts
…ing-procedure # Conflicts: # scripts/verify-real-ida.mjs
…ences to every matched address
…he admitted program
|
On the three points from the review above: 1. 2. Signed 64-bit addresses. Addresses are normalized to unsigned hexadecimal strings with 3. The |
…xref-coverage # Conflicts: # src/ida/IdaWorkspaceThinning.test.ts
…-feature-xref-coverage # Conflicts: # src/application/InvestigationProviders.ts
Summary
With the modern headless IDA profile,
trace_featurefailed withcapability_unavailableforresolve_containing_procedure, andinspect_address_contextfailed forlist_documents. The profile now implements both operations, so feature tracing and address context work on IDA. A containing function comes from upstreamlookup_funcs; when no function contains the address, the database's own segments decide between the two negative reasons, and a missing or inconsistent segment fact fails the read instead of guessing a reason.Fixes #2335
Builds on #2348 (
trace_featurereference coverage); its commits appear in this branch until #2348 is merged. The capped-reference qualification it adds is exercised here end to end.Problem and expected behavior
Observed on real IDA Professional 9.1 (headless idalib, ida-pro-mcp
c133c3853faa111a9b00ee615c013b720d0c4acd) with a small arm64 Mach-O:trace_feature {"query": "sum_point"}andinspect_address_context {"address": "0x100000564"}both returnedcapability_unavailablenaming those operations; with an explicitdocument, address context answered but every containment facet stayed unavailable. Upstreamlookup_funcsreturns the canonical containing function for an interior address (0x100000564gave_use_wrapperat0x100000560) andfn: null, error: "Not a function"for data, which does not say whether the address is mapped.Expected: an entry, interior or tail address returns its canonical containing procedure (the body stays unavailable, as for other IDA identities); an address inside a segment but outside any function is
not_in_procedure; an unmapped address isoutside_segments; if segment membership cannot be established, the read fails.list_documentsreturns the single admitted program, so default document resolution works without enumerating unrelated upstream databases.Change and scope
src/ida/IdaProviderCapabilities.ts:IDA_OPERATIONSgains the two operations;idaProfileAdmitsmakes the modern headless profile the only one that declares them. The legacy and native attached profiles declare 12 operations, as before; the headless profile declares 14.src/ida/IdaSessionClient.ts: refuses the operations outside the headless profile before any upstream call, records whether the server advertisessurvey_binary, and passes the admitted program path to the runner. The normal pre- and post-operation identity checks, cancellation draining and partial-observation retention apply unchanged.src/ida/IdaOperationRunner.ts: thelookup_funcsrow is parsed once into a function, an expected "missing" answer (exactlyNot foundorNot a function) or a producer failure; procedure selection keeps its previous semantics and messages, and containment reuses the same parsing. For an expected missing answer,survey_binary {detail_level: "minimal"}(scoped to the bound database) supplies segment intervals with exclusive ends; membership decidesnot_in_procedureversusoutside_segments. A different query in the reply, a function together with an error, an unknown error text or neither a function nor an error is a producer failure and reads no segments.list_documentsreturns the admitted path, not the private workspace copy.src/ida/IdaProtocolValues.ts: the survey reply is reduced to validated intervals. Any malformed coordinate, reversed or empty interval, size that disagrees with the bounds, segment count that disagrees with the survey statistics, absent or empty segment list rejects the whole reply. A transport-truncated preview is already rejected by the decoder. A server that does not advertisesurvey_binarycan still answer positive lookups; a negative lookup fails with a precise message.src/application/CapabilityInventory.ts:trace_featurerequiressearch_stringsandsearch_procedures, the operations the workflow actually calls (it listedlist_stringsandlist_procedures).src/application/EnhancedLiteralTracing.ts: a reference source that several matches share is resolved once.docs/ida-provider.md,docs/testing.md: the coverage text describes the new operations and keeps every existing exclusion (binary_overview, whole-symbol inventory, typed reference edges, complete body ranges); the verification text lists the added real-lane checks.scripts/verify-real-ida.mjs: for the headless profile, the real lane checks the admitted program as the single document, containment at the entry and a second instruction of the selected procedure, an unmapped address, a mapped non-function address when the target has strings,inspect_address_contextwith the default document, andtrace_featurefor the selected procedure's name.Intentionally not included:
list_segments: the segment schema's provenance admits only Hopper and Ghidra sources, so an honest IDA reply would need a schema change.read_bytes: upstreamget_bytesfills unloaded bytes with zeros without an error and needs its own segment check.address_to_file_offset: the pinned upstream exposes no file-region mapping.Contract and boundary impact
src/ida), at the profile's operation inventory and the operation runner.capabilitiesandbinary_sessionnow report them as available for the headless IDA profile (14 declared operations, 13 available, instead of 12 and 11).lookup_funcs,survey_binary); existing Evidence is unchanged.survey_binaryrequest (see Observed, not changed).Evidence and regression coverage
src/ida/IdaContainment.test.ts(headless session client over the recording fake): descriptors per profile; the legacy profile and the native profile refuse both operations without any upstream call; an interior address resolves to the canonical entry without reading segments; a matrix of negative addresses at segment starts, last bytes, exclusive ends, adjacent segments, gaps and above 2^53 (a one-byte segment that a rounded number cannot tell apart) in ascending and descending survey order; every kind of survey defect (missing, null or empty list, malformed coordinate, reversed bounds, disagreeing size, disagreeing count, a malformed row after valid ones, tool error, transport preview, tool not advertised) fails with the completed replies retained; each lookup anomaly fails without reading segments; both accepted missing texts; cancellation between lookup and survey; invalid address and foreign document refused before any upstream call;list_documentsreturns exactly the admitted path (not a source alias), runs the identity checks, fails on a changed target and honours cancellation.tests/boundary/providers/ida/containment.test.ts:trace_featureattributes a reference to its containing procedure and keeps an upstream reference cap visible;inspect_address_contextwith and without the explicit document gives the same result with an available procedure facet and the other facets unavailable.tests/conformance/ida/providerContracts.test.ts: the contract matrix covers the new operations for the headless profile.src/application/CapabilityInventory.test.ts: each search prerequisite oftrace_featureis required independently.src/ida/IdaNativeProtocol.test.ts: the native profile does not admit the operations.bfcb5afde,99ff05d09,64701e8f3: 28 failed inIdaContainment.test.ts, the four boundary tests failed withcapability_unavailable, two inventory tests failed). Real run on macOS 26.5 arm64 with IDA Professional 9.1:npm run verify:idawith the extended headless scenario passed (all six checks), including containment at the entry and an interior instruction, an unmapped address andtrace_feature.Validation performed
npm run check:fast,npm run check,npm run docs:check,npm run verify:test-discovery(968 files) - greennpm run test:fast- 409 files, 5359 passed, 7 skipped, 0 failed;npm run test:mcp- 103 files passed, 2 skipped, 448 passed, 3 skipped;npm run test:boundary -- tests/boundary/providers/idaafternpm run build:cached- 18 passedREA_IDA_MCP_CONFIG=$HOME/ida-mcp.json npm run verify:ida -- --target <inventory> --procedure _rea_fixture_add --report <path>- passed, mode headless, six checks; no IDA worker left runningmacOS arm64 only; Linux and Windows were not executed.
Compatibility, safety, and release
trace_featureandinspect_address_contextnow succeed on headless IDA instead of reportingcapability_unavailable.Observed, not changed
survey_binaryrequest; the minimal survey still enumerates functions and hashes the input, so atrace_featureover many distinct reference sources that are not inside any function repeats it per distinct source. A source shared by several matches is resolved once. Caching the segment layout for the session would change the "live results" semantics and is left out.Review checklist
type(scope): outcome.