wowdump 0.3.4 → 0.3.5

package/README.md

@@ -26,6 +26,9 @@ wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind dump --confir
 
 # 5. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
 wowdump memory read --pid 1234 --profile "$HOME\.wowdump\retail@VERSION\profile\player-state.json" --field playerAuras
+
+# 枚举已提交虚拟内存区（复用同一个管理员 broker）
+wowdump memory regions --pid 1234 --start 0x15000000000 --end 0x15400000000 --max-regions 20000
 ```
 
 Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续调用复用同一 broker，空闲 20 分钟后退出。Frida 运行时导出需要显式 `--confirm`；高开销 Stalker 默认关闭。

package/dist/cli.js

@@ -475,6 +475,20 @@ export function createWowdumpCli(dependencies = {}) {
         }
         writeJson(io, await broker({ command: "read", payload }));
     });
+    memory.command("regions")
+        .description("Enumerate committed virtual memory regions through VirtualQueryEx")
+        .requiredOption("--pid <pid>", "target process ID")
+        .option("--start <hex>", "query start address", "0x0")
+        .option("--end <hex>", "query end address")
+        .option("--max-regions <count>", "maximum returned regions", "4096")
+        .option("--include-free", "include free and reserved regions")
+        .action(async (options) => writeJson(io, await broker({ command: "regions", payload: {
+            pid: positiveInteger(options.pid, "pid"),
+            start: options.start,
+            ...(options.end ? { end: options.end } : {}),
+            maxRegions: positiveInteger(options.maxRegions, "max-regions"),
+            includeFree: options.includeFree === true
+        } })));
     const watch = memory.command("watch").description("Manage broker-owned memory monitors");
     watch.command("start")
         .description("Start a monitor")

package/dist/reader/broker.js

@@ -5,6 +5,9 @@ export const DEFAULT_RIGHTS = Object.freeze([
     "PROCESS_QUERY_INFORMATION",
     "PROCESS_VM_READ"
 ]);
+const MEM_COMMIT = 0x1000;
+const DEFAULT_QUERY_END = BigInt("0x7fffffffffff");
+const MAX_QUERY_REGIONS = 100_000;
 function hexAddress(value) {
     const normalized = value.trim();
     if (!/^0x[0-9a-f]+$/i.test(normalized)) {
@@ -30,6 +33,15 @@ function boundedPid(value) {
     }
     return pid;
 }
+function boundedCount(value, name, maximum, fallback) {
+    if (value === undefined)
+        return fallback;
+    const count = Number(value);
+    if (!Number.isSafeInteger(count) || count < 1 || count > maximum) {
+        throw new ReaderProtocolError("INVALID_COUNT", `${name} must be an integer between 1 and ${maximum}`);
+    }
+    return count;
+}
 function toHex(bytes) {
     return Buffer.from(bytes).toString("hex");
 }
@@ -169,6 +181,8 @@ export class ReaderBroker {
                 return this.runFrida(request);
             case "modules":
                 return this.modules(request);
+            case "regions":
+                return this.regions(request);
             case "open":
                 return this.open(request);
             case "close":
@@ -255,6 +269,63 @@ export class ReaderBroker {
         }
         return { pid, modules: await this.backend.enumerateModules(pid) };
     }
+    async regions(request) {
+        if (!this.backend.virtualQueryEx) {
+            throw new ReaderProtocolError("VIRTUAL_QUERY_UNAVAILABLE", "native VirtualQueryEx backend is not installed");
+        }
+        const pid = boundedPid(request.pid);
+        const start = hexAddress(request.start ?? "0x0");
+        const end = hexAddress(request.end ?? `0x${DEFAULT_QUERY_END.toString(16)}`);
+        if (end < start)
+            throw new ReaderProtocolError("INVALID_RANGE", "end must be greater than or equal to start");
+        const maxRegions = boundedCount(request.maxRegions, "maxRegions", MAX_QUERY_REGIONS, 4096);
+        const includeFree = request.includeFree === true;
+        const handle = await this.getHandle(pid, request.handle);
+        const regions = [];
+        let cursor = start;
+        let truncated = false;
+        while (cursor <= end) {
+            const raw = await this.backend.virtualQueryEx(handle, cursor);
+            const baseAddress = hexAddress(String(raw.baseAddress ?? "0x0"));
+            let regionSize;
+            try {
+                regionSize = BigInt(String(raw.regionSize ?? "0"));
+            }
+            catch {
+                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx returned an invalid region size");
+            }
+            if (regionSize <= 0n)
+                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx returned a non-positive region size");
+            const next = baseAddress + regionSize;
+            if (next <= cursor)
+                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx did not advance the query address");
+            const state = Number(raw.state);
+            if (includeFree || state === MEM_COMMIT) {
+                regions.push({
+                    ...raw,
+                    baseAddress: `0x${baseAddress.toString(16)}`,
+                    regionSize: regionSize.toString(),
+                    committed: state === MEM_COMMIT
+                });
+            }
+            cursor = next;
+            if (regions.length >= maxRegions) {
+                truncated = cursor <= end;
+                break;
+            }
+        }
+        return {
+            pid,
+            handle: handle.id,
+            start: `0x${start.toString(16)}`,
+            end: `0x${end.toString(16)}`,
+            includeFree,
+            maxRegions,
+            regions,
+            nextAddress: `0x${cursor.toString(16)}`,
+            truncated
+        };
+    }
     async watchStart(request) {
         const pid = boundedPid(request.pid);
         const address = hexAddress(request.address);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowdump",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "WoW native memory analysis CLI with Frida evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
   "license": "MIT",
   "repository": {

package/skills/wowdump/SKILL.md

@@ -12,6 +12,7 @@ description: 以 Frida 运行时探测为主，按证据需要交替使用 IDA P
 1. 先运行 `wowdump targets`，确认 PID、Wow.exe 路径、哈希和 buildKey；多个目标时让用户选择。该命令会创建或复用 `~/.wowdump/<buildKey>/database/`。
 2. 先检查 `wowdump database status --build <buildKey>`。同一可执行文件哈希、首选 image base 和模块大小时复用已有 IDA 数据库；哈希变化时数据库为 `stale`。
 3. 有 `reader_ready` profile 时先用 `wowdump memory read --pid <pid> --build <buildKey> --profile <profile> --field <name>`；Reader 不读取 IDA 数据库、dump 二进制或 runtime JSON。
+   需要定位堆或确认可读范围时，先用 `wowdump memory regions --pid <pid> --start <hex> --end <hex>` 枚举 `VirtualQueryEx` 返回的已提交区，再用同一 broker 做有界 `memory read`；默认不包含 free/reserved 区。
 4. 没有可用 profile 时，由 Agent 编写并显式传入 GumJS：`wowdump analyze dynamic --pid <pid> --build <buildKey> --script <GumJS> --confirm`。脚本可做快照、有限 Hook 和事件采集。
 5. 动态线索需要静态证据时运行 `wowdump analyze runtime --kind dump`。dump 只写当前 session 的 `.text/.rdata/.pdata`，`.data` 通过 `--sections` 按需加入；不创建新的静态数据库。
 6. 优先让 IDA Pro MCP 打开该 build 的 `database/ida/Wow.i64`，按 manifest 将 runtime overlay 映射到原始 Wow.exe，输出函数 RVA、字符串 RVA、XREF、结构偏移和字段类型。没有 IDA MCP 时，用 iced-x86 对相关范围局部反汇编。

package/skills/wowdump/references/commands.md

@@ -78,4 +78,16 @@ wowdump memory read `
 
 需要连续观察时使用 `memory watch start/poll/stop`。字段未定义、模块不匹配、指针为空或发生短读时，保留 JSON 证据并停止该字段，不改写 profile。
 
+需要枚举目标进程的虚拟内存布局时使用 `memory regions`。它通过同一个管理员 broker 调用 Windows `VirtualQueryEx`，默认只返回 `MEM_COMMIT` 区域；查询有地址范围和数量上限，不会把整片地址空间读入内存：
+
+```powershell
+wowdump memory regions `
+  --pid 33976 `
+  --start 0x15000000000 `
+  --end 0x15400000000 `
+  --max-regions 20000
+```
+
+需要诊断空闲/保留区时显式加入 `--include-free`。输出包含 `baseAddress`、`regionSize`、`state`、`protect`、`type` 和 `committed`，可将已提交的 heap 区域交给后续只读扫描。
+
 静态分析完成后回到 `analyze dynamic` Hook 验证候选，再生成 profile。短时 Hook/事件采集可以复制 [scripts/dynamic-session.js](../scripts/dynamic-session.js) 后按请求修改；它不会被 CLI 自动执行。详细脚本规则见 [dynamic.md](dynamic.md) 和 [disassemble.md](disassemble.md)。字段请求格式见 [request-schema.md](request-schema.md)，profile 生命周期见 [profiles.md](profiles.md)。