7f8da4be71
Replaces the abandoned pe-sieve Task B: attach + scan the live process to map resolved import pointers (RVA->dll!Func) and label /v2. Recon-first hard gate; clean labels; read-only Frida. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
110 lines
6.9 KiB
Markdown
110 lines
6.9 KiB
Markdown
# Frida import-map — naming dynamically-resolved Win32 APIs — design
|
|
|
|
**Date:** 2026-07-09
|
|
**Status:** approved (design), plan pending
|
|
**Replaces:** the abandoned pe-sieve Task B in
|
|
`docs/superpowers/plans/2026-07-09-re-tooling-handler-labels-and-iat.md`.
|
|
**Home in the canonical map:** results + the mapping mechanism land in `docs/engine-re.md`
|
|
(the runbook already carries the design sketch under "IAT reconstruction — tried, DOESN'T WORK →
|
|
the right approach"); the tools go in `docs/tools-reference.md`. This spec is the design record.
|
|
|
|
## Motivation
|
|
|
|
AGE.EXE ships with a **zeroed IAT** resolved via `GetProcAddress` at load (confirmed: `pack_check.py`,
|
|
and pe-sieve's `/imp` produced ~17 genuine + 300+ spurious entries — see the `engine-re.md` runbook).
|
|
So the game's hot Win32 APIs (`ReadFile`/`CreateFileA`/`SetFilePointer`/`timeGetTime`/d3d9 device
|
|
methods) show in Ghidra only as indirect calls through unnamed pointers, and we have been identifying
|
|
them by format-string and behaviour archaeology. This slice names them at their call sites in one pass —
|
|
the same high-leverage move as the Task A dispatch-handler labeling, for the Win32 surface.
|
|
|
|
## Approach (decided in brainstorming)
|
|
|
|
**Attach + scan, recon-first**, applying **clean labels** (no type archive):
|
|
- Build `{runtime_addr → "dll!Func"}` from the **live** process's loaded-module export tables.
|
|
- Scan the `0x400000` module's memory for aligned DWORDs whose value is in that set → those locations
|
|
hold resolved import pointers → record **`RVA → name`**.
|
|
- Apply `imp_<dll>_<func>` **labels** to the `/v2` Ghidra image at `0x400000 + RVA`.
|
|
|
|
**Why ASLR-safe:** the export map and the module scan are done in the *same* live process, so the stored
|
|
pointer values and the export addresses are from one consistent address space. We carry back only the
|
|
**RVA** (offset into the fixed-base `0x400000` main module, which is not relocated), so the labels
|
|
computed live apply to the earlier dump — the code/table *locations* are identical across launches even
|
|
though the stored pointer *values* differ.
|
|
|
|
**Why read-only / anti-tamper-safe:** only Frida `enumerateModules`/`enumerateExports` + memory reads —
|
|
the same plain-JS read pattern the existing capture scripts use. No spawn, no `GetProcAddress` hook, no
|
|
patching. (This is *not* the "live-debugger" case the user gated behind "probe carefully first.")
|
|
|
|
## The one unknown, and the recon gate
|
|
|
|
We do **not** yet know *where* the packer stores the resolved pointers. pe-sieve found genuine import
|
|
thunks at RVA `~0x202xxx` **inside the module** (`in_main:1`), which suggests a module-resident,
|
|
RVA-stable pointer table — exactly what this approach needs. But whether the `GetProcAddress`-resolved
|
|
hot APIs also land in-module, or in a heap block (non-stable base, **not** in the `/v2` dump), is unproven.
|
|
|
|
**Recon is a HARD GATE.** Task 1 is read-only and only *reports*. It must show the matches cluster in a
|
|
**module-resident** region within the dump's range (RVA `< 0x260000`, the dump size) before any labeler
|
|
is built. If the pointers turn out to be heap-resident, we **stop and report that honestly** — the slice
|
|
cannot label the dump and would need a different mechanism (e.g. a heap dump keyed to the same launch).
|
|
No forcing.
|
|
|
|
## Components
|
|
|
|
### 1. `tools/frida/map_imports.py` — export map + module scan (Tasks 1 & 2)
|
|
|
|
- Attach by PID (default: locate `AGE.EXE`, like `dump_engine.py`).
|
|
- Frida JS: `Process.enumerateModules()` → `Module.enumerateExports(m.name)` → `{addr → "dll!Func"}`.
|
|
Handle collisions/forwarders (multiple names per addr) by keeping a canonical name + noting alternates.
|
|
- Read the `0x400000` module range; scan 4-byte-aligned DWORDs; collect `(RVA, value, name)` for values
|
|
in the export set.
|
|
- **`--recon` (Task 1, report only):** print total exports mapped, total matches, and the **clustering**:
|
|
contiguous aligned runs (candidate import tables) vs isolated singletons; min/max RVA of matches and how
|
|
many fall within the dump range (`< 0x260000`). No file written. This is the gate.
|
|
- **default (Task 2):** write `build/import-map.json` = `{ "0xRVA": "dll!Func", ... }` restricted to matches
|
|
inside identified contiguous table region(s); isolated singletons written to a separate
|
|
`build/import-map-singletons.json` for review (not auto-applied — a lone match is more likely coincidental).
|
|
|
|
### 2. Ghidra labeler (Task 3) — `run_script_inline` Java (reuse the Task A pattern)
|
|
|
|
- Confirm the active program is `/v2/range_00400000.bin` (base `0x400000`, 4308 fns — the two-program
|
|
gotcha from Task A).
|
|
- Read `build/import-map.json`; for each `RVA → name`: `createLabel(toAddr(0x400000+RVA),
|
|
"imp_" + sanitize(dll) + "_" + func, SourceType.USER_DEFINED)`. Skip if a `USER_DEFINED` label already
|
|
exists there (idempotent, no clobber). One transaction; `save_program`.
|
|
|
|
## Data flow
|
|
|
|
live process ─▶ export map `{addr→name}` + module DWORD scan ─▶ `RVA→name` (`build/import-map.json`)
|
|
─▶ Ghidra `createLabel` on `/v2` ─▶ call sites read `CALL dword ptr [imp_kernel32_ReadFile]`.
|
|
|
|
## Validation (Task 4)
|
|
|
|
Cross-check against APIs already hand-identified, so the mapping is proven, not assumed:
|
|
- The `call-script` resolver chain (`FUN_0044f390` / `FUN_0040e980`) should now show `CreateFileA` /
|
|
`SetFilePointer` / `ReadFile` at its file-I/O call sites.
|
|
- The `sleep` timer source (`sleep_op_0xc8` → `DAT_0056f3d4`) should resolve to a `timeGetTime`/`GetTickCount`-class import.
|
|
- A `d3d9` `Present`/`Direct3DCreate9` site should be named.
|
|
|
|
If those light up correctly, the mapping is real. Record the count of labels applied and the validated
|
|
anchors. Then update `docs/engine-re.md` (mechanism + result), `docs/tools-reference.md` (the new tool),
|
|
and the status memory.
|
|
|
|
## Scope & boundaries
|
|
|
|
- **In:** all loaded modules' exports (no curation); module-resident import pointers; clean labels.
|
|
- **Out (explicitly):** typed Win32 signatures / the type archive (labels only this pass — signatures are a
|
|
later layer); heap-resident pointer tables (out of reach of the dump — recon decides if this blocks us);
|
|
the `GetProcAddress`-hook/spawn variant (rejected: fragile, needs spawn); renaming the DLL functions
|
|
themselves (we label the *pointer slots*, not the targets, which aren't in the dump).
|
|
- **Regenerable:** `build/import-map.json` regenerates from a live run; disposable per project convention.
|
|
|
|
## Acceptance criteria
|
|
|
|
- Recon (Task 1) reports match clustering and the in-module/in-range verdict; **the gate is passed
|
|
explicitly** (matches are module-resident, within the dump) before Task 2/3 run — or the slice stops
|
|
here with a documented finding.
|
|
- `build/import-map.json` produced with a sane count (dozens+ of real imports, not ~17 and not 300+ noise).
|
|
- Ghidra labeler applies labels with 0 clobbers of existing `USER_DEFINED` symbols; `save_program` succeeds.
|
|
- ≥2 of the three validation anchors (resolver-chain file I/O, sleep timer, d3d9) read as named calls.
|
|
- Docs + memory updated.
|