wowdump 0.3.5 → 0.3.7

package/dist/debug/cdb.js

@@ -0,0 +1,412 @@
+import { createHash } from "node:crypto";
+import { spawn as nodeSpawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+export class CdbError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "CdbError";
+        this.code = code;
+        this.details = details;
+    }
+}
+function boundedInteger(value, name, minimum, maximum) {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
+        throw new CdbError("CDB_ARGUMENT_INVALID", `${name} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return number;
+}
+function address(value, name) {
+    const text = String(value ?? "").trim();
+    if (!/^0x[0-9a-f]+$/i.test(text))
+        throw new CdbError("CDB_ARGUMENT_INVALID", `${name} must be a hexadecimal address`);
+    const result = BigInt(text);
+    if (result < 0n || result > 0xffffffffffffffffn)
+        throw new CdbError("CDB_ARGUMENT_INVALID", `${name} is outside the 64-bit range`);
+    return result;
+}
+function hex(value) { return `0x${value.toString(16)}`; }
+function validCommand(value, name) {
+    const command = String(value ?? "");
+    if (!command || command.includes("\0") || command.length > 64 * 1024)
+        throw new CdbError("CDB_ARGUMENT_INVALID", `${name} is empty or too large`);
+    return command;
+}
+function validCommandList(values, fallback = []) {
+    const source = values ?? fallback;
+    if (!Array.isArray(source) || source.length > 256)
+        throw new CdbError("CDB_ARGUMENT_INVALID", "CDB command list is too large");
+    const commands = source.map((value, index) => validCommand(value, `commands[${index}]`));
+    if (commands.join("\n").length > 512 * 1024)
+        throw new CdbError("CDB_ARGUMENT_INVALID", "CDB command script is too large");
+    return commands;
+}
+function validArgs(values) {
+    if (values === undefined)
+        return [];
+    if (!Array.isArray(values) || values.length > 128)
+        throw new CdbError("CDB_ARGUMENT_INVALID", "CDB argument list is too large");
+    return values.map((value, index) => {
+        const arg = String(value ?? "");
+        if (arg.includes("\0") || arg.length > 32 * 1024)
+            throw new CdbError("CDB_ARGUMENT_INVALID", `cdbArgs[${index}] is invalid`);
+        return arg;
+    });
+}
+async function spawnText(executable, args, timeoutMs) {
+    return runCdbProcess({ executable, args, cwd: dirname(executable), timeoutMs });
+}
+async function runWhere(name) {
+    if (process.platform !== "win32")
+        return undefined;
+    const result = await runCdbProcess({ executable: "where.exe", args: [name], cwd: process.cwd(), timeoutMs: 2_000 });
+    if (result.exitCode !== 0)
+        return undefined;
+    return result.stdout.split(/\r?\n/).map(value => value.trim()).find(value => value && existsSync(value));
+}
+function candidatePaths(env) {
+    const values = [];
+    const configured = env.WOWDUMP_CDB?.trim();
+    if (configured)
+        values.push({ path: configured, source: "environment" });
+    const programFilesX86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    const programFiles = env.ProgramFiles ?? "C:\\Program Files";
+    const windir = env.WINDIR ?? "C:\\Windows";
+    values.push({ path: join(programFilesX86, "Windows Kits", "10", "Debuggers", "x64", "cdb.exe"), source: "windows-sdk" }, { path: join(programFiles, "Windows Kits", "10", "Debuggers", "x64", "cdb.exe"), source: "windows-sdk" }, { path: join(windir, "System32", "cdb.exe"), source: "windbg" }, { path: join(programFiles, "WindowsApps", "Microsoft.WinDbg_", "cdb.exe"), source: "windbg" }, { path: join(programFiles, "Windows Kits", "10", "Debuggers", "x64", "cdb.exe"), source: "windbg" });
+    return values;
+}
+async function discoverWinDbgDirectories(env) {
+    const roots = [env.ProgramFiles, env["ProgramFiles(x86)"], env.LOCALAPPDATA].filter((value) => Boolean(value));
+    const results = [];
+    for (const root of roots) {
+        for (const relative of ["Windows Kits", "WinDbg", "WindowsApps"]) {
+            const directory = join(root, relative);
+            try {
+                const entries = await readdir(directory, { withFileTypes: true });
+                for (const entry of entries.filter(item => item.isDirectory()).slice(0, 200)) {
+                    results.push(join(directory, entry.name, "Debuggers", "x64", "cdb.exe"));
+                    results.push(join(directory, entry.name, "cdb.exe"));
+                }
+            }
+            catch { /* directory is optional */ }
+        }
+    }
+    return results;
+}
+export async function discoverCdb(env = process.env) {
+    if (process.platform !== "win32" && env.WOWDUMP_CDB?.trim() === undefined) {
+        return { available: false, code: "CDB_NOT_FOUND", message: "未找到 WinDbg CDB" };
+    }
+    const candidates = [...candidatePaths(env), ...(await discoverWinDbgDirectories(env)).map(path => ({ path, source: "windbg" }))];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        const path = resolve(candidate.path);
+        const key = path.toLowerCase();
+        if (seen.has(key) || !existsSync(path))
+            continue;
+        seen.add(key);
+        const version = await spawnText(path, ["-version"], 3_000).catch(() => ({ stdout: "", stderr: "" }));
+        return { available: true, executable: path, version: (version.stdout || version.stderr).split(/\r?\n/).map(value => value.trim()).find(Boolean) ?? null, source: candidate.source };
+    }
+    const found = await runWhere("cdb.exe");
+    if (found) {
+        const version = await spawnText(found, ["-version"], 3_000).catch(() => ({ stdout: "", stderr: "" }));
+        return { available: true, executable: resolve(found), version: (version.stdout || version.stderr).split(/\r?\n/).map(value => value.trim()).find(Boolean) ?? null, source: "where" };
+    }
+    return { available: false, code: "CDB_NOT_FOUND", message: "未找到 WinDbg CDB" };
+}
+async function terminateProcess(child) {
+    if (child.exitCode !== null)
+        return;
+    try {
+        child.kill();
+    }
+    catch { /* already exited */ }
+    if (process.platform === "win32" && child.pid) {
+        await new Promise(resolveDone => {
+            const killer = nodeSpawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+            killer.once("exit", () => resolveDone());
+            killer.once("error", () => resolveDone());
+        });
+    }
+}
+export function runCdbProcess(options) {
+    const spawn = options.spawn ?? nodeSpawn;
+    return new Promise(resolveResult => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        let child;
+        let timer;
+        const finish = (exitCode, signal, started) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolveResult({ exitCode, signal, stdout, stderr, timedOut, started });
+        };
+        try {
+            child = spawn(options.executable, [...options.args], {
+                shell: false,
+                windowsHide: true,
+                cwd: resolve(options.cwd),
+                env: options.env ?? process.env,
+                stdio: ["ignore", "pipe", "pipe"]
+            });
+        }
+        catch (error) {
+            stderr += error instanceof Error ? error.message : String(error);
+            finish(1, null, false);
+            return;
+        }
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", value => { stdout += String(value); });
+        child.stderr?.on("data", value => { stderr += String(value); });
+        timer = setTimeout(() => {
+            timedOut = true;
+            void terminateProcess(child).finally(() => finish(1, null, true));
+        }, Math.max(1, options.timeoutMs));
+        timer.unref?.();
+        child.once("error", error => { stderr += error.message; finish(1, null, child.pid !== undefined); });
+        child.once("exit", (code, signal) => finish(code ?? 1, signal, true));
+    });
+}
+function readU16(buffer, offset) { return buffer.readUInt16LE(offset); }
+function readU32(buffer, offset) { return buffer.readUInt32LE(offset); }
+export async function readPeLayout(file) {
+    const input = resolve(file);
+    const buffer = await readFile(input);
+    if (buffer.length < 0x100 || buffer.toString("ascii", 0, 2) !== "MZ")
+        throw new CdbError("PE_INVALID", "Wow.exe has no DOS header");
+    const peOffset = readU32(buffer, 0x3c);
+    if (peOffset + 24 > buffer.length || buffer.toString("ascii", peOffset, peOffset + 4) !== "PE\0\0")
+        throw new CdbError("PE_INVALID", "Wow.exe has no PE header");
+    const sections = readU16(buffer, peOffset + 6);
+    const optionalSize = readU16(buffer, peOffset + 20);
+    const optional = peOffset + 24;
+    const magic = readU16(buffer, optional);
+    const imageBase = magic === 0x20b ? buffer.readBigUInt64LE(optional + 24) : BigInt(readU32(buffer, optional + 28));
+    const sizeOfImage = readU32(buffer, optional + 56);
+    const table = optional + optionalSize;
+    const values = [];
+    for (let index = 0; index < sections; index += 1) {
+        const offset = table + index * 40;
+        if (offset + 40 > buffer.length)
+            break;
+        const name = buffer.subarray(offset, offset + 8).toString("ascii").replace(/\0+$/u, "");
+        const virtualSize = readU32(buffer, offset + 8);
+        const rva = readU32(buffer, offset + 12);
+        const rawSize = readU32(buffer, offset + 16);
+        const characteristics = readU32(buffer, offset + 36);
+        const protection = `${characteristics & 0x40000000 ? "r" : ""}${characteristics & 0x80000000 ? "w" : ""}${characteristics & 0x20000000 ? "x" : ""}`;
+        if (name && (virtualSize || rawSize))
+            values.push({ name, rva: hex(BigInt(rva)), virtualSize, rawSize, characteristics: hex(BigInt(characteristics)), protection });
+    }
+    return { imageBase: hex(imageBase), moduleSize: sizeOfImage, sections: values };
+}
+function quoteCdbPath(file) {
+    const value = resolve(file);
+    if (!isAbsolute(value) || value.includes("\0"))
+        throw new CdbError("CDB_ARGUMENT_INVALID", "CDB output path must be absolute");
+    return `"${value.replace(/"/gu, "\\\"")}"`;
+}
+function baseCdbCommands(request, generated) {
+    const extra = validCommandList(request.commands);
+    return [...generated, ...extra, "q"];
+}
+function buildCdbArgs(request, commandFile) {
+    const extra = validArgs(request.cdbArgs);
+    return ["-p", String(request.pid), "-cf", commandFile, ...extra];
+}
+function parseHexValue(value) {
+    const match = value.match(/0x[0-9a-f]+/i);
+    return match ? `0x${BigInt(match[0]).toString(16)}` : "0x0";
+}
+export function parseBreakpointHits(output) {
+    const hits = [];
+    const blocks = output.split("WOWDUMP_HIT_BEGIN").slice(1);
+    for (const block of blocks) {
+        const end = block.indexOf("WOWDUMP_HIT_END");
+        if (end < 0)
+            continue;
+        const values = {};
+        for (const line of block.slice(0, end).split(/\r?\n/)) {
+            const match = line.match(/^\s*(rip|rcx|rdx|r8|r9|rsp|returnAddress|threadId)\s*=\s*(\S+)/u);
+            if (match)
+                values[match[1]] = parseHexValue(match[2]);
+        }
+        if (values.rip && values.rcx && values.rdx && values.r8 && values.r9 && values.rsp && values.returnAddress && values.threadId) {
+            hits.push(values);
+        }
+    }
+    return hits;
+}
+async function writeCdbScript(directory, commands) {
+    await mkdir(directory, { recursive: true });
+    const file = join(directory, `commands-${Date.now()}-${Math.random().toString(16).slice(2)}.cdb`);
+    await writeFile(file, `${commands.join("\n")}\n`, "utf8");
+    return file;
+}
+async function sha256(file) {
+    const hash = createHash("sha256");
+    hash.update(await readFile(file));
+    return hash.digest("hex");
+}
+async function dump(request, info) {
+    const outputDir = resolve(request.outputDir);
+    const maxSectionBytes = boundedInteger(request.maxSectionBytes, "maxSectionBytes", 1, 512 * 1024 * 1024);
+    const maxTotalBytes = boundedInteger(request.maxTotalBytes, "maxTotalBytes", 1, 768 * 1024 * 1024);
+    const timeoutMs = boundedInteger(request.timeoutMs, "timeoutMs", 1, 15 * 60 * 1000);
+    if (!Array.isArray(request.sections) || request.sections.length === 0 || request.sections.length > 64)
+        throw new CdbError("CDB_ARGUMENT_INVALID", "sections must contain between 1 and 64 entries");
+    let totalRequested = 0;
+    const normalizedSections = request.sections.map((section, index) => {
+        const readSize = boundedInteger(section.readSize, `sections[${index}].readSize`, 1, Math.min(maxSectionBytes, maxTotalBytes));
+        const file = resolve(section.file);
+        if (dirname(file).toLowerCase() !== outputDir.toLowerCase())
+            throw new CdbError("CDB_ARGUMENT_INVALID", `sections[${index}].file must be inside outputDir`);
+        totalRequested += readSize;
+        if (totalRequested > maxTotalBytes)
+            throw new CdbError("CDB_ARGUMENT_INVALID", "section sizes exceed maxTotalBytes");
+        return { ...section, readSize, file };
+    });
+    await mkdir(outputDir, { recursive: true });
+    const generated = [".echo WOWDUMP_DUMP_BEGIN"];
+    for (const section of normalizedSections) {
+        const start = address(section.runtimeAddress, `${section.name}.runtimeAddress`);
+        const end = start + BigInt(section.readSize);
+        generated.push(`.writemem ${quoteCdbPath(section.file)} ${hex(start)} ${hex(end)}`);
+        generated.push(`.echo WOWDUMP_DUMP_SECTION ${section.name}`);
+    }
+    const commands = baseCdbCommands(request, generated);
+    const commandFile = await writeCdbScript(outputDir, commands);
+    const logFile = join(outputDir, "cdb.log");
+    try {
+        const result = await runCdbProcess({ executable: info.executable, args: buildCdbArgs(request, commandFile), cwd: outputDir, timeoutMs });
+        await writeFile(logFile, `${result.stdout}${result.stderr ? `\n[stderr]\n${result.stderr}` : ""}`, "utf8");
+        if (!result.started)
+            throw new CdbError("CDB_START_FAILED", "CDB 启动失败", { executable: info.executable, stderr: result.stderr });
+        if (result.timedOut)
+            throw new CdbError("CDB_TIMEOUT", "CDB 调试请求超时", { timeoutMs, logFile });
+        if (result.exitCode !== 0)
+            throw new CdbError("CDB_EXIT_NONZERO", `CDB exited with code ${result.exitCode}`, { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, logFile });
+        const manifestSections = [];
+        for (const section of normalizedSections) {
+            const bytes = await stat(section.file).then(value => value.size).catch(() => 0);
+            manifestSections.push({ ...section, bytes, sha256: bytes > 0 ? await sha256(section.file) : null, shortRead: bytes !== section.readSize });
+        }
+        const manifest = {
+            schema: "wowdump.runtime-dump.v3",
+            kind: "dump",
+            buildKey: request.buildKey,
+            pid: request.pid,
+            executableSha256: request.executableSha256 ?? null,
+            moduleBase: hex(address(request.moduleBase, "moduleBase")),
+            preferredImageBase: request.preferredImageBase ?? null,
+            moduleSize: request.moduleSize ?? null,
+            sections: manifestSections,
+            totalBytes: manifestSections.reduce((sum, value) => sum + Number(value.bytes ?? 0), 0),
+            engine: { name: "cdb", path: info.executable, version: info.version ?? null },
+            logFile,
+            dumpParameters: {
+                executableSha256: request.executableSha256 ?? null,
+                sections: normalizedSections.map(section => section.name),
+                maxSectionBytes,
+                maxTotalBytes,
+                cdbArgs: validArgs(request.cdbArgs),
+                commands: validCommandList(request.commands)
+            },
+            generatedAt: new Date().toISOString()
+        };
+        const manifestFile = join(outputDir, "manifest.json");
+        await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        return { ok: true, kind: "dump", manifestFile, outputDirectory: outputDir, manifest, sections: manifestSections.map(value => ({ name: value.name, bytes: value.bytes, sha256: value.sha256 })) };
+    }
+    finally {
+        await rm(commandFile, { force: true }).catch(() => undefined);
+    }
+}
+async function breakpoint(request, info, queryPage) {
+    const maxHits = boundedInteger(request.maxHits, "maxHits", 1, 1024);
+    const durationMs = boundedInteger(request.durationMs, "durationMs", 1, 10 * 60 * 1000);
+    const runtimeAddress = address(request.moduleBase, "moduleBase") + address(request.rva, "rva");
+    const entryPage = queryPage ? await queryPage(runtimeAddress).catch(error => ({ error: error instanceof Error ? error.message : String(error) })) : null;
+    const escaped = `.printf \"WOWDUMP_HIT_BEGIN\\nrip=0x%p\\nrcx=0x%p\\nrdx=0x%p\\nr8=0x%p\\nr9=0x%p\\nrsp=0x%p\\nreturnAddress=0x%p\\nthreadId=0x%p\\nWOWDUMP_HIT_END\\n\", @rip, @rcx, @rdx, @r8, @r9, @rsp, poi(@rsp), @$tid`;
+    const generated = [
+        "r @$t0 = 0",
+        `ba e 1 ${hex(runtimeAddress)} \".if (@$t0 >= ${maxHits}) { bc *; q } .else { r @$t0 = @$t0 + 1; ${escaped}; gc }\"`,
+        "g"
+    ];
+    const commands = baseCdbCommands(request, generated);
+    const directory = request.outputFile ? dirname(resolve(request.outputFile)) : await mkdtemp(join(tmpdir(), "wowdump-cdb-breakpoint-"));
+    const commandFile = await writeCdbScript(directory, commands);
+    try {
+        const result = await runCdbProcess({ executable: info.executable, args: buildCdbArgs(request, commandFile), cwd: directory, timeoutMs: durationMs });
+        const hits = parseBreakpointHits(`${result.stdout}\n${result.stderr}`).slice(0, maxHits);
+        const enriched = await Promise.all(hits.map(async (hit) => ({ ...hit, returnAddressPage: queryPage ? await queryPage(address(hit.returnAddress, "returnAddress")).catch(error => ({ error: error instanceof Error ? error.message : String(error) })) : null })));
+        const value = {
+            ok: result.started && !result.timedOut && result.exitCode === 0,
+            kind: "breakpoint",
+            rva: hex(address(request.rva, "rva")),
+            runtimeAddress: hex(runtimeAddress),
+            maxHits,
+            hits: enriched,
+            hitCount: enriched.length,
+            detached: true,
+            timedOut: result.timedOut,
+            entryPage,
+            engine: { name: "cdb", path: info.executable, version: info.version ?? null },
+            stdout: result.stdout.slice(0, 256 * 1024),
+            stderr: result.stderr.slice(0, 256 * 1024),
+            evidence: [{ source: "windbg", kind: "hardware-execution-breakpoint" }]
+        };
+        if (request.outputFile)
+            await writeFile(resolve(request.outputFile), `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        return value;
+    }
+    finally {
+        await rm(commandFile, { force: true }).catch(() => undefined);
+        if (!request.outputFile)
+            await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function command(request, info) {
+    const durationMs = boundedInteger(request.durationMs, "durationMs", 1, 15 * 60 * 1000);
+    const commands = baseCdbCommands(request, request.commands);
+    const directory = request.outputFile ? dirname(resolve(request.outputFile)) : await mkdtemp(join(tmpdir(), "wowdump-cdb-command-"));
+    const commandFile = await writeCdbScript(directory, commands);
+    try {
+        const result = await runCdbProcess({ executable: info.executable, args: buildCdbArgs(request, commandFile), cwd: directory, timeoutMs: durationMs });
+        const value = { ok: result.started && !result.timedOut && result.exitCode === 0, kind: "command", pid: request.pid, exitCode: result.exitCode, timedOut: result.timedOut, stdout: result.stdout.slice(0, 512 * 1024), stderr: result.stderr.slice(0, 512 * 1024), engine: { name: "cdb", path: info.executable, version: info.version ?? null }, evidence: [{ source: "windbg", kind: "cdb-command" }] };
+        if (request.outputFile)
+            await writeFile(resolve(request.outputFile), `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        return value;
+    }
+    finally {
+        await rm(commandFile, { force: true }).catch(() => undefined);
+        if (!request.outputFile)
+            await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export async function executeCdbDebug(request, queryPage) {
+    if (!request || !["dump", "breakpoint", "command"].includes(String(request.kind)))
+        throw new CdbError("CDB_ARGUMENT_INVALID", "kind must be dump, breakpoint, or command");
+    const info = await discoverCdb();
+    if (!info.available || !info.executable)
+        throw new CdbError("CDB_NOT_FOUND", info.message ?? "未找到 WinDbg CDB", { discovery: info });
+    if (!Number.isSafeInteger(request.pid) || request.pid <= 0)
+        throw new CdbError("CDB_ARGUMENT_INVALID", "pid must be positive");
+    if (request.kind === "dump")
+        return dump(request, info);
+    if (request.kind === "breakpoint")
+        return breakpoint(request, info, queryPage);
+    return command(request, info);
+}

package/dist/reader/broker.js

@@ -6,7 +6,12 @@ export const DEFAULT_RIGHTS = Object.freeze([
     "PROCESS_VM_READ"
 ]);
 const MEM_COMMIT = 0x1000;
-const DEFAULT_QUERY_END = BigInt("0x7fffffffffff");
+// Windows rejects VirtualQueryEx at the null page (Win32 error 87).  The
+// lowest user-mode allocation address is 0x10000 on supported Windows hosts.
+const DEFAULT_QUERY_START = 0x10000n;
+// GetSystemInfo().lpMaximumApplicationAddress on supported Windows x64 hosts.
+const MAX_USER_QUERY_ADDRESS = BigInt("0x7ffffffeffff");
+const DEFAULT_QUERY_END = MAX_USER_QUERY_ADDRESS;
 const MAX_QUERY_REGIONS = 100_000;
 function hexAddress(value) {
     const normalized = value.trim();
@@ -97,7 +102,7 @@ export class ReaderBroker {
     backend;
     now;
     onShutdown;
-    runFrida;
+    runDebug;
     handles = new Map();
     watches = new Map();
     idleTimer;
@@ -108,7 +113,7 @@ export class ReaderBroker {
         this.idleTimeoutMs = Math.max(1, Math.floor(options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS));
         this.now = options.now ?? Date.now;
         this.onShutdown = options.onShutdown;
-        this.runFrida = options.runFrida;
+        this.runDebug = options.runDebug;
         this.armIdleTimer();
     }
     get isStopped() {
@@ -175,10 +180,10 @@ export class ReaderBroker {
                     activeWatches: this.activeWatchCount,
                     elevation: await Promise.resolve(this.backend.elevationStatus?.() ?? { state: "unknown" })
                 };
-            case "frida":
-                if (!this.runFrida)
-                    throw new ReaderProtocolError("FRIDA_NOT_CONFIGURED", "elevated Frida runner is not configured");
-                return this.runFrida(request);
+            case "debug":
+                if (!this.runDebug)
+                    throw new ReaderProtocolError("CDB_NOT_CONFIGURED", "elevated CDB runner is not configured");
+                return this.runDebug(request);
             case "modules":
                 return this.modules(request);
             case "regions":
@@ -274,8 +279,10 @@ export class ReaderBroker {
             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)}`);
+        const requestedStart = hexAddress(request.start ?? `0x${DEFAULT_QUERY_START.toString(16)}`);
+        const start = requestedStart === 0n ? DEFAULT_QUERY_START : requestedStart;
+        const requestedEnd = hexAddress(request.end ?? `0x${DEFAULT_QUERY_END.toString(16)}`);
+        const end = requestedEnd > MAX_USER_QUERY_ADDRESS ? MAX_USER_QUERY_ADDRESS : requestedEnd;
         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);
@@ -319,6 +326,7 @@ export class ReaderBroker {
             handle: handle.id,
             start: `0x${start.toString(16)}`,
             end: `0x${end.toString(16)}`,
+            endClamped: requestedEnd !== end,
             includeFree,
             maxRegions,
             regions,
@@ -419,9 +427,11 @@ function serializeError(error, backend) {
         return { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) };
     }
     const message = error instanceof Error ? error.message : String(error);
+    const typed = error;
     return {
-        code: "READER_ERROR",
+        code: typeof typed.code === "string" ? typed.code : "READER_ERROR",
         message,
+        ...(typed.details && typeof typed.details === "object" ? { details: typed.details } : {}),
         elevation: backend.elevationStatus ? backend.elevationStatus() : { state: "unknown" }
     };
 }

package/dist/reader/launcher.js

@@ -130,17 +130,17 @@ export class WindowsBrokerManager {
     }
     async request(invocation) {
         const request = invocationRequest(invocation);
+        const requestTimeout = invocation.command === "debug"
+            ? Math.max(this.options.requestTimeoutMs ?? 30_000, Math.min(15 * 60_000, Number(invocation.payload.durationMs ?? invocation.payload.timeoutMs ?? 120_000) + 10_000))
+            : this.options.requestTimeoutMs ?? 30_000;
         const existing = await this.readMetadata();
         if (existing) {
-            const requestTimeout = invocation.command === "frida"
-                ? Math.max(this.options.requestTimeoutMs ?? 30_000, Math.min(600_000, Number(invocation.payload.timeoutMs ?? 120_000) + 10_000))
-                : this.options.requestTimeoutMs ?? 30_000;
             try {
                 return await requestPipe(existing, request, requestTimeout);
             }
             catch (error) {
                 const code = error.code;
-                // A long-running Frida request is not evidence that the broker died.
+                // A long-running debugger request is not evidence that the broker died.
                 // Keep its metadata so the next command reuses the elevated process.
                 if (code === "BROKER_REQUEST_TIMEOUT")
                     throw error;
@@ -148,7 +148,7 @@ export class WindowsBrokerManager {
             }
         }
         const metadata = await this.launchBroker();
-        return requestPipe(metadata, request, this.options.requestTimeoutMs ?? 30_000);
+        return requestPipe(metadata, request, requestTimeout);
     }
     async readMetadata() {
         try {

package/dist/reader/main.js

@@ -1,41 +1,10 @@
 #!/usr/bin/env node
 import { createServer } from "node:net";
-import { spawn } from "node:child_process";
 import { mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname } from "node:path";
 import { serveReaderBroker } from "./broker.js";
+import { executeCdbDebug } from "../debug/cdb.js";
 import { createWindowsNativeReader } from "./windows.js";
-async function runElevatedFrida(request) {
-    const worker = resolve(request.worker);
-    if (!isAbsolute(request.worker) || worker !== request.worker && process.platform === "win32") {
-        throw new Error("Frida worker path must be absolute");
-    }
-    const timeoutMs = Math.max(1, Math.min(Number(request.timeoutMs ?? 120_000), 600_000));
-    return new Promise(resolveResult => {
-        const child = spawn(process.execPath, [worker], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
-        let stdout = "";
-        let stderr = "";
-        let settled = false;
-        const finish = (exitCode, timedOut = false) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolveResult({ exitCode, stdout, stderr, timedOut });
-        };
-        child.stdout.setEncoding("utf8");
-        child.stderr.setEncoding("utf8");
-        child.stdout.on("data", value => { stdout += value; });
-        child.stderr.on("data", value => { stderr += value; });
-        child.once("error", error => { stderr += error.message; finish(1); });
-        child.once("exit", code => finish(code ?? 1));
-        const timer = setTimeout(() => {
-            child.kill();
-            finish(1, true);
-        }, timeoutMs);
-        child.stdin.end(request.input);
-    });
-}
 function argument(name) {
     const index = process.argv.indexOf(name);
     return index >= 0 ? process.argv[index + 1] : undefined;
@@ -45,10 +14,24 @@ const port = Number(argument("--port") ?? "0");
 const token = argument("--token");
 const metadata = argument("--metadata");
 let server;
+const backend = process.env.WOWDUMP_USE_FAKE_READER === "1" ? undefined : createWindowsNativeReader();
 const broker = serveReaderBroker({
     attachStdio: !listen,
-    backend: process.env.WOWDUMP_USE_FAKE_READER === "1" ? undefined : createWindowsNativeReader(),
-    runFrida: runElevatedFrida,
+    backend,
+    runDebug: async (request) => {
+        const debugRequest = request;
+        if (!backend)
+            return executeCdbDebug(debugRequest);
+        const handle = await backend.openProcess(request.pid, ["PROCESS_QUERY_INFORMATION"]);
+        try {
+            return await executeCdbDebug(debugRequest, address => backend.virtualQueryEx
+                ? backend.virtualQueryEx(handle, address)
+                : Promise.reject(new Error("VirtualQueryEx is not installed")));
+        }
+        finally {
+            await Promise.resolve(handle.close()).catch(() => undefined);
+        }
+    },
     onShutdown: async () => {
         server?.close();
         if (metadata)

package/dist/reader/windows.js

@@ -154,7 +154,7 @@ export class WindowsNativeReader {
         const buffer = Buffer.alloc(48);
         const result = Number(VirtualQueryEx(native.raw, address, buffer, buffer.length));
         if (result === 0)
-            throw win32Error(`VirtualQueryEx(${native.id})`);
+            throw win32Error(`VirtualQueryEx(${native.id}, 0x${address.toString(16)})`);
         return {
             baseAddress: `0x${buffer.readBigUInt64LE(0).toString(16)}`,
             allocationBase: `0x${buffer.readBigUInt64LE(8).toString(16)}`,
@@ -185,7 +185,7 @@ export class WindowsNativeReader {
         };
     }
 }
-/** Enumerate processes without spawning a shell or depending on Frida. */
+/** Enumerate processes without spawning a shell or depending on an injector. */
 export function enumerateWindowsProcesses() {
     if (process.platform !== "win32")
         return [];

package/dist/toolchain.js

@@ -6,19 +6,19 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolveWowdumpHome } from "./core/build-store.js";
 export const DEFAULT_WOWDUMP_SKILL = `---
 name: wowdump
-description: 用 Frida 运行时证据和 IDA Pro MCP 或 iced-x86 定位 WoW 字段，生成并验证 Reader profile。
+description: 用 WinDbg CDB 运行时证据和 IDA Pro MCP 或 iced-x86 定位 WoW 字段，生成并验证 Reader profile。
 ---
 
 # wowdump
 
-先运行 \`wowdump targets\`，再复用 \`~/.wowdump/<buildKey>/database/\`。动态脚本必须由 Agent 显式提供；runtime dump 保存当前 session 的二进制证据，Reader 只读取 build profile。详情见 references/workflow.md、references/commands.md、references/dynamic.md、references/disassemble.md 和 references/profiles.md。
+先运行 \`wowdump targets\`，再复用 \`~/.wowdump/<buildKey>/database/\`。runtime dump 保存当前 session 的二进制证据，debug 命令保存 CDB 证据，Reader 只读取 build profile。详情见 references/workflow.md、references/commands.md、references/windbg.md、references/disassemble.md 和 references/profiles.md。
 `;
 export const DEFAULT_WOWDUMP_COMMANDS = `# wowdump 命令参考
 
 1. \`wowdump targets\`
 2. \`wowdump database status --build <buildKey>\`
 3. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind dump --confirm\`
-4. \`wowdump analyze dynamic --pid <pid> --build <buildKey> --script <GumJS> --export collect --confirm\`
+4. \`wowdump analyze debug --pid <pid> --build <buildKey> --rva <rva> --kind breakpoint --confirm\`
 5. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind verify --profile <profile.json> --confirm\`
 6. \`wowdump memory read --pid <pid> --build <buildKey> --profile <profile.json> --field <name>\`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wowdump",
-  "version": "0.3.5",
-  "description": "WoW native memory analysis CLI with Frida evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
+  "version": "0.3.7",
+  "description": "WoW native memory analysis CLI with WinDbg CDB evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -34,7 +34,6 @@
   },
   "dependencies": {
     "commander": "^13.1.0",
-    "frida": "^17.2.0",
     "iced-x86": "^1.21.0",
     "koffi": "^2.16.3",
     "zod": "^3.24.2"
@@ -44,7 +43,7 @@
     "typescript": "^5.7.3"
   },
   "allowScripts": {
-    "frida@17.17.0": true,
-    "koffi@2.16.3": true
+    "koffi@2.16.3": true,
+    "wowdump@0.3.7": true
   }
 }