Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(pcap): preserve exact UTC capture instants
morluto796faa0e4e6b
diff --git a/docs/pcap-analysis.md b/docs/pcap-analysis.mdindex 1df3e5ccd..3e13ec225 100644--- a/docs/pcap-analysis.md+++ b/docs/pcap-analysis.md@@ -58,6 +58,11 @@ tools read that copy, which is hashed again after analysis. Capture metadata andliteral field values are producer observations; address/protocol counts and DNSassociations are derivations. Capture Evidence has historical-reference authority.+`capture_start` and `capture_end` are RFC 3339 UTC instants derived from+`capinfos -S` epoch seconds, retaining all producer fractional digits (up to+nanoseconds). Empty captures, malformed timestamps and instants outside years+0000–9999 remain `null`; host-local timestamps without a zone are not inferred.+Addresses count once per packet, including loopback and nested IP occurrences.DNS addresses are associated only with one question in the same response packet;additional records may be included, so this does not prove final resolution.diff --git a/src/pcap/PcapConfiguration.test.ts b/src/pcap/PcapConfiguration.test.tsindex decca2812..5fa458893 100644--- a/src/pcap/PcapConfiguration.test.ts+++ b/src/pcap/PcapConfiguration.test.ts@@ -48,8 +48,8 @@ const REAL_CAPINFOS = ["Number of packets: 50","File size: 23279 bytes","Capture duration: 0.373473 seconds",- "Earliest packet time: 2026-10-11 14:13:40.608505",- "Latest packet time: 2026-10-11 14:13:40.981978",+ "Earliest packet time: 1791728020.608505",+ "Latest packet time: 1791728020.981978","SHA256: c94f94742b3288b9a979711509ed5eab3028576301f8938319de3c22a6f5c40b",].join("\n");@@ -59,8 +59,8 @@ describe("parseCapinfosOutput", () => {fileType: "Wireshark/tcpdump/... - pcap",encapsulation: "Linux cooked-mode capture v2",packetCount: 50,- captureStart: "2026-10-11 14:13:40.608505",- captureEnd: "2026-10-11 14:13:40.981978",+ captureStart: "2026-10-11T14:13:40.608505Z",+ captureEnd: "2026-10-11T14:13:40.981978Z",captureDurationSeconds: 0.373473,snapshotLength: 262144,sha256:@@ -74,8 +74,67 @@ describe("parseCapinfosOutput", () => {"First packet time",).replace("Latest packet time", "Last packet time");const metadata = parseCapinfosOutput(output);- expect(metadata.captureStart).toBe("2026-10-11 14:13:40.608505");- expect(metadata.captureEnd).toBe("2026-10-11 14:13:40.981978");+ expect(metadata.captureStart).toBe("2026-10-11T14:13:40.608505Z");+ expect(metadata.captureEnd).toBe("2026-10-11T14:13:40.981978Z");+ });++ it("projects epoch timestamps to UTC instants and keeps other spellings unknown", () => {+ const withTimes = (start: string, end: string): string =>+ REAL_CAPINFOS.replace("1791728020.608505", start).replace(+ "1791728020.981978",+ end,+ );+ expect(+ parseCapinfosOutput(withTimes("1791728020", "1791728020.500000")),+ ).toMatchObject({+ captureStart: "2026-10-11T14:13:40Z",+ captureEnd: "2026-10-11T14:13:40.500000Z",+ });+ // capinfos prints n/a for an empty capture, and its default wall-clock+ // spelling carries no zone, so neither names an instant.+ expect(+ parseCapinfosOutput(withTimes("n/a", "2026-10-11 14:13:40.981978")),+ ).toMatchObject({ captureStart: null, captureEnd: null });+ // a packet before the epoch prints with a leading minus; the whole seconds+ // and the fraction are borrowed so the instant stays exact+ expect(parseCapinfosOutput(withTimes("-1", "-1.250000"))).toMatchObject({+ captureStart: "1969-12-31T23:59:59Z",+ captureEnd: "1969-12-31T23:59:58.750000Z",+ });+ expect(parseCapinfosOutput(withTimes("-0.5", "0"))).toMatchObject({+ captureStart: "1969-12-31T23:59:59.5Z",+ captureEnd: "1970-01-01T00:00:00Z",+ });+ // beyond the RFC 3339 year range in either direction stays unknown+ expect(+ parseCapinfosOutput(withTimes("-62167219201", "253402300800")),+ ).toMatchObject({ captureStart: null, captureEnd: null });+ });++ it.each([+ ["0.000000001", "1970-01-01T00:00:00.000000001Z"],+ ["-0.000000001", "1969-12-31T23:59:59.999999999Z"],+ ["-1.000000", "1969-12-31T23:59:59.000000Z"],+ ["-0.000000", "1970-01-01T00:00:00.000000Z"],+ ["-62167219200.000000001", null],+ ["-62167219200", "0000-01-01T00:00:00Z"],+ ["253402300799.999999999", "9999-12-31T23:59:59.999999999Z"],+ ["253402300800", null],+ ["NaN", null],+ ["Infinity", null],+ ["1791728020.5junk", null],+ ["1e3", null],+ ["1.1234567890", null],+ ["9".repeat(1000), null],+ ])("preserves the exact instant or unknown for %s", (text, expected) => {+ const metadata = parseCapinfosOutput(+ REAL_CAPINFOS.replace("1791728020.608505", text).replace(+ "1791728020.981978",+ text,+ ),+ );+ expect(metadata.captureStart).toBe(expected);+ expect(metadata.captureEnd).toBe(expected);});it("keeps missing capture timestamps unknown", () => {diff --git a/src/pcap/PcapOutput.ts b/src/pcap/PcapOutput.tsindex 274a85e81..9a9838f58 100644--- a/src/pcap/PcapOutput.ts+++ b/src/pcap/PcapOutput.ts@@ -27,6 +27,40 @@ export interface CapinfosMetadata {readonly sha256: string | null;}+/**+ * capinfos -S prints each packet timestamp as seconds since the Unix epoch+ * with the capture's own fractional precision, a leading minus for an instant+ * before the epoch. Its default spelling is a zone-less local wall-clock time,+ * so one capture reads differently on hosts in different time zones. Project+ * the exact value to an RFC 3339 UTC instant, keeping the fractional digit+ * count. "n/a" (an empty capture), a wall-clock spelling and a value outside+ * years 0000 to 9999 stay unknown.+ */+const captureInstant = (value: string | undefined): string | null => {+ // Wireshark formats at most 64-bit seconds and nine fractional digits.+ const match = /^(-?)(\d{1,20})(?:\.(\d{1,9}))?$/u.exec(value ?? "");+ if (match?.[2] === undefined) return null;+ const negative = match[1] === "-";+ let seconds = BigInt(match[2]);+ let fraction = match[3] ?? "";+ if (negative) {+ // -1.25 is one and a quarter seconds before the epoch: whole second+ // -2 plus 0.75, so the fraction is borrowed from the next whole second.+ const digits = fraction.length;+ const borrowed = digits > 0 && BigInt(fraction) > 0n;+ seconds = -seconds - (borrowed ? 1n : 0n);+ if (borrowed)+ fraction = (10n ** BigInt(digits) - BigInt(fraction))+ .toString()+ .padStart(digits, "0");+ }+ if (seconds < -62_167_219_200n || seconds > 253_402_300_799n) return null;+ const date = new Date(Number(seconds) * 1000);+ const year = date.getUTCFullYear();+ if (Number.isNaN(year) || year < 0 || year > 9999) return null;+ return `${date.toISOString().slice(0, 19)}${fraction === "" ? "" : `.${fraction}`}Z`;+};+/** capinfos -M with a C locale provides exact numbers instead of "20 k". */export const parseCapinfosOutput = (stdout: string): CapinfosMetadata => {const lines = new Map<string, string>();@@ -66,12 +100,12 @@ export const parseCapinfosOutput = (stdout: string): CapinfosMetadata => {fileType,encapsulation,packetCount,- captureStart:- lines.get("Earliest packet time") ??- lines.get("First packet time") ??- null,- captureEnd:- lines.get("Latest packet time") ?? lines.get("Last packet time") ?? null,+ captureStart: captureInstant(+ lines.get("Earliest packet time") ?? lines.get("First packet time"),+ ),+ captureEnd: captureInstant(+ lines.get("Latest packet time") ?? lines.get("Last packet time"),+ ),captureDurationSeconds: duration === null ? null : Number(duration[1]),snapshotLength:snapshotLength !== null &&diff --git a/src/pcap/PcapProvider.ts b/src/pcap/PcapProvider.tsindex 2e9abed31..420557584 100644--- a/src/pcap/PcapProvider.ts+++ b/src/pcap/PcapProvider.ts@@ -578,7 +578,7 @@ export class PcapProvider {const info = await this.run("inspect_pcap_capture",selection.capinfos.command,- ["-M", "--", snapshot.path],+ ["-M", "-S", "--", snapshot.path],{ timeoutMs: 60_000, maxOutputBytes: 64 * 1024 },signal,snapshot,diff --git a/tests/boundary/mcp/pcapMcp.test.ts b/tests/boundary/mcp/pcapMcp.test.tsindex d3a6d203d..dff164ee5 100644--- a/tests/boundary/mcp/pcapMcp.test.ts+++ b/tests/boundary/mcp/pcapMcp.test.ts@@ -43,8 +43,8 @@ it("advertises exact valid pcap schemas and records inline evidence through MCP"file_type: "Wireshark/tcpdump/... - pcap",encapsulation: "Linux cooked-mode capture v2",packet_count: 50,- capture_start: "2026-10-11 14:13:40.608505",- capture_end: "2026-10-11 14:13:40.981978",+ capture_start: "2026-10-11T14:13:40.608505Z",+ capture_end: "2026-10-11T14:13:40.981978Z",capture_duration_seconds: 0.373473,snapshot_length: 262144,endpoints: [@@ -112,6 +112,8 @@ it("advertises exact valid pcap schemas and records inline evidence through MCP"const evidence = parseEvidence(JSON.parse(text));expect(evidence.normalized_result).toMatchObject({packet_count: 50,+ capture_start: "2026-10-11T14:13:40.608505Z",+ capture_end: "2026-10-11T14:13:40.981978Z",tls_sni_values: ["example.com"],coverage: "complete",});diff --git a/tests/boundary/pcap/pcapProvider.test.ts b/tests/boundary/pcap/pcapProvider.test.tsindex 9c51b96e5..fbc8b1358 100644--- a/tests/boundary/pcap/pcapProvider.test.ts+++ b/tests/boundary/pcap/pcapProvider.test.ts@@ -26,6 +26,8 @@ const CAPINFOS_OUTPUT = ["Packet size limit: file hdr: 262144 bytes","Number of packets: 3","Capture duration: 0.123 seconds",+ "Earliest packet time: 1791728020.608505",+ "Latest packet time: 1791728020.981978",].join("\n");const TSHARK_JSON = JSON.stringify([@@ -86,7 +88,7 @@ exit 0capinfos,`#!/bin/shif [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-stub\\n'; exit 0; fi-[ "$1" = "-M" ] && [ "$2" = "--" ] && [ "$#" = "3" ] || exit 2+[ "$1" = "-M" ] && [ "$2" = "-S" ] && [ "$3" = "--" ] && [ "$#" = "4" ] || exit 2if [ "${String(options.failCapinfos === true)}" = "true" ]; thenprintf 'capinfos: The file is not a capture file' >&2; exit 1fi@@ -165,6 +167,8 @@ it("inspects a capture with endpoints, DNS, TLS SNI, and HTTP", async () => {sha256: createHash("sha256").update("pcap-fixture-bytes").digest("hex"),});expect(result.file_type).toBe("Wireshark/tcpdump/... - pcap");+ expect(result.capture_start).toBe("2026-10-11T14:13:40.608505Z");+ expect(result.capture_end).toBe("2026-10-11T14:13:40.981978Z");expect(result.packet_count).toBe(3);expect(result.endpoints).toEqual(expect.arrayContaining([diff --git a/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts b/tests/boundary/pcap/pcapProviderCrossPlatform.test.tsindex 8f07d6c7c..8170e712a 100644--- a/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts+++ b/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts@@ -131,6 +131,8 @@ it.runIf(hasNativeBound)(});expect(result.file_type).toContain("pcap");expect(result.packet_count).toBe(3);+ expect(result.capture_start).toBe("2026-10-11T14:13:40.608505Z");+ expect(result.capture_end).toBe("2026-10-11T14:13:40.981978Z");expect((result.endpoints as unknown[]).length).toBeGreaterThan(0);expect((result.protocol_distribution as unknown[]).length).toBeGreaterThan(0,diff --git a/tests/fixtures/pcap/capinfos-stub.cmd b/tests/fixtures/pcap/capinfos-stub.cmdindex 6f783bcf5..8fca0945d 100644--- a/tests/fixtures/pcap/capinfos-stub.cmd+++ b/tests/fixtures/pcap/capinfos-stub.cmd@@ -7,8 +7,9 @@ if "%~1"=="--version" ()if not "%~1"=="-M" exit /b 2-if not "%~2"=="--" exit /b 2-if "%~3"=="" exit /b 2+if not "%~2"=="-S" exit /b 2+if not "%~3"=="--" exit /b 2+if "%~4"=="" exit /b 2echo File name: capture.pcapecho File type: Wireshark/tcpdump/... - pcap@@ -16,4 +17,6 @@ echo File encapsulation: Ethernetecho Packet size limit: file hdr: 262144 bytesecho Number of packets: 3echo Capture duration: 0.123 seconds+echo Earliest packet time: 1791728020.608505+echo Latest packet time: 1791728020.981978exit /b 0diff --git a/tests/fixtures/pcap/capinfos-stub.sh b/tests/fixtures/pcap/capinfos-stub.shindex 47d61b1b1..52700df1c 100755--- a/tests/fixtures/pcap/capinfos-stub.sh+++ b/tests/fixtures/pcap/capinfos-stub.sh@@ -1,11 +1,13 @@#!/bin/sh# POSIX capinfos stub (mirrors capinfos-stub.cmd for Windows parity).if [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-posix-stub\n'; exit 0; fi-[ "$1" = "-M" ] && [ "$2" = "--" ] && [ "$#" = "3" ] || exit 2+[ "$1" = "-M" ] && [ "$2" = "-S" ] && [ "$3" = "--" ] && [ "$#" = "4" ] || exit 2printf '%s\n' 'File name: capture.pcap'printf '%s\n' 'File type: Wireshark/tcpdump/... - pcap'printf '%s\n' 'File encapsulation: Ethernet'printf '%s\n' 'Packet size limit: file hdr: 262144 bytes'printf '%s\n' 'Number of packets: 3'printf '%s\n' 'Capture duration: 0.123 seconds'+printf '%s\n' 'Earliest packet time: 1791728020.608505'+printf '%s\n' 'Latest packet time: 1791728020.981978'exit 0