> 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-an-external-scan/recording-browser-session.md).

# Recording Browser Session

Record and manage an authenticated browser session.

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

## Open Browser Session Manager

1. Open **External 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-d854b7d86c48153ad6c43f40a7add7a52209bc29%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** and wait for the proxied browser to become ready.

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.

### 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.

### Clipboard Limitation

The proxied browser does not reliably share your local system clipboard. Type credentials in the proxied browser or use the recorder's supported input and authentication helpers. Do not assume that a normal local copy/paste action reached the remote browser.

## 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/Email/Mobile OTPs](/enterprise/how-to-trigger-an-external-scan/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-an-external-scan/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, close any abandoned proxied browser, then re-record or delete the failed session before continuing.

## 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.