Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

feat(audit): audit supervisor session establishment (connect, relay, tunnel)

Offen
  • Stimmt etwas nicht?
#3,018 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@Samyra312007 arbeitet bereits daran.

Seit 30.9.2026.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
rust
Bereich
security

Rechercherichtung

Beginne damit, den Gateway-/Supervisor-Sessionpfad rund um ConnectSupervisor, RelayStream und den WebSocket-Tunnel zu lesen. Untersuche anschließend den wiederverwendbaren Audit-Helfer, die Zuordnung von Principal zu Actor und den Master-Schalter aus #2911/#2912. Erledigt ist die Aufgabe, wenn sowohl der Aufbau als auch der Abbau für jeden Pfad mit den erforderlichen Feldern für Identität, Kanal, Ergebnis und Korrelation protokolliert werden, Geheimnisse redigiert sind, der Schalter greift und die Dokumentation für Operatoren sowie Tests dieses Verhalten abdecken.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

area:gateway state:validated topic:observability

User Story

As a security or compliance owner running OpenShell, I want supervisor session establishment — a sandbox connecting its supervisor, a relay stream being claimed, a WebSocket tunnel opening — recorded as structured audit events, so I can see when and by which principal a live control channel into a sandbox was opened and closed, not only what happened over it.

Problem Statement

OpenShell is gaining a structured audit trail for state-changing gateway operations (#2911) and for authentication and authorization outcomes (#2912). Neither covers the establishment of the supervisor↔gateway session and the relay and tunnel channels that ride it. ConnectSupervisor, RelayStream, and the WebSocket tunnel open and close are the moments a live channel into a sandbox comes up and goes down; today they surface only as ordinary diagnostic logs. Session establishment is not a resource mutation, so it is outside #2911's scope, and a successful, authorized establishment is not an authentication failure, so it is outside #2912. It falls between the two.

Impact / Why This Matters

An operator investigating a sandbox cannot reconstruct when its control channel was established, by which principal, or how long it stayed open — the session boundary that frames every exec, forward, and relay that follows. The exec and forward events (from #2911) presuppose a session that is already up; without a record of establishment and teardown, the trail has the actions but not the sessions that carried them, and cannot answer "when did a live channel into this sandbox exist, and who held it?" The current workaround is to infer session lifetime from surrounding diagnostic logs, which is neither stable nor attributable.

Proposed Design

Emit one structured OCSF audit event on establishment and one on teardown for each session-bearing path — ConnectSupervisor, RelayStream, and the WebSocket tunnel — naming the authenticated principal (sandbox or user), the sandbox, the channel type, the outcome, and a correlation id. The events never carry session input/output or bearer material. They reuse the audit helper, actor model, and master toggle that govern the control-plane audit events. The OCSF class is left to the implementer — an Entity Management (3004) session lifecycle event, in the spirit of the existing ssh-session records, is a natural fit. Emission is governed by the [openshell.gateway.audit] master toggle.

Acceptance Criteria

  • Each session-bearing path (ConnectSupervisor, RelayStream, WebSocket tunnel) emits an establishment record and a teardown record.
  • Each record names the authenticated principal, the sandbox, the channel type, the outcome, and a correlation id.
  • No session input/output, bearer token, or other secret material appears in any record; automated tests cover representative secret canaries.
  • Emission is governed by the existing [openshell.gateway.audit] master toggle.
  • Establishment and teardown for the same session share a correlation id so a session's lifetime can be reconstructed.
  • The events, their fields, and redaction behavior are documented for operators.

Alternatives Considered

  • Fold into #2911. Rejected: session establishment is not a resource mutation, and modeling a channel's open/close as a CRUD event on a resource distorts the mutation catalog.
  • Infer sessions from exec/forward events. Rejected: those events assume a session is already established, so the session boundary and its lifetime are lost, and a session that carried no exec would leave no trace at all.
  • Accept the gap. Leaves the control-channel lifecycle — a first-order security fact about a sandbox — unrecorded.

Agent Investigation

  • The session-bearing paths are ConnectSupervisor, RelayStream, and the WebSocket tunnel in the gateway/supervisor session path, with the authenticated principal available at the boundary.
  • The audit helper, principal→actor mapping, and master toggle being contributed for #2911/#2912 are directly reusable — this is incremental instrumentation on an established pattern.
  • This scope was explicitly deferred in the original audit-taxonomy design (recorded alongside the deferred credential-disclosure reads). It has no home in the current decomposition, which is why it is filed as its own request.

Checklist

  • I've reviewed existing issues and the architecture docs
  • This is a design proposal, not a "please build this" request
Vorherrschende Sprache
Rust
Sterne
15.4k
Forks
1.7k
Ø Merge
2 T. 22 Min.
Gemergte PRs (30 T.)
352

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus NVIDIA/OpenShell

Alle Issues in NVIDIA/OpenShell

Ähnliche Issues

Weitere Issues zu Rust

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.