safetynet/docs/agent-visual-export.md

Inspected page viewport export for local agents

Administrators separately enable the screenshot action scope in the signed central baseline and individual grant. The capability starts unchecked; new grants start disabled with no scopes. Destination restrictions, expiry, generation rotation and targeted revocation still apply. Remove the scope or disable agents and publish to revoke access once the policy reaches the browser. Policy changes must follow the configured independent review workflow; auditor controls are read-only.

The action accepts only an optional native sessionId. Omission captures the foreground tab once; explicitly selecting a background tab is refused. Its internal transport scope is browser:screenshot. A successful protected reply has exactly these fields:

{"mime":"image/png","width":1280,"height":720,"data":"<canonical base64 PNG>"}

This exports the current foreground managed HTTPS webpage viewport. There is no clip rectangle, resizing, full-page scroll capture, offscreen target, desktop, other-window or browser-chrome capture API. PNG bytes are bounded to 2 MiB, dimensions to 4096 each, and pixels to 8 Mi. The example describes the reply shape, not a real image. Agents receive sensitive image data and must handle it as such; this API does not authorize onward cloud transfer.

Before and after capture/inspection, privileged code checks the current native context, document/view revision, actor/generation, policy, destination, foreground identity and cancellation. Returning to the same URL or tab does not restore a changed context. A fixed isolated-world probe rejects credential, card and authentication-bearing controls, including hidden/offscreen controls. Open shadow trees are recursively observed; queued mutation records are drained before comparison, and newly discovered roots advance the revision. Native closed/declarative shadow roots and child frames are initially refused; their presence is a compatibility limitation, not an implicit permission to capture their pixels.

Local image inspection with complete OCR coverage is mandatory. Enabled central YARA and semantic checks, plus upload ICAP when configured, remain required. The exact bounded PNG is inspected before return; byte binding and repeated context probes prevent reuse of a changed buffer or inspected context. An opaque private release guard, absent from the API projection, rechecks the original policy, native frame/process/routing identity, loading state, context token, actor and foreground activation after final authorization/encryption and immediately before the protected reply is sent. Legacy callers receive the same original-context check.

allowSensitiveRead does not override visual inspection. Unavailable required inspection, incomplete coverage, sensitive content or changed authority denies the export. Disabling supplemental manual document scanning does not grant this capability or waive required inspection.

OCR/classifiers can miss rendered secrets, tiny text, image-based secrets or steganography and can produce false positives. Complete reported OCR coverage is not proof of absence of confidential information. Shadow/frame refusals do not establish a universal browser side-channel guarantee. No claim is made for arbitrary animated pages, accessibility surfaces, OS overlays or independent security review.

Security audit records fixed action/scope/outcome/session/principal metadata. Only required image chunks and a supported standard sRGB marker are accepted; arbitrary ancillary text/EXIF/profile metadata are refused. The successful reply is encrypted on the wire, but the trusted helper decrypts it for its caller. Byte buffers are wiped best effort; immutable base64 strings and caller copies cannot be guaranteed erased.

PNG/base64, OCR text, page URLs and extracted secrets must not enter ordinary audit or diagnostic fields. Named debug stages cover probe, capture, local and enterprise inspection and audit. Diagnostics are separately centrally disableable; a failed export is not permission to retry a protected operation automatically.

Verification status

The central unchecked capability and individual-grant/read-only controls have focused UI tests. The actual Windows/Electron admin fixture proves separate author/reviewer publication, self-approval denial, auditor read-only controls and reviewed removal from both baseline and grant at version 5. All 200 completed API requests exported parent-correlated backend spans; no requests failed. Evidence: artifacts/agent-grants-history-admin-proof.json and artifacts/agent-grants-history-admin-traces.json.

The first expanded fixture runs exceeded the shared IP rate bucket because their short synthetic cookie values did not meet the real per-session bucket length criteria. The fixture now uses realistic-length synthetic capabilities; production rate limits and deadlines were not weakened. Those failed diagnostics are retained.

The existing actual Windows/Electron proof exercised public viewport export, mandatory OCR even with supplemental document scanning disabled, confidential canvas rejection, mandatory PNG antivirus rejection, offscreen sensitive controls, closed shadows, public open shadows, child frames, foreground/policy races and central revocation (artifacts/agent-visual-export-native-proof.json). The latest native run also rejects a policy change after classification despite remaining screenshot/grant/host permissions, a foreground change after helper return and an open-shadow mutation/revert. Its final release remains a child of the outer request. Trace aad45c8a85f25619a233b78e132d7bad contains all eight visual stages; final release took 0.2507 ms. ICAP recorded 26 scans, five PNG scans and one expected block; the protected collector rejected no writes.

695 tests and syntax checks pass (artifacts/agent-visual-final-suite.log, artifacts/agent-visual-final-syntax.log). The final stable Windows build and exact packaged-source/runtime verification pass (artifacts/agent-visual-release-windows-build.log, artifacts/agent-visual-final-package-proof.log). The executable remains NotSigned. These narrow proofs do not establish universal secret detection or independent security certification.