first commit

docs/agent-observability-requirements.md

@@ -0,0 +1,36 @@
+# First-class agents and forensic observability
+
+User clarification, 2026-10-13: agents must operate the application as first-class
+clients, including tabs, permitted settings and bookmarks. Central administrators
+can disable access and limit individual capabilities. Mandatory corporate policy
+applies equally to a human and an agent. Generic JavaScript/CDP, cookie extraction
+and overriding a centrally locked setting are not alternate control paths.
+
+Agent authentication must support cryptographic client identity, narrowly scoped
+revocable credentials, bounded requests, replay protection and attributable audit.
+Current loopback capability tokens and Windows DPAPI are a foundation; delegated
+per-agent identities, request proof of possession and individual revocation remain
+required work. Full UI automation, history/library, safe screenshots and broader
+application capabilities remain separately tracked from the implemented controls.
+
+Security analysts need enough detail to reconstruct what happened: navigation,
+download name/source/hash/scan outcome, click target, copy/cut/paste direction,
+initiating tab/agent and the relevant rule and result. Confidentiality alone must
+not suppress security-relevant evidence. Passwords and authentication tokens must
+never enter logs. URLs, element labels and content may themselves contain secrets;
+they need typed redaction and centrally governed evidence collection.
+
+The security audit and confidential evidence store are distinct from operational
+OpenTelemetry. The evidence store must encrypt records, bind them to immutable
+event identities, restrict analyst access, log every access, enforce retention and
+support incident correlation and SIEM references. Selected relevant content may be
+retained by policy; storing entire documents is not required. Existing metadata
+events do not satisfy this full forensic requirement. Detailed download records,
+human click tracking and controlled content evidence are still to implement.
+
+OpenTelemetry debug mode must expose correlated spans for IPC, agents, navigation,
+network/DNS, document/OCR/YARA/semantic inspection, policy handling and management
+requests, including durations and named code stages. Debug collection is centrally
+managed, bounded and disableable. Operational spans do not silently become a raw
+content or credential archive. Backend tracing and collector/SIEM permissions,
+encryption and retention must complete the end-to-end pipeline.