wowdump 0.3.2 → 0.3.4

package/README.md

@@ -14,19 +14,23 @@ wowdump init
 ## 基本流程
 
 ```powershell
-# 1. 导出运行时模块或 provider
-wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind text --duration-ms 5000 --max-events 100 --confirm > runtime.json
+# 1. 发现目标并创建/复用 build 数据库
+wowdump targets
+wowdump database status --build "retail@VERSION"
 
-# 2. 通过 IDA Pro MCP（若可用）或 iced-x86 局部反汇编生成 profile
-wowdump analyze disassemble --exe "C:\Games\World of Warcraft\_retail_\Wow.exe" --build "retail@VERSION" --runtime-export "$HOME\.wowdump\runtime\<session-id>\text.json" --output "$HOME\.wowdump\runtime\<session-id>\candidate.profile.json"
+# 2. 导出运行时模块段
+wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind dump --confirm
 
-# 3. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
+# 3. 用 IDA Pro MCP（若可用）或 iced-x86 分析 session dump manifest，保存字段候选和证据
+# 4. 将候选证据交给 verify，再用 Reader 验证
+
+# 5. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
 wowdump memory read --pid 1234 --profile "$HOME\.wowdump\retail@VERSION\profile\player-state.json" --field playerAuras
 ```
 
 Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续调用复用同一 broker，空闲 20 分钟后退出。Frida 运行时导出需要显式 `--confirm`；高开销 Stalker 默认关闭。
 
-当前 build 的持久化 profile 放在 `~/.wowdump/<buildKey>/profile/`；动态导出、静态候选和验证报告放在 runtime 会话临时目录。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md` 与 `references/profiles.md`；短时 Hook 示例见 `~/.agents/skills/wowdump/scripts/dynamic-session.js`。
+`targets` 会写入 `~/.wowdump/<buildKey>/build.json` 和 `database/database.json`；同一 build 的 IDA 数据库只创建一份。`analyze runtime --kind dump` 默认把 `.text`、`.rdata`、`.pdata` 流式写入当前 session，`.data` 需通过 `--sections` 显式加入。`analyze runtime --kind verify --profile <file>` 只验证已有 profile 的 RVA。Reader 只读取 `~/.wowdump/<buildKey>/profile/`，不读取 IDA 数据库和 dump 二进制。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md` 与 `references/profiles.md`；短时 Hook 示例见 `~/.agents/skills/wowdump/scripts/dynamic-session.js`。
 
 ## 开发验证
 

package/dist/analysis/frida-runtime.js

@@ -281,6 +281,32 @@ export class FridaCommandRuntime {
             await this.detachSession(sessionId).catch(() => undefined);
         }
     }
+    /**
+     * Run a caller-supplied export while forwarding Frida binary messages to a
+     * consumer. Runtime dump uses this path so ArrayBuffers never become JSON.
+     */
+    async streamScriptCall(request, context, handler, callArgs = []) {
+        const record = await this.session(request, context);
+        const source = this.source(request.source);
+        const script = await record.session.createScript(buildPrelude(context ?? record.context) + "\n" + source, request.options);
+        let pending = Promise.resolve();
+        script.message?.connect((message, data) => {
+            pending = pending.then(() => handler(message, data));
+        });
+        await script.load();
+        try {
+            const name = requireString(request.exportName ?? request.method, "exportName");
+            const value = await exportFunction(script, name)(...callArgs.map(item => decodeHostArg(item)));
+            await pending;
+            return { sessionId: record.id, value: normalize(value), ...sessionContext(record) };
+        }
+        finally {
+            try {
+                await script.unload();
+            }
+            catch { /* cleanup is best effort */ }
+        }
+    }
     async api() {
         if (this.apiOverride)
             return this.apiOverride;

package/dist/analysis/runtime-dump.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+function safeName(name) {
+    const value = String(name ?? "section");
+    return /^[A-Za-z0-9_.-]+$/.test(value) ? value : "section";
+}
+/** Streams Frida ArrayBuffer messages into section files without Base64 JSON. */
+export class RuntimeDumpWriter {
+    outputDirectory;
+    options;
+    sections = new Map();
+    aborted = false;
+    constructor(options) {
+        this.options = options;
+        this.outputDirectory = resolve(options.outputDirectory);
+    }
+    async initialize() {
+        await mkdir(this.outputDirectory, { recursive: true });
+    }
+    async writeChunk(meta, data) {
+        if (this.aborted)
+            throw new Error("runtime dump writer is aborted");
+        if (!data)
+            throw new Error("runtime dump chunk has no binary payload");
+        const name = safeName(meta.section);
+        const offset = Number(meta.offset);
+        if (!Number.isSafeInteger(offset) || offset < 0)
+            throw new Error(`invalid ${name} chunk offset`);
+        let state = this.sections.get(name);
+        if (!state) {
+            const file = join(this.outputDirectory, `${name}.bin`);
+            state = { name, file, handle: await open(file, "w"), hash: createHash("sha256"), offset: 0, bytes: 0 };
+            this.sections.set(name, state);
+        }
+        if (offset !== state.offset)
+            throw new Error(`${name} chunk offset ${offset} does not follow ${state.offset}`);
+        const bytes = Buffer.from(data);
+        await state.handle.write(bytes, 0, bytes.length, state.offset);
+        state.hash.update(bytes);
+        state.offset += bytes.length;
+        state.bytes += bytes.length;
+    }
+    async finalize(value) {
+        if (this.aborted)
+            throw new Error("runtime dump writer is aborted");
+        for (const state of this.sections.values())
+            await state.handle.close();
+        const rawSections = Array.isArray(value.sections) ? value.sections : [];
+        for (const section of rawSections) {
+            const name = safeName(section.name);
+            if (!this.sections.has(name))
+                await writeFile(join(this.outputDirectory, `${name}.bin`), Buffer.alloc(0));
+        }
+        const sections = rawSections.map((section) => {
+            const name = safeName(section.name);
+            const state = this.sections.get(name);
+            return {
+                ...section,
+                ...(state ? { file: state.file, bytes: state.bytes, sha256: state.hash.digest("hex") } : { file: join(this.outputDirectory, `${name}.bin`), bytes: 0, sha256: null })
+            };
+        });
+        const manifest = {
+            schema: "wowdump.runtime-dump.v2",
+            kind: "dump",
+            buildKey: this.options.buildKey,
+            pid: this.options.pid,
+            executableSha256: this.options.executableSha256 ?? null,
+            preferredImageBase: this.options.preferredImageBase ?? null,
+            moduleBase: typeof value.module?.moduleBase === "string"
+                ? value.module.moduleBase
+                : typeof value.module?.base === "string" ? value.module.base : null,
+            moduleSize: this.options.moduleSize ?? (typeof value.module?.moduleSize === "number" ? value.module.moduleSize : null),
+            module: value.module ?? null,
+            totalBytes: sections.reduce((sum, section) => sum + Number(section.bytes ?? 0), 0),
+            truncated: value.truncated === true || sections.some(section => section.truncated === true),
+            limits: value.limits ?? null,
+            dumpParameters: this.options.dumpParameters ?? null,
+            sections,
+            evidence: value.evidence ?? [],
+            generatedAt: new Date().toISOString()
+        };
+        const manifestFile = join(this.outputDirectory, "manifest.json");
+        await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        return { ok: true, kind: "dump", manifestFile, outputDirectory: this.outputDirectory, manifest, sections: sections.map(section => ({ name: section.name, bytes: section.bytes, sha256: section.sha256 })) };
+    }
+    async abort() {
+        this.aborted = true;
+        for (const state of this.sections.values())
+            await state.handle.close().catch(() => undefined);
+        await rm(this.outputDirectory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/analysis/runtime-script.js

@@ -1,36 +1,156 @@
-/** Built-in bounded sampler used by `analyze runtime`; dynamic stays caller-owned. */
+/**
+ * Built-in runtime evidence operations used by `analyze runtime`.
+ *
+ * The caller-supplied `analyze dynamic` path remains the escape hatch for
+ * field-specific GumJS. This script only provides two bounded primitives:
+ * `dump` exports PE sections for static analysis and `verify` reads profile
+ * candidates at runtime.
+ */
 export const RUNTIME_EXPORT_SCRIPT = String.raw `
 "use strict";
 const input = globalThis.__WOWDUMP_INPUT__ || {};
 const moduleName = typeof input.module === "string" && input.module ? input.module : "Wow.exe";
 const module = Process.findModuleByName(moduleName);
-const limit = Math.min(Math.max(Number(input.maxEvents || 16), 1), 256);
-const sampleBytes = Math.min(Math.max(Number(input.sampleBytes || 64), 1), 256);
-function bytes(address, size) { const value = address.readByteArray(size); return value ? Array.from(new Uint8Array(value), byte => byte.toString(16).padStart(2, "0")).join("") : ""; }
-function collect() {
-  if (!module) return { ok: false, module: { name: moduleName }, records: [], evidence: [{ source: "frida", kind: "module-missing" }] };
-  if (input.kind === "text") {
-    const ranges = Process.enumerateRanges("r-x").filter(range => range.base.compare(module.base) >= 0 && range.base.compare(module.base.add(module.size)) < 0);
-    const textRanges = ranges.map(range => ({ base: range.base.toString(), rva: range.base.sub(module.base).toString(), size: range.size, protection: range.protection }));
-    const records = [];
-    for (const range of ranges) {
-      if (records.length >= limit) break;
-      const rva = range.base.sub(module.base);
-      const offset = rva.isNull() && range.size > 0x1000 ? 0x1000 : 0;
-      const address = range.base.add(offset);
-      records.push({ address: address.toString(), rva: address.sub(module.base).toString(), size: Math.min(sampleBytes, range.size - offset), bytesHex: bytes(address, Math.min(sampleBytes, range.size - offset)) });
+const maxCandidates = Math.min(Math.max(Number(input.maxCandidates || input.maxEvents || 256), 1), 4096);
+const maxSectionBytes = Math.min(Math.max(Number(input.maxSectionBytes || 128 * 1024 * 1024), 1), 512 * 1024 * 1024);
+const maxTotalBytes = Math.min(Math.max(Number(input.maxTotalBytes || 256 * 1024 * 1024), 1), 768 * 1024 * 1024);
+const chunkSize = Math.min(Math.max(Number(input.chunkSize || 1024 * 1024), 4096), 4 * 1024 * 1024);
+const maxVerifyBytes = Math.min(Math.max(Number(input.maxVerifyBytes || 256), 1), 4096);
+
+function readBytes(address, size) {
+  const value = address.readByteArray(size);
+  return value ? new Uint8Array(value) : null;
+}
+
+function bytesHex(address, size) {
+  const bytes = readBytes(address, size);
+  if (!bytes) return "";
+  let output = "";
+  for (let index = 0; index < bytes.length; index++) output += bytes[index].toString(16).padStart(2, "0");
+  return output;
+}
+
+function ascii(address, size) {
+  const bytes = readBytes(address, size);
+  if (!bytes) return "";
+  let output = "";
+  for (let index = 0; index < bytes.length; index++) {
+    const value = bytes[index];
+    output += value >= 0x20 && value <= 0x7e ? String.fromCharCode(value) : "";
+  }
+  return output;
+}
+
+function u16(address) { return address.readU16(); }
+function u32(address) { return address.readU32(); }
+function sectionName(address) {
+  return ascii(address, 8).replace(/\0/g, "").trim();
+}
+
+function parseSections() {
+  if (!module) return { error: "module-missing", sections: [] };
+  try {
+    const base = module.base;
+    if (u16(base) !== 0x5a4d) return { error: "invalid-dos-signature", sections: [] };
+    const peOffset = u32(base.add(0x3c));
+    if (peOffset < 0x40 || peOffset > module.size - 24) return { error: "invalid-pe-offset", sections: [] };
+    const pe = base.add(peOffset);
+    if (u32(pe) !== 0x00004550) return { error: "invalid-pe-signature", sections: [] };
+    const count = u16(pe.add(6));
+    const optionalSize = u16(pe.add(20));
+    if (count < 1 || count > 96 || optionalSize < 0x60) return { error: "invalid-section-table", sections: [] };
+    const table = pe.add(24 + optionalSize);
+    const sections = [];
+    for (let index = 0; index < count; index++) {
+      const header = table.add(index * 40);
+      const name = sectionName(header);
+      const virtualSize = u32(header.add(8));
+      const rva = u32(header.add(12));
+      const rawSize = u32(header.add(16));
+      const characteristics = u32(header.add(36));
+      const size = Math.max(virtualSize, rawSize);
+      if (!name || !size || rva >= module.size) continue;
+      const boundedSize = Math.min(size, module.size - rva);
+      const executable = (characteristics & 0x20000000) !== 0;
+      const writable = (characteristics & 0x80000000) !== 0;
+      const readable = (characteristics & 0x40000000) !== 0;
+      sections.push({
+        name,
+        rva: "0x" + rva.toString(16),
+        runtimeAddress: base.add(rva).toString(),
+        virtualSize,
+        rawSize,
+        characteristics: "0x" + characteristics.toString(16),
+        protection: (readable ? "r" : "") + (writable ? "w" : "") + (executable ? "x" : ""),
+        size: boundedSize
+      });
     }
-    return { ok: true, kind: "text", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, textRanges, samples: records, records, evidence: [{ source: "frida", kind: "frida-runtime-text", samples: records.length }] };
+    return { error: null, sections };
+  } catch (error) {
+    return { error: String(error), sections: [] };
+  }
+}
+
+function dumpSection(section, totalState) {
+  const requestedSize = Math.min(section.size, maxSectionBytes);
+  const available = Math.max(0, maxTotalBytes - totalState.bytes);
+  const readSize = Math.min(requestedSize, available);
+  let offset = 0;
+  while (offset < readSize) {
+    const size = Math.min(chunkSize, readSize - offset);
+    const bytes = readBytes(module.base.add(parseInt(section.rva, 16)).add(offset), size);
+    if (!bytes) break;
+    send({ type: "wowdump.dump.chunk", section: section.name, offset, size: bytes.length }, bytes.buffer);
+    offset += bytes.length;
+    if (bytes.length !== size) break;
+  }
+  totalState.bytes += offset;
+  return { ...section, requestedSize, readSize: offset, truncated: offset < section.size };
+}
+
+function candidateEntries(profile) {
+  const entries = [];
+  const fields = profile && typeof profile.fields === "object" && !Array.isArray(profile.fields) ? profile.fields : {};
+  for (const [name, value] of Object.entries(fields)) entries.push({ name, value });
+  return entries.slice(0, maxCandidates);
+}
+
+function candidateRva(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const item = value;
+  const root = item.root && typeof item.root === "object" && !Array.isArray(item.root) ? item.root : {};
+  const rva = item.rva ?? root.rva;
+  if (typeof rva !== "string" && typeof rva !== "number") return null;
+  try { return ptr(String(rva)).toString(); } catch (_) { return null; }
+}
+
+function collect() {
+  if (!module) return { ok: false, kind: input.kind || "dump", module: { name: moduleName }, sections: [], records: [], evidence: [{ source: "frida", kind: "module-missing" }] };
+  if (input.kind === "dump") {
+    const parsed = parseSections();
+    if (parsed.error) return { ok: false, kind: "dump", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, sections: [], records: [], evidence: [{ source: "frida", kind: "pe-parse-failed", error: parsed.error }] };
+    const requestedSections = Array.isArray(input.sections) && input.sections.length > 0
+      ? input.sections.map(value => String(value).toLowerCase())
+      : [".text", ".rdata", ".pdata"];
+    const selected = parsed.sections.filter(section => requestedSections.includes(section.name.toLowerCase()));
+    const totalState = { bytes: 0 };
+    const sections = selected.map(section => dumpSection(section, totalState));
+    return { ok: true, kind: "dump", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size, path: module.path }, sections, totalBytes: totalState.bytes, limits: { maxSectionBytes, maxTotalBytes, chunkSize }, truncated: sections.some(section => section.truncated), evidence: [{ source: "frida", kind: "frida-runtime-pe-sections", sections: sections.map(section => section.name), totalBytes: totalState.bytes }] };
   }
-  const profile = input.profile && typeof input.profile === "object" ? input.profile : {};
-  const candidates = Array.isArray(profile.providers) ? profile.providers : [];
+  if (input.kind !== "verify") return { ok: false, kind: input.kind || null, module: { name: module.name }, records: [], evidence: [{ source: "frida", kind: "unsupported-runtime-kind" }] };
+  const profile = input.profile && typeof input.profile === "object" ? input.profile : null;
+  if (!profile) return { ok: false, kind: "verify", module: { name: module.name, moduleBase: module.base.toString() }, records: [], evidence: [{ source: "frida", kind: "profile-required" }] };
   const records = [];
-  for (const candidate of candidates.slice(0, limit)) {
-    if (!candidate || typeof candidate.rva !== "string") continue;
-    const address = module.base.add(ptr(candidate.rva));
-    records.push({ name: candidate.name || "candidate", rva: candidate.rva, runtimeAddress: address.toString(), bytesHex: bytes(address, Math.min(Number(candidate.size || 16), 256)), source: "frida" });
+  for (const entry of candidateEntries(profile)) {
+    const rva = candidateRva(entry.value);
+    if (rva === null) { records.push({ name: entry.name, ok: false, reason: "missing-rva", source: "frida" }); continue; }
+    const address = module.base.add(ptr(rva));
+    try {
+      const bytes = bytesHex(address, Math.min(Number(entry.value.size || entry.value.byteSize || maxVerifyBytes), maxVerifyBytes));
+      records.push({ name: entry.name, rva, runtimeAddress: address.toString(), bytesHex: bytes, bytesRead: bytes.length / 2, complete: bytes.length > 0, ok: bytes.length > 0, source: "frida" });
+    } catch (error) { records.push({ name: entry.name, rva, runtimeAddress: address.toString(), ok: false, reason: String(error), source: "frida" }); }
   }
-  return { ok: true, module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, records, evidence: [{ source: "frida", kind: "frida-runtime-read", count: records.length }] };
+  return { ok: true, kind: "verify", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size, path: module.path }, records, evidence: [{ source: "frida", kind: "frida-runtime-verify", candidates: records.length, passed: records.filter(item => item.ok).length }] };
 }
 rpc.exports = { collect };
 `;