Repository navigation
Centralized audit/event log #1933
Description
Activity
- added a parent issue
on Jun 16, 2026 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.
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.
Reacted by Brian M and Fran DelgadoI 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_AVAILABLEevent should carry identifiers and correlation metadata; an authorized consumer would then useGetDraftPolicyand 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
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.
Placeholder for capturing minimal requirements on audit events that come from BYO extensions as well as built-in events/capabilities.