> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/data-exfiltration-prevention/exfiltration_endpoint/policies/advanced_settings/automated_action/session-replay-and-bring-your-own-bucket.md). # Session Replay and Bring Your Own Bucket Capture screen recordings around endpoint exfiltration events and store them in your own cloud bucket. Session Replay (shown in the console as **Record Before & After**) captures the user's screen around an endpoint exfiltration event so investigators can review what happened. You can store those recordings in a cloud bucket that your organization owns. This capability is available for **macOS** and **Windows** endpoint policies. ## How it works 1. Enable Session Replay for your organization in Endpoint settings. 2. Connect a storage bucket (or use Nightfall-managed storage, if it is enabled for your account). 3. Turn on **Record Before & After** on each endpoint exfiltration policy that should capture recordings, and choose the storage destination. 4. When that policy detects an exfiltration event, Nightfall records the screen for a window before and after the event and writes the recording to the selected bucket. 5. Open the event in Nightfall to play the recording. If an event matches more than one policy with recording enabled, Nightfall can write the recording to each policy's selected bucket. ```mermaid flowchart LR A[Enable Session Replay] --> B[Connect a storage bucket] B --> C[Turn on Record Before and After on the policy] C --> D[Exfiltration event occurs] D --> E[Recording is stored in your bucket] E --> F[Play the recording from the event] ``` ## What is supported | Area | Support | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Platforms | macOS and Windows | | Policies | Endpoint exfiltration policies | | Triggers | Any endpoint trigger that produces an exfiltration event, including browser uploads, clipboard paste, desktop apps, cloud sync, removable media, print, and Git push | | Enforcement | Works with monitor, warn, and block policies | | Storage | Amazon S3, Google Cloud Storage, and Azure Blob Storage | | Nightfall-managed storage | Available when Nightfall has enabled it for your account | | Displays | Multiple monitors | | Playback | Exfiltration event **Replay** view, including timeline controls and event markers | On macOS, the Nightfall agent requires **Screen Recording** permission to capture recordings. ## What is stored in your bucket Your bucket stores the **session recordings** captured around matching exfiltration events. Nightfall writes a recording when a policy with **Record Before & After** enabled is triggered. The recording covers the configured window before and after the event. {% hint style="info" %} Keep recordings in the bucket for at least **180 days**. If a lifecycle rule deletes objects sooner, investigators may not be able to play older events. {% endhint %} Nightfall recommends enabling encryption on the bucket (for example, AWS SSE-KMS, Google CMEK, or Azure customer-managed keys). Encryption is a best practice and is not required to connect the bucket. ## Requirements * The Nightfall endpoint agent is installed and connected on the device. * Session Replay is enabled in **Endpoint** → **Settings**. * A storage destination is available: a connected customer bucket, or Nightfall-managed storage if it is enabled for your account. * The Nightfall user who connects buckets has **bucket management** access. * The Nightfall user who plays recordings has **screen recording** access. * On macOS, Screen Recording permission is granted to the Nightfall agent. ## Enable Session Replay {% stepper %} {% step %} ### Turn on Session Replay for the organization 1. In Nightfall, open **Endpoint**. 2. Open the **Settings** tab. 3. Enable **Session Replay** / **Record Before & After**. 4. Review **Snapshot Frequency** (every 1–5 seconds) and the **Recording Window** shown for the time before and after an event. Snapshot frequency is configured at the organization level and applies to policies that have recording enabled. {% endstep %} {% step %} ### Connect a storage bucket 1. Go to **Settings** → **Storage Buckets**. 2. Click **Connect Bucket** (or use the command palette and search for **Connect Bucket**). 3. Choose **Amazon S3**, **Google Cloud Storage**, or **Azure Blob Storage**. 4. Complete the cloud setup for that provider, then enter the connection details in Nightfall. 5. Nightfall validates access (write, read, and delete) before saving the bucket. A successful connection may still show a **warning** if the bucket's lifecycle policy could remove recordings earlier than 180 days. You can continue and adjust the lifecycle policy in your cloud console. Bucket statuses: * **Active** — Nightfall can store recordings. * **Inactive** — Access failed a health check. Use **Reconnect** after you restore permissions. * **Disabled** — The destination is turned off for the account. You cannot delete a bucket that is still selected on a policy. Remove it from those policies first. {% endstep %} {% step %} ### Enable recording on the policy 1. Create or edit an endpoint exfiltration policy. 2. On the **Automated Actions** step, enable **Record Before & After**. 3. Under **Storage Destination**, select the bucket for this policy. 4. If Nightfall-managed storage is available, you can keep **Use Nightfall-managed storage (default)** selected instead of a customer bucket. 5. Save the policy. The policy toggle is available only after Session Replay is enabled for the organization. If no customer bucket is connected and Nightfall-managed storage is not available, connect a bucket before you save the policy. {% endstep %} {% step %} ### View a recording 1. Open **Exfiltration Prevention** and select an event. 2. On the event summary, click **Replay**. 3. Use the timeline to move through the recording. If the device has more than one display, switch between monitors in the player. If the recording is still arriving from the device, the player shows that screenshots are still uploading. Refresh the event after a few minutes. {% endstep %} {% endstepper %} ## Connect Amazon S3 Nightfall accesses the bucket with a cross-account IAM role. No long-lived access keys are stored. **What you enter in Nightfall** | Field | Description | | ------------ | --------------------------------------------------- | | Bucket name | Name of the S3 bucket | | IAM Role ARN | Role Nightfall assumes to access the bucket | | External ID | Filled automatically with your Nightfall Company ID | {% tabs %} {% tab title="IAM policy" %} Create an IAM policy that grants Nightfall access to the bucket. Replace `YOUR_BUCKET_NAME` and, if you use SSE-KMS, `YOUR_KMS_KEY_ARN`. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "S3Access", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:ListBucket", "s3:GetBucketLocation", "s3:GetLifecycleConfiguration" ], "Resource": [ "arn:aws:s3:::YOUR_BUCKET_NAME", "arn:aws:s3:::YOUR_BUCKET_NAME/*" ] }, { "Sid": "KMSAccess", "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt", "kms:DescribeKey" ], "Resource": "YOUR_KMS_KEY_ARN" } ] } ``` If the bucket does not use KMS, you can omit the `KMSAccess` statement. {% endtab %} {% tab title="IAM role" %} 1. In the AWS IAM console, create a role. 2. Trusted entity: **AWS account** → **Another AWS account**. 3. Account ID: `053737762392` (Nightfall). 4. Enable **Require external ID** and paste the External ID shown in Nightfall (your Company ID). 5. Attach the IAM policy from the previous tab. 6. Copy the role ARN into Nightfall and connect the bucket. {% endtab %} {% endtabs %} ## Connect Google Cloud Storage Nightfall accesses the bucket by impersonating a service account in your Google Cloud project. **What you enter in Nightfall** | Field | Description | | --------------------- | -------------------------------------- | | Bucket name | Name of the GCS bucket | | Service account email | Service account Nightfall impersonates | 1. Create a GCS bucket in your project. 2. Create a dedicated service account (for example, `nightfall-dlp-worker@YOUR_PROJECT.iam.gserviceaccount.com`). 3. Grant that service account **Storage Object Admin** and **Storage Legacy Bucket Reader** on the bucket. 4. Grant the service account permission to sign requests (`roles/iam.serviceAccountTokenCreator` on itself). 5. Allow Nightfall's hub service account to impersonate your service account: ```bash gcloud iam service-accounts add-iam-policy-binding YOUR_SERVICE_ACCOUNT_EMAIL \ --role="roles/iam.serviceAccountTokenCreator" \ --member="serviceAccount:saas-hub-operator@gcs-byod-prod.iam.gserviceaccount.com" ``` 6. If the bucket uses a customer-managed encryption key, grant the Cloud Storage service agent **Cloud KMS CryptoKey Encrypter/Decrypter** on that key. 7. Enter the bucket name and service account email in Nightfall and connect the bucket. ## Connect Azure Blob Storage Nightfall accesses the container with federated identity. No long-lived secrets are exchanged. **What you enter in Nightfall** | Field | Description | | ---------------------------------- | ------------------------------------------------------------------------- | | Storage account name | Azure storage account | | Container name | Blob container for recordings | | Tenant ID | Microsoft Entra tenant ID | | Client ID | Application (client) ID of the identity Nightfall uses | | Subscription ID and Resource group | Optional. Include these if you want Nightfall to check lifecycle policies | 1. Create a storage account and a container for recordings. 2. Create a managed identity or app registration and add a federated credential. Nightfall provides the OIDC issuer, audience, namespace, and service account values during setup. 3. Grant the identity **Storage Blob Data Contributor** and **Storage Blob Delegator** on the storage account. 4. Optionally grant **Reader** on the storage account so Nightfall can check lifecycle policies. 5. If you use customer-managed keys, grant **Key Vault Crypto Service Encryption User** on the key. 6. Enter the values in Nightfall and connect the bucket. ## Troubleshooting | Situation | What to check | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Record Before & After** is disabled on the policy | Enable Session Replay in **Endpoint** → **Settings**. | | Nightfall asks you to connect a bucket before saving | Connect a bucket in **Settings** → **Storage Buckets**, or select Nightfall-managed storage if it is available. | | Bucket is **Inactive** | Restore write, read, and delete access in your cloud account, then use **Reconnect**. Recordings may not store correctly while the bucket is inactive. | | macOS devices are not producing recordings | Confirm Screen Recording permission is granted to the Nightfall agent. | | Player says screenshots are still uploading | Wait for the post-event window to finish, then refresh the event. | | Player cannot load the recording | Confirm the bucket is Active and that lifecycle rules have not removed the recording. | | You cannot delete a bucket | Remove the bucket from every policy that uses it as the storage destination, then delete it. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.nightfall.ai/data-exfiltration-prevention/exfiltration_endpoint/policies/advanced_settings/automated_action/session-replay-and-bring-your-own-bucket.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.