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

<figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2FuM4ca4vRAktZwKj10hZX%2Fimage.png?alt=media&#x26;token=a06f17b7-fa2d-4a4b-878b-dc0665bc22d9" alt=""><figcaption></figcaption></figure>

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

   <figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2Fqv9jCYNDqGGt57P61sAP%2FScreenshot%202026-01-04%20at%205.45.46%E2%80%AFPM.jpeg?alt=media&#x26;token=13b5e6c0-d5b5-49da-9160-d27971ebe34e" alt=""><figcaption></figcaption></figure>

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 %}

<figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2FfzXR3MCpajT7WKOcPlzj%2Fimage.png?alt=media&#x26;token=506c7c0b-a474-4b84-84c1-80655951c9a6" alt=""><figcaption></figcaption></figure>

#### Understanding Record Session Toolbar:

<figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2FuC7embYC5Y9EtMfVk70y%2Fimage.png?alt=media&#x26;token=228729e8-5c4d-47e6-920e-41a7612d9315" alt=""><figcaption></figcaption></figure>

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

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

   <figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2FBEQMrvprIiYSNEIpAOCv%2Fimage.png?alt=media&#x26;token=9697051e-0807-413d-938f-95166b41ff9c" alt=""><figcaption></figcaption></figure>
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., <admin@juice-sh.op>).
     * 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.

   <figure><img src="https://232193438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwolEZzMm5QD9NoFKutSj%2Fuploads%2FjyIOdPSHzGLWjrFgn8py%2Fimage.png?alt=media&#x26;token=4f1fd093-32a3-4a35-ab85-b74d5cf6b058" alt=""><figcaption></figcaption></figure>
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
* **Page Hashes**: Visual and content checksum to validate session stability and detect changes.