BastionGuard-bankopener (Secure Browser Launcher)

1. Overview

BastionGuard-bankopener is a standalone launcher executable that acts as the controlled entry point for BastionGuard’s Secure Browser (CEF-based sandbox). Its purpose is to:

  • Accept a user-provided URL as a command-line argument
  • Determine whether the URL belongs to a trusted banking/payment allowlist
  • Launch the URL inside the hardened CEF SecureBrowser when trusted
  • Otherwise fall back to opening the URL in the system browser (gio open / xdg-open)
  • Handle CEF multi-process requirements by executing subprocess roles and exiting appropriately
  • Auto-select display backend (Wayland/X11) and apply GPU stability settings

This executable is typically spawned by UI components (e.g., Secure Payments/Bank GUI) through Gio::Subprocess or equivalent, making it a clean separation point between the GUI process and the CEF browsing process.

2. Process Model (CEF Multi-process Handling)

CEF uses a multi-process architecture and requires an early check to determine whether the current process instance is a CEF child/subprocess. This is handled by:

CefMainArgs cef_args(argc, argv);
int rc = CefExecuteProcess(cef_args, nullptr, nullptr);
if (rc >= 0)
    return rc;

Behavior:

  • If rc >= 0, the executable is running as a CEF subprocess role (renderer/GPU/etc.) and must exit immediately with rc.
  • If rc < 0, the process is the main browser process and continues normal execution.

This ensures correct CEF runtime behavior and prevents accidental double-initialization.

3. Command-line Interface

Usage:

BastionGuard-bankopener <url>

If fewer than two arguments are provided (argc < 2), the program prints a localized usage string and exits with code 2.

4. Display Backend Auto-selection (Wayland / X11)

Before launching CEF, the launcher auto-detects the desktop session type by inspecting environment variables:

  • WAYLAND_DISPLAY – indicates Wayland session availability
  • DISPLAY – indicates X11 session availability

Selection policy:

  • Wayland present: set GDK_BACKEND=wayland and OZONE_PLATFORM=wayland
  • X11 present: set GDK_BACKEND=x11 and OZONE_PLATFORM=x11
  • No GUI detected: force X11 and enable software rendering (LIBGL_ALWAYS_SOFTWARE=1)

This backend selection aims to improve compatibility across Linux desktops and reduce launch failures in mixed environments.

5. GPU Stability Configuration

To reduce the likelihood of GPU/driver-related crashes in hardened browsing sessions, the launcher forces software rendering:

setenv("LIBGL_ALWAYS_SOFTWARE", "1", 1);

This setting is applied unconditionally after backend selection, prioritizing stability and predictability over hardware acceleration.

6. Trusted-domain Routing Logic

6.1 Trust Gate

The launcher delegates domain trust evaluation to:

BankOpener::open_if_trusted(url)

Expected behavior of this helper (by contract):

  • If the URL is trusted (bank/payment allowlist), it opens the URL via SecureBrowser::open(url, argc, argv) internally and returns true.
  • If not trusted, it returns false and no secure browser is launched.

When trusted, the launcher exits with status 0 after delegating to SecureBrowser.

6.2 Fallback to System Browser

If the URL is not trusted, the launcher falls back to opening the URL in the system browser. To maximize compatibility, it prefers gio if present:

  • If gio exists: gio open "<url>"
  • Otherwise: xdg-open "<url>"

Execution uses std::system(). The return code is propagated as the program’s exit status, and failures are logged.

7. Logging and Localization

The launcher prints diagnostic messages to standard output/error and uses gettext localization through <glibmm/i18n.h>. This keeps the CLI diagnostics consistent with BastionGuard’s localization model.

8. Security and Operational Considerations

  • Trust boundary: this executable is a routing gate. Correctness of open_if_trusted() and allowlist hygiene directly impacts security posture.
  • Environment control: setting GDK_BACKEND, OZONE_PLATFORM, and LIBGL_ALWAYS_SOFTWARE influences the runtime and should remain scoped to this process to avoid side effects on the parent application.
  • Shell execution: fallback uses shell command execution. The URL is quoted, but callers should still ensure input is treated as untrusted data at higher levels.
  • Stability over performance: forcing software rendering reduces crash risk but may reduce performance; this is a deliberate trade-off for secure browsing contexts.
  • CEF subprocess correctness: early CefExecuteProcess handling is mandatory; removing it can break CEF multi-process behavior.

In summary, BastionGuard-bankopener is the hardened, CEF-aware launcher that routes URLs into the SecureBrowser only when allowlisted, while providing robust desktop backend selection and safe fallback behavior for all other URLs.

Published on:
Last updated on: