aherman
/
boundary
mirror of https://github.com/hashicorp/boundary
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '4e2335e27f'
${ noResults }
boundary/website/content/docs/session-recording/data/bsr-file-structure.mdx

277 lines
11 KiB
Raw Blame History Escape

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
layout: docs
page_title: BSR file data structure
description: >-
Understand the data structure in Boundary's proprietary BSR file that stores session recording data.
---
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
# BSR file data structure
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
The BSR (Boundary Session Recording) defines a hierarchical directory structure of files and a binary file format.
It contains all the data transmitted between a user and a target during a single session.
Boundary creates the top-level directory of the BSR as `<sessionRecordingID>.bsr`. This top level directory contains session summary
information and subdirectories for connections.
A BSR connections directory contains a summary of connections, as well as inbound and outbound requests.
If you use a multiplexed protocol, there are subdirectories for the channels.
Every directory contains a SHA256SUMS and SHA256SUMS.sig file, to be used for cryptographically verifying the contents of
that directory. The SHA256SUMS file contains rows of file names paired with a checksum for file contents. The
SHA256SUMS.sign is a copy of the SHA256SUMS file, signed with the BSR’s private key. For more information on verifying a
session recording, refer to [Validating the integrity of session recordings](/boundary/docs/session-recording/compliance/validate-session-recordings).
The example BSR below is for a multiplexed session recording with the ID `sr_iNCdGSREeX`. The session recording contains one connection,
`cr_3bB78W53Y9`. Connection `cr_3bB78W53Y9` contains two channels, `chr_VUnVuVnITu` and `chr_nITuVUnVuV`.
The files in each directory are explained in the following sections.
```
└── sr_iNCdGSREeX.bsr
├── SHA256SUM
├── SHA256SUM.sig
├── bsrKey.pub
├── pubKeyBsrSignature.sign
├── pubKeySelfSignature.sign
├── session-meta.json
├── session-recording-summary.json
├── session-recording.meta
├── wrappedBsrKey
├── wrappedPrivKey
├── cr_3bB78W53Y9.connection
│ ├── SHA256SUM
│ ├── SHA256SUM.sig
│ ├── connection-recording-summary.json
│ ├── connection-recording.meta
│ ├── requests-inbound.data
│ ├── requests-outbound.data
│ ├── chr_VUnVuVnITu.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ ├── chr_nITuVUnVuV.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ └──
└──
```
## BSR Session folder
A BSR session folder contains the following files:
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
- `bsrKey.pub` is the public ed25519 key.
- `pubKeySelfSignature.sign` is a self-signature of the plaintext public ed25519 key created with its private key.
- `pubKeyBsrSignature.sign` is a signature of the plaintext public ed25519 key created with the BSR key.
- `wrappedBsrKey` is the BSR key wrapped by the external KMS AES-GCM key that you configure.
- `wrappedPrivKey` is the private ed25519 key wrapped by the external KMS AES-GCM key that you configure.
- `session-meta.json` is a JSON file that contains metadata about the session, including the session id, endpoint,
user, target, host, worker, and credentials used to access the target. The intention of this file is to provide all information
relevant to the recorded session so that the BSR provides a complete snapshot of a session even in the absence of the Boundary
control plane.
- `session-recording.meta` is a plaintext file that contains metadata about the session, including the session id, protocol,
and a connection ids. For each connection id listed, there should be a corresponding connection directory in the session directory.
- `session-recording-summary.json` is a JSON file that contains a summary of the session recording, including the session id, connection count,
start time, end time, and any errors encountered during recording of the session.
`session-recording.meta` file example:
```
id: sr_iNCdGSREeX
protocol: BSSH
connection: cr_3bB78W53Y9.connection
```
`session-recording-summary.json` file example:
```
{
"Id": "sr_iNCdGSREeX",
"ConnectionCount": 1,
"StartTime": "2023-09-19T15:05:39.343307163Z",
"EndTime": "2023-09-19T15:08:02.953159598Z",
"Errors": ""
}
```
`session-meta.json` file example:
```
{
"PublicId": "s_HQbVb8fJaM",
"Endpoint": "ssh://openssh-server:2222",
"User": {
"PublicId": "u_5Ry4oDiEVp",
"Scope": {
"PublicId": "global",
"Name": "global",
"Description": "Global Scope",
"Type": "global",
"ParentId": "",
"PrimaryAuthMethodId": "ampw_CdIa5KR9iw"
},
"Name": "admin",
"Description": "Initial admin user within the \"global\" scope"
},
"Target": {
"PublicId": "tssh_TIx4ENZMdA",
"Scope": {
"PublicId": "p_7Qe46uNMYX",
"Name": "session-recording-project",
"Description": "",
"Type": "project",
"ParentId": "o_yK7GoA6OG2",
"PrimaryAuthMethodId": ""
},
"Name": "session-recording-target",
"Description": "",
"DefaultPort": 2222,
"DefaultClientPort": 0,
"SessionMaxSeconds": 28800,
"SessionConnectionLimit": -1,
"WorkerFilter": "",
"EgressWorkerFilter": "",
"IngressWorkerFilter": "\"pki\" in \"/tags/type\"",
"EnableSessionRecording": true,
"StorageBucketId": "sb_vqn871JdQf"
},
"Worker": {
"PublicId": "w_ogOQt0rsuQ",
"Version": "0.13.0",
"Sha": ""
},
"StaticHost": null,
"DynamicHost": null,
"StaticJSONCredentials": null,
"StaticUsernamePasswordCredentials": [
{
"PublicId": "credup_gdzeB5UWJv",
"Name": "",
"Description": "",
"Username": "username",
"PasswordHmac": "PasswordHmac,
"Purposes": [
"injected_application"
],
"CredentialStore": {
"PublicId": "csst_agwIT97uZ7",
"ProjectId": "p_7Qe46uNMYX",
"Name": "ssh static store",
"Description": "SSH Static Cred store"
}
}
],
"StaticSshPrivateKeyCredentials": null,
"VaultGenericLibraries": null,
"VaultSshCertificateLibraries": null
}
```
## BSR Connection folder
A BSR connection folder contains the following files:
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
- `connection-recording.meta` is a plaintext file that contains metadata about the connection, including the connection id,
requests seen, channel ids, and any errors seen. For each channel id listed, there should be a corresponding channel directory in the connection directory.
- `connection-recording-summary.json` is a JSON file that contains a summary of the connection, including the connection id,
start time, end time, bytes up, bytes down, and any errors encountered during recording the connection.
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the connection.
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the connection.
`connection-recording.meta` file example:
```
id: cr_W53Y93bB78
requests: outbound
requests: inbound
channel: chr_uVVuUITnVn.channel
error: error message would be appear here
```
`connection-recording-summary.json` file example:
```
{
"Id": "cr_W53Y93bB78",
"ChannelCount": 1,
"StartTime": "2023-07-13T20:21:49.164105381Z",
"EndTime": "2023-07-13T20:22:37.241911112Z",
"BytesUp": 125,
"BytesDown": 748,
"Errors": null
}
```
### BSR Channel folder
A BSR connection folder contains the following files:
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
- `channel-recording.meta` is a plaintext file that contains metadata about the channel, including the channel id,
inbound and outbound requests seen, and inbound and outbound messages seen.
- `channel-recording-summary.json` is a JSON file that contains a summary of the channel, including the channel id,
start time, end time, bytes up, bytes down, channel type, session program, subsystem name (if applicable), exec program (if applicable),
and file transfer direction (if applicable).
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the channel.
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the channel.
- `messages-inbound.data` is a binary file containing all inbound SSH data transmitted for the channel.
- `messages-outbound.data` is a binary file containing all outbound SSH data transmitted for the channel.
`channel-recording.meta` file example:
```
id: chr_uVVuUITnVn
channelType: session
messages: outbound
requests: outbound
messages: inbound
requests: inbound
```
`channel-recording-summary.json` file example:
```
{
"ChannelSummary": {
"Id": "chr_uVVuUITnVn",
"ConnectionRecordingId": "cr_W53Y93bB78",
"StartTime": "2023-07-13T20:21:49.230916214Z",
"EndTime": "2023-07-13T20:22:37.229379944Z",
"BytesUp": 125,
"BytesDown": 748,
"ChannelType": "session"
},
"SessionProgram": "shell",
"SubsystemName": "",
"ExecProgram": "",
"FileTransferDirection": "not applicable"
}
```
For more information, refer to the [overview of session recording](/boundary/docs/session-recording).
Reference in new issue View Git Blame Copy Permalink