rea-agents 6.4.0 → 6.7.0

package/dist/native/pe/PeResourceParser.js

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import { setImmediate } from "node:timers/promises";
+import { assertArtifactReadActive } from "../../artifacts/ArtifactFileOperation.js";
 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);
+const limit = (message, boundary) => {
+    throw new ArtifactReaderFailure("limit", message, { boundary });
 };
 /** Count bytes through the canonical bounded JSON writer. */
 const jsonBytes = (value, maximum) => {
@@ -20,7 +21,7 @@ const jsonBytes = (value, maximum) => {
 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();
+    assertArtifactReadActive(signal);
     const layout = readPeResourceLayout(bytes);
     const directories = [];
     const resources = [];
@@ -30,7 +31,7 @@ export const parsePeResources = async (bytes, artifact, input, signal) => {
     let metadataBytes = 0;
     const ensureCapacity = (projectedBytes) => {
         if (metadataBytes + projectedBytes > METADATA_BYTES)
-            limit("PE resource metadata exceeds the 8 MiB complete-result allocation budget.");
+            limit("PE resource metadata exceeds the 8 MiB complete-result allocation budget.", "memory");
     };
     const accountBytes = (projectedBytes) => {
         ensureCapacity(projectedBytes);
@@ -94,7 +95,7 @@ export const parsePeResources = async (bytes, artifact, input, signal) => {
         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.");
+            limit("PE resource directory entry budget exceeded; no partial inventory was returned.", "capacity");
         examined += count;
         relative(at, 16 + 8 * count);
         const directory = {
@@ -113,7 +114,7 @@ export const parsePeResources = async (bytes, artifact, input, signal) => {
         for (let index = 0; index < count; index++) {
             if (index % 128 === 0) {
                 await setImmediate();
-                signal?.throwIfAborted();
+                assertArtifactReadActive(signal);
             }
             const entry = header + 16 + index * 8;
             const encoded = bytes.readUInt32LE(entry);
@@ -177,7 +178,7 @@ export const parsePeResources = async (bytes, artifact, input, signal) => {
             const hash = createHash("sha256");
             for (let offset = 0; offset < range.bytes; offset += 1048576) {
                 await setImmediate();
-                signal?.throwIfAborted();
+                assertArtifactReadActive(signal);
                 hash.update(bytes.subarray(range.offset + offset, range.offset + Math.min(range.bytes, offset + 1048576)));
             }
             digest = hash.digest("hex");
@@ -211,9 +212,9 @@ export const parsePeResources = async (bytes, artifact, input, signal) => {
             "Exact shared byte ranges are retained; non-identical overlapping resource structures or payloads are rejected.",
         ],
     };
-    signal?.throwIfAborted();
+    assertArtifactReadActive(signal);
     if (jsonBytes(report, METADATA_BYTES) > METADATA_BYTES)
-        limit("PE resource result exceeds the 8 MiB allocation budget.");
+        limit("PE resource result exceeds the 8 MiB allocation budget.", "memory");
     return report;
 };
 const rejectOverlappingRanges = (ranges) => {

package/dist/native/pe/PeResourcesProvider.js

@@ -1,39 +1,86 @@
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
 import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { ArtifactFileCleanupFailure, bindArtifactFileCleanup, artifactFileCancellationCause, } from "../../artifacts/ArtifactFileOperation.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 { MAX_INSPECT_PE_DIRECTORY_ENTRIES, MAX_INSPECT_PE_FILE_BYTES, } from "../../domain/native/peResources.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();
+    async close() {
+        try {
+            await this.#resources.close();
+        }
+        catch (cause) {
+            if (!(cause instanceof ArtifactReaderFailure) ||
+                cause.cleanup === undefined)
+                throw cause;
+            const error = new ProviderCleanupError(PE_RESOURCES_PROVIDER.id, cause.cleanup.resources, { reason: cause.cleanup.reason }, { cause, operation: "inspect_pe_resources" });
+            bindArtifactFileCleanup(cause, error);
+            throw error;
+        }
+    }
     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));
+            return await this.#resources.run(async () => {
+                const snapshot = await 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 peResourcesFailure = (cause, input, signal) => {
+/**
+ * Remediation for a caller-selected budget refusal. At the schema ceiling
+ * there is no value left to raise the bound to, so the advice names the
+ * ceiling instead of an impossible raise.
+ */
+export const inputBudgetRemediation = (boundary, input) => boundary === "file-size"
+    ? input.max_file_bytes >= MAX_INSPECT_PE_FILE_BYTES
+        ? `The image exceeds the ${String(MAX_INSPECT_PE_FILE_BYTES)}-byte input ceiling this operation accepts; select a smaller artifact.`
+        : `Raise max_file_bytes above ${String(input.max_file_bytes)} bytes or select a smaller artifact; the limit is the caller-selected input read budget.`
+    : input.max_entries >= MAX_INSPECT_PE_DIRECTORY_ENTRIES
+        ? `The image exceeds the ${String(MAX_INSPECT_PE_DIRECTORY_ENTRIES)}-entry resource-directory ceiling this operation accepts; select a smaller artifact.`
+        : `Raise max_entries above ${String(input.max_entries)} or select a smaller artifact; the limit is the caller-selected resource directory entry budget.`;
+const peResourcesFailurePrimary = (cause, input) => {
     const operation = "inspect_pe_resources";
-    if (signal?.aborted)
-        return new AnalysisCancelledError(operation, { cause });
+    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: artifactFileCancellationCause(cause),
+        });
     if (cause instanceof ArtifactReaderFailure) {
+        // An input byte budget is a file-size bound, not a memory constraint, and
+        // an entry budget is a capacity bound. Report what was actually exceeded.
         if (cause.reason === "limit")
-            return new AnalysisResourceConstraintError(operation, "memory", cause.message, {
+            return new AnalysisResourceConstraintError(operation, cause.boundary ?? "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 });
+            }, {
+                cause,
+                // Both bounds are caller-selected and deterministic for the same
+                // input, so waiting for an active analysis cannot help.
+                ...(cause.boundary === undefined || cause.boundary === "memory"
+                    ? {}
+                    : {
+                        retryable: false,
+                        remediationAction: inputBudgetRemediation(cause.boundary, input),
+                    }),
+            });
         if (cause.reason === "path" || cause.reason === "format")
             return new AnalysisInputError(operation, { cause }, [
                 {
@@ -42,8 +89,6 @@ const peResourcesFailure = (cause, input, signal) => {
                     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")
@@ -61,3 +106,19 @@ const peResourcesFailure = (cause, input, signal) => {
     }
     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 = cause instanceof ArtifactFileCleanupFailure &&
+        cause.fileCleanupFailure.outcome.kind === "failed"
+        ? peResourcesFailurePrimary(cause.fileCleanupFailure.outcome.cause, input)
+        : cause instanceof ArtifactFileCleanupFailure && signal?.aborted
+            ? new AnalysisCancelledError("inspect_pe_resources", {
+                cause: signal.reason,
+            })
+            : peResourcesFailurePrimary(cause, input);
+    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 });
+    const error = analysisErrorWithCleanupFailure(primary, cleanup, "inspect_pe_resources");
+    bindArtifactFileCleanup(cause, error);
+    return error;
+};

package/dist/native/pwndbg/CoreFileMappingAuthority.js

@@ -0,0 +1,51 @@
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { err, ok } from "../../domain/result.js";
+/** Interpret source-bound ELF64 NT_FILE paths once, before GDB can open them. */
+export function validateCoreFileMappingAuthority(report, snapshot) {
+    for (const note of report.notes) {
+        if (note.type !== "NT_FILE")
+            continue;
+        const refuse = (reason) => {
+            const message = `Core mapping note ${note.index} cannot be confined to the owned debugger sysroot: ${reason}.`;
+            return err(new AnalysisCapabilityUnavailableError("pwndbg-core", "inspect_recorded_crash", message, {
+                userMessage: `${message} Omit include_debugger_context for basic recorded evidence.`,
+                capturedOutput: report.decoder_diagnostics,
+            }));
+        };
+        // The provider has already bound this range and note kind to the snapshot.
+        const start = Number(BigInt(note.descriptor_location.offset));
+        const bytes = snapshot.subarray(start, start + Number(BigInt(note.descriptor_location.bytes)));
+        if (bytes.length < 16)
+            return refuse("missing mapping table header");
+        const count = bytes.readBigUInt64LE(0);
+        if (count > BigInt(Math.floor((bytes.length - 16) / 24)))
+            return refuse("mapping count exceeds its descriptor");
+        let position = 16 + Number(count) * 24;
+        for (let index = 0; index < Number(count); index++) {
+            const end = bytes.indexOf(0, position);
+            if (end < 0)
+                return refuse("unterminated mapping pathname");
+            const path = bytes.subarray(position, end);
+            // Inspect Unix path bytes without lossy UTF-8 decoding or host resolution.
+            // Relative paths bypass GDB's sysroot; dot segments can escape its prefix.
+            if (path[0] !== 0x2f)
+                return refuse("mapping pathname is not absolute");
+            let component = 0;
+            for (let cursor = 0; cursor <= path.length; cursor++) {
+                if (cursor !== path.length && path[cursor] !== 0x2f)
+                    continue;
+                const length = cursor - component;
+                if ((length === 1 && path[component] === 0x2e) ||
+                    (length === 2 &&
+                        path[component] === 0x2e &&
+                        path[component + 1] === 0x2e))
+                    return refuse("mapping pathname contains a dot segment");
+                component = cursor + 1;
+            }
+            position = end + 1;
+        }
+        if (bytes.subarray(position).some((byte) => byte !== 0))
+            return refuse("mapping pathname coverage is unresolved");
+    }
+    return ok(undefined);
+}

package/dist/native/pwndbg/PwndbgCoreContext.js

@@ -1,3 +1,4 @@
+import { bindArtifactFileCleanup, artifactFileCancellationCause, } from "../../artifacts/ArtifactFileOperation.js";
 import { access, mkdir, stat, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -8,7 +9,8 @@ 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 { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.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 +30,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, architecture, 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 ?? "";
@@ -40,6 +42,7 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
     const checkCancelled = () => {
         if (options?.signal?.aborted)
             throw new AnalysisCancelledError(OPERATION, {
+                cause: options.signal.reason,
                 capturedOutput: diagnostics,
             });
     };
@@ -68,8 +71,8 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
             checkCancelled();
         }
         catch (cause) {
-            if (options?.signal?.aborted)
-                checkCancelled();
+            if (cause instanceof AnalysisCancelledError)
+                throw cause;
             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);
         }
     }
@@ -82,13 +85,20 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
         snapshot_path: join(rootPath, "object.snapshot"),
         reply_path: replyPath,
         gdb,
+        architecture,
         gdbinit: entry,
         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({
+        checkCancelled();
+        const execution = await runCommand({
             command: environment.REA_PWNTOOLS_PYTHON ?? "",
             arguments: [
                 "-I",
@@ -111,28 +121,36 @@ 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, {
+            if (cause instanceof ArtifactReaderFailure &&
+                cause.reason === "cancelled") {
+                const error = new AnalysisCancelledError(OPERATION, {
+                    cause: artifactFileCancellationCause(cause),
                     capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                    ...(cause instanceof ArtifactReaderFailure &&
+                        cause.cleanup !== undefined
+                        ? { cleanup: cause.cleanup }
+                        : {}),
                 });
-            throw new AnalysisOutputError(OPERATION, `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+                bindArtifactFileCleanup(cause, error);
+                throw error;
+            }
+            const error = new AnalysisOutputError(OPERATION, `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
                 cause,
+                ...(cause instanceof ArtifactReaderFailure
+                    ? { cleanup: cause.cleanup }
+                    : {}),
                 capturedOutput: recordedCrashStageOutput(diagnostics, output),
             });
+            bindArtifactFileCleanup(cause, error);
+            throw error;
         }
         if (!reply.ok) {
             if (reply.reason === "unavailable" || reply.reason === "unsupported")
@@ -157,17 +175,10 @@ export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, op
         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,
-        });
+        if (cause instanceof AnalysisError && cause.cleanupIncomplete)
+            throw cause;
+        const primary = 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. */