From 0ee5f044ba31f78899dedc8f4a65c5a643444c72 Mon Sep 17 00:00:00 2001 From: irenarindos Date: Thu, 21 Mar 2024 12:19:46 -0400 Subject: [PATCH] docs(bsr): explain bsr data chunks --- website/content/docs/concepts/auditing.mdx | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/website/content/docs/concepts/auditing.mdx b/website/content/docs/concepts/auditing.mdx index 9f193edc6a..e217b14d68 100644 --- a/website/content/docs/concepts/auditing.mdx +++ b/website/content/docs/concepts/auditing.mdx @@ -352,3 +352,29 @@ requests: inbound ``` For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording). + +### Reading a BSR Data File + +BSR data files are where all the data transmitted during a session is stored. BSR data files +have the file suffix `.data` and are binary files written in network byte order (big-endian). The first eight bytes of a +BSR data file always contains the following signature, which identifies the file as a BSR file:`"\x89BSR\r\n\x1a\n"` + +Following the BSR signature, a BSR file contains “chunks” of data. Each chunk contains the same basic metadata information +(length, protocol, chunk type, direction, and a timestamp). The chunk type indicates the expected data payload. The first +chunk in a BSR file is the header chunk, and the last chunk in a BSR file is the EOF chunk. The remaining +chunks in the file are dependent on the protocol identified in the BSR header. + +The only protocol currently supported for session recording is SSH. Data files for SSH are prefixed with either `messages-` +or `requests-` and suffixed with either `inbound` or `outbound` to indicate the direction the data came from. Messages +files contain raw data from an SSH session and contain a header chunk, data chunks, and an EOF chunk. Requests files +contain a header chunk, SSH request message chunks, and an EOF chunk. + +SSH request message chunks follow the SSH connection and channel request definitions. Boundary populates these chunks +using a protobuf definition provided here: [SSH Chunks] (https://github.com/hashicorp/boundary/blob/main/internal/bsr/proto/ssh/v1/ssh_chunks.proto). + +Boundary session recording playback generates an asciinema from a session channel’s `messages-outbound.data` file. For more +information on finding and viewing BSR data this way, refer to [Find and view recorded sessions] (https://developer.hashicorp.com/boundary/docs/operations/session-recordings/manage-recorded-sessions). + +While Boundary does not currently provide tooling to read other BSR .data files, our BSR definition is available in our +[community repository](https://github.com/hashicorp/boundary/tree/main/internal/bsr) and can be used to develop external tooling. +