# Recording Browser Session
The Record Browser Session feature enables users to capture interactive browser sessions on a configured sandbox agent. This allows Pentest Copilot to gain a deeper understanding of a target website's structure, user flows, and behaviours. By manually navigating the site, you can simulate specific user roles and permissions, record the session for later replay, and provide Pentest Copilot with the ability to impersonate authenticated users.
{% hint style="info" %}
Learn about [Window Controls](#browser-window-controls) while Recording Browser Session.
{% endhint %}
### Step 1: Configure Session Details
Before starting, define the session context and assign tags to the Browser Session.
1. **Session Context**: Provide a clear description of the user role, permissions, and intended functionalities. This metadata helps Pentest Copilot interpret the browser session's scope.
* **Example**: "Admin user with full access to user management, settings, and reports."
2. **Tags**: Add optional labels to categorise and filter sessions later.
* **Examples**: "admin", "read-only", "finance-team", "hr-manager".
Once configured, proceed to start the recording.
### Step 2: Start Recording
1. Click **Start Record**.
* A NoVNC URL and temporary password will be generated and displayed.
* Open the NoVNC URL in your local browser and enter the password to access the remote browser window on the sandbox agent.
The browser window is now active. You can begin exploring unauthenticated (pre-authentication) features.
{% hint style="info" %}
**Note:** Please wait for page to be loaded and elements to be highlighted before proceeding
{% endhint %}
#### Understanding Record Session Toolbar:
The record session toolbar is identified by the **SESSION** tag present at the start of the toolbar.
| Button | Function |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Set Start URL** | Sets the currently open page as the Start URL. This URL will be used as the entry point when a scan is triggered using this recorded session. |
| **Set Verify URL** | Sets the currently open page as the Verification URL. This URL is used to determine whether the session is successfully authenticated. |
| **Start Auth** | Marks the beginning of the authentication flow. All actions performed after clicking this button are recorded as Authentication Steps. Once activated, this button automatically changes to Stop Auth. |
| **Stop Auth** | Marks the end of the authentication flow. All actions recorded between Start Auth and Stop Auth are used to regenerate an authenticated session. Any actions performed after this point are marked as Post-Authentication steps. |
| **Refesh** | Re-applies page highlighting if elements are not properly detected or highlighted during recording. |
| **Done** | Finalizes the recording process and saves the recorded session. |
### Handling auth challenges during recording
The recording toolbar includes an **Auth helper** dropdown for dealing with OTPs, magic links, and authenticator apps. Click it to reveal four options.
#### Auth helper toolbar
| Button | Color | When to use |
| -------------------- | ------ | ---------------------------------------------------------------- |
| **TOTP** | Indigo | Target shows a QR code or Base32 secret for an authenticator app |
| **Email OTP** | Green | Target sent a 6-digit code to the monitored inbox |
| **Email Magic Link** | Red | Target sent a sign-in link to the monitored inbox |
| **Phone OTP** | Purple | Target sent a 6-digit code to the monitored phone |
#### How each button works
| Button | What happens when you click it |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TOTP** | A popup asks for the Base32 secret. Paste it, click OK. Then click the OTP input field on the page. The platform types the current 6-digit code. |
| **Email OTP** | No popup. Status bar shows "Email OTP ready". Click the OTP input field. The platform fetches the latest verification email, extracts the code, and types it. |
| **Email Magic Link** | No popup and no click needed. The platform fetches the latest verification email, extracts the link, and navigates directly to it. |
| **Phone OTP** | A popup asks you to type the 6-digit code from the SMS. Paste it, click OK. Then click the OTP input field on the page. |
Popup for TOTP secret input
#### Where the email and phone come from
The monitored email and phone used for Email OTP, Magic Link, and Phone OTP are shown as copyable chips in the info notice at the top of the recording form. Use those exact values on the target app when it asks for an email or phone number.
For more info how this works refer to:
{% 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 %}
### Step 3: Explore Pre-Authentication Features
* Navigate freely through the website: Click buttons, fill forms, and visit different pages.
* All interactions are automatically categorized as pre-authentication data, building Pentest Copilot's baseline understanding of the site's public-facing elements.
* **Important**: You may only click on a few pages/buttons, no need to be exhaustive about this
### Step 4: Record Authentication and Post-Authentication Flows
Authentication is a critical phase, as it transitions the session from public to privileged access. Follow these steps to ensure accurate capture:
1. Navigate to the login page.
2. Click **Start Auth** in the recording interface.
* This flags the start of the login process, allowing Pentest Copilot to distinguish authentication steps from general navigation.
3. Perform login actions:
* Perform the browser actions that record the browser session.
* Example (On the OWASP Juice Shop login page):
* Click the email field
* Paste credentials (e.g., ).
* Click the password field
* Paste the credentials (e.g., admin123).
* Click the **Login** button.
* **Note**: Actions are recorded in real-time, including any multi-step verification. Make sure to wait till the status button turns green after every action.
4. Once authenticated, click **Stop Auth**
* This finalises the browser session recording, stores the final browser session.
5. Explore post-authentication features:
* Test role-specific functionalities (e.g., admin dashboard in Juice Shop).
* Continue navigating to capture permission-based behaviors.
6. **Lastly, configure an Authentication Verification URL.** This URL is used to verify whether the recorded session is authenticated. During scanning, the system will visit this page to confirm the authentication state.
If needed, use **Set Start URL** to set the starting URL from where the scan will initiate.
### What Gets Recorded
Each session captures a comprehensive snapshot to enable reliable regeneration by Pentest Copilot. Recorded elements include:
* **Cookies**: All authentication and session cookies for maintaining logged-in state.
* **Local Storage**: Persistent browser data (e.g., user preferences).
* **Session Storage**: Temporary data tied to the current session.
* **Cache Storage**: Pre-loaded resources to speed up replays.
* **Indexed DB**: Client-side database entries.
* **Browser Actions**: Sequence of interactions (clicks, keystrokes, form submissions) for step-by-step reproduction.
* **Authentication Verification URL:** Page to visit to confirm/verify authentication
* **Authentication Verification Regex:** A regex match is run against the authentication verification URL - if the matched, user is authenticated.
* **Page Hashes**: Visual and content checksum to validate session stability and detect changes.
---
# Agent Instructions: 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:
```
GET https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-an-external-scan/recording-browser-session.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.