fix(environment): preserve HAR body source identity and scan coverage (#11829)

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
This commit is contained in:
ShuaixinHuangandShuaixinHuang authored and GitHub committed 2026-11-17 09:11:48 -05:00
1 parent 51459cf203
commit 5ccb7c59c8
8 files changed
+268 -23

No files matched your search

+7 -2
View File
@@ -206,8 +206,13 @@ scanned by event (`event 4 response /token` names
content event, including a response whose request began before the browser was
attached and a transaction no record represents, and each transaction URL's
query once. Bodies larger than 4 MiB of UTF-8 text are not
scanned; `credential-scan-incomplete` counts them and lists up to 20 record or
event pointers, including base64 bodies whose decoded scan was cut. An empty name
scanned. A retained HAR base64 body must match its declared source text and
representation before replay or state extraction; HAR's admitted ASCII whitespace
differences do not change source identity. A mismatched or missing retained source
is not promoted and is counted as unscanned, while its original Evidence is retained.
`credential-scan-incomplete` counts these unavailable sources and oversized
bodies, listing up to 20 record or event pointers, including base64 bodies whose
decoded scan was cut. An empty name
warning does not establish that these bodies were checked. A browser scenario's
saved values (`save` and `save_response`) named like credentials but not marked
`secret: true` are recorded unredacted; `credential-named-saved-values` lists up
@@ -1,4 +1,5 @@
import { describe, expect, it } from "vitest";
import { createHash } from "node:crypto";
import { scenarioCaptureFixture } from "../../../tests/fixtures/browserScenarioCapture.js";
import type { WebNetworkCaptureRecord } from "../../domain/webNetworkCapture.js";
@@ -337,7 +338,7 @@ describe("scanCredentialNames coverage", () => {
status: 200,
content: {
mimeType: "application/json",
text: "",
text: bytes.toString("base64"),
encoding: "base64",
},
},
@@ -345,8 +346,11 @@ describe("scanCredentialNames coverage", () => {
binary_fields: [
{
pointer: "/response/content/text",
representation: "har-base64-content",
state: "retained",
content_base64: bytes.toString("base64"),
bytes: bytes.length,
sha256: createHash("sha256").update(bytes).digest("hex"),
},
],
}) as unknown as WebNetworkCaptureRecord;
@@ -11,7 +11,7 @@ import {
import {
decodeRetainedBase64,
readRecordedResponseBody,
type RecordedResponseBody,
type RecordedResponseBodyRead,
} from "../../domain/analysisView/recordedResponseBody.js";
import { scenarioContentMediaType } from "../../domain/analysisView/scenarioCaptureRecords.js";
import type { BrowserScenarioEvent } from "../../domain/browserScenarioCaptureValues.js";
@@ -96,7 +96,7 @@ const member = (value: unknown, name: string): unknown =>
? Reflect.get(value, name)
: undefined;
/** A recorded body: a JSON value to walk, form fields in order with every occurrence kept, as headers and query strings are, or text too large to scan. */
/** A recorded body: JSON or form fields to walk, or a body the scan could not examine. */
type ScannedBody =
| { readonly kind: "json"; readonly value: unknown }
| { readonly kind: "form"; readonly fields: readonly [string, string][] }
@@ -138,14 +138,16 @@ const parsedBody = (
}
};
/** Decoded body text as the scan reads it; binary bytes hold no JSON or form text. */
/** Unproven body sources remain unscanned; binary bytes hold no JSON or form text. */
const decodedBody = (
body: RecordedResponseBody,
body: RecordedResponseBodyRead,
mediaType: unknown,
): ScannedBody | undefined =>
body.bodyEncoding === "base64"
? undefined
: parsedBody(body.bodyText, mediaType, body.bodyCut === true);
body.sourceUnavailable === true
? { kind: "skipped" }
: body.bodyEncoding === "base64"
? undefined
: parsedBody(body.bodyText, mediaType, body.bodyCut === true);
/** Name/value pairs such as HAR headers and query strings. */
const namedValues = (value: unknown): (readonly [string, unknown])[] =>
@@ -326,7 +328,7 @@ export const credentialScanWarnings = (capture: {
if (scanned.skipped.count > 0)
warnings.push({
code: "credential-scan-incomplete",
message: `${String(scanned.skipped.count)} recorded bodies exceed the credential-name scan's 4 MiB limit and were not scanned; evidence.json ships them, so review them before sharing.`,
message: `${String(scanned.skipped.count)} recorded bodies could not be completely scanned for credential-like names (4 MiB limit or unavailable response-body source); evidence.json ships their retained representation, so review it before sharing.`,
pointers: scanned.skipped.pointers,
});
return warnings;
@@ -184,14 +184,21 @@ const schemaInputError = (
export const recordedExchange = (
record: WebNetworkCaptureRecord,
line: Extract<RecordedRequestLine, { readonly kind: "line" }>,
): RecordedExchange => ({
ordinal: record.ordinal,
path: line.path,
query: line.query === undefined || line.query === "" ? null : line.query,
status: line.status,
contentType: line.rawMime === "" ? null : line.rawMime,
...readRecordedResponseBody(record, REPLAY_BODY_LIMIT_BYTES),
});
): RecordedExchange => {
const body = readRecordedResponseBody(record, REPLAY_BODY_LIMIT_BYTES);
return {
ordinal: record.ordinal,
path: line.path,
query: line.query === undefined || line.query === "" ? null : line.query,
status: line.status,
contentType: line.rawMime === "" ? null : line.rawMime,
bodyText: body.bodyText,
...(body.bodyEncoding === undefined
? {}
: { bodyEncoding: body.bodyEncoding }),
...(body.bodyCut === true ? { bodyCut: true } : {}),
};
};
/** Authenticate a view Evidence file and require one view kind; a refusal names the file role. */
export const parseViewEvidence = <Kind extends AnalysisViewResult["kind"]>(
@@ -12,6 +12,12 @@ export interface RecordedResponseBody {
readonly bodyCut?: true;
}
/** Source admission is separate from the body fields consumed by replay. */
export interface RecordedResponseBodyRead extends RecordedResponseBody {
/** A declared body could not be associated with its retained HAR bytes. */
readonly sourceUnavailable?: true;
}
const responseDeclarationSchema = z.object({
response: z.object({
status: z.unknown().optional(),
@@ -81,6 +87,19 @@ export const decodeRetainedBase64 = (
}
};
/** Compare HAR's source spelling without decoding or copying another whole body. */
const sameHarBase64 = (reported: string, retained: string): boolean => {
if (reported === retained) return true;
let at = 0;
for (let index = 0; index < reported.length; index++) {
const code = reported.charCodeAt(index);
// These are the four whitespace characters admitted by the HAR producer.
if (code === 9 || code === 10 || code === 13 || code === 32) continue;
if (code !== retained.charCodeAt(at++)) return false;
}
return at === retained.length;
};
/** Read producer-decoded text or supported HAR base64; unknown encoding declarations stay opaque. Base64 beyond `limitBytes` is decoded only that far. */
export const readRecordedResponseBody = (
record: WebNetworkCaptureRecord,
@@ -88,7 +107,7 @@ export const readRecordedResponseBody = (
declaration: RecordedResponseDeclaration = readRecordedResponseDeclaration(
record.reported,
),
): RecordedResponseBody => {
): RecordedResponseBodyRead => {
const content = declaration?.content;
if (content == null) return { bodyText: null };
const bodyCoordinates = [
@@ -129,8 +148,13 @@ export const readRecordedResponseBody = (
(field) =>
field.pointer === "/response/content/text" && field.state === "retained",
);
if (binary === undefined || binary.content_base64 === null)
return { bodyText: null };
if (
binary === undefined ||
binary.representation !== "har-base64-content" ||
binary.content_base64 === null ||
!sameHarBase64(text, binary.content_base64)
)
return { bodyText: null, sourceUnavailable: true };
return decodeRetainedBase64(binary.content_base64, limitBytes);
};
@@ -49,6 +49,64 @@ import {
} from "../../../src/domain/evidenceBundle.js";
import { inspectEvidenceBundle } from "../../../src/application/investigation/InspectEvidenceBundle.js";
cliTest.for([false, true])(
"requires source agreement before treating a HAR response as empty: %s",
async (emptyReported, { cli }) => {
const capture = environmentManifestCaptureFixture([
{
request: {
method: "POST",
url: "http://app.example/jobs",
postData: { mimeType: "application/json", text: '{"name":"one"}' },
},
response: {
status: 201,
content: {
mimeType: "application/octet-stream",
encoding: "base64",
text: emptyReported
? ""
: Buffer.from("not empty").toString("base64"),
},
},
},
]);
capture.records[0]!.binary_fields = [
{
pointer: "/response/content/text",
representation: "har-base64-content",
state: "retained",
content_base64: "",
bytes: 0,
sha256: createHash("sha256").update("").digest("hex"),
},
];
const root = await createTestTempDirectory("rea-har-body-source-");
const request = join(root, "request.json");
await writeFile(
request,
JSON.stringify({
source: {
kind: "inline",
evidence: analysisViewCaptureEvidence(capture),
},
view: { kind: "environment-manifest" },
}),
);
const response = await cli.run({
arguments: ["inspect-analysis-view", request, "--json"],
});
expect(response.exitCode, response.stderr).toBe(0);
const view = z
.object({
kind: z.literal("environment-manifest"),
tools: z.array(z.unknown()),
})
.parse(parseEvidence(response.json).normalized_result);
expect(view.tools).toHaveLength(emptyReported ? 1 : 0);
},
);
cliTest(
"reads a saved scalar pseudocode observation without starting an analysis engine",
async ({ cli }) => {
@@ -1,9 +1,17 @@
import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
import { join, sep } from "node:path";
import { createHash } from "node:crypto";
import { expect } from "vitest";
import { environmentManifestHar } from "../../fixtures/historicalHar.js";
import {
analysisViewCaptureEvidence,
environmentManifestCaptureFixture,
} from "../../fixtures/analysisView.js";
import { parseEvidence } from "../../../src/domain/evidence.js";
import { environmentBuildReportSchema } from "../../../src/domain/environmentBundleExport.js";
import { webNetworkCaptureSchema } from "../../../src/domain/webNetworkCapture.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { cliTest } from "../../support/cli/cliFixture.js";
@@ -14,6 +22,84 @@ const RULES = [
"prefix-variance",
];
cliTest.for(["different-content", "wrong-role", "matching"] as const)(
"reports credential scan coverage for shipped HAR source bytes: %s",
async (mode, { cli }) => {
const root = await createTestTempDirectory("rea-environment-body-source-");
const retained = Buffer.from('{"token":"retained-only-secret"}');
const encoded = retained.toString("base64");
const capture = environmentManifestCaptureFixture([
{
request: { method: "GET", url: "http://app.example/api/proof" },
response: {
status: 200,
content: {
mimeType: "application/json",
encoding: "base64",
text:
mode === "different-content"
? Buffer.from('{"ok":true}').toString("base64")
: ` \t${encoded}\n`,
},
},
},
]);
capture.records[0]!.binary_fields = [
{
pointer: "/response/content/text",
representation:
mode === "wrong-role" ? "producer-bytes" : "har-base64-content",
state: "retained",
content_base64: encoded,
bytes: retained.length,
sha256: createHash("sha256").update(retained).digest("hex"),
},
];
const input = JSON.stringify(analysisViewCaptureEvidence(capture));
const path = join(root, "capture.json");
const output = join(root, "bundle");
await writeFile(path, input);
const result = await cli.run({
arguments: ["environment-build", path, output, "--json"],
});
expect(result.exitCode, result.stderr).toBe(0);
const report = environmentBuildReportSchema.parse(result.json);
const shipped = webNetworkCaptureSchema.parse(
parseEvidence(
JSON.parse(
await readFile(
join(output, "envs", report.name, "evidence.json"),
"utf8",
),
),
).normalized_result,
);
expect(shipped.records[0]!.binary_fields).toEqual(
capture.records[0]!.binary_fields,
);
expect(shipped.records[0]!.reported).toEqual(capture.records[0]!.reported);
expect(await readFile(path, "utf8")).toBe(input);
const warnings = report.warnings.filter(({ code }) =>
code.startsWith("credential-"),
);
expect(warnings).toEqual([
expect.objectContaining({
code:
mode === "matching"
? "credential-named-members"
: "credential-scan-incomplete",
pointers: [
mode === "matching"
? "record 0 response /token"
: "record 0 response",
],
}),
]);
if (mode !== "matching") expect(warnings[0]?.message).toContain("source");
expect(JSON.stringify(report)).not.toContain("retained-only-secret");
},
);
const listFiles = async (root: string): Promise<string[]> =>
(await readdir(root, { recursive: true, withFileTypes: true }))
.filter((entry) => entry.isFile())
+60 -1
View File
@@ -1,5 +1,10 @@
import { readFile } from "node:fs/promises";
import { timedCaptureEvidence } from "../../fixtures/analysisView.js";
import {
analysisViewCaptureEvidence,
environmentManifestCaptureFixture,
timedCaptureEvidence,
} from "../../fixtures/analysisView.js";
import { createHash } from "node:crypto";
import { INITIAL_TRASH_ROWS } from "../../fixtures/environmentStateLaterReads.js";
import { jsonObjectSchema } from "../../../src/domain/jsonValue.js";
import { advertisedInputDialectViolations } from "../../../src/contracts/advertisedDialect.js";
@@ -59,6 +64,60 @@ const connect = async (url: URL) => {
return client;
};
processTest.for(["different-content", "wrong-role", "matching"] as const)(
"admits only source-matched HAR bytes through HTTP MCP replay: %s",
async (mode, { processes }) => {
const body = { id: 1, title: "retained" };
const retained = Buffer.from(JSON.stringify(body));
const encoded = retained.toString("base64");
const capture = environmentManifestCaptureFixture([
{
request: { method: "GET", url: "http://app.example/api/books/1" },
response: {
status: 200,
content: {
mimeType: "application/json",
encoding: "base64",
text:
mode === "different-content"
? Buffer.from('{"id":2}').toString("base64")
: ` \t${encoded}\r\n`,
},
},
},
]);
capture.records[0]!.binary_fields = [
{
pointer: "/response/content/text",
representation:
mode === "wrong-role" ? "producer-bytes" : "har-base64-content",
state: "retained",
content_base64: encoded,
bytes: retained.length,
sha256: createHash("sha256").update(retained).digest("hex"),
},
];
const fixture = environmentStateServeFixture(
analysisViewCaptureEvidence(capture),
);
const started = await serveReplayOnly(processes, {}, fixture);
const client = await connect(started.url);
try {
const response = await client.callTool({
name: "get_books_by_id",
arguments: { id: "1" },
});
expect(response.isError).toBeFalsy();
expect(response.structuredContent).toMatchObject({
body: mode === "matching" ? body : null,
replay: { body_recorded: mode === "matching" },
});
} finally {
await client.close();
}
},
);
processTest(
"replays a recorded list containing an initially deleted entity",
async ({ processes }) => {