wowdump 0.3.4 → 0.3.7

package/dist/analysis/runtime-script.js

@@ -1,156 +0,0 @@
-/**
- * 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 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 { 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 }] };
-  }
-  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 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, 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 };
-`;

package/dist/frida-worker.js

@@ -1,153 +0,0 @@
-import { readFile, writeFile } from "node:fs/promises";
-import { createInterface } from "node:readline";
-import { FridaCommandRuntime } from "./analysis/frida-runtime.js";
-import { RuntimeDumpWriter } from "./analysis/runtime-dump.js";
-import { isAbsolute, resolve } from "node:path";
-function record(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function positive(value, name) {
-    const number = Number(value);
-    if (!Number.isSafeInteger(number) || number < 1)
-        throw new Error(`${name} must be a positive integer`);
-    return number;
-}
-/**
- * Elevated Frida execution boundary. Analysis belongs to the caller-supplied
- * GumJS source; this process only attaches, loads, calls, and cleans it up.
- */
-async function run(input) {
-    if (input.command !== "dynamic-script" && input.command !== "runtime-dump")
-        throw new Error("unsupported worker command");
-    const pid = positive(input.pid, "pid");
-    const buildKey = String(input.build ?? input.buildKey ?? "").trim();
-    if (!buildKey)
-        throw new Error("build is required");
-    const source = typeof input.source === "string"
-        ? input.source
-        : typeof input.script === "string" ? await readFile(input.script, "utf8") : "";
-    if (!source.trim())
-        throw new Error("script or source is required");
-    const runtime = new FridaCommandRuntime({ artifactDir: process.env.WOW_ANALYZE_DIR });
-    let sessionId;
-    let loaded = false;
-    const isDump = input.command === "runtime-dump";
-    const outputDirectory = isDump ? resolve(String(input.outputDir ?? "")) : undefined;
-    const outputDirectoryInput = isDump ? String(input.outputDir ?? "") : "";
-    const writer = isDump ? new RuntimeDumpWriter({
-        outputDirectory: outputDirectory,
-        buildKey,
-        pid,
-        executableSha256: typeof input.executableSha256 === "string" ? input.executableSha256 : null,
-        preferredImageBase: typeof input.preferredImageBase === "string" ? input.preferredImageBase : null,
-        moduleSize: Number.isSafeInteger(Number(input.moduleSize)) ? Number(input.moduleSize) : null,
-        dumpParameters: input.dumpParameters && typeof input.dumpParameters === "object" ? input.dumpParameters : undefined
-    }) : undefined;
-    let finalized = false;
-    try {
-        if (isDump) {
-            if (!outputDirectoryInput || !isAbsolute(outputDirectoryInput))
-                throw new Error("runtime dump outputDir must be an absolute path");
-            await writer.initialize();
-        }
-        const attached = await runtime.execute({ operation: "attach", pid, buildKey, allowUnmatched: true });
-        sessionId = String(attached.sessionId);
-        const modules = await runtime.execute({ operation: "modules", sessionId, pid, buildKey });
-        const module = Array.isArray(modules.modules)
-            ? modules.modules.find(item => String(item.name ?? "").toLowerCase() === "wow.exe")
-            : undefined;
-        const scriptSource = `globalThis.__WOWDUMP_INPUT__ = Object.freeze(${JSON.stringify(input.args ?? {})});\n${source}`;
-        let value;
-        let messages = [];
-        if (isDump) {
-            await writeFile(resolve(outputDirectory, "..", "target.json"), `${JSON.stringify({ schema: "wowdump.runtime-target.v1", pid, buildKey, module, executableSha256: input.executableSha256 ?? null, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8").catch(() => undefined);
-            let progressBytes = 0;
-            const streamed = await runtime.streamScriptCall({
-                operation: "script_load",
-                sessionId,
-                pid,
-                buildKey,
-                source: scriptSource,
-                exportName: typeof input.exportName === "string" ? input.exportName : "collect"
-            }, undefined, async (message, data) => {
-                const envelope = message && typeof message === "object" ? message : {};
-                if (envelope.type !== "send" || !data)
-                    return;
-                const payload = envelope.payload && typeof envelope.payload === "object" ? envelope.payload : {};
-                if (payload.type !== "wowdump.dump.chunk")
-                    return;
-                await writer.writeChunk(payload, data);
-                progressBytes += data.byteLength;
-                if (input.progress !== false)
-                    process.stderr.write(`wowdump dump ${progressBytes} bytes\\n`);
-            });
-            value = streamed.value;
-            const result = value && typeof value === "object" ? value : {};
-            if (result.ok !== true)
-                throw new Error(String(result.error ?? "runtime dump failed"));
-            const persisted = await writer.finalize({ ...result, module: module ?? result.module });
-            finalized = true;
-            await writeFile(resolve(outputDirectory, "..", "dynamic.json"), `${JSON.stringify({ ...result, manifestFile: persisted.manifestFile, generatedAt: new Date().toISOString() }, null, 2)}\n`, "utf8").catch(() => undefined);
-            return { ok: true, command: "analyze.runtime.dump", pid, buildKey, manifestFile: persisted.manifestFile, outputDirectory, manifest: persisted.manifest, sections: persisted.sections };
-        }
-        await runtime.execute({
-            operation: "script_load",
-            sessionId,
-            pid,
-            buildKey,
-            source: scriptSource,
-            scriptId: "dynamic"
-        });
-        loaded = true;
-        if (typeof input.exportName === "string" && input.exportName.trim()) {
-            const called = await runtime.execute({
-                operation: "script_call",
-                sessionId,
-                scriptId: "dynamic",
-                exportName: input.exportName,
-                args: Array.isArray(input.callArgs) ? input.callArgs : []
-            });
-            value = called.value;
-            messages = Array.isArray(called.messages) ? called.messages : [];
-        }
-        const durationMs = Math.min(120_000, positive(input.durationMs ?? 100, "duration-ms"));
-        if (value === undefined)
-            await new Promise(resolve => setTimeout(resolve, durationMs));
-        return {
-            ok: true,
-            command: "analyze.dynamic",
-            pid,
-            buildKey,
-            module: module && typeof module.base === "string"
-                ? { name: module.name, moduleBase: module.base, moduleSize: module.size ?? null }
-                : null,
-            exportName: typeof input.exportName === "string" ? input.exportName : null,
-            value,
-            messages,
-            script: typeof input.script === "string" ? input.script : "<inline>",
-            evidence: [{ kind: "frida-gumjs", source: "frida", moduleBase: module?.base ?? null }]
-        };
-    }
-    finally {
-        if (sessionId && loaded)
-            await runtime.execute({ operation: "script_unload", sessionId, scriptId: "dynamic" }).catch(() => undefined);
-        if (isDump && writer && !finalized)
-            await writer.abort().catch(() => undefined);
-        await runtime.close();
-    }
-}
-const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
-let failed = false;
-for await (const line of input) {
-    if (!line.trim())
-        continue;
-    try {
-        process.stdout.write(`${JSON.stringify(await run(record(JSON.parse(line))))}\n`);
-    }
-    catch (error) {
-        failed = true;
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-}
-if (failed)
-    process.exitCode = 1;

package/skills/wowdump/references/dynamic.md

@@ -1,54 +0,0 @@
-# Dynamic GumJS 编写指南
-
-## 目标与优先级
-
-dynamic 是默认主路径，负责从当前运行进程取得真实值和线索：模块基址、对象地址、函数地址、字节样本、字符串、返回值或事件证据。脚本可以使用静态阶段给出的候选 RVA，也可以自己做有界签名扫描；不要把未经验证的绝对地址当成长期 profile。
-
-## 脚本入口
-
-通过 `rpc.exports` 暴露一个小而明确的函数，例如 `collect`。CLI 的 `--args` 会放在 `globalThis.__WOWDUMP_INPUT__`，字段列表和读取上限从这里取得。
-
-API 参考： [Frida JavaScript API](https://frida.re/docs/javascript-api/)。
-
-一次普通 run 由 CLI 完成 attach 并加载脚本，脚本在同一次执行中完成 Hook、采集、限时和 cleanup。需要持续观察时，由脚本内部维护事件队列、采样计时器和清理逻辑，在一次 run 结束时返回结果；不增加单独的 `analyze focus` 命令，也暂不实现跨命令的 status、pause 或 checkpoint。
-
-轻量模式保持不变：
-
-```text
-wowdump analyze dynamic --script <GumJS> --confirm
-```
-
-`--script` 必须由 Agent 显式提供。仓库中的 `scripts/dynamic-session.js` 只是可复制和修改的示例，不是 CLI 默认脚本，也不会被自动执行。
-
-## 允许的操作
-
-- 枚举模块和导出
-- 在指定模块或范围内扫描模式
-- 读取有界内存并返回十六进制样本
-- 短时 Hook、回调或事件监听
-- 返回候选地址、RVA、对象关系和置信度
-
-每次脚本都要设置读取范围、最大 Hook 数、最大事件数和结束时间。默认禁止 `Stalker`；除非用户明确要求并给出极小范围、时长和事件上限，否则不要启用它。Hook、事件和内存读取都必须有上限。
-
-## 输出要求
-
-```json
-{
-  "buildKey": "retail@12.1.0.69587",
-  "pid": 33976,
-  "module": { "name": "Wow.exe", "moduleBase": "0x7ff7b5040000" },
-  "fields": {
-    "playerAuras": [{ "address": "0x...", "bytesHex": "...", "source": "frida" }]
-  },
-  "evidence": [{ "source": "frida", "kind": "runtime-sample" }]
-}
-```
-
-输出应足够让 IDA Pro MCP 或 iced-x86 在样本附近定位函数、字符串和 XREF，也应保留 Hook 的 `this`、参数、返回值和访问到的对象地址。拿不到字段时返回空数组和原因，不填充猜测地址。
-
-## 与静态分析交替
-
-- 已有候选 RVA：优先直接 Hook，观察真实调用和返回值。
-- 没有候选 RVA：先做小范围模块/字节扫描；仍不明确时导出最小 text 样本交给 IDA 或 iced。
-- 静态给出候选后回到 dynamic 验证，不要求一次静态分析解决全部字段。
-- 运行时值、用户触发动作和短时事件优先由 Frida 完成；长期稳定的 RVA、指针链和类型才需要静态证据。

package/skills/wowdump/scripts/dynamic-session.js

@@ -1,133 +0,0 @@
-/*
- * Copy-and-edit example for `wowdump analyze dynamic`.
- * It is intentionally not selected or executed by the CLI automatically.
- */
-"use strict";
-
-const input = globalThis.__WOWDUMP_INPUT__ && typeof globalThis.__WOWDUMP_INPUT__ === "object"
-  ? globalThis.__WOWDUMP_INPUT__
-  : {};
-
-const limit = (value, fallback, maximum) => {
-  const number = Number(value);
-  if (!Number.isFinite(number) || number < 1) return fallback;
-  return Math.min(Math.floor(number), maximum);
-};
-
-const durationMs = limit(input.durationMs, 5000, 120000);
-const maxEvents = limit(input.maxEvents, 100, 10000);
-const maxHooks = limit(input.maxHooks, 1, 32);
-const maxReadBytes = limit(input.maxReadBytes, 64, 256);
-const events = [];
-const candidates = [];
-const errors = [];
-const hooks = [];
-let stopWaiting;
-
-function record(event) {
-  if (events.length >= maxEvents) return false;
-  events.push({ timestamp: Date.now(), ...event });
-  if (events.length >= maxEvents && stopWaiting) stopWaiting();
-  return events.length < maxEvents;
-}
-
-function candidateAddress(candidate, module) {
-  if (!candidate || typeof candidate !== "object") return null;
-  if (candidate.address !== undefined) return ptr(String(candidate.address));
-  if (candidate.rva !== undefined) return module.base.add(ptr(String(candidate.rva)));
-  return null;
-}
-
-function inModule(address, module) {
-  const end = module.base.add(module.size);
-  return address.compare(module.base) >= 0 && address.compare(end) < 0;
-}
-
-function sampleBytes(address) {
-  try {
-    const range = Process.findRangeByAddress(address, "r--");
-    if (!range) return null;
-    const bytes = Memory.readByteArray(address, Math.min(maxReadBytes, range.size));
-    return bytes ? Array.from(new Uint8Array(bytes), value => value.toString(16).padStart(2, "0")).join("") : null;
-  } catch (error) {
-    errors.push(`read ${address}: ${error}`);
-    return null;
-  }
-}
-
-function installHook(address, name) {
-  if (hooks.length >= maxHooks) return;
-  try {
-    const listener = Interceptor.attach(address, {
-      onEnter(args) {
-        record({ kind: "enter", name, address: address.toString(), firstArg: args[0] ? args[0].toString() : null });
-      },
-      onLeave(retval) {
-        record({ kind: "leave", name, address: address.toString(), returnValue: retval.toString() });
-      }
-    });
-    hooks.push(listener);
-  } catch (error) {
-    errors.push(`hook ${name}: ${error}`);
-  }
-}
-
-rpc.exports = {
-  async collect() {
-    const moduleName = typeof input.module === "string" && input.module.trim() ? input.module : "Wow.exe";
-    const module = Process.findModuleByName(moduleName);
-    if (!module) {
-      return { ok: false, module: { name: moduleName }, candidates: [], events: [], evidence: [], errors: [`module ${moduleName} was not found`] };
-    }
-
-    const requested = Array.isArray(input.candidates) ? input.candidates.slice(0, maxHooks) : [];
-    const resolved = [];
-    for (const [index, value] of requested.entries()) {
-      try {
-        const address = candidateAddress(value, module);
-        if (!address || !inModule(address, module)) {
-          errors.push(`candidate ${index} is outside ${moduleName}`);
-          continue;
-        }
-        const item = {
-          name: value && typeof value.name === "string" ? value.name : `candidate_${index}`,
-          address: address.toString(),
-          rva: address.sub(module.base).toString(),
-          bytesHex: sampleBytes(address),
-          source: "frida"
-        };
-        candidates.push(item);
-        resolved.push({ address, name: item.name });
-      } catch (error) {
-        errors.push(`candidate ${index}: ${error}`);
-      }
-    }
-
-    for (const item of resolved) installHook(item.address, item.name);
-    let timer;
-    try {
-      await new Promise(resolve => {
-        stopWaiting = resolve;
-        timer = setTimeout(resolve, durationMs);
-      });
-    } finally {
-      stopWaiting = undefined;
-      if (timer) clearTimeout(timer);
-      for (const listener of hooks.splice(0)) {
-        try { listener.detach(); } catch (error) { errors.push(`cleanup: ${error}`); }
-      }
-    }
-
-    return {
-      ok: errors.length === 0,
-      module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size },
-      moduleBase: module.base.toString(),
-      candidates,
-      events,
-      truncated: events.length >= maxEvents,
-      limits: { durationMs, maxEvents, maxHooks, maxReadBytes },
-      evidence: [{ source: "frida", kind: "dynamic-session", moduleBase: module.base.toString(), eventCount: events.length, hookCount: candidates.length }],
-      errors
-    };
-  }
-};