safetynet/docs/browser-diagnostics.md

Browser diagnostics and operational OpenTelemetry

Browser diagnostics use the actual OpenTelemetry JavaScript trace and log SDKs, exported as OTLP/HTTP JSON to a collector selected in signed company policy. They are distinct from durable security audit and encrypted forensic evidence. This module never sends document fragments, prompts, page text, password fields, access tokens, URLs or generic exception messages to the collector.

Central configuration

policy.diagnostics is strict, signed and disabled by default. Only an administrator's normal policy publication workflow can enable, reconfigure or disable it. Endpoint, sampling and resource bounds cannot be changed through website JavaScript or renderer preferences.

Example:

{
  "enabled": true,
  "mode": "debug",
  "endpoint": "http://127.0.0.1:4318",
  "sampleRate": 0.1,
  "debugSampleRate": 1,
  "maxQueueSize": 512,
  "flushIntervalMs": 2000,
  "maxRecordAgeMs": 30000,
  "exportTimeoutMs": 2000
}

Operational mode uses sampleRate; debug mode uses debugSampleRate. Sampling 1 records every eligible operation within resource limits. Debug does not authorize raw content collection. Queue size is 16–4096 records per signal, export batches at most 128, concurrent active spans at most 128. Records expire after the configured age; exporter requests time out. Excess data is dropped rather than delaying or bypassing a security decision. Frequent configuration changes cannot accumulate unlimited retired SDK generations.

Collectors require HTTPS, or HTTP to a numeric loopback address for a local collector. URL user information, query parameters and fragments are rejected. There is no environment-selected endpoint or cloud fallback. HTTPS certificate validation is explicitly enabled. Ambient OTEL_* headers and resource attributes are excluded; telemetry contains neither environment credentials nor process command lines, hostnames or OS usernames. Redirect responses fail instead of forwarding telemetry to another destination.

A local collector is the preferred enterprise transport boundary: it can handle customer authentication, mutual TLS, proxy routing, SIEM distribution and retention. Browser OTLP uses Node's controlled HTTP transport, outside website requests. Direct exporter support for enterprise proxy credentials and customer certificate provisioning is not yet implemented.

Recorded timing and correlation

The privileged browser instruments fixed operation families: IPC, local agent actions, management requests, navigation, DNS, outbound requests, local and enterprise inspection, download, clipboard, visual login checks, password fill, AI, network posture, tab and policy operations. Every recorded span has start/end timestamps and measured duration in milliseconds. Nested operations share trace IDs and parent span IDs through an isolated async context. Related diagnostic log records carry the same correlation identifiers. Durable security events may attach these identifiers without attaching content.

Attributes are explicitly typed and allowlisted: registered operation/component enums, UUID session/device IDs, policy version, bounded byte/count fields, duration, decision, request type and status. Failure spans receive a status and a fixed exception category (Error, TypeError or RangeError), never an exception message or stack. Arbitrary operation names are not recorded. Returned model answers, credential values and inspected content are never inferred as diagnostic attributes.

Signed debug mode imports validated private-pipe timing records as inspector child spans: inspection, parsing, OCR, OCR model initialization, YARA, macro extraction, semantic inference and semantic model initialization. Operational mode retains the call boundary. Renderer paint/layout, individual model kernels and Chromium internal tracing remain separate future work. This is explicit application instrumentation, not a claim to trace every Chromium function.

Protected evidence delivery has separate capture, challenge, encryption, send and acknowledgement stages, correlated with backend decrypt/store spans. Startup before enrollment or before a verified diagnostics policy cannot export telemetry; local smoke fixtures record bounded startup phase, window loading state and resource snapshots without URLs or credentials. Do not attribute an early startup timeout to a model or CPU pressure without measurements.

Lifecycle and security behavior

Only verified policy configures the provider. Reconfiguration immediately invalidates the old generation, drops queued old records and closes old exporter sockets. Disabling prevents future exporter requests and retries. Bytes already delivered cannot be recalled. Device revocation and expired policy disable diagnostics. A security block under otherwise valid policy can still be observed.

Export failure never repeats the protected operation, changes its result or authorizes blocked data. Successful and failing functions retain their original results/errors. Normal shutdown attempts a bounded flush; diagnostics are intentionally nondurable and can be lost in a crash. Durable audit and forensic evidence require their separate pipelines.

Local status distinguishes current-generation failedExports from process-lifetime lifetimeFailedExports. Disabling or changing policy resets the former but retains the latter until process restart. This counter does not export after disable.

Policy reconciliation now names signature verification, bookmark verification, agent reconciliation, page configuration and durable audit phases. Same-version refreshes preserve correlated child spans under the policy request. A new policy deliberately disables the previous provider during proxy/DNS changes; only phases after verified new diagnostics activation can export. That gap is intentional.

Verification

node --test tests/diagnostics.test.mjs exercises a real local OTLP receiver: parent/child traces, measured durations, correlated logs, typed attributes, password/token/URL/error sentinels absent, environment headers/resources excluded, disable/reconfigure queue invalidation, expiry, bounded batches and failed export without operation retry.

node scripts/native-tabs-smoke.mjs additionally runs the actual production Electron main process with a signed debug policy and a separate local collector. It verifies native IPC/navigation/DNS/request timing, parent/child IDs and correlated logs, preserves the existing all-tab DLP assertions, and checks that centrally revoking the browser stops subsequent diagnostic exports. Evidence is written to artifacts/native-browser-diagnostics-proof.json alongside the native tab proof.

Passwords and access tokens must remain excluded from any future forensic store as well. Selective confidential evidence, encryption, access control and retention are handled independently; enabling operational diagnostics does not enable forensic content retention.