fix(pe): report the enforced resource parser limit (#12328)

This commit is contained in:
morluto authored and GitHub committed 2026-11-19 12:49:07 +00:00
1 parent 067ebd7349
commit 39d20dce3d
4 files changed
+81 -58

No files matched your search

+2
View File
@@ -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
+1 -2
View File
@@ -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. */
+12
View File
@@ -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",
+66 -56
View File
@@ -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,