diff --git a/docs/guides/web/web-network-captures.md b/docs/guides/web/web-network-captures.md index c57515da0e..5f49655f87 100644 --- a/docs/guides/web/web-network-captures.md +++ b/docs/guides/web/web-network-captures.md @@ -246,10 +246,11 @@ when MIME metadata is unavailable. CLI exposes `--protobuf-body-pointer` and base64 layer also checks explicit exclusions; newly recognized trailer credentials exclude the entire affected binary sidecar and its reported encoding, preserving a redaction coordinate instead of a credential digest. -Credential inspection covers every selected body before descriptor reads or -field expansion. Later capacity or schema failures can therefore retain the -sanitized source even with explicit sensitivity options. If that source pass -is interrupted, unchecked bodies are not published as partial Evidence. +Credential checks use visible transport declarations for format-owned bodies in +selected records before descriptor reads or field expansion. The `body_pointers` +filter applies to wire interpretation. Later capacity or schema failures can +retain the sanitized source even with explicit sensitivity options. An interrupted +source pass withholds unchecked bodies from partial Evidence. Framing overrides apply only to format-owned body coordinates and preserve exclusions for the transport declared in MIME metadata. Explicitly excluded or conflicting MIME metadata is not treated as absent: diff --git a/src/browser/history/protobuf/ProtobufCapture.ts b/src/browser/history/protobuf/ProtobufCapture.ts index 2e5e9545b2..dda89fa444 100644 --- a/src/browser/history/protobuf/ProtobufCapture.ts +++ b/src/browser/history/protobuf/ProtobufCapture.ts @@ -423,7 +423,7 @@ export const prepareCaptureProtobuf = async ( ); for (const field of record.binary_fields) { await work.checkpoint(); - if (pointers !== undefined && !pointers.has(field.pointer)) continue; + const interpret = pointers?.has(field.pointer) ?? true; const metadata = bodyMetadata( record, field.pointer, @@ -433,23 +433,32 @@ export const prepareCaptureProtobuf = async ( // Framing overrides interpret bodies; header and extension bytes remain their own facts. if (metadata === undefined) continue; if (field.state !== "retained") { - incomplete = true; + incomplete ||= interpret; continue; } const { contentType, mimeProfile, declaredFramings } = metadata; const automatic = mimeProfile.ok ? mimeProfile.value.framing : undefined; - if (!mimeProfile.ok) { + if (interpret && !mimeProfile.ok) { if (automaticSelected) incomplete = true; record.limitations.push(mimeProfile.error.issue); } - if (automaticSelected && !metadata.contentTypeKnown && field.bytes > 0) { + if ( + interpret && + automaticSelected && + !metadata.contentTypeKnown && + field.bytes > 0 + ) { incomplete = true; record.limitations.push( "Selected body's MIME metadata is excluded, conflicting or unavailable, so automatic protobuf framing applicability is unknown; its retained bytes were not interpreted. Select explicit framing to decode them.", ); } - const framing = - explicitFraming ?? (metadata.contentTypeKnown ? automatic : undefined); + // A body filter scopes wire analysis. Every body that remains in the + // retained records still needs its source-declared transport checks. + const framing = interpret + ? (explicitFraming ?? + (metadata.contentTypeKnown ? automatic : undefined)) + : undefined; if (framing === undefined && declaredFramings.size === 0) continue; if ( field.bytes > captureBudgets().inputBytes || @@ -480,7 +489,7 @@ export const prepareCaptureProtobuf = async ( if (excluded !== undefined) { excludeBody(record, field.pointer, excluded); binaryByPointer.delete(field.pointer); - incomplete = true; + incomplete ||= interpret; continue; } // Analysis eligibility never bypasses the independent source exclusions. @@ -495,6 +504,7 @@ export const prepareCaptureProtobuf = async ( "Use a capture with available HTTP coding metadata, or select records whose transport can be inspected. Unchecked source bytes were not published.", }, ); + if (!interpret) continue; if (!metadata.httpIdentityKnown) { incomplete = true; record.limitations.push( diff --git a/tests/acceptance/tools/protobufCapture.test.ts b/tests/acceptance/tools/protobufCapture.test.ts index 71c625d725..c995e690a7 100644 --- a/tests/acceptance/tools/protobufCapture.test.ts +++ b/tests/acceptance/tools/protobufCapture.test.ts @@ -524,9 +524,6 @@ captureTest( const { call, args, capture, descriptor } = await prepareMcpCapture( mcp.call, ); - const complete = await call("inspect_web_network_capture", args); - expect(complete.isError, JSON.stringify(complete)).not.toBe(true); - const parent = parseEvidence(complete.structuredContent); const cliResult = await cli.run({ arguments: [ "inspect-web-network-capture", @@ -542,7 +539,6 @@ captureTest( ], }); expect(cliResult.exitCode, cliResult.stdout + cliResult.stderr).toBe(0); - expect(parseEvidence(cliResult.json).evidence_id).toBe(parent.evidence_id); const redacted = await call("inspect_web_network_capture", { ...args, sensitive_values: ["hello"], @@ -558,28 +554,31 @@ captureTest( inspected_records: 1, }); expect(JSON.stringify(redacted)).not.toContain("hello"); - const summary = await call("inspect_web_network_capture", { - ...args, - detail: "summary", - }); - expect(summary.isError, JSON.stringify(summary)).not.toBe(true); - const result = analysisViewResultSchema.parse( - parseEvidence(summary.structuredContent).normalized_result, - ); - expect(result).toMatchObject({ - kind: "summary", - parent_evidence_id: parent.evidence_id, - }); const invalid = await call("inspect_web_network_capture", { ...args, record_ordinals: undefined, }); expect(invalid.isError).toBe(true); expect(parseMcpToolError(invalid).error.code).toBe("invalid_request"); + const summary = await call("inspect_web_network_capture", { + ...args, + detail: "summary", + }); + expect(summary.isError, JSON.stringify(summary)).not.toBe(true); + const view = analysisViewResultSchema.parse( + parseEvidence(summary.structuredContent).normalized_result, + ); + if (view.kind !== "summary") throw new Error("Expected capture summary"); + expect(view.parent_evidence_id).toBe( + parseEvidence(cliResult.json).evidence_id, + ); await unlink(capture); await unlink(descriptor); const viewed = await call("inspect_analysis_view", { - source: { kind: "retained-evidence", evidence_id: parent.evidence_id }, + source: { + kind: "retained-evidence", + evidence_id: view.parent_evidence_id, + }, view: { kind: "protobuf", collection: "fields", diff --git a/tests/acceptance/tools/protobufMimeAdmission.test.ts b/tests/acceptance/tools/protobufMimeAdmission.test.ts index c3146051e5..c34899fa0b 100644 --- a/tests/acceptance/tools/protobufMimeAdmission.test.ts +++ b/tests/acceptance/tools/protobufMimeAdmission.test.ts @@ -200,20 +200,25 @@ cliTest( const original = JSON.stringify(archive); await writeFile(path, original); const call = await cli.sharedMcpCall!(); - for (const framing of ["auto", "raw"] as const) { + for (const protobuf of [ + { framing: "auto", body_pointers: ["/response/content/text"] }, + { framing: "raw" }, + { body_pointers: [] }, + ]) { + const selected = protobuf.body_pointers?.length !== 0; const reply = await call("inspect_web_network_capture", { capture_path: path, format: "har", record_ordinals: [0, 1, 2, 3], sensitive_values: ["excluded-declaration"], - protobuf: { framing }, + protobuf, }); expect(reply.isError, JSON.stringify(reply)).not.toBe(true); const report = webNetworkCaptureSchema.parse( parseEvidence(reply.structuredContent).normalized_result, ); expect(report.protobuf_coverage).toEqual({ - status: "partial", + status: selected ? "partial" : "complete", selected_records: 4, inspected_records: 4, }); @@ -223,7 +228,7 @@ cliTest( for (const [ordinal, record] of report.records.slice(0, 3).entries()) { expect( record.protobuf, - `record ${ordinal} (${framing})`, + `record ${ordinal} (${protobuf.framing ?? "unselected"})`, ).toBeUndefined(); expect(record.reported).toMatchObject({ response: { @@ -244,11 +249,13 @@ cliTest( reason: "transport-credential", }); } - expect(report.records[3]?.protobuf?.[0]).toMatchObject({ - content_type: raw.value, - framing: "raw", - fields: [{ number: 1, value: "1" }], - }); + if (selected) + expect(report.records[3]?.protobuf?.[0]).toMatchObject({ + content_type: raw.value, + framing: "raw", + fields: [{ number: 1, value: "1" }], + }); + else expect(report.records[3]?.protobuf).toBeUndefined(); expect(report.records[3]?.binary_fields).toContainEqual( expect.objectContaining({ pointer: "/response/content/text",