> For the complete documentation index, see [llms.txt](https://copilot-docs.bugbase.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/recording-browser-session.md).

# Recording a Browser Session

Record and manage an authenticated browser session.

A browser session stores login actions and browser state so web assessments can test an authenticated account. Record separate sessions for roles whose permissions should be assessed independently.

## Open Browser Session Manager

1. Open **Web Assessment -> Run Assessment**.
2. Choose an intent and continue to **Scope**.
3. Select the target asset and enable **Authenticated** coverage.
4. Select **Record new session**.

Browser Session Manager shows recording, validation, and failure status for sessions associated with that target.

## 1. Describe the Account

Choose an email identity when the login uses a monitored email OTP or magic link. Choose **None** for a customer-managed account, long-lived session, or inbox that Pentest Copilot should not poll.

Provide:

* **Session Context**: the account's role, permissions, plan, tenant, or other facts needed to distinguish it;
* **Tags**: short labels such as `admin`, `read-only`, or `billing`.

Good context is specific: “Workspace administrator who can manage users and reports” is more useful than “logged-in user.”

## 2. Choose Where the Browser Runs

Choose sandbox or residential egress and the required location. Recording, validation, and assessment should use compatible egress. Sites that restrict traffic by IP or country can reject a valid session when later validation uses a different route.

## 3. Choose Where Recording Starts

**Open recorder at** is optional. Enter a login URL when it is not easy to reach from the domain root.

The scan starting page and authentication verification page are captured inside the recorder. After recording, review them under **Captured scan pages**.

<figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2Fgit-blob-09525c6a4a2d38bbdde0935bff41e86b683d7168%2Fbrowser-session-manager-recording-start.jpg?alt=media" alt="Browser Session Manager egress and optional recorder start settings"><figcaption><p>Use the same egress for recording, validation, and scanning when the target restricts source location.</p></figcaption></figure>

## 4. Record the Login

Select **Start Recording**. The proxied browser opens in a new tab when the sandbox is ready. If your browser blocks the tab, use the **Proxied noVNC URL** shown in Browser Session Manager.

1. Navigate to the login page.
2. Select **Start Auth** immediately before the first authentication action.
3. Complete the login one step at a time.
4. After dynamic fields or screens appear, select **Refresh** so the recorder rescans the DOM and highlights the new actionable elements.
5. On a page that is visible only when logged in, select **Set Verify URL**.
6. Select **Stop Auth**.
7. Optionally open the page where authenticated scanning should begin and select **Set Starting URL**.
8. Select **Done** and wait for the recording to finish saving.

Complete the recording within the time shown in Browser Session Manager (at most 30 minutes from its start). This is a fixed session limit: activity does not extend it. When the limit is reached, the recording and its sandbox submodule stop.

### What Refresh Does

**Refresh** does not reload the website. It refreshes the recorder's element map and highlights. Use it after a login step changes the current page without a full navigation—for example, when a password or OTP field appears dynamically.

### Paste Text into the Proxied Browser

Copy text on your computer, focus the proxied browser, and paste normally. The noVNC clipboard bridge sends plain text to the remote browser. If your browser blocks clipboard access, open the noVNC clipboard panel and paste there, or use the recorder's input and authentication helpers. Check the remote field before continuing with a login.

### Close or Reopen an Active Recording

The VNC tab shows **End recording**. It asks for confirmation before ending the VNC session and its submodule. Closing or navigating away from the tab may show your browser's leave-page confirmation. Choose **Stay** to keep recording; confirmed closure ends the recording and can discard unsaved actions. You can also use **Cancel recording** in Browser Session Manager.

Closing Browser Session Manager alone does not end an active VNC tab. Reopen the manager for the same target to see the active recording and its remaining time. If the VNC tab is missing, copy the **Proxied noVNC URL** from the active recording card and open it in a new tab. Do this before starting another recording for the target.

## Authentication Helpers

The **Auth Actions** menu supports:

| Action               | Use                                                                               |
| -------------------- | --------------------------------------------------------------------------------- |
| **TOTP**             | Generate a code from a supplied Base32 secret and fill the selected OTP field.    |
| **Email OTP**        | Poll the selected email identity and fill the extracted code.                     |
| **Email Magic Link** | Poll the selected identity and navigate to the extracted sign-in link.            |
| **Phone OTP**        | Use the configured SMS flow for the account.                                      |
| **OCR Captcha**      | Select the captcha image and destination input for supported image-text captchas. |

{% content-ref url="/pages/TZ5SP2OUJviyjLgpvBqw" %}
[Handling CAPTCHA and OTP Challenges](/enterprise/how-to-trigger-a-web-assessment/handling-captcha-email-mobile-otps.md)
{% endcontent-ref %}

## Review and Validate

After saving:

1. Review **Captured scan pages** and correct the scan or verification page if needed.
2. Confirm the verification expression identifies authenticated content rather than a public page.
3. Select **Validate Session**.
4. Use the session in an authenticated assessment only when validation is ready.

{% content-ref url="/pages/qlsZUTSSIvcyvgbeitK1" %}
[Validating Browser Sessions](/enterprise/how-to-trigger-a-web-assessment/validating-browser-sessions.md)
{% endcontent-ref %}

## Re-record or Delete

* **Re-record** updates an existing session while retaining its identity for linked configurations.
* **Delete** removes a session that is failed, obsolete, or no longer authorized. Check whether saved schedules still reference it.

If recording fails, review the visible error before starting another attempt:

* **Sandbox paused because host memory is high:** wait for the sandbox to recover or ask an operator to free capacity, then retry.
* **Sandbox VNC service unavailable:** ask an operator to check the sandbox's noVNC service and private network route. A live VNC tab offers **Retry connection** or **End recording**; ending it releases the submodule.
* **Recording ended:** the session was completed, cancelled, or expired. Close the old tab and start a new recording if needed.

The proxied URL uses your Pentest Copilot session and is scoped to the recording owner. Do not share it as a way to grant access to the sandbox.

## What Is Stored

A session can include login actions, cookies, local/session/cache storage, IndexedDB, WebAuthn data, captured pages, authentication criteria, page hashes, email-identity metadata, context, and tags. Treat exported session JSON as sensitive authentication material.