rea-agents 6.3.0 → 6.5.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,77 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.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 { ProviderCleanupError } from "../../domain/providerCleanupError.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;
+    #resources = new ArtifactResourceScope();
+    close() {
+        return this.#resources.close();
+    }
+    async inspect(input, options) {
+        try {
+            const snapshot = await this.#resources.run(() => readStableArtifact(input.path, input.max_file_bytes, options?.signal, undefined, this.#resources));
+            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 peResourcesFailurePrimary = (cause, input, signal) => {
+    const operation = "inspect_pe_resources";
+    if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")
+        return new AnalysisArtifactChangedError(operation, input.path, cause.message, { cause });
+    if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
+        return new AnalysisCancelledError(operation, { cause });
+    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 === "path" || cause.reason === "format")
+            return new AnalysisInputError(operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_format",
+                    message: cause.message,
+                },
+            ]);
+    }
+    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 });
+};
+const peResourcesFailure = (cause, input, signal) => {
+    const primary = peResourcesFailurePrimary(cause, input, signal);
+    if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)
+        return primary;
+    const cleanup = new ProviderCleanupError(PE_RESOURCES_PROVIDER.id, cause.cleanup.resources, { reason: cause.cleanup.reason }, { operation: "inspect_pe_resources", cause });
+    return analysisErrorWithCleanupFailure(primary, cleanup, "inspect_pe_resources");
+};

package/dist/native/pwndbg/PwndbgCoreContext.js

@@ -8,7 +8,7 @@ import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOut
 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 { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { capturedPwntoolsOutput, pwntoolsDecoderFailure, } from "../pwntools/PwntoolsFailures.js";
 import { PWNTOOLS_LIMITS } from "../pwntools/PwntoolsRelease.js";
 import { readPwntoolsFailureEvidence } from "../pwntools/PwntoolsResourceLimits.js";
@@ -28,7 +28,7 @@ const replySchema = z.discriminatedUnion("ok", [
     }),
 ]);
 /** Add mapping candidates from an owned core-only debugger, using the existing snapshot. */
-export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, options, launcher, probePath, }) => {
+export const inspectPwndbgCore = async ({ environment, rootPath, resources, diagnostics, options, runCommand, probePath, }) => {
     const gdb = environment.REA_PWNDBG_GDB ?? "/usr/bin/gdb";
     const entry = environment.REA_PWNDBG_GDBINIT ?? "";
     const venv = environment.REA_PWNDBG_VENV_PATH ?? "";
@@ -86,9 +86,15 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
         venv,
     }), { flag: "wx", mode: 0o600 });
     let output;
+    const failureContext = {
+        operation: OPERATION,
+        providerId: "pwndbg-core",
+        precedingOutput: diagnostics,
+    };
+    const failure = (cause) => pwntoolsDecoderFailure(cause, "debugger", gdb, environment.REA_PWNTOOLS_PYTHON ?? "", {}, failureContext);
     try {
         options?.signal?.throwIfAborted();
-        const execution = await runOwnedCommand({
+        const execution = await runCommand({
             command: environment.REA_PWNTOOLS_PYTHON ?? "",
             arguments: [
                 "-I",
@@ -111,22 +117,17 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
                 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 }),
-        });
+        }, failure);
         output = capturedPwntoolsOutput(execution);
         let reply;
         try {
-            const raw = await readStableArtifact(replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal);
+            const raw = await readStableArtifact(replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal, undefined, resources);
             reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8")));
         }
         catch (cause) {
             if (options?.signal?.aborted)
                 throw new AnalysisCancelledError(OPERATION, {
+                    cause,
                     capturedOutput: recordedCrashStageOutput(diagnostics, output),
                 });
             throw new AnalysisOutputError(OPERATION, `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
@@ -157,17 +158,16 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
         return { ...reply.value, diagnostics: output };
     }
     catch (cause) {
-        if (options?.signal?.aborted &&
+        if (cause instanceof AnalysisError && cause.cleanupIncomplete)
+            throw cause;
+        const primary = options?.signal?.aborted &&
             (cause === options.signal.reason ||
-                (cause instanceof Error && cause.name === "AbortError")))
-            throw new AnalysisCancelledError(OPERATION, {
+                (cause instanceof Error && cause.name === "AbortError"))
+            ? 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,
-        });
+            })
+            : pwntoolsDecoderFailure(cause, "debugger", gdb, environment.REA_PWNTOOLS_PYTHON ?? "", await readPwntoolsFailureEvidence(cause, stage, resources), failureContext);
+        throw primary;
     }
 };
 /** Preserve both stages' exact text and their independently observed truncation state. */