Recording Browser Session

Record Browser Sessions and help Pentest Copilot understand more about the domain.

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.

Video walkthrough: Record a browser session

Learn about Window Controls while Recording Browser Session.

Step 1: Prepare the Browser Session

Open the Browser Session Manager for the target domain before starting the recorder.

1. Confirm the correct target domain is selected. If the product asks for domain ownership verification, complete verification before recording.

2. Choose whether to create or update a session:

   • Create New Session records a new role or account state.

   • Re-record updates an existing browser session in place, keeping the same session identity for scans and findings.

3. Select an Email identity if the login flow uses email OTPs or magic links. Select None when you are using a customer-managed account, an existing long-lived session, or an inbox that Pentest Copilot should not poll.

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

5. Tags: Add labels to categorise and filter sessions later. At least one tag is required before recording.

   • Examples: "admin", "read-only", "finance-team", "hr-manager".

6. Optional settings:

   • Authentication Verification Regex: Text or a regex that should be visible only when the session is authenticated, such as Dashboard or Welcome\s+Jane.

   • Starting URL: Open the recorder directly on the login page or tenant-specific start path.

   • Use Residential IP for browser traffic: Use this for bot-sensitive login pages. It may be slower.

Once configured, proceed to start the recording.

Step 2: Start Recording

1. Click Start Recording.

   • A proxied browser window opens automatically.

   • If the browser window does not open, copy the Proxied noVNC URL shown in the active recording card and open it in your browser.

     

The browser window is now active. You can begin exploring unauthenticated (pre-authentication) features.

Note: Please wait for page to be loaded and elements to be highlighted before proceeding

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.
Refresh	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 VNC browser toolbar includes an Auth Actions dropdown for dealing with OTPs, magic links, authenticator apps, and OCR image captchas.

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 assigned identity selected for this session
Email Magic Link	Red	Target sent a sign-in link to the assigned identity selected for this session
Phone OTP	Purple	Target sent a text-message code for the phone number used in the recording flow
OCR Captcha	Blue	Target shows a captcha image and a textbox where the answer must be entered

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 mail for the selected identity, extracts the code, and types it.
Email Magic Link	No popup and no click needed. The platform fetches mail for the selected identity, extracts the link, and navigates directly to it.
Phone OTP	Use this when the target sends a text-message code. SMS handling happens through the product flow; messages are not directly forwarded for you to monitor separately.
OCR Captcha	Status bar first asks you to click the captcha image, then asks you to click the captcha input. The platform solves the image text and fills the input.

Popup for TOTP secret input

Where identities come from

Email OTPs and magic links are tied to the assigned identity selected in the recording form. Later scans poll only that exact inbox, so use one of the identities shown in the product rather than inventing a new plus-address suffix.

Phone OTPs are handled through Auth Actions in the VNC browser flow. SMS messages are not directly forwarded for separate monitoring.

For more info how this works refer to:

Handling Captcha/Email/Mobile OTPs

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: Record representative pages and buttons. You do not need to click every route in the application.

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., [e-mail]).

     • 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 the browser state needed for replay. 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.