wowdump 0.3.4 → 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

@@ -5,6 +5,14 @@ export const DEFAULT_RIGHTS = Object.freeze([
     "PROCESS_QUERY_INFORMATION",
     "PROCESS_VM_READ"
 ]);
+const MEM_COMMIT = 0x1000;
+// 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();
     if (!/^0x[0-9a-f]+$/i.test(normalized)) {
@@ -30,6 +38,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");
 }
@@ -85,7 +102,7 @@ export class ReaderBroker {
     backend;
     now;
     onShutdown;
-    runFrida;
+    runDebug;
     handles = new Map();
     watches = new Map();
     idleTimer;
@@ -96,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() {
@@ -163,12 +180,14 @@ 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":
+                return this.regions(request);
             case "open":
                 return this.open(request);
             case "close":
@@ -255,6 +274,66 @@ 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 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);
+        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)}`,
+            endClamped: requestedEnd !== end,
+            includeFree,
+            maxRegions,
+            regions,
+            nextAddress: `0x${cursor.toString(16)}`,
+            truncated
+        };
+    }
     async watchStart(request) {
         const pid = boundedPid(request.pid);
         const address = hexAddress(request.address);
@@ -348,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)