RESX analysis integration

COMMANDS.md

@@ -14,6 +14,7 @@
 - `resx cfg <dll> <function>`
 - `resx cfg <dll> --at <rva>`
 - `resx cfg <dll> --ordinal <n>`
+- `resx reconstruct-cfg <dll>`
 - `resx intelli <dll> [function]`
 - `resx peinfo <dll>`
 - `resx sections <dll>`
@@ -26,6 +27,7 @@
 - `resx locate <name>`
 - `resx locate-sym <name>`
 - `resx explain <name>`
+- `resx scan <path>`
 - `resx yara <dll> <rule.yar>`
 - `resx update`
 
@@ -36,6 +38,9 @@
 - `--recomp`
 - `--c-out <file>`
 - `--cfg text`
+- `--reconstruct-cfg`
+- `--thread-filter <term>`
+- `--api-filter <term>`
 - `--funcs`
 - `--funcs-depth <n>`
 - `--explain`
@@ -47,6 +52,7 @@
 - `--unsafe-map-image`
 - `--hookchk`
 - `--intelli`
+- `--hostile`
 - `--follow-jmp`
 - `--no-follow-jmp`
 - `--rebase <addr>`
@@ -64,6 +70,30 @@
 - `--api` forces API/symbol-mode interpretation.
 - `dump --explain` reuses the same explanation engine inline for the current target.
 
+## Reconstruct CFG
+
+- `resx reconstruct-cfg <dll>` builds a bounded startup/TLS-to-exit graph.
+- The graph follows intra-image calls, tail jumps, import edges, indirect-call annotations, recovered thread/workpool callbacks, and x64 unwind exception-handler edges.
+- PDB symbols are used when available for names, prototypes, and size-backed decode bounds.
+- `--thread-filter <term>` and `--api-filter <term>` focus the text output for non-interactive review.
+- `--json` emits a versioned `reconstruct_cfg` report with roots, nested edge children, PDB status, statistics, and static-analysis notes.
+
+## Scan
+
+- `resx scan <path>` inventories `.exe`, `.dll`, and `.sys` files under a root.
+- `--jsonl` emits one JSON object per image for agent and corpus workflows.
+- `--extensions <list>`, `--max-files <n>`, `--max-file-mb <mb>`, and `--max-candidates <n>` control scan scope and output size.
+- Results include image metadata, risk imports, anomalies, and ranked fuzz-target candidates.
+- Candidate entries include `name`, `rva`, `source`, `score`, `reasons`, `input_surface`, `harness_kind`, `suggested_invocation`, and `confidence`; scores are triage hints, not exploitability claims.
+
+## JSON Output
+
+- JSON output uses `schema_version: 1`.
+- Most commands emit `{ "schema_version": 1, "kind": "<command>", "<command>": ... }`.
+- `scan --json` emits `{ "tool": "resx", "schema_version": 1, "kind": "scan", "results": [...] }`.
+- `scan --jsonl` emits one image report per line without the outer scan envelope.
+- See [docs/json-schemas.md](docs/json-schemas.md) for field-level notes.
+
 ## Symbol Flags
 
 - `--pdb <file>`
@@ -116,17 +146,23 @@
 - `dump --cfg text` can recover and render `Switch Map` sections for jump-table dispatchers.
 - `cfg` supports function names, `--at <rva>`, and `--ordinal <n>` just like `dump`.
 - `cfg` and `dump` use the same instruction and API/symbol highlighting path for call targets and comments.
+- `dump --funcs` discovers direct, import, IAT-indirect, register-indirect, and switch-dispatch call targets.
 - `dump --recomp` emits corrected bit-test branches and better local-call placeholders.
+- `dump --recomp` uses PDB prototype text and x64 unwind metadata when available.
 - `dump --funcs-depth <n>` expands nested API call depth and accepts levels `1` through `5`.
 - `syms --verbose` can show exact PDB identity/load diagnostics, including RSDS-derived kernel PDB names.
 - `dump` can resolve internal names from enumerated PDB symbols when exports do not contain the target.
-- `dump` can surface syscall service numbers and kernel targets for `Nt*` and `Zw*` stubs.
+- `dump` can surface syscall service numbers and kernel targets for `Nt*`, `Zw*`, and Win32K GUI syscall stubs.
+- Extensionless system image lookup supports `.dll`, `.exe`, and `.sys`, including `user32`, `win32u`, `win32k`, `win32kbase`, `win32kfull`, and `ntoskrnl`.
 - `locate` and `locate-sym` search only the priority set by default.
 - `callers` uses the priority set by default.
 - `--include-dir` and `--include-image` widen the scan beyond the priority set for `locate` and `callers`.
 - `callers --include-dir` will scan `.dll` and `.sys` images by default, and `.exe` as well when `--scan-exe` is set.
 - `--include` filters the entire callers scan list; `--scope-file` only filters files discovered through `--include-dir`.
 - `priority` opens the generated priority config JSON where you can edit directories, exact names, prefixes, and regexes.
+- `reconstruct-cfg` reconstructs startup flow using PE entry/TLS/startup roots, direct calls, import calls, recovered callbacks, and unwind exception edges.
+- `scan` inventories PE corpora and ranks fuzz-target candidates from exports, startup paths, risky imports, and section anomalies.
+- `resx-palace/` is the local controlled fixture corpus that exercises discovery, recursive CFG, EH, typed reconstruction, indirect control flow, and scan output.
 
 ## Examples
 
@@ -135,8 +171,11 @@ resx dump ntdll.dll NtOpenProcess --cfg text --hookchk
 resx cfg ntdll.dll --at 0x161F40
 resx intelli suspicious.dll
 resx intelli suspicious.dll WinMain --hookchk --cfg text --strings
+resx reconstruct-cfg suspicious.dll --depth 6 --max-total 300
 resx dump ntoskrnl.exe KiSystemCall64 --cfg text --funcs --recomp
 resx dump ntoskrnl.exe NtQuerySystemInformation --cfg text
+resx dump win32u NtUserGetMessage --funcs
+resx peinfo win32kfull
 resx syms ntoskrnl.exe --verbose
 resx callers blackbird.sys BLACKBIRDNtAllocateVirtualMemoryHookStub --depth 2
 resx callers ntoskrnl.exe NtOpenProcess --include-dir C:\Work\Drivers --depth 2
@@ -146,5 +185,6 @@ resx locate NtOpenProcess
 resx locate NtOpenProcess --include-dir C:\Work\Drivers
 resx locate-sym NtWriteVirtualMemory --include-image .\mydriver.sys
 resx explain NtQuerySystemInformation --api
+resx scan C:\Windows\System32\drivers --jsonl --max-files 200
 resx update
 ```

README.md

@@ -16,6 +16,8 @@ RESX is a Windows binary analysis toolkit for terminal-first reversing, symbol-b
 ## Documentation
 
 - [CLI documentation](docs/cli.md)
+- [Analysis surfaces](docs/analysis-surfaces.md)
+- [JSON schemas](docs/json-schemas.md)
 - [VS Code extension documentation](docs/vscode-extension.md)
 
 ## Screenshots
@@ -68,9 +70,13 @@ Common commands:
 ```powershell
 resx dump <dll> <function>
 resx cfg <dll> <function>
+resx reconstruct-cfg <dll>
 resx intelli <dll> [function]
 resx peinfo <dll>
 resx locate <name>
 resx locate-sym <name>
+resx scan <path>
 resx syms <dll>
 ```
+
+Newer analysis surfaces include PDB/export-backed function discovery, recursive startup CFG reconstruction, x64 unwind and exception-handler edges, typed pseudo-C reconstruction, indirect-control-flow annotations, Win32K GUI syscall tracing, scan-driven fuzz target ranking, and versioned JSON output for automation.

docs/analysis-surfaces.md

@@ -0,0 +1,94 @@
+# RESX Analysis Surfaces
+
+This page summarizes the analysis surfaces added around function discovery, recursive CFG reconstruction, exception metadata, typed reconstruction, indirect control flow, corpus scanning, and the `resx-palace` test corpus.
+
+## Function Discovery
+
+RESX discovers callable targets from several sources and keeps the source visible in reports:
+
+- Export tables provide named entry points and ordinal-backed targets.
+- PDB symbols provide internal functions, sizes, and prototype/type text when symbols are available.
+- PE startup metadata contributes entry point, TLS callbacks, and startup handoff candidates.
+- Disassembly contributes direct `CALL` and tail `JMP` targets.
+- Import tables identify external API edges and IAT-backed call sites.
+- Switch-dispatch recovery contributes jump-table targets where the dispatcher can be statically recovered.
+
+Use `resx dump <image> <function> --funcs` for a local call map. Use `--funcs-depth <n>` to recurse into internal callees up to levels `1` through `5`.
+
+## Recursive CFG
+
+`resx reconstruct-cfg <image>` builds a bounded startup/TLS-to-exit graph. The graph starts from PE entry and startup roots, follows intra-image call and jump targets, annotates import edges, and nests recovered children until `--depth` or `--max-total` stops expansion.
+
+Useful controls:
+
+- `--depth <n>` limits recursive expansion depth.
+- `--max-total <n>` caps the total number of expanded functions.
+- `--thread-filter <term>` focuses text output on thread-related paths.
+- `--api-filter <term>` focuses text output on matching APIs or functions.
+- `--json` emits the structured `reconstruct_cfg` report.
+
+Each function node reports name, kind, RVA/VA, section, symbol source/category, PDB prototype text when present, decode bound, status, return sites, and outgoing edges.
+
+## Unwind And EH
+
+RESX reads x64 `.pdata` / `UNWIND_INFO` where available:
+
+- `dump --json` can include `data.unwind[]` entries with runtime-function ranges, unwind-info RVA, prolog size, unwind code count, flags, and exception-handler RVA.
+- `dump --recomp` emits a `.pdata` comment above reconstructed C-like output.
+- `reconstruct-cfg` follows executable exception-handler RVAs as `exception-handler` edges tagged with `try-except` and `unwind`.
+
+Language-specific scope tables are not fully expanded; exception edges are best-effort static edges from unwind metadata.
+
+## Typed IR And Reconstruction
+
+The current typed reconstruction surface is PDB-backed and C-like:
+
+- `resx types <image> --pdb <file>` inventories PDB type records, members, and symbol references.
+- `dump --recomp` uses PDB function type text when available to recover return type, calling convention, and parameters.
+- `dump --recomp` also uses unwind metadata to annotate frame and handler state.
+- Without PDB types, reconstruction falls back to architecture defaults and observed argument-register usage.
+
+This is not a full decompiler IR contract. Treat it as a typed pseudo-C and typed-IR reporting surface for review, triage, and agent consumption.
+
+## Indirect Control Flow
+
+Indirect-control-flow visibility appears in disassembly, call maps, CFG output, and JSON:
+
+- IAT-backed memory calls are resolved to imported DLL/function names when possible.
+- Register-indirect calls and jumps are traced backward through nearby register assignments.
+- `--hostile` enables more aggressive reverse-index and indirect-JMP emission paths for hostile or obfuscated samples.
+- API call JSON includes `is_indirect`, `indirect_method`, and `switch_cases` fields.
+- `reconstruct-cfg` counts indirect edges and tags unresolved or partially resolved indirect calls.
+
+Static recovery may miss data-dependent dispatch, generated code, or targets materialized outside the local decode window.
+
+## Fuzz Target Output
+
+`resx scan <path>` recursively inventories PE corpora and ranks fuzz-target candidates. It emits JSON by default and JSON Lines with `--jsonl`.
+
+Candidate scoring uses:
+
+- Image kind, including driver detection.
+- Entry point and exported function names.
+- Risk imports such as IOCTL, parser, decompression, crypto, network, file, registry, and kernel buffer APIs.
+- Section anomalies and header corruption.
+- Driver and WDF-style naming patterns.
+
+Each candidate includes `name`, `rva`, `source`, `score`, `reasons`, `input_surface`, `harness_kind`, `suggested_invocation`, and `confidence`. Scores are triage hints, not exploitability claims.
+
+## resx-palace Test Corpus
+
+`resx-palace/` is the local corpus root for exercising these surfaces against controlled fixtures. It contains Windows C sources, a local build script, and generated DLL/EXE samples under `resx-palace/build/` when compiled.
+
+Use it for fixtures that need to stress:
+
+- Export and PDB-backed function discovery.
+- Recursive direct-call and tail-call CFG expansion.
+- x64 unwind and exception-handler edges.
+- PDB type/prototype-backed reconstruction.
+- IAT, register-indirect, and switch-dispatch control flow.
+- Scan output and fuzz-candidate ranking.
+
+The current corpus builds `resx_palace.dll` and `resx_palace_probe.exe`. The DLL exports `ResxParsePacket`, `ResxDeviceIoctlDispatch`, `ResxThreadCallbackEntry`, `ResxSwitchJumpTableDispatch`, and `ResxIndirectCallMessage`; the integration suite uses RESX itself to verify PE metadata, exports, dumps, CFG output, recursive reconstruction, and scan/fuzz-candidate output.
+
+Keep generated binaries, source fixtures, and runner scripts isolated under `resx-palace/` so docs and schema expectations can describe the intended test surface without mixing fixture code into RESX source.

docs/cli.md

@@ -22,6 +22,7 @@ resx dump <dll> --ordinal <n>
 resx cfg <dll> <function>
 resx cfg <dll> --at <rva>
 resx cfg <dll> --ordinal <n>
+resx reconstruct-cfg <dll>
 resx intelli <dll> [function]
 resx peinfo <dll>
 resx sections <dll>
@@ -34,6 +35,7 @@ resx callers <dll> <function>
 resx locate <name>
 resx locate-sym <name>
 resx explain <name>
+resx scan <path>
 resx yara <dll> <rule.yar>
 resx update
 resx help
@@ -55,26 +57,41 @@ resx iat kernel32.dll
 resx pechk suspicious.dll
 resx dump ntoskrnl.exe KiSystemCall64 --cfg text --funcs --recomp
 resx dump ntoskrnl.exe NtQuerySystemInformation --cfg text
+resx reconstruct-cfg suspicious.dll --depth 6 --max-total 300
 resx callers .\blackbird.sys BLACKBIRDNtAllocateVirtualMemoryHookStub --depth 2
 resx callers ntoskrnl.exe PsOpenProcess --include-dir C:\Windows\System32\drivers --scope-file *.sys
 resx locate NtOpenProcess
 resx locate NtOpenProcess --include-dir C:\Work\Drivers
 resx locate-sym RtlpHeapHandleError
 resx explain NtQuerySystemInformation --api
+resx scan C:\Windows\System32\drivers --jsonl --max-files 200
 resx syms ntoskrnl.exe --verbose
 resx yara suspicious.dll .\rules\triage.yar
 ```
 
 ## Notable Capabilities
 
 - Export and PDB-backed symbol resolution
+- Function discovery from exports, PDB symbols, startup roots, direct calls, imports, and switch-dispatch targets
 - Targeted disassembly with `--at`, ordinal, and symbol lookup flows
-- Recovered CFG text output and switch-dispatch analysis
+- Recovered CFG text output, recursive startup CFG reconstruction, and switch-dispatch analysis
+- x64 unwind metadata and exception-handler edge reporting
+- Startup-to-exit flow reconstruction with thread/workpool callback and exception-handler edges
+- Indirect-control-flow annotations for IAT, register-indirect, unresolved, and switch-dispatch paths
+- Typed pseudo-C reconstruction from PDB function prototypes and unwind metadata
+- Corpus scanning with risk imports and fuzz-target candidate ranking
 - Nested API call expansion with `--funcs-depth 1..5`
 - Syscall service number and kernel-target surfacing for `Nt*` and `Zw*` stubs
+- Win32K GUI syscall support through `user32`, `win32u`, `win32k`, `win32kbase`, and `win32kfull`
 - Pseudo-C reconstruction with `--recomp`
 - PE metadata, mitigation, signer, and debug-directory inspection
 - Priority-based locate and caller tracing workflows
+- Versioned JSON output for dump, reconstruct-cfg, scan, types, metadata, explain, and caller workflows
+
+## Analysis And Schema References
+
+- [Analysis surfaces](analysis-surfaces.md)
+- [JSON schemas](json-schemas.md)
 
 ## References