reverseport 0.0.0-stage → 1.2.0

package/dist/native/pe/PeResourceParser.js

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import { setImmediate } from "node:timers/promises";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { jsonParts } from "../../domain/jsonSerialization.js";
+import { peFailure, readPeResourceLayout, requirePeRange, } from "./PeResourceLayout.js";
+const METADATA_BYTES = 8 * 1024 * 1024;
+const limit = (message) => {
+    throw new ArtifactReaderFailure("limit", message);
+};
+/** Count bytes through the canonical bounded JSON writer. */
+const jsonBytes = (value, maximum) => {
+    let size = 0;
+    for (const part of jsonParts(value)) {
+        size += Buffer.byteLength(part, "utf8");
+        if (size > maximum)
+            return size;
+    }
+    return size;
+};
+const identityKey = (id) => id.kind === "id" ? `id:${String(id.id)}` : `name:${id.utf16le_hex}`;
+/** Decode the conventional type/name/language tree; never infer payload meaning or runtime loading. */
+export const parsePeResources = async (bytes, artifact, input, signal) => {
+    signal?.throwIfAborted();
+    const layout = readPeResourceLayout(bytes);
+    const directories = [];
+    const resources = [];
+    const occupied = [];
+    const names = new Map();
+    let examined = 0;
+    let metadataBytes = 0;
+    const ensureCapacity = (projectedBytes) => {
+        if (metadataBytes + projectedBytes > METADATA_BYTES)
+            limit("PE resource metadata exceeds the 8 MiB complete-result allocation budget.");
+    };
+    const accountBytes = (projectedBytes) => {
+        ensureCapacity(projectedBytes);
+        metadataBytes += projectedBytes;
+    };
+    const account = (value) => {
+        // Rows are retained in arrays; reserve a separator along with each row.
+        accountBytes(jsonBytes(value, METADATA_BYTES - metadataBytes - 1) + 1);
+    };
+    const reserveDecodedName = (utf16Units) => {
+        // A JSON string can need six ASCII bytes per UTF-16 code unit (for example,
+        // a control character encoded as `\\u0000`). The original spelling and
+        // its hex form are both retained in the result.
+        const projectedBytes = 10 * utf16Units + 256;
+        ensureCapacity(projectedBytes);
+    };
+    const root = layout.size === 0 ? 0 : layout.map(layout.rva, layout.size);
+    const relative = (at, length) => {
+        if (at > layout.size - length || at < 0)
+            peFailure("Resource directory offset leaves the declared resource interval.");
+        requirePeRange(bytes, root + at, length);
+        return root + at;
+    };
+    const recordRange = (offset, size, kind) => {
+        const range = { offset, bytes: size };
+        if (size > 0)
+            occupied.push({ ...range, kind });
+        return range;
+    };
+    const readIdentity = (encoded) => {
+        if ((encoded & 0x80000000) === 0)
+            return { kind: "id", id: encoded };
+        const at = encoded & 0x7fffffff;
+        const previous = names.get(at);
+        if (previous !== undefined)
+            return previous;
+        if (at % 2 !== 0)
+            peFailure("Unaligned PE resource name.");
+        const start = relative(at, 2);
+        const utf16Units = bytes.readUInt16LE(start);
+        reserveDecodedName(utf16Units);
+        const length = utf16Units * 2;
+        relative(at, 2 + length);
+        const raw = bytes.subarray(start + 2, start + 2 + length);
+        const value = {
+            kind: "name",
+            name: raw.toString("utf16le"),
+            utf16le_hex: raw.toString("hex"),
+            location: recordRange(start, 2 + length, "name"),
+        };
+        names.set(at, value);
+        return value;
+    };
+    const visit = async (at, path, entryLocations, ancestors) => {
+        if (ancestors.has(at))
+            peFailure("Cyclic PE resource directory.");
+        if (at % 4 !== 0)
+            peFailure("Unaligned PE resource directory.");
+        const header = relative(at, 16);
+        const named = bytes.readUInt16LE(header + 12);
+        const ids = bytes.readUInt16LE(header + 14);
+        const count = named + ids;
+        if (count > input.max_entries - examined)
+            limit("PE resource directory entry budget exceeded; no partial inventory was returned.");
+        examined += count;
+        relative(at, 16 + 8 * count);
+        const directory = {
+            location: recordRange(header, 16 + 8 * count, "directory"),
+            characteristics: bytes.readUInt32LE(header),
+            timestamp: bytes.readUInt32LE(header + 4),
+            major_version: bytes.readUInt16LE(header + 8),
+            minor_version: bytes.readUInt16LE(header + 10),
+            named_entries: named,
+            id_entries: ids,
+        };
+        account(directory);
+        directories.push(directory);
+        const keys = new Set();
+        const nested = new Set([...ancestors, at]);
+        for (let index = 0; index < count; index++) {
+            if (index % 128 === 0) {
+                await setImmediate();
+                signal?.throwIfAborted();
+            }
+            const entry = header + 16 + index * 8;
+            const encoded = bytes.readUInt32LE(entry);
+            if (((encoded & 0x80000000) !== 0) !== index < named)
+                peFailure("Resource name/ID entry counts disagree with encoded identities.");
+            const identity = readIdentity(encoded);
+            const key = identityKey(identity);
+            if (keys.has(key))
+                peFailure("Duplicate identity within a resource directory.");
+            keys.add(key);
+            const next = [...path, identity];
+            const locations = [...entryLocations, { offset: entry, bytes: 8 }];
+            const target = bytes.readUInt32LE(entry + 4);
+            const offset = target & 0x7fffffff;
+            if ((target & 0x80000000) !== 0) {
+                if (next.length >= 3)
+                    peFailure("Unsupported resource tree deeper than type/name/language.");
+                await visit(offset, next, locations, nested);
+            }
+            else {
+                if (next.length !== 3)
+                    peFailure("Unsupported resource leaf outside the type/name/language profile.");
+                const data = relative(offset, 16);
+                if (offset % 4 !== 0)
+                    peFailure("Unaligned resource data entry.");
+                const rva = bytes.readUInt32LE(data);
+                const size = bytes.readUInt32LE(data + 4);
+                const payloadOffset = layout.map(rva, size);
+                const [type, name, language] = next;
+                if (type === undefined || name === undefined || language === undefined)
+                    return peFailure("Incomplete resource identity.");
+                const resource = {
+                    index: resources.length,
+                    type,
+                    name,
+                    language,
+                    entry_locations: locations,
+                    data_entry_location: recordRange(data, 16, "data-entry"),
+                    code_page: bytes.readUInt32LE(data + 8),
+                    reserved: bytes.readUInt32LE(data + 12),
+                    payload: {
+                        rva,
+                        location: recordRange(payloadOffset, size, "payload"),
+                        sha256: "0".repeat(64),
+                    },
+                };
+                account(resource);
+                resources.push(resource);
+            }
+        }
+    };
+    if (layout.size > 0)
+        await visit(0, [], [], new Set());
+    rejectOverlappingRanges(occupied);
+    const hashes = new Map();
+    for (const resource of resources) {
+        const range = resource.payload.location;
+        const key = `${String(range.offset)}:${String(range.bytes)}`;
+        let digest = hashes.get(key);
+        if (digest === undefined) {
+            const hash = createHash("sha256");
+            for (let offset = 0; offset < range.bytes; offset += 1048576) {
+                await setImmediate();
+                signal?.throwIfAborted();
+                hash.update(bytes.subarray(range.offset + offset, range.offset + Math.min(range.bytes, offset + 1048576)));
+            }
+            digest = hash.digest("hex");
+            hashes.set(key, digest);
+        }
+        resource.payload.sha256 = digest;
+    }
+    const iconGroups = readIconGroups(bytes, resources, account, ensureCapacity);
+    const report = {
+        artifact,
+        format: layout.format,
+        machine: layout.machine,
+        directory: layout.size === 0
+            ? null
+            : {
+                rva: layout.rva,
+                location: { offset: root, bytes: layout.size },
+                data_directory_location: { offset: layout.directoryAt, bytes: 8 },
+            },
+        directories,
+        resources,
+        icon_groups: iconGroups,
+        coverage: {
+            status: "complete",
+            examined_entries: examined,
+            resources: resources.length,
+        },
+        limitations: [
+            "Static PE32/PE32+ type/name/language resource inventory; payloads other than RT_GROUP_ICON remain opaque.",
+            "Icon candidates are resource-table relationships. Language fallback, image decoding and actual shell/window loading are not observed.",
+            "Exact shared byte ranges are retained; non-identical overlapping resource structures or payloads are rejected.",
+        ],
+    };
+    signal?.throwIfAborted();
+    if (jsonBytes(report, METADATA_BYTES) > METADATA_BYTES)
+        limit("PE resource result exceeds the 8 MiB allocation budget.");
+    return report;
+};
+const rejectOverlappingRanges = (ranges) => {
+    ranges.sort((left, right) => left.offset - right.offset || right.bytes - left.bytes);
+    let previous;
+    for (const current of ranges) {
+        if (previous !== undefined &&
+            current.offset < previous.offset + previous.bytes &&
+            (current.offset !== previous.offset ||
+                current.bytes !== previous.bytes ||
+                current.kind !== previous.kind))
+            peFailure("Non-identical resource byte ranges overlap.");
+        previous = current;
+    }
+};
+const readIconGroups = (bytes, resources, account, ensureCapacity) => {
+    const imagesById = new Map();
+    for (const resource of resources) {
+        if (resource.type.kind !== "id" ||
+            resource.type.id !== 3 ||
+            resource.name.kind !== "id")
+            continue;
+        const candidates = imagesById.get(resource.name.id) ?? [];
+        candidates.push(resource);
+        imagesById.set(resource.name.id, candidates);
+    }
+    return resources
+        .filter((resource) => resource.type.kind === "id" && resource.type.id === 14)
+        .map((group) => {
+        const { offset, bytes: size } = group.payload.location;
+        if (size < 6 ||
+            bytes.readUInt16LE(offset) !== 0 ||
+            bytes.readUInt16LE(offset + 2) !== 1)
+            peFailure("Malformed RT_GROUP_ICON header.");
+        const count = bytes.readUInt16LE(offset + 4);
+        if (size !== 6 + count * 14)
+            peFailure("RT_GROUP_ICON length does not match its image count.");
+        const images = [];
+        for (let index = 0; index < count; index++) {
+            const at = offset + 6 + index * 14;
+            const id = bytes.readUInt16LE(at + 12);
+            const candidates = imagesById.get(id) ?? [];
+            const exact = candidates.find((resource) => identityKey(resource.language) === identityKey(group.language));
+            // Indices are uint32 values and each needs at most ten decimal digits
+            // plus a comma. Check the expanded candidate list before allocating it.
+            ensureCapacity(302 + candidates.length * 11);
+            const declaredBytes = bytes.readUInt32LE(at + 8);
+            const image = {
+                location: { offset: at, bytes: 14 },
+                width: bytes[at] ?? 0,
+                height: bytes[at + 1] ?? 0,
+                color_count: bytes[at + 2] ?? 0,
+                reserved: bytes[at + 3] ?? 0,
+                planes: bytes.readUInt16LE(at + 4),
+                bit_count: bytes.readUInt16LE(at + 6),
+                declared_bytes: declaredBytes,
+                resource_id: id,
+                candidate_resource_indices: candidates.map(({ index }) => index),
+                same_language_resource_index: exact?.index ?? null,
+                size_matches: exact === undefined
+                    ? null
+                    : exact.payload.location.bytes === declaredBytes,
+            };
+            account(image);
+            images.push(image);
+        }
+        account({ resource_index: group.index, images: [] });
+        return { resource_index: group.index, images };
+    });
+};

package/dist/native/pe/PeResourcesProvider.js

@@ -0,0 +1,63 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, } from "../../domain/analysisErrorCore.js";
+import { err, ok } from "../../domain/result.js";
+import { PE_RESOURCES_PROVIDER } from "../../application/InvestigationProviders.js";
+import { parsePeResources } from "./PeResourceParser.js";
+/** Portable parser over one bounded, identity-checked regular file. */
+export class PeResourcesProvider {
+    identity = PE_RESOURCES_PROVIDER;
+    async inspect(input, options) {
+        try {
+            const snapshot = await readStableArtifact(input.path, input.max_file_bytes, options?.signal);
+            return ok(await parsePeResources(snapshot.bytes, {
+                path: input.path,
+                sha256: snapshot.sha256,
+                bytes: snapshot.bytes.length,
+            }, input, options?.signal));
+        }
+        catch (cause) {
+            return err(peResourcesFailure(cause, input, options?.signal));
+        }
+    }
+}
+const peResourcesFailure = (cause, input, signal) => {
+    const operation = "inspect_pe_resources";
+    if (signal?.aborted)
+        return new AnalysisCancelledError(operation, { cause });
+    if (cause instanceof ArtifactReaderFailure) {
+        if (cause.reason === "limit")
+            return new AnalysisResourceConstraintError(operation, "memory", cause.message, {
+                max_file_bytes: input.max_file_bytes,
+                max_entries: input.max_entries,
+            }, { cause });
+        if (cause.reason === "integrity")
+            return new AnalysisArtifactChangedError(operation, input.path, cause.message, { cause });
+        if (cause.reason === "path" || cause.reason === "format")
+            return new AnalysisInputError(operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_format",
+                    message: cause.message,
+                },
+            ]);
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError(operation, { cause });
+    }
+    if (cause instanceof Error && "code" in cause) {
+        if (cause.code === "EACCES" || cause.code === "EPERM")
+            return new AnalysisAccessDeniedError(operation, input.path, cause.code, {
+                cause,
+            });
+        if (cause.code === "ENOENT" || cause.code === "ENOTDIR")
+            return new AnalysisInputError(operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_value",
+                    message: `Selected PE image could not be read (${cause.code}): ${input.path}.`,
+                },
+            ]);
+    }
+    return new ArtifactOperationError(operation, cause instanceof ArtifactReaderFailure ? cause.reason : "io", undefined, cause instanceof Error ? cause.message : "PE artifact inspection failed.", { cause });
+};

package/dist/native/pwndbg/PwndbgCoreContext.js

@@ -0,0 +1,180 @@
+import { access, mkdir, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { recordedCrashDebuggerSchema, } from "../../domain/native/recordedCrash.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { runOwnedCommand } from "../../process/OwnedCommand.js";
+import { capturedPwntoolsOutput, pwntoolsDecoderFailure, } from "../pwntools/PwntoolsFailures.js";
+import { PWNTOOLS_LIMITS } from "../pwntools/PwntoolsRelease.js";
+import { readPwntoolsFailureEvidence } from "../pwntools/PwntoolsResourceLimits.js";
+const OPERATION = "inspect_recorded_crash";
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), value: recordedCrashDebuggerSchema }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum([
+            "unavailable",
+            "unsupported",
+            "decoder",
+            "format",
+            "output-limit",
+        ]),
+        message: z.string(),
+    }),
+]);
+/** Add mapping candidates from an owned core-only debugger, using the existing snapshot. */
+export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, options, launcher, probePath, }) => {
+    const gdb = environment.REA_PWNDBG_GDB ?? "/usr/bin/gdb";
+    const entry = environment.REA_PWNDBG_GDBINIT ?? "";
+    const venv = environment.REA_PWNDBG_VENV_PATH ?? "";
+    const unavailable = (message, cause) => new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, message, {
+        ...(cause === undefined ? {} : { cause }),
+        userMessage: message,
+        capturedOutput: diagnostics,
+    });
+    const checkCancelled = () => {
+        if (options?.signal?.aborted)
+            throw new AnalysisCancelledError(OPERATION, {
+                capturedOutput: diagnostics,
+            });
+    };
+    checkCancelled();
+    for (const [key, path, kind] of [
+        ["REA_PWNDBG_GDB", gdb, "file"],
+        ["REA_PWNDBG_GDBINIT", entry, "file"],
+        ["REA_PWNDBG_VENV_PATH", venv, "directory"],
+    ]) {
+        try {
+            checkCancelled();
+            if (!isAbsolute(path))
+                throw new Error("Expected an absolute caller-supplied path.");
+            const mode = key === "REA_PWNDBG_GDB" ? constants.X_OK : constants.R_OK;
+            if (probePath !== undefined) {
+                await probePath(path, kind, mode);
+            }
+            else {
+                await access(path, mode);
+                checkCancelled();
+                const information = await stat(path);
+                checkCancelled();
+                if (kind === "file" ? !information.isFile() : !information.isDirectory())
+                    throw new Error(`Expected a ${kind}.`);
+            }
+            checkCancelled();
+        }
+        catch (cause) {
+            if (options?.signal?.aborted)
+                checkCancelled();
+            throw unavailable(`${key} is unavailable at ${path}: ${cause instanceof Error ? cause.message : String(cause)}. Configure the requested core-only context, or omit include_debugger_context for basic recorded evidence.`, cause);
+        }
+    }
+    checkCancelled();
+    const stage = join(rootPath, "debugger");
+    await mkdir(stage, { mode: 0o700 });
+    const requestPath = join(stage, "request.json");
+    const replyPath = join(stage, "reply.json");
+    await writeFile(requestPath, JSON.stringify({
+        snapshot_path: join(rootPath, "object.snapshot"),
+        reply_path: replyPath,
+        gdb,
+        gdbinit: entry,
+        venv,
+    }), { flag: "wx", mode: 0o600 });
+    let output;
+    try {
+        options?.signal?.throwIfAborted();
+        const execution = await runOwnedCommand({
+            command: environment.REA_PWNTOOLS_PYTHON ?? "",
+            arguments: [
+                "-I",
+                fileURLToPath(new URL("../../../bridge/pwndbg/launch.py", import.meta.url)),
+                join(stage, "resource.failure"),
+                requestPath,
+            ],
+            cwd: stage,
+            runId: `rea-recorded-core-debugger-${randomUUID()}`,
+            hostEnvironment: {
+                ...environment,
+                PWNDBG_NO_AUTOUPDATE: "1",
+                PWNDBG_VENV_PATH: venv,
+                PWNLIB_NOTERM: "1",
+                TERM: "dumb",
+                HOME: stage,
+                XDG_CACHE_HOME: join(stage, "cache"),
+                XDG_CONFIG_HOME: join(stage, "config"),
+                PYTHONNOUSERSITE: "1",
+                OPENBLAS_NUM_THREADS: "1",
+                OMP_NUM_THREADS: "1",
+            },
+        }, {
+            timeoutMs: PWNTOOLS_LIMITS.timeoutMs,
+            diagnosticBytes: PWNTOOLS_LIMITS.diagnosticBytes,
+        }, {
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            ...(launcher === undefined ? {} : { launcher }),
+        });
+        output = capturedPwntoolsOutput(execution);
+        let reply;
+        try {
+            const raw = await readStableArtifact(replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal);
+            reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8")));
+        }
+        catch (cause) {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION, {
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            throw new AnalysisOutputError(OPERATION, `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+                cause,
+                capturedOutput: recordedCrashStageOutput(diagnostics, output),
+            });
+        }
+        if (!reply.ok) {
+            if (reply.reason === "unavailable" || reply.reason === "unsupported")
+                throw new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, reply.message, {
+                    userMessage: reply.message,
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            if (reply.reason === "format" || reply.reason === "output-limit")
+                throw new AnalysisOutputError(OPERATION, reply.message, {
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            throw new ProviderAdapterError("pwndbg-core", OPERATION, {
+                diagnostics: {
+                    stage: "debugger",
+                    reason: reply.message,
+                    captured_output: { ...recordedCrashStageOutput(diagnostics, output) },
+                },
+            });
+        }
+        if (reply.value.status !== "available")
+            throw new AnalysisOutputError(OPERATION, "Requested debugger context returned no core evidence.", { capturedOutput: recordedCrashStageOutput(diagnostics, output) });
+        return { ...reply.value, diagnostics: output };
+    }
+    catch (cause) {
+        if (options?.signal?.aborted &&
+            (cause === options.signal.reason ||
+                (cause instanceof Error && cause.name === "AbortError")))
+            throw new AnalysisCancelledError(OPERATION, {
+                capturedOutput: recordedCrashStageOutput(diagnostics, output),
+            });
+        throw pwntoolsDecoderFailure(cause, "debugger", gdb, environment.REA_PWNTOOLS_PYTHON ?? "", await readPwntoolsFailureEvidence(cause, stage), {
+            operation: OPERATION,
+            providerId: "pwndbg-core",
+            precedingOutput: diagnostics,
+        });
+    }
+};
+/** Preserve both stages' exact text and their independently observed truncation state. */
+export const recordedCrashStageOutput = (basic, debuggerOutput) => debuggerOutput === undefined
+    ? basic
+    : {
+        stdout: `[core decoder]\n${basic.stdout}\n[debugger]\n${debuggerOutput.stdout}`,
+        stderr: `[core decoder]\n${basic.stderr}\n[debugger]\n${debuggerOutput.stderr}`,
+        truncated: basic.truncated || debuggerOutput.truncated,
+    };