feat(ocsf): comprehensive audit telemetry and off-box OTLP export

[mattj-monad]

TLDR

OpenShell can run agents safely, but understanding the actions the agent took (or were denied by policy) is limited to a subset of actions and the logs cannot be exported for analysis.. This PR makes every security-relevant action a structured, standard-schema (OCSF) event and streams the logs to any OpenTelemetry collector. It turns OpenShell into an enterprise ready solution with full visibility, which can audited, monitored, and learned from.

Why it matters

• Understand and improve your agents and models. Every choice an agent takes or has blocked, the commands it runs, the resources it reaches for, the policies and boundaries it hits, where it stalls or retries, all becomes collectable data. This lets teams building on OpenShell see how their agents actually behave in the wild and rapidly improve their own models, prompts, and policies from real usage rather than guesswork, all while providing the security team visibility.
• Built for enterprise scale. One correlated, standard-schema stream with accountable delivery, designed to run across thousands of sandboxes at once. An efficient push format keeps the per-event cost low so the volume stays manageable at fleet scale.
• Audit — a provable record of who created, changed, minted, or deleted anything: sandboxes, credentials, policies, tokens, workspaces. It answers "who deleted this sandbox?" and "was this credential rotated by a person or by a job?" — questions that had no data behind them before.
• Security — authentication failures and boundary violations become first-class alerts.
• Open standard, no lock-in — everything is OCSF (the security schema OpenShell already uses for sandbox events) carried over OTLP (the transport agent frameworks already speak), so it drops into tooling teams already run.

What we built

• Control-plane audit (new). 34 state-changing gateway operations that previously emitted nothing now each produce one structured event carrying the authenticated actor and the outcome — across workspaces, providers, credentials, sandboxes, SSH sessions, exec, policy, settings, inference routes, and token issuance. Background work (credential rotation, reconciliation, startup) is attributed to a system actor instead of going unrecorded.
• Authentication & boundary alerts (new). Auth failures are recorded with mechanism and a safe reason category; cross-boundary attempts dual-emit a high-severity security finding alongside the ordinary denial.
• Log Export (new). The sandbox's existing OCSF security events and these new control-plane events export together as OTLP logs to any OpenTelemetry collector, correlated per sandbox, on the same endpoint the gateway already uses for traces.
• Accountable delivery. Bounded buffering with retries on both hops (sandbox→gateway and gateway→collector); anything dropped under load surfaces as a countable gap, so the record is never silently incomplete.
• Safe by construction. No credential, token, or bearer material ever enters a record. A single master toggle governs the whole trail; it's on by default.

Example

Every event is human-greppable shorthand and full OCSF JSON. A sandbox deletion, for example, renders as:

ENTITY:DELETE [INFO] sandbox "sb-abc123" by user:alice(alice@corp)

...and exports as a complete OCSF Entity Management record carrying the actor, outcome, correlation id, and severity for downstream filtering and alerting.

Scope

Four OCSF event classes (Entity Management, Config State Change, Authentication, Detection Finding), ~34 instrumented handlers, spanning the shared OCSF and OTLP crates, the sandbox supervisor, and the gateway.

Alignment with roadmap

This is the built, tested implementation of OpenShell's own Enterprise Observability direction (NVIDIA#1055) and the issues the maintainers have already broken it into: control-plane audit events (NVIDIA#2911), gateway authentication and boundary findings (NVIDIA#2912), OCSF-over-OTLP export (NVIDIA#2892), and accountable relay delivery (NVIDIA#2642). Sandbox and control plane, one correlated stream, off the box — ready now.

Next steps.

We are working with the OpenShell maintainer team to get the fixes and issues aligned with requests and requirements. Once merged, these contributions should allow enterprise teams to adopt OpenShell with full visibility into the entire projects actions.