diff --git a/docs/agent-environments.md b/docs/agent-environments.md index 4b27ba6721..f2365960e5 100644 --- a/docs/agent-environments.md +++ b/docs/agent-environments.md @@ -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 diff --git a/src/application/environment/environmentBuildReport.test.ts b/src/application/environment/environmentBuildReport.test.ts index 774fa36697..8c3afcbd36 100644 --- a/src/application/environment/environmentBuildReport.test.ts +++ b/src/application/environment/environmentBuildReport.test.ts @@ -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; diff --git a/src/application/environment/environmentBuildReport.ts b/src/application/environment/environmentBuildReport.ts index f9384e6fbd..87869ee1d2 100644 --- a/src/application/environment/environmentBuildReport.ts +++ b/src/application/environment/environmentBuildReport.ts @@ -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; diff --git a/src/application/environment/environmentSource.ts b/src/application/environment/environmentSource.ts index 14d6c219e0..e2c2089438 100644 --- a/src/application/environment/environmentSource.ts +++ b/src/application/environment/environmentSource.ts @@ -184,14 +184,21 @@ const schemaInputError = ( export const recordedExchange = ( record: WebNetworkCaptureRecord, line: Extract, -): 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 = ( diff --git a/src/domain/analysisView/recordedResponseBody.ts b/src/domain/analysisView/recordedResponseBody.ts index 9d811d177c..939bf1bc05 100644 --- a/src/domain/analysisView/recordedResponseBody.ts +++ b/src/domain/analysisView/recordedResponseBody.ts @@ -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); }; diff --git a/tests/boundary/cli/analysisViewCli.test.ts b/tests/boundary/cli/analysisViewCli.test.ts index f532778fb2..825b4d6821 100644 --- a/tests/boundary/cli/analysisViewCli.test.ts +++ b/tests/boundary/cli/analysisViewCli.test.ts @@ -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 }) => { diff --git a/tests/boundary/cli/environmentBuildCli.test.ts b/tests/boundary/cli/environmentBuildCli.test.ts index 65b890f24d..ca71a7ac04 100644 --- a/tests/boundary/cli/environmentBuildCli.test.ts +++ b/tests/boundary/cli/environmentBuildCli.test.ts @@ -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 => (await readdir(root, { recursive: true, withFileTypes: true })) .filter((entry) => entry.isFile()) diff --git a/tests/boundary/mcp/environmentServeMcp.test.ts b/tests/boundary/mcp/environmentServeMcp.test.ts index 3e1bdc48ea..ecc8217c67 100644 --- a/tests/boundary/mcp/environmentServeMcp.test.ts +++ b/tests/boundary/mcp/environmentServeMcp.test.ts @@ -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 }) => {