first commit

docs/threat-model.md

@@ -0,0 +1,90 @@
+# S Browser threat model and security acceptance gates
+
+Status: implementation threat model, 2026-10-13. This is not an independent security
+assessment. See `requirements-audit.md` for current implementation evidence.
+
+## Assets and adversaries
+
+Protect confidential document/prompt bytes, credential material, browser session
+authority, signed policy versions, classification features, administrator identity,
+audit integrity and availability. Hashes and semantic vectors are confidential
+derived data, even though source documents are not retained.
+
+Consider malicious sites and frames, hostile document/media files, malicious
+clipboard instructions, compromised AI output, unauthorized local agents, stolen
+device credentials, network interception, stale policy caches and unauthorized or
+compromised management identities. A local OS administrator can replace executable
+code or inspect process memory: protecting against that requires endpoint controls
+outside this browser's present assurance boundary.
+
+## Trust boundaries
+
+1. **Remote site to privileged browser.** Website content has no trusted UI bridge,
+   Node access or administrative authority. Renderer requests and DOM observations
+   are untrusted; native policy checks own transfer decisions. Website appearance
+   cannot establish origin identity.
+2. **Browser to clipboard/files/network.** Inspect before release. An approval must
+   bind destination, bytes, current policy and current target context. Unsupported
+   transfer paths remain blocked. Rich/file/subframe clipboard paths are not silently
+   downgraded to plain-text inspection.
+3. **Document bytes to parser/model worker.** Authentication to the loopback broker
+   is separate from permission to parse a document. Untrusted documents must run in
+   a restricted worker with no broker credentials, host data access or network
+   capability. Job Objects limit resources but do not satisfy this boundary alone.
+4. **Device to management.** Enrollment establishes device identity; it never
+   establishes admin authority. HTTPS, independently pinned policy keys, signed
+   monotone versions, expiries and authenticated device requests all remain required.
+5. **Administrator to management.** Verified OIDC identity and exact role permissions
+   authorize every backend route. Hidden controls are a usability property. Session
+   revocation invalidates current cookies; removing an IdP group must also prevent
+   future logins. Mandatory independent approval is still a separate gate.
+6. **Browser/AI gateway to approved model.** Classify locally/customer-side before
+   external transmission. Provider credentials stay at the gateway. Page content,
+   retrieved documents and model output cannot grant tool permissions or change
+   policies. Model similarity is evidence, not a proof of confidentiality absence.
+7. **Local agent to browser.** Pairing capabilities are scoped, device-local and
+   revocable. Fixed actions validate the target/session again before execution.
+   No arbitrary JavaScript, CDP, cookie export or password export is exposed.
+8. **Enforcement to audit/SIEM.** Record bounded metadata rather than source contents,
+   prompts or credentials. Durable event ingestion and deduplication are separate
+   from sampled operational traces. SIEM failures must retain a retryable backlog.
+
+## Abuse cases and acceptance evidence
+
+| ID | Abuse case | Required invariant / release test |
+| --- | --- | --- |
+| DLP-01 | Page swaps an approved file after scanning | Receiver obtains only the inspected immutable bytes; native file transfer binding is still open. |
+| DLP-02 | Worker/frame/WebSocket/stream bypasses a form control | Every permitted channel is gated before transmission; explicitly block unsupported channels and test controlled receivers. |
+| DLP-03 | Clipboard selection or destination changes during scan | Discard the pending release; scan approval cannot authorize a new selection, document or policy generation. |
+| DLP-04 | ClickFix asks employee to execute copied instructions | Withhold covered dangerous command patterns; do not claim this heuristic detects all executable malware. |
+| PARSE-01 | Document exploits native parser and reads user secrets | Native restricted-worker probe cannot read a synthetic private file outside explicitly approved roots. |
+| PARSE-02 | Exploited parser sends document bytes to network | Native worker TCP/UDP probes fail without network capability; no loopback exemption or credential forwarding. |
+| PARSE-03 | Worker forks, hangs, exhausts memory or survives owner | Process tree limits, no breakaway, deadline termination and clean subsequent scan; prove actual OS behavior. |
+| POLICY-01 | Attacker replays old/expired/different-device policy | Signature, device binding, expiry and monotone revision reject it; emergency restore is published as a new version. |
+| POLICY-02 | Operator forges admin permissions in session/UI | Backend recomputes role permissions; direct publication/revocation requests fail. |
+| POLICY-03 | Cross-site page triggers an admin mutation | Exact Origin validation rejects cookie-authenticated writes and logout from other/missing origins. |
+| AUTH-01 | Stolen/shared bootstrap token bypasses enterprise SSO | Remote HTTPS management rejects development bootstrap credentials. |
+| AUTH-02 | Removed admin retains existing browser cookie | Explicit emergency session revocation rejects the next request; continuous IdP/back-channel revocation remains open. |
+| PHISH-01 | Unknown domain renders a trusted login page | Pixel reference match plus exact HTTPS origin mismatch quarantines the page; validate layouts/languages/iframes and false positives before fleet-wide use. |
+| AI-01 | Prompt injection asks agent/model to disclose other data | Policy and tool permissions are independent of prompt contents; retrieval ACLs and full tool governance remain open. |
+| LOG-01 | Prompts, URLs with secrets or source documents enter logs | Allowlisted bounded metadata; inspect actual exported OTLP/ECS/CEF output and failure responses. |
+| UPDATE-01 | Attacker supplies modified browser/model/update | Pinned artifact hashes and verified publisher signatures; production signed updater is still open. |
+
+## Operational response and residual risks
+
+Revoke compromised device credentials and management sessions; publish strengthened
+rules as a new policy version and verify device acknowledgement. Preserve bounded
+audit evidence under the customer's retention/access rules. Rotate affected keys
+and provider credentials through deployment tooling; automated key rotation and
+full incident workflow are not complete.
+
+Unavailable scanners, unsupported content or expired policy must not be interpreted
+as an allow verdict. Test recovery separately: a blocked parser request must not
+force permanent loss of the scanner. Network/proxy/VPN detection has its documented
+latency and cannot prove operating-system routing on its own.
+
+Camera capture, manual retyping, other applications, administrator tampering,
+unvalidated classifier accuracy and covert/encoded exfiltration remain residual
+risks. Extend endpoint/network controls and independent bypass testing before
+production approval. Each acceptance row needs evidence matching its full scope;
+a green synthetic test for one path does not close all related paths.