Centralized audit/event log

[johntmyers]

Placeholder for capturing minimal requirements on audit events that come from BYO extensions as well as built-in events/capabilities.

[github-actions]

This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.

[fbricon]

This issue started as an audit log placeholder, but I'd like to propose expanding the scope to a general-purpose client-facing event stream — since the same infrastructure (event types, subscriptions, streaming transport) would also serve audit.

Today, WatchSandbox is the only streaming watch RPC on the public OpenShell service, and it's scoped to a single sandbox by ID. There's no way for 3rd party clients (e.g. Kaiden) to observe changes across sandboxes, providers, services, or policy state without polling List* RPCs.

A few related threads:

• feat(gateway): multi-sandbox approval inbox via streaming proposal updates #1612 proposed WatchProposalInbox for multi-sandbox policy draft streaming — scoped to policy, but recognised the streaming pattern gap.
• Push gateway-owned desired state to supervisors #1731 is about internal supervisor→gateway events, not the client-facing surface.
  What I think would be useful here is a single WatchEvents server-streaming RPC on the OpenShell service that emits structured events for entity lifecycle changes a client has permission to see:

rpc WatchEvents(WatchEventsRequest) returns (stream PlatformEvent);

message WatchEventsRequest {
  repeated EventType filters = 1;       // entity types to subscribe to
  bool replay_past_events = 2;          // best-effort replay on connect
  int64 since_ms = 3;                   // only events after this timestamp
}

Entity types to cover: sandbox (created, phase change, deleted), provider (attached, detached, credential expiry), service (exposed, removed), ssh_session (created, revoked), policy (draft proposed, approved, rejected — overlaps with #1612's inbox), settings (config change).
The gateway already has OCSF structured events internally — these could be mirrored onto the event stream with appropriate redaction. That gives audit out of the box (structured, schema'd, replayable) while also solving the multi-entity watch problem for clients.
Key design questions to resolve:

• Retention/backlog — keep events in the database for replay, or only stream live?
• Filtering at the server vs client side — repeated EventType filters avoids flooding thin clients.
• Authz — reuse the existing role policy (caller's read scope defines visibility per entity type).
• Rate-limiting — a rogue client subscribing to all event types shouldn't hammer the store.
  This would unify audit, client-side watch/subscribe, and the policy inbox stream under one event model instead of adding per-entity watch RPCs one at a time.

[delgadof]

I support expanding this issue into a supported, general-purpose client event subscription rather than limiting it to centralized audit storage.

The use case is broader than any individual partner:

• SIEM and security data lakes
• SOAR and incident-response automation
• Policy advisors and approval services
• Fleet-health and AIOps systems
• Compliance and audit consumers
• Partner dashboards and SDK integrations

This should complement, not replace, the file-first durable export being investigated in #1922:

• File/collector export is the durable archival and SIEM path.
• A client-facing event stream is the real-time automation and integration path.

I propose that the public contract support:

• Typed OCSF security events and typed OpenShell lifecycle events
• Sandbox, provider, service, settings, and policy lifecycle events
• Sandbox ID/name and label-selector filtering
• Event class, action, and severity filtering
• Stable event IDs and sequence numbers
• Opaque resume cursors and bounded replay
• Heartbeats and explicit delivery-gap/drop reporting
• OIDC/RBAC visibility scoped to authorized resources
• Schema/producer versioning and documented redaction
• Correlation between enforcement, draft creation, approval/rejection, policy reload, and controlled retry

The authoritative policy state should remain in the existing policy APIs. For example, a DRAFT_CHUNK_AVAILABLE event should carry identifiers and correlation metadata; an authorized consumer would then use GetDraftPolicy and the existing approval/rejection RPCs.

Related work:

• Enterprise Observability #1055 — enterprise observability umbrella
• feat(observability): investigate portable sandbox log collection #1922 — durable portable log collection
• Add OpenTelemetry trace correlation across gateway activity #1758 — OTel/OCSF correlation
• OpenShell Agent-Driven Policy Management #1062 — policy lifecycle audit events
• feat(gateway): multi-sandbox approval inbox via streaming proposal updates #1612 — prior resumable proposal inbox design
• Push gateway-owned desired state to supervisors #1731 — internal supervisor event transport

[github-actions]

This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.