From 39d20dce3d5769eb9a6929af7eacb4df4037ece7 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:49:07 -0500 Subject: [PATCH] fix(pe): report the enforced resource parser limit (#12328) --- docs/guides/native/binary-diagnostics.md | 2 + src/domain/pe/peResourceInventory.ts | 3 +- src/native/pe/PeResourcesProvider.test.ts | 12 +++ src/native/pe/PeResourcesProvider.ts | 122 ++++++++++++---------- 4 files changed, 81 insertions(+), 58 deletions(-) diff --git a/docs/guides/native/binary-diagnostics.md b/docs/guides/native/binary-diagnostics.md index 47fda8b7f3..530f5029b9 100644 --- a/docs/guides/native/binary-diagnostics.md +++ b/docs/guides/native/binary-diagnostics.md @@ -278,6 +278,8 @@ and language. Other resource payload formats remain opaque. 16384, the largest stock Windows resource image measured with headroom (maximum 65536). CLI options are `--max-file-bytes` and `--max-entries`. Metadata is bounded to 8 MiB; exceeding any budget fails without truncation. +Parser refusals report the exhausted limit and enforced maximum in +`details.reported_limits`. Large Evidence envelopes may require a caller-configured MCP transport receive buffer because envelope copies add overhead. Requests honor cancellation during snapshot reading, directory traversal and payload hashing. The operation reads diff --git a/src/domain/pe/peResourceInventory.ts b/src/domain/pe/peResourceInventory.ts index 159c489a09..d1881d0fd7 100644 --- a/src/domain/pe/peResourceInventory.ts +++ b/src/domain/pe/peResourceInventory.ts @@ -29,8 +29,7 @@ type OccupiedRange = Range & { kind: "directory" | "name" | "data-entry" | "payload"; }; /** Complete PE resource result retained before a refusal. */ -export const PE_RESOURCE_METADATA_BYTES = 8 * 1024 * 1024; -const METADATA_BYTES = PE_RESOURCE_METADATA_BYTES; +const METADATA_BYTES = 8 * 1024 * 1024; /** The fixed allowance for retained resource metadata. */ const METADATA_LIMIT = "pe_resource_metadata_bytes"; /** The caller-selected resource directory entry budget. */ diff --git a/src/native/pe/PeResourcesProvider.test.ts b/src/native/pe/PeResourcesProvider.test.ts index 6164ac8bfc..311408a6d4 100644 --- a/src/native/pe/PeResourcesProvider.test.ts +++ b/src/native/pe/PeResourcesProvider.test.ts @@ -65,6 +65,13 @@ describe("PE resource provider budget reporting", () => { expect(projectAnalysisError(error)).toMatchObject({ retryable: false, remediation: { action: error.remediationAction }, + details: { + reported_limits: { + boundary: "max_entries", + maximum: 1, + max_entries: 1, + }, + }, }); }); @@ -181,6 +188,11 @@ it("names the fixed PE metadata allowance instead of host memory", async () => { const projected = projectAnalysisError(error); expect(projected.retryable).toBe(false); expect(projected.details).toMatchObject({ + reported_limits: { + boundary: "pe_resource_metadata_bytes", + maximum: 8 * 1024 * 1024, + maximum_metadata_bytes: 8 * 1024 * 1024, + }, refusal: { kind: "fixed_ceiling", allowance_kind: "parser", diff --git a/src/native/pe/PeResourcesProvider.ts b/src/native/pe/PeResourcesProvider.ts index 1b7962d25e..d85e360ec2 100644 --- a/src/native/pe/PeResourcesProvider.ts +++ b/src/native/pe/PeResourcesProvider.ts @@ -28,10 +28,13 @@ import { } from "../../domain/native/peResources.js"; import { err, ok } from "../../domain/result.js"; import { PE_RESOURCES_PROVIDER } from "../../domain/investigationProviders.js"; +import { + isParseLimit, + parseLimitConstraint, +} from "../../domain/parseFailureAnalysisError.js"; import { parsePeResources, peResourceLimitBoundary, - PE_RESOURCE_METADATA_BYTES, } from "../../domain/pe/peResourceInventory.js"; /** Portable parser over one bounded, identity-checked regular file. */ @@ -73,11 +76,12 @@ export class PeResourcesProvider implements PeResourcesPort { ), ); } catch (cause) { - throw artifactParseFailure( - cause, - options?.signal, - peResourceLimitBoundary, - ); + if ( + isParseLimit(cause, "pe") && + !Object.is(cause, options?.signal?.reason) + ) + throw cause; + throw artifactParseFailure(cause, options?.signal); } }); } catch (cause) { @@ -91,15 +95,10 @@ export class PeResourcesProvider implements PeResourcesPort { * there is no value left to raise the bound to, so the advice names the * ceiling instead of an impossible raise. */ -const inputBudgetRemediation = ( - boundary: "file-size" | "capacity", - input: InspectPeResourcesInput, -): string => - boundary === "file-size" - ? imageFileSizeRemediation(input.max_file_bytes, MAX_INSPECT_PE_FILE_BYTES) - : 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. This release has no runtime override. 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 entryBudgetRemediation = (maximum: number): string => + maximum >= MAX_INSPECT_PE_DIRECTORY_ENTRIES + ? `The image exceeds the ${String(MAX_INSPECT_PE_DIRECTORY_ENTRIES)}-entry resource-directory ceiling this operation accepts. This release has no runtime override. Select a smaller artifact.` + : `Raise max_entries above ${String(maximum)} or select a smaller artifact; the limit is the caller-selected resource directory entry budget.`; const peResourcesFailurePrimary = ( facts: ArtifactFilePrimaryFacts, @@ -121,49 +120,60 @@ const peResourcesFailurePrimary = ( ); if (inputFailure !== undefined) return inputFailure; + const reportedLimitContext = { + max_file_bytes: input.max_file_bytes, + max_entries: input.max_entries, + }; + if (origin === "owned-or-classified" && isParseLimit(cause, "pe")) { + const { limit } = cause.failure; + const boundary = peResourceLimitBoundary(limit); + if (boundary === "memory") + return parseLimitConstraint(operation, boundary, cause, { + reportedLimitContext: { + ...reportedLimitContext, + maximum_metadata_bytes: limit.maximum, + }, + ...fixedNativeAllowance( + "The PE resource metadata allowance", + "parser", + limit.maximum, + "bytes", + ), + }); + if (boundary === "capacity") + return parseLimitConstraint(operation, boundary, cause, { + reportedLimitContext: { + ...reportedLimitContext, + max_entries: limit.maximum, + }, + retryable: false, + remediationAction: entryBudgetRemediation(limit.maximum), + }); + } + if ( origin === "owned-or-classified" && - 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") { - const metadata = cause.boundary === "memory"; - return new AnalysisResourceConstraintError( - operation, - cause.boundary ?? "memory", - cause.message, - { - max_file_bytes: input.max_file_bytes, - max_entries: input.max_entries, - ...(metadata - ? { maximum_metadata_bytes: PE_RESOURCE_METADATA_BYTES } - : {}), - }, - { - cause, - // Caller-selected budgets and the fixed metadata allowance are - // deterministic for the same input, so waiting cannot help. - ...(cause.boundary === undefined - ? {} - : metadata - ? fixedNativeAllowance( - "The PE resource metadata allowance", - "parser", - PE_RESOURCE_METADATA_BYTES, - "bytes", - ) - : { - retryable: false as const, - remediationAction: inputBudgetRemediation( - cause.boundary, - input, - ), - }), - }, - ); - } - } + cause instanceof ArtifactReaderFailure && + cause.reason === "limit" + ) + return new AnalysisResourceConstraintError( + operation, + cause.boundary ?? "memory", + cause.message, + reportedLimitContext, + { + cause, + ...(cause.boundary === "file-size" + ? { + retryable: false, + remediationAction: imageFileSizeRemediation( + input.max_file_bytes, + MAX_INSPECT_PE_FILE_BYTES, + ), + } + : {}), + }, + ); const fileFailure = projectSelectedArtifactFileFailure( cause,