Skip to content

feat(observability): join inspected HTTP receipts with OCSF records #5393

Open

Description

@afourniernv

User Story

I run sandboxes that call protected HTTP APIs and need to match a response to
the OpenShell security record and supervisor trace for that request.

Problem Statement

Trace export alone does not provide a shared per-request receipt. Timestamp
matching is ambiguous, and a request blocked locally must not be recorded as
allowed or confused with a request that reached the API.

Proposed Design

Reuse OpenShell's middleware UUID for each inspected request. Return it in the
protected X-OpenShell-Request-ID header and record it as OCSF
metadata.correlation_uid. Emit one primary HTTP Activity record when final
response headers are accepted, with an early-failure fallback and distinct late
exceptions. Preserve original path, process and policy attribution.

#5214 also includes a supervisor-owned request span and children for stages that
actually run. Valid sampled or unsampled workload W3C context is an explicitly
untrusted link, never the supervisor parent. Inspected requests do not create
additional denial-only spans. Audit records, enforcement and receipt joins do
not depend on sampling or export. End HTTP tracing before upgraded sessions.

The header joins records; it is not authorization or proof of completed delivery.
Uninspected traffic retains its existing behavior. #5471 no longer represents a
separate tracing slice; operator sampling configuration remains independent in
#5362. Upstream propagation is outside this core.

Acceptance Criteria

  • Inspected allow, deny and pre-header failures have a shared request ID and
    one accurate primary HTTP Activity record.
  • Middleware, credential and reinspection outcomes retain request attribution;
    late failures are not silently lost or mistaken for a second primary.
  • Callers, upstreams and middleware cannot forge or remove the receipt.
  • Supervisor traces use untrusted workload links, accurate stage timing and
    no additional denial-only spans on inspected paths.
  • Enforcement and receipt joins remain correct without sampled/exported spans;
    existing transport and uninspected behavior remain compatible.

Alternatives Considered

Timestamp joins are insufficient. A remote middleware service cannot observe all
requests rejected before middleware or protect every inspected response receipt.
Workload trace parenting would give the workload control over supervisor trace
identity and parent-based sampling.

Agent Investigation

The current implementation b595d7060 passed 1,660 network tests, 385 supporting
tests and full pre-commit. Three real model-driven Hermes/Relay workflows
produced 68 native spans and 12 receipts joined to supervisor-owned traces and
OCSF records, including denial/recovery, redaction and authenticated GitHub.
A trace-disabled live rerun retained four receipts and OCSF records, with no
supervisor request spans exported.

The receipt core adds an additive Rust OCSF setter; tracing helpers are internal.
No new configuration field, gateway RPC or Relay dependency. Component of #5210;
the broader tracker stays open.

Checklist

  • Reviewed existing issues and published docs.
  • Includes a design proposal, not only a feature request.

Activity

  1. added
    state:acceptedA maintainer decided OpenShell should pursue this issue
    and removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Nov 9, 2026
  2. changed the title [-]feat(observability): correlate inspected HTTP requests with traces and OCSF[/-] [+]feat(observability): join inspected HTTP receipts with OCSF records[/+] on Nov 10, 2026
  3. added a commit that references this issue on Nov 13, 2026
    11030e5
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:acceptedA maintainer decided OpenShell should pursue this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions