wpscanteam/wpscan · error · WPScan::Error::BrowserFailed

--expect-saml requires Chrome or Chromium to be installed an

Error message

--expect-saml requires Chrome or Chromium to be installed and available on PATH (install Chrome / Chromium, or point Ferrum at a binary via BROWSER_PATH). Underlying error: #{error.message}

What it means

WPScan::Error::BrowserFailed raised in run_login_session (lib/wpscan/browser_authenticator.rb:39-40) when Ferrum raises BinaryNotFoundError or EmptyPathError while constructing Ferrum::Browser.new(headless: false). Ferrum locates a Chrome/Chromium binary by scanning PATH (or the BROWSER_PATH env var); --expect-saml cannot work without one, and the message includes the underlying Ferrum error for details.

Source

Thrown at lib/wpscan/browser_authenticator.rb:40

      serialize_cookies(cookies)
    end

    # Drives the interactive browser session and returns the resulting cookie jar.
    # Translates Ferrum failures into BrowserFailed with a context-specific message.
    def self.run_login_session(login_url)
      browser = Ferrum::Browser.new(headless: false)

      puts 'SAML authentication needed. Log in via the browser window that just opened, then press enter.'
      browser.goto(login_url)
      gets # Waits for user input

      # Attempt an innocuous command to check if the browser is still responsive
      browser.current_url

      browser.cookies.all
    rescue Ferrum::BinaryNotFoundError, Ferrum::EmptyPathError => e
      raise WPScan::Error::BrowserFailed, chrome_not_found_message(e)
    rescue Ferrum::Error => e
      raise WPScan::Error::BrowserFailed,
            'The browser was closed or failed before SAML authentication could be completed ' \
            "(#{e.class}: #{e.message})."
    ensure
      browser.quit if browser&.process
    end

    def self.chrome_not_found_message(error)
      '--expect-saml requires Chrome or Chromium to be installed and available on PATH ' \
        '(install Chrome / Chromium, or point Ferrum at a binary via BROWSER_PATH). ' \
        "Underlying error: #{error.message}"
    end

    def self.serialize_cookies(cookies)
      cookies.map do |_name, cookie|
        raise WPScan::Error::SAMLAuthenticationFailed if cookie.name.match?(COOKIE_DELIMITERS) ||
                                                         cookie.value.to_s.match?(COOKIE_DELIMITERS)

View on GitHub (pinned to 62c9cef471)

Solutions

1. Install Chrome or Chromium, e.g. apt-get install -y chromium || apt-get install -y google-chrome-stable
2. Or point Ferrum at the binary explicitly: export BROWSER_PATH=/usr/bin/chromium (macOS: export BROWSER_PATH='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
3. Verify with: $BROWSER_PATH --version or command -v google-chrome chromium chromium-browser
4. In Docker, install the browser in the same image the scan runs in, not just on the host

Example fix

# before
$ wpscan --url https://example.com --expect-saml
# => BrowserFailed: --expect-saml requires Chrome or Chromium ... Underlying error: Could not find an executable for the browser

# after
$ export BROWSER_PATH=$(command -v chromium || command -v google-chrome)
$ wpscan --url https://example.com --expect-saml

# Fail fast with a clear message before the scan starts
require 'mkmf'
browser_bin = ENV['BROWSER_PATH'] || %w[google-chrome chromium chromium-browser chrome].find do |b|
  find_executable(b)
end
abort 'Chrome/Chromium not found: install it or set BROWSER_PATH' if browser_bin.nil?

begin
  WPScan::BrowserAuthenticator.run_login_session(login_url)
rescue WPScan::Error::BrowserFailed => e
  # message from chrome_not_found_message includes the underlying Ferrum error;
  # not retryable until the environment changes
  abort e.message
end

When it happens

Trigger: Running wpscan --expect-saml on a server/container/minimal VM with no Chrome or Chromium installed; BROWSER_PATH set to a wrong or non-executable path; Chrome installed via snap/flatpak whose wrapper is not on the PATH wpscan sees; calling WPScan::BrowserAuthenticator.run_login_session programmatically on a bare CI image.

Common situations: Alpine/Debian slim Docker images (no browser bundled); macOS where Chrome exists at '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' but Ferrum's search order misses it; hardened servers where chrome was removed; stale BROWSER_PATH from a previous chrome-chromium setup.

Related errors

• The browser was closed or failed before SAML authentication
• SAML authentication is required to access this resource. Ple
• SAML authentication needs an interactive terminal to wait fo
• The option #{opt.to_long} is required
• One of the following options is required: #{opt.to_long}, --

AI-assisted analysis of wpscanteam/wpscan@62c9cef471 (2026-08-21). Data as JSON: /api/errors/f1e1e4170e6d4717. Report an issue: GitHub.