Session Recording & Audit Logs
Relevant source files
The following files were used as context for generating this wiki page:
Session Recording and Audit Logs constitute a core security feature of the Hoop gateway, providing comprehensive visibility into user and AI agent interactions with production infrastructure. The system captures every command, query, and response across supported protocols (SQL, Shell, Kubernetes, etc.), allowing for real-time monitoring and post-execution forensics.
The architecture relies on a Write-Ahead Log (WAL) mechanism to record streaming data incrementally, which is then persisted as blobs in the database. Beyond raw traffic capture, the system generates high-level security audit logs for administrative actions and integrates with DLP (Data Loss Prevention) and AI analyzers to detect sensitive data or anomalous behavior within sessions.
Sources: README.md, gateway/transport/plugins/audit/wal.go:273-288
Session Recording Architecture
The recording system is implemented as an audit plugin that intercepts protocol traffic. It utilizes a WAL-based approach to ensure data integrity and enable real-time streaming of session events.
Data Flow & Persistence
When a session starts, the audit plugin creates a WAL folder on disk. During the session, events are written to the WAL and periodically flushed (every 50 seconds) to a permanent blob store in PostgreSQL using JSONB concatenation.
The diagram shows the transition of session data from live traffic to local disk persistence, and finally to long-term database storage.
Sources: gateway/transport/plugins/audit/wal.go:102-120, gateway/transport/plugins/audit/wal.go:159-178, gateway/models/session.go:283-305
Event Structures
Individual events are stored as encoded triples containing the elapsed time, event type, and base64-encoded content.
| Event Field | Type | Description |
|---|---|---|
elapsed | float64 | Relative time in seconds from session start |
type | string | Type of event (e.g., 'i' for input, 'o' for output, 'e' for error) |
content | string | Base64 encoded payload of the protocol packet |
Sources: gateway/transport/plugins/audit/wal.go:273-288, gateway/api/session/session.go:429-436
Security Audit Logs
Security Audit Logs track administrative and management actions within the gateway. These are distinct from session recordings and focus on "who did what" at the API level.
Audited Actions
The system automatically records actions related to resource management, user groups, and security configurations. These logs include the actor's identity, the source IP, and the outcome of the request.
The sequence diagram illustrates how API requests are intercepted to record management operations.
Sources: webapp_v2/src/pages/Settings/AuditLogs/index.jsx:26-38, gateway/api/openapi/openapiv3.json
Core Audit Metadata
| Field | Source | Description |
|---|---|---|
actor_email | JWT/Session | The email of the user who performed the action |
action | HTTP Method | create, update, delete, or revoke |
resource_type | URL Path | connections, users, agents, etc. |
client_ip | Network | The source IP address of the requester |
http_status | Response | The resulting status code (e.g., 201, 403) |
Sources: webapp_v2/src/pages/Settings/AuditLogs/index.jsx:49-65, gateway/api/openapi/openapiv3.json
Derived Events & Intelligence
As sessions close, the gateway derives high-level events by analyzing the captured recording and associated metadata.
Event Catalog
Hoop publishes events to external sinks (like webhooks) based on session outcomes:
- session.started / session.closed: Lifecycle markers for every interaction.
- session.guardrail_violation: Triggered if a command matches a blocked pattern.
- alert.data_masked: Emitted when the DLP provider redacts sensitive information.
- session.anomaly_detected: Fires when the AI analyzer flags high-risk activity.
- session.pci_scope_entered: Triggered when a connection tagged with "pci" is accessed.
Sources: gateway/events/catalog.go:26-170, gateway/events/derive.go:57-95
AI Session Analysis
The AI analyzer evaluates session scripts to provide risk scores and explanations.
Intelligence logic derived from the post-session analysis flow.
Sources: gateway/events/derive.go:81-85, gateway/models/session.go:73-78
Management and Retrieval
CLI Access
Users can inspect sessions via the hoop sessions command. This supports filtering by role, user, and date range.
# List recent sessions for a specific connection
hoop sessions list --role prod-db
# Get full details including recorded input for a specific session
hoop sessions get <session-id> --json
Sources: client/cmd/sessions.go:50-80
Web UI
The React-based web interface provides a searchable table for audit logs with expandable rows to view raw request payloads and error messages.
Sources: webapp_v2/src/pages/Settings/AuditLogs/index.jsx:135-155
Session Download & Streaming
Session recordings can be retrieved through the API in various formats:
- Real-time Streaming: Accessible via Server-Sent Events (SSE) for active sessions.
- CSV/JSON Download: Decodes the blob stream into readable files, optionally including timestamps and line breaks.
- Plain Text: Returns the raw output via a chunked transfer encoding stream.
Sources: gateway/api/session/session.go:404-428, gateway/api/session/session.go:585-610
Conclusion
The Session Recording & Audit Log system provides a robust foundation for compliance and security. By combining low-level protocol capture (WAL/Blobs) with high-level API auditing and automated intelligence (DLP/AI), Hoop ensures that every interaction with production environments is transparent, attributable, and replayable.
Sources: README.md, gateway/events/catalog.go