feat(pe): inspect import and delay-load tables (#6509)

* feat(pe): inspect import and delay-load tables

Add inspect_pe_imports / inspect-pe-imports to read PE32/PE32+ import
and delay-load directories without executing the image. The report keeps
DLL names, named and ordinal functions, ILT/IAT RVAs, and a pefile
import hash of the standard import table. A missing directory is
observed absence, not proof the image never imported APIs.

* fix(pe): default PE import fixture options

Allow peImportImage() without an argument so CLI and filesystem tests
can use the KERNEL32 sample without repeating an empty options object.

* test(pe): keep import path cases on the dedicated MCP contract

inspect_pe_imports already rejects relative MCP paths in its own
boundary test. Leave the shared absolute-path matrix to tools whose
handler issue projection matches that suite's expected shape.

* fix(native): index virtual-to-file mapping lookups

mappedFileOffset scans every mapping twice per span, so a parser that
translates one span per table entry costs sections x entries. Add
fileMappingLookup, which builds an O(n log n) interval index once and
answers each span in O(log n) with the same accept, reject and
translation results. A differential test checks it against
mappedFileOffset over randomized overlapping mappings and zero fills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ra7LM2NyQ7DumdssxbUq5g

* fix(pe): report partial import evidence and exact pefile hashes

- Withhold imphash with an explicit reason whenever the standard import
  table is partial (unreadable names or thunks, missing tables), or when
  pefile 2024.8.26 would hash a different row sequence: invalid or
  truncated names, ordinal 0, descriptors without functions, tables its
  bounds or repeat/spread heuristics discard, and its 8192-thunk import
  symbol cap. Delay-load issues do not withhold it.
- Hash ordinal imports with pefile's complete ordlookup tables and its
  ord<decimal> fallback instead of declining unmapped ordinals.
- Report a nonterminal descriptor whose FirstThunk is zero, and a
  delay-load descriptor whose IAT or INT RVA is zero, as malformed_entry
  partial coverage instead of a complete empty inventory.
- Directory evidence lists the file spans actually consumed for the
  descriptor array and terminator; discontiguous mappings produce
  separate spans and separate Evidence ranges.
- Carry exhausted limits as PeImportLimitFailure.limit and derive
  recovery from it; the fixed 16 MiB retained-text ceiling reports a
  fixed allowance instead of max_file_bytes advice.
- Translate RVAs through the indexed mapping lookup and yield with a
  cancellation check every 1024 table entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ra7LM2NyQ7DumdssxbUq5g

* fix(pe): read only own ordinal tables for DLL names

DLL names such as constructor and __proto__ pass pefile's name rule but
resolved inherited object members, throwing before the ord<n> fallback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ra7LM2NyQ7DumdssxbUq5g

* fix(native): preserve PE import facts and prove hash compatibility

* test(native): verify PE import workflows and measured costs

* refactor(native): narrow PE facts across the container union

* docs(native): record integrated PE import validation

* fix(native): bound every PE import RVA span

* docs(native): measure RVA guard completed workflows

* fix(pe): reconcile import coverage with retained rows

* fix(pe): retain partial imports at descriptor mapping gaps

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>

docs/pe-imports.md

@@ -0,0 +1,73 @@
+# PE import and delay-load tables
+
+`inspect_pe_imports` / `inspect-pe-imports` answers whether one selected local
+PE32/PE32+ image declares an `IMAGE_DIRECTORY_ENTRY_IMPORT` table, which DLLs
+and functions that table names, which delay-load descriptors are present, and
+the pefile-compatible import hash of the standard import table. It reads the
+file without executing it and does not require a Windows SDK or disassembler.
+
+```bash
+rea inspect-pe-imports /absolute/path/to/application.exe --json
+```
+
+The CLI resolves relative paths against the caller's working directory. MCP
+and the advertised input schema require an absolute filesystem path and
+preserve that exact selection:
+
+```json
+{
+  "name": "inspect_pe_imports",
+  "arguments": { "path": "/artifacts/application.exe" }
+}
+```
+
+## Observations
+
+The inline Evidence result contains the artifact path, SHA-256, and byte length.
+`import_directory` and `delay_import_directory` report the data directory RVA
+and size, or `null` when a directory is absent or zero. Their `locations` are
+the file spans actually read for the descriptor array and its terminator. When
+consecutive descriptors map to discontiguous file bytes (for example across a
+section boundary), each span is reported separately, and each becomes its own
+Evidence file-offset range.
+If the first descriptor cannot be examined, the directory declaration remains
+present with no consumed `locations`, and coverage is partial. Descriptors,
+thunks and NUL-terminated names stay within PE's 32-bit RVA space, including
+PE32+ images; earlier valid rows survive an overflowing descriptor walk.
+
+Each `imports[]` item reports the DLL name, descriptor RVAs, and named or
+ordinal functions with ILT/IAT RVAs. `delay_imports[]` reports RVA-based
+delay-load descriptors separately. `imphash` is pefile's `get_imphash()` over
+the standard import table only; delay-load rows do not participate. Ordinal
+imports use pefile's ordinal name tables and otherwise its `ord<decimal>`
+fallback.
+
+`imphash.md5` is `null` with a `reason` whenever the value would not be
+pefile's hash of this image: the standard import table is partial, or pefile
+would read a different row sequence (names it treats as invalid or truncates,
+ordinal 0, descriptors without functions, or tables its bounds and import
+symbol cap truncate). Delay-load issues do not withhold the hash.
+
+A missing import directory is observed absence of that table. It is not proof
+the image never imported APIs through another table or overlay.
+
+## Limits and failures
+
+The selected file is limited to 64 MiB by default (512 MiB maximum). At most
+256 import and delay-load descriptors are examined by default (4096 maximum),
+and at most 8192 functions across every table (262144 maximum). Malformed PE
+headers and exhausted DLL or function budgets fail without partial success.
+Decoded DLL and function names are limited to a fixed 16 MiB of retained text
+with no runtime override; `max_file_bytes`, `max_dlls` and `max_functions` do
+not raise it. Resource failures report the exhausted allowance as `limit`
+(`dlls`, `functions` or `retained_text`) with matching recovery.
+
+Unreadable DLL names, hint/name entries, or thunks are reported as partial
+coverage with `issues`. A descriptor whose required table RVA is zero (a
+standard `FirstThunk`, or a delay-load import address or name table) is
+reported as `malformed_entry` with no functions, never as a complete empty
+inventory. Delay-load descriptors that store virtual addresses rather than RVAs
+are recorded as `unsupported_form` and are not decoded.
+
+This workflow does not resolve bound imports, loaded IAT contents, or
+export-forward names in another DLL.