selenium_tor 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99d3e4260b0873513c67db620d3057d61078b4c1cbae7b5c8c7b3e4cfdbbfbec
-  data.tar.gz: bb02cb9d07024a4798723185f4103246dac9b4c008e3f20abec5f710426a26a6
+  metadata.gz: fcf1656f54ce23992e788e76b1d6342157b6ba3996ec95f04c955a2857e9b2be
+  data.tar.gz: a9ef924f85fdd1370638ff3c12f9009ec1b2ab1b65b5a872bb8bd3d3e3e6e4f5
 SHA512:
-  metadata.gz: 654db110ca016a71d04b6def25d4befb86efc27cd2c0cce1ed7874834921d309262bc537b6b23bf8b77603b4d29960c88a10d83c8508ce6398b1d44a13577df1
-  data.tar.gz: 7d7369f8055ca42c229079d8732ab49d8d1467af49d35c547528dd792f1208101abcd123a6f05873b9fee4b704863a364708fc9148850f798635b9f3f6b3b8da
+  metadata.gz: 68018127837d8e59dd60647d9a0d60da4af363da8fad7104ac6ed52bf15844d7ead4d4cbc81f1b2403e64ad2fdda55f488ce725ca71b23c618686fb3ed5dbde3
+  data.tar.gz: 3a6bd3db60f2a9de62e232774edabb11e4ccd7bb6e48158c4b6709339f8c964e56f4817f78d471d8ae57a970fec25b325a76a4c3779a3ee67aee8bdc2ad5250f

data/.rubocop.yml

@@ -10,8 +10,9 @@ AllCops:
 Style/HashSyntax:
   Enabled: false  # yuk Ruby 3.1
 
-Layout/LineLength:
-  Max: 120
+Naming/MethodName:
+  Exclude:
+    - !ruby/regexp /test_.*\.rb$/ # for test_FOO constant tests
 
 Security/Eval:
   Exclude:
@@ -28,6 +29,9 @@ Style/RegexpLiteral:
 Minitest/TestMethodName:
   Enabled: true
 
+Minitest/AssertTruthy:
+  Enabled: false
+
 Minitest/TestFileName:
   Exclude:
     - test/features/fingerprinting/vglrun_test_fingerprintjs.rb

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## master (unreleased)
 
+## [1.3.0] - 2024-08-05
+
+### Bug fixes
+
+* [#14](https://gitlab.com/matzfan/selenium-tor/-/issues/14)
+
+### New features
+
+* add ability to get and set driver preferences dynamically
+* add Tor Browser alpha release to CI tests ([#12](https://gitlab.com/matzfan/selenium-tor/-/issues/12))
+
+## [1.2.0] - 2024-07-31
+
+### Bug fixes
+
+* [#11](https://gitlab.com/matzfan/selenium-tor/-/issues/11)
+
+### New features
+
+* add ability to change security level
+* add ability to get new circuit for page ([#10](https://gitlab.com/matzfan/selenium-tor/-/issues/10))
+
 ## [1.1.0] - 2024-07-28
 
 ### Bug fixes

data/README.md

@@ -17,6 +17,10 @@ The above approach will hide your IP, but there is a good chance your browser's
 
 ## Known issues
 
+Known issues are recorded [here](https://gitlab.com/matzfan/selenium-tor/-/issues).
+
+### Fingerprinting
+
 The gem uses Xvfb to allow Tor Browser to be manipulated headlessly. Xvfb in turn uses `llvmpipe` software acceleration which may lead to issues with WebGL fingerprinting - see [issue #7](https://gitlab.com/matzfan/selenium-tor/-/issues/7). If this is a problem we recommend using [VirtualGL](https://www.virtualgl.org) to force Xvfb to use your hardware driver instead. This is done by prepending your executable code with the command `vglrun`. For an example see the section below on testing. VirtualGL can be installed from a [package repo](https://virtualgl.org/Downloads/YUM). 
 
 ## Installation
@@ -41,7 +45,8 @@ options = Selenium::WebDriver::Tor::Options.new
 @driver = Selenium::WebDriver.for :tor, options: options
 
 @driver.get 'https://check.torproject.org'
-@driver.title # => Congratulations. This browser is configured to use Tor.
+@driver.title
+# => Congratulations. This browser is configured to use Tor.
 @driver.quit
 ```
 If the network is inaccessible for any reason a `TorNetworkError` will result.
@@ -52,28 +57,49 @@ Running multiple `tor` processes requires that each uses different ports for Soc
 ```ruby
 require 'parallel'
 
-socks_port = 9150
-control_port = 9151
+@socks_port = 9150
+@control_port = 9151
 
-def driver(socks_p, control_p)
-  options = Selenium::WebDriver::Tor::Options.new tor_opts: { socks_port: socks_p, control_port: control_p }
-  Selenium::WebDriver.for :tor, options: options # new tor process started with tor_opts
+def driver
+  @socks_port += 2
+  @control_port += 2
+  options = Selenium::WebDriver::Tor::Options.new tor_opts: { socks_port: @socks_port, control_port: @control_port }
+  Selenium::WebDriver.for :tor, options: options
 end
 
-driver1 = driver(socks_port, control_port)
-driver2 = driver(socks_port += 2, control_port += 2)
+@drivers = [driver, driver]
 
-title = 'Congratulations. This browser is configured to use Tor.'
-
-Parallel.all?([driver1, driver2], in_threads: 2) do |driver|
+Parallel.all?(@drivers, in_threads: @drivers.size) do |driver|
   driver.get 'https://check.torproject.org'
-  driver.title == title
 end
-# => true
 
-driver1&.quit
-driver2&.quit
+@drivers.each(&:quit)
 ```
+### Tor Browser specific functionality
+
+You can get and set the secuirty level (shield icon in TB) as follows. 4 is 'Standard', 2 is 'Safer', 1 is 'Safest'.
+```ruby
+@driver.security_level
+# => 4 - the default value
+@driver.security_level = 2
+@driver.security_level
+# => 2
+```
+You can get a new circuit for the current page ('New Tor circuit for this site' on TB's application menu):
+```ruby
+@driver.new_circuit_for_site # new circuit for the current page domain
+```
+### Miscellaneous
+
+You can get and set Driver preferences dynamically like this. Caveat emptor.
+```ruby
+@driver.pref['browser.download.dir']
+# => ""
+@driver.pref['browser.download.dir'] = 'home/user/Downloads'
+@driver.pref['browser.download.dir']
+# => "home/user/Downloads"
+```
+
 The `Selenium::WebDriver::Tor` namespace is used for `Driver`, `Options`, `Profile` and all tor-specific classes. Otherwise Selenium's `Selenium::WebDriver::Firefox` namespace is used.
 
 Remote functionality is not tested, but may be if a suitable Tor Browser Docker container becomes available.
@@ -92,6 +118,8 @@ Tor::TBB_VERSION # the version installed, e.g. "13.0.1", note: driver.capabiliti
 
 [Tor Browser](https://www.torproject.org/download).
 
+The shared libraries Tor Bowser requires will be available if you have Firefox or Firefox ESR installed on your system. If not, do `sudo apt install firefox-esr` or similar.
+
 As with Firefox browser, `geckodriver` needs to be installed and in your PATH.
 
 The gem needs to know the location of the Tor Browser Bundle (TBB). The Tor Browser download package archive must be extracted and the root TBB directory (named "tor-browser") placed somewhere on your system. By default it is assumed to be in the current user's HOME directory. An alternative location can be set via the env var `TOR_BROWSER_ROOT_DIR` - e.g. `export TOR_BROWSER_ROOT_DIR=/home/<user>/Downloads`. The Tor Browser binary location is *automatically set* by reference to this directory, so there is no need to do this:

data/lib/firefox_js_helpers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+module Selenium
+  module WebDriver
+    # namespace
+    module Firefox
+      # js helpers
+      module FirefoxJsHelpers
+        def execute_script_in_chrome_context(...)
+          in_chrome_context { execute_script(...) }
+        end
+
+        def es6_const_call(es6:, const:)
+          es6_import(es6) << "return m.#{const}"
+        end
+
+        def es6_function_call(es6:, func:, args:)
+          es6_import(es6) << "return m.#{es6}.#{func}('#{args}')"
+        end
+
+        private
+
+        def es6_import(es6)
+          "let m = ChromeUtils.importESModule('resource://gre/modules/#{es6}.sys.mjs');"
+        end
+
+        def in_chrome_context
+          raise(ArgumentError, "##{__method__} takes a block arg") unless block_given?
+
+          old_context = context
+          self.context = 'chrome'
+          yield
+        ensure
+          self.context = old_context if old_context
+        end
+      end
+      Firefox::Driver.prepend FirefoxJsHelpers
+    end
+  end
+end

data/lib/firefox_prefs.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative '../lib/firefox_js_helpers'
+
+module Selenium
+  module WebDriver
+    module Firefox
+      # representation of a firefox pref
+      class Preference
+        PREF_TYPES = { 'PREF_BOOL' => 128, 'PREF_INT' => 64, 'PREF_INVALID' => 0, 'PREF_STRING' => 32 }.freeze
+        GET_METHODS = { 0 => 'getStringPref', 32 => 'getStringPref', 64 => 'getIntPref', 128 => 'getBoolPref' }.freeze
+        SET_METHODS = { 32 => 'setStringPref', 64 => 'setIntPref', 128 => 'setBoolPref' }.freeze
+
+        def initialize(driver)
+          @driver = driver
+        end
+
+        def [](str)
+          @driver.execute_script_in_chrome_context script_string(str)
+        end
+
+        def []=(str, val)
+          @driver.execute_script_in_chrome_context script_string(str, val)
+        end
+
+        private
+
+        def script_string(str, val = nil)
+          val ? setter_script(str, val) : getter_script(str)
+        end
+
+        def getter_script(str)
+          type = pref_type(str)
+          "return Services.prefs.#{GET_METHODS[type]}('#{str}'#{default(type)})"
+        end
+
+        def default(type)
+          type.zero? ? ", ''" : '' # empty string default arg if pref not found, otherwise no default arg
+        end
+
+        def setter_script(str, val)
+          "Services.prefs.#{set_method(str, val)}('#{str}', #{quote_str(val)})"
+        end
+
+        def set_method(str, val)
+          type = pref_type(str)
+          return SET_METHODS[type] unless type.zero?
+          return 'setBoolPref' if val.instance_of?(TrueClass) || val.instance_of?(FalseClass)
+          return 'setIntPref' if val.is_a? Integer
+
+          'setStringPref' # everthing else gets set as a string
+        end
+
+        def pref_type(string)
+          @driver.execute_script_in_chrome_context("return Services.prefs.getPrefType('#{string}')")
+        end
+
+        def quote_str(value)
+          value.is_a?(String) ? "'#{value}'" : value
+        end
+      end
+
+      # adds Driver#pref method and [] and []= methods on that object
+      module FirefoxPrefs
+        def pref
+          Preference.new self
+        end
+      end
+
+      class Driver
+        prepend FirefoxPrefs
+      end
+    end
+  end
+end

data/lib/tor/driver.rb

@@ -3,26 +3,33 @@
 require 'open-uri'
 require_relative '../service'
 require_relative '../options'
+require_relative '../firefox_prefs'
 require_relative 'profile'
 require_relative 'tor_process'
 
 module Selenium
   module WebDriver
     module Tor
-      # delegate class so extensions can be added & connection to tor made
-      class DriverNotYetConnectedToTorNetwork < Firefox::Driver; end
+      # delegate class
+      class DriverDelegate < Firefox::Driver; end
 
       # tor driver
-      class Driver < DelegateClass(DriverNotYetConnectedToTorNetwork)
-        class TorNetworkError < StandardError; end
+      class Driver < DelegateClass(DriverDelegate)
+        TORRC_PATH_PREF = 'extensions.torlauncher.torrc_path'
+        TORRC = 'torrc'
+        BROWSER_SECURITY_LEVEL_PREF = 'browser.security_level.security_slider'
+        DOMAIN_ISOLATOR = 'TorDomainIsolator' # ES6 module
+        NEW_CIRCUIT = 'newCircuitForDomain' # js function
+        TB_SEC_LEVELS = { 'standard' => 4, 'safer' => 2, 'safest' => 1 }.freeze
 
         def initialize(options: nil, **)
           @data_dir = Dir.mktmpdir
-          add_torrc_path_to_options options
-          @instance = DriverNotYetConnectedToTorNetwork.new(options: options, **)
+          @options = options || Options.new # fix for issue #11, 'tis a puzzlement
+          add_torrc_path_to_options
+          @instance = DriverDelegate.new(options: @options, **)
+          install_extensions @instance
+          create_tor_process_and_start_tor @options.tor_opts
           super(@instance)
-          install_extensions(@instance)
-          create_tor_process_and_start_tor options&.tor_opts
         end
 
         def browser
@@ -35,12 +42,26 @@ module Selenium
           super
         end
 
-        private
+        def security_level
+          pref[BROWSER_SECURITY_LEVEL_PREF]
+        end
+
+        def security_level=(int)
+          raise(ArgumentError, "Valid security levels are: #{TB_SEC_LEVELS.values}") unless TB_SEC_LEVELS.value?(int)
 
-        def add_torrc_path_to_options(options)
-          return unless options
+          pref[BROWSER_SECURITY_LEVEL_PREF] = int
+        end
 
-          options.prefs['extensions.torlauncher.torrc_path'] = File.join(@data_dir, 'torrc')
+        def new_circuit_for_site
+          execute_script_in_chrome_context es6_function_call(es6: DOMAIN_ISOLATOR, func: NEW_CIRCUIT, args: domain)
+        end
+
+        alias new_circuit_for_page new_circuit_for_site
+
+        private
+
+        def add_torrc_path_to_options
+          @options.prefs[TORRC_PATH_PREF] = File.join(@data_dir, TORRC)
         end
 
         def install_extensions(instance)
@@ -50,6 +71,12 @@ module Selenium
         def create_tor_process_and_start_tor(opts)
           @tor_process = TorProcess.new(@data_dir, opts || {})
           @tor_process.start_tor
+        rescue Tor::TorProcess::TorProcessError => e
+          raise Error::WebDriverError, e
+        end
+
+        def domain
+          URI(current_url).host&.match(/[^\.]+\.\w+$/)
         end
       end
     end

data/lib/tor/options.rb

@@ -26,9 +26,9 @@ module Selenium
         def initialize(log_level: nil, **opts)
           opts[:tor_opts] = opts.delete(:system_tor).opts if opts[:system_tor] # DEPRECATED 2.0
           @tor_opts = opts[:tor_opts] ? opts.delete(:tor_opts) : {} # must be deleted before call to super
-          super(log_level: log_level, **tor_options(opts.delete(:prefs)).merge(opts))
           do_start_tor_browser_script_stuff # stuff the start-tor-browser script in TBB does
-          copy_fonts # so we don't have to change dir before executing TB binary #2 and #9
+          copy_fonts # so we don't have to change dir before executing TB binary - issues #2 and #9
+          super(log_level: log_level, **tor_options(opts.delete(:prefs)).merge(opts))
         end
 
         private

data/lib/tor/tor_process.rb

@@ -14,8 +14,7 @@ module Selenium
         class TorProcessError < StandardError; end
 
         BOOTSTRAP_SUCCESS_REGEX = /Bootstrapped 100% \(done\): Done$/
-        BOOTSTRAP_FAIL_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
-        # BOOTSTRAP_TIMEOUT_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
+        BOOTSTRAP_FAIL_REGEX = /^[A-Z][a-z]{2} \d{2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
 
         attr_reader :pid, :config
 
@@ -69,7 +68,6 @@ module Selenium
             lines << line
             break lines.join if line.match BOOTSTRAP_FAIL_REGEX
             break '' if line.match BOOTSTRAP_SUCCESS_REGEX
-            # break false if line.match BOOTSTRAP_TIMEOUT_REGEX
           end
         end
       end

data/lib/tor/version.rb

@@ -3,7 +3,7 @@
 module Selenium
   module WebDriver
     module Tor
-      VERSION = '1.1.0'
+      VERSION = '1.3.0'
     end
   end
 end

data/selenium_tor.gemspec

@@ -30,5 +30,5 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.22'
+  spec.add_dependency 'selenium-webdriver', '>= 4.23'
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: selenium_tor
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - MatzFan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-28 00:00:00.000000000 Z
+date: 2024-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.22'
+        version: '4.23'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.22'
+        version: '4.23'
 description: An extension for Selenium::WebDriver that automates Tor Browser
 email:
 executables: []
@@ -41,6 +41,8 @@ files:
 - Rakefile
 - fonts/000_README.txt
 - lib/driver.rb
+- lib/firefox_js_helpers.rb
+- lib/firefox_prefs.rb
 - lib/options.rb
 - lib/selenium_tor.rb
 - lib/service.rb
@@ -78,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: Selenium extension for Tor Browser