feat(observability): export an atomic sandbox governance evidence bundle

[imran-siddique]

Problem Statement

OpenShell already exposes the ingredients needed by external governance and compliance consumers: the effective sandbox policy, sandbox configuration and revision state, and OCSF audit events. Those ingredients are currently retrieved independently, however, so a consumer cannot establish that they describe the same sandbox state or determine whether the event interval is complete.

This is complementary to #1922 (portable, durable sandbox log collection) and #2640 (trace/span correlation). Durable logs and correlation fields are valuable inputs, but they do not bind the exact effective policy, sandbox/workload identity, event bytes, and completeness state into one authoritative export.

External adapters can hash and sign bytes they receive, but they should not invent authoritative associations or claim completeness that OpenShell itself has not established.

Proposed Design

Add an atomic export command along these lines:

openshell sandbox evidence export <sandbox> --since <timestamp> --output <directory>

The export would contain:

• manifest.json
• effective-policy.yaml
• events.ocsf.jsonl

manifest.json should include:

• evidence format version;
• immutable sandbox ID and display name;
• OpenShell version;
• configuration and effective-policy revision;
• SHA-256 digest of the exact effective-policy.yaml bytes;
• workload/image digest when available;
• capture start and end times in epoch milliseconds;
• an explicit complete boolean and, when false, a machine-readable reason;
• OCSF schema version and event count;
• SHA-256 digests of every exported file; and
• trace/span identifiers when available.

Required invariants:

1. effective-policy.yaml is the policy OpenShell actually enforced, not the originally submitted input.
2. Every exported OCSF event's metadata.uid identifies the exported sandbox.
3. OCSF product metadata records the OpenShell version that produced the event.
4. complete: true is emitted only when OpenShell can account for the entire requested interval. Rotation, truncation, gateway restart, or unavailable history must produce complete: false with a reason.
5. File digests cover the exact exported bytes. Existing credential redaction guarantees remain in force.
6. The export stays vendor-neutral. OpenShell should provide authoritative evidence, not implement TRACE-specific signing or conformance logic.

Acceptance tests should cover:

• allowed and denied events validating against the vendored OCSF schemas;
• successful verification of all manifest digests;
• rotation/truncation causing an explicitly incomplete export;
• policy changes producing a new revision and digest;
• rejection/detection of cross-sandbox file substitution; and
• a credential-canary scan proving exported files preserve redaction.

This primitive would support SIEM ingestion, incident response, audit archives, and third-party governance formats without coupling OpenShell to any one consumer.

Alternatives Considered

• Implement only feat(observability): investigate portable sandbox log collection #1922: durable portable logs solve retention and transport, but not policy/workload binding or an authoritative completeness assertion.
• Let external tools stitch existing commands together: consumers cannot prove the reads were atomic or authoritatively declare completeness.
• Persist the current gateway log buffer: it remains an event source without binding to exact policy/configuration state.
• Use OTLP alone: OTLP is useful for semantic telemetry export, but does not by itself define an exact-byte, revision-bound evidence bundle.

Agent Investigation

Investigation was performed against OpenShell v0.0.105 (0f8fad23c4712afc1d4a7b07a06d635b030e9521):

• proto/sandbox.proto exposes GetSandboxConfigResponse.config_revision.
• proto/openshell.proto exposes sandbox policy status/revision APIs.
• The CLI/docs expose openshell policy get <name> --full and JSON sandbox retrieval.
• OCSF JSON export is available when ocsf_json_enabled is enabled.
• crates/openshell-ocsf supplies product identity and sandbox identity through metadata.uid.
• A duplicate search found feat(observability): investigate portable sandbox log collection #1922 and feat(ocsf): add trace_id/span_id correlation fields to OCSF event builders #2640, but no proposal for an atomic policy/revision/event/completeness evidence export.

A released external consumer demonstrates the current integration boundary and the reason the authoritative association belongs in OpenShell:

• https://pypi.org/project/agentrust-trace-adapters/0.1.0/
• https://github.com/agentrust-io/integrations/tree/main/integrations/openshell
• https://github.com/agentrust-io/integrations/blob/main/integrations/openshell/upstream-evidence-export-proposal.md

Checklist

• I have reviewed existing issues and architecture documentation.
• This is a concrete design proposal rather than a feature wish list.