selenium_tor 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 387e1f6800b7d9b1f7eb269a0e6d53f699123b59f3daa1b4ae66536037fdc3ff
-  data.tar.gz: a59fa065eef2328abb0832ead2ada221172b5d4d55c34fe0285c02f6075e8d93
+  metadata.gz: 53381bfb6eec61ccbffdd84ce01dd3e83413822c139ef6877f1873505fdf9560
+  data.tar.gz: b0aaf6755f2139ab92f66941f6874a38a1ee0d5da6c4a4891968c2c22afb114f
 SHA512:
-  metadata.gz: 6a5d2aa8ecf3527edadcec9aab17480dfdd0055525322b7c97f0c8f4e6588e392d0e5b10d4eca05c5a1766e22f87b6793109da8965a45ac6bc26216888be50de
-  data.tar.gz: b145dab8c18821750a8be414af2cf44a8046a0393e69907c52dc14cc8dd4f376e626d10d77fe473655604d27810d93ea5539f5a316f78659a6a8abaaf6780f8c
+  metadata.gz: f5ce3f9a6def6cf03b4ddcb9eaa24548f70d87f7624d2c6b8deae473210f6a02e7239a80a4ba5ba9a925b8a33f9bb9e4adde8182d93fe90c17a8dd581de25351
+  data.tar.gz: c153ff3ea434a2a141f3f15670e923b0800159e1ee2126414b7fd498fbe937e155de652735255d9f4576735789ab9215f259c2983922627e0d68fbcad33825a7

data/.jshintrc

@@ -0,0 +1,3 @@
+{
+  "esversion": 6
+}

data/.rubocop.yml

@@ -6,10 +6,21 @@ require:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 2.7
 
 Style/HashSyntax:
   Enabled: false  # yuk Ruby 3.1
 
 Layout/LineLength:
   Max: 120
+
+Security/Eval:
+  Exclude:
+    - 'test/test_readme.rb'
+
+Lint/RescueException:
+  Exclude:
+    - 'test/test_readme.rb'
+
+Style/RegexpLiteral:
+  Exclude:
+    - 'Guardfile'

data/.ruby-version

@@ -1 +1 @@
-3.3.0-preview3
+3.3.4

data/CHANGELOG.md

@@ -1,11 +1,29 @@
 ## master (unreleased)
 
+## [0.2.0] - 2024-07-10
+
+### Breaking changes
+
+* RUN_HEADED_TESTS env var now ignored
+
+### New features
+
+* add README code block tests
+* fingerprintjs tests cover WebGL llvmpipe driver and WebGL being disabled 
+* special test added to test WebGL fingerprint when code run with vglrun
+
+### Bug fixes
+
+* [#4](https://gitlab.com/matzfan/selenium-tor/-/issues/4)
+* [#5](https://gitlab.com/matzfan/selenium-tor/-/issues/5)
+* [#7](https://gitlab.com/matzfan/selenium-tor/-/issues/7)
+
 ## [0.1.3] - 2023-12-08
 
 ### Bug fixes
 
 * added selenium-webdriver as runtime dependency
-* [#2](https://gitlab.com/matzfan/selenium_tor/-/issues/2) fixed, fingerprintjs VisitorId now same as TB's
+* [#2](https://gitlab.com/matzfan/selenium-tor/-/issues/2) fixed, fingerprintjs VisitorId now same as TB's
 
 ### New features
 
@@ -30,7 +48,7 @@
 ### Bug fixes
 
 * Fix inability to add options to Tor::Options
-* [#1](https://gitlab.com/matzfan/selenium_tor/-/issues/1): Fix fonts leak at browserleaks
+* [#1](https://gitlab.com/matzfan/selenium-tor/-/issues/1): Fix fonts leak at browserleaks
 
 ### New features
 

data/Guardfile

@@ -1,25 +1,9 @@
 # frozen_string_literal: true
 
-# A sample Guardfile
-# More info at https://github.com/guard/guard#readme
-
-## Uncomment and set this to only include directories you want to watch
-# directories %w(app lib config test spec features) \
-#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
-
-## Note: if you are using the `directories` clause above and you are not
-## watching the project directory ('.'), then you will want to move
-## the Guardfile to a watched dir and symlink it back, e.g.
-#
-#  $ mkdir config
-#  $ mv Guardfile config/
-#  $ ln -s config/Guardfile .
-#
-# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
-
 guard :minitest do
   watch(%r{^test/(.*)/?test_(.*)\.rb$})
   watch(%r{^features/(.*)/?test_(.*)\.rb$})
-  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
-  watch(%r{^test/test_helper\.rb$})      { 'test' }
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})        { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$})         { 'test' }
+  watch(%r{^README.md$})                    { 'test/test_readme.rb' }
 end

data/README.md

@@ -5,14 +5,19 @@
 
 A Selenium extension for Tor Browser.
 ```ruby
-driver = Selenium::WebDriver.for :tor
+@driver = Selenium::WebDriver.for :tor
+@driver.quit
 ```
 
-# \_why?
+## \_why?
 
 I can use Firefox with Selenium and set a SOCKS proxy to use the Tor network, so why the need?
 
-The above approach will hide your IP, but there is a good chance your browser's unique or near-unique fingerprint may be logged by site owners. Subsequent visits could identify you. A primary aim of this project is to enable Selenium to leverage Tor Browser's unique anonymity characteristics - in particular its resitance to browser fingerprinting. The aim is to ensure Selenium Tor site visits leave an identical fingerprint to the thousands of regular Tor Browser users.
+The above approach will hide your IP, but there is a good chance your browser's unique or near-unique fingerprint may be logged by site owners. Subsequent visits could identify you. A primary aim of this project is to enable Selenium to leverage Tor Browser's unique anonymity characteristics - in particular its resistance to browser fingerprinting. The aim is to ensure Selenium Tor site visits leave an identical fingerprint to the thousands of regular Tor Browser users.
+
+## Known issues
+
+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
 
@@ -31,12 +36,11 @@ Tor Browser is based on Firefox, so for usage please read the Selenium [docs](ht
 A driver is instantiated like this:
 ```ruby
 options = Selenium::WebDriver::Tor::Options.new
-options.add_argument '--headless' # whatever you need
-driver = Selenium::WebDriver.for :tor, options: options
+@driver = Selenium::WebDriver.for :tor, options: options
 
-driver.get 'https://check.torproject.org'
-puts driver.title # => Congratulations. This browser is configured to use Tor.
-driver.quit
+@driver.get 'https://check.torproject.org'
+@driver.title # => Congratulations. This browser is configured to use Tor.
+@driver.quit
 ```
 The driver will not be instantiated until a connection to the Tor network is made. If the network is inaccessible for any reason a `TorNetworkError` will result.
 
@@ -48,7 +52,7 @@ A number of constants are set during driver initialization based upon values fou
 ```ruby
 Tor::TBB_DIR # path to the TBB root directory
 Tor::TBB_BROWSER_DIR # path to the 'Browser' directory in the above
-Tor::TBB_BINARY_PATH # path to the binary
+Tor::TBB_BINARY_PATH # path to the firefox binary
 Tor::TBB_PROFILE_DIR # path to the default profile directory
 Tor::TBB_EXTENSIONS_DIR # path to the 'extensions' directory in the above
 Tor::TBB_VERSION # the version installed, e.g. "13.0.1", note: driver.capabilities.browser_version returns the Firefox version Tor Browser is based on 
@@ -56,14 +60,17 @@ Tor::TBB_VERSION # the version installed, e.g. "13.0.1", note: driver.capabiliti
 
 ## Dependencies and configuration
 
+[Tor Browser](https://www.torproject.org/download).
+
 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). This can be installed from the Tor Project [downloads page](https://www.torproject.org/download/). The 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:
+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:
 ```ruby
+options = Selenium::WebDriver::Tor::Options.new
 options.binary = '/some/path/to/tor_firefox_binary' # UNNECESSARY
 ```
 
-The location of the TBB is not expected to change during execution.
+The location of the TBB is not expected to change during code execution.
 
 Tor Selenium is tested on **Linux only** right now.
 
@@ -71,11 +78,15 @@ Tor Selenium is tested on **Linux only** right now.
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests.
 
-Tests are run in headless mode by default. If you want to see what the browser is doing you can do this:
+Tests are run in the display set by the `DISPLAY` env var, :0 by default. To run headless tests, set it to another value:
+
+    $ DISPLAY=:99 bundle exec rake
+
+If you find tests are failing with `TorNetworkError` and a timeout message, check you have no other Tor Browser processes running. The processes to look for are either "firefox.real" or "firefox-esr". The latter may be legitimate if you are also running Firefox browser. You may also want to check the Tor network is actually up, it isn't always..
 
-    $ export RUN_HEADED_TESTS=1 && bundle exec rake
+If you wish run the `vglrun` WebGL fingerprint test (excluded from Rake) install VirtualGL (see above, assumes you have the relevent drivers installed) and run the following command:
 
-If you find tests are failing with `TorNetworkError` and a timeout message, check you have no other Tor Browser processes running. The process to look for is called "firefox.real". You may also want to check the Tor network is actually up, it isn't always..
+    $ DISPLAY=:99 vglrun bundle exec ruby test/features/fingerprinting/test_fingerprintjs_with_vglrun.rb
 
 ## Development
 
@@ -85,9 +96,9 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitLab at https://gitlab.com/matzfan/selenium_tor. For a pull request please checkout a suitably named feature branch before making and submitting changes.
+Bug reports and pull requests are welcome on GitLab at https://gitlab.com/matzfan/selenium-tor. For a pull request please checkout a suitably named feature branch before making and submitting changes.
 
-This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://gitlab.com/matzfan/selenium_tor/CODE_OF_CONDUCT.md).
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://gitlab.com/matzfan/selenium-tor/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -95,4 +106,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Selenium Tor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://gitlab.com/matzfan/selenium_tor/CODE_OF_CONDUCT.md).
+Everyone interacting in the Selenium Tor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://gitlab.com/matzfan/selenium-tor/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -6,7 +6,8 @@ require 'rake/testtask'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
-  t.test_files = FileList['test/**/test_*.rb']
+  t.test_files = FileList['test/**/test_*.rb'] - ['test/features/fingerprinting/test_fingerprintjs_with_vglrun.rb']
+  # t.warning = false
 end
 
 require 'rubocop/rake_task'

data/lib/tor/driver.rb

@@ -10,29 +10,38 @@ module Selenium
       class Driver < DelegateClass(DriverNotYetConnectedToTorNetwork)
         class TorNetworkError < StandardError; end
 
-        CONNECTION_STATUS_ID = 'torPreferences-status-tor-connect'
-        CONNECTED = "Tor Network:\nConnected"
-        NO_SCRIPT_XPI_URL = 'https://addons.mozilla.org/firefox/downloads/file/4178438/noscript-11.4.28.xpi'
+        CONNECT_BUTTON_ID = 'network-status-tor-connect-button' # visible only until connected
+        TOR_PREFS_CONNECTION_URL = 'about:preferences#connection'
+
+        attr_reader :support_data
 
         def initialize(...)
-          @instance = DriverNotYetConnectedToTorNetwork.new(...)
+          instantiate_driver_from_tbb_dir(...)
           super(@instance)
           wait_for_tor_connection
-          install_addons
+          install_extensions
         end
 
         private
 
+        def instantiate_driver_from_tbb_dir(...)
+          cwd = FileUtils.pwd
+          FileUtils.cd TBB_BROWSER_DIR # crucial - fixes [#2](https://gitlab.com/matzfan/selenium-tor/-/issues/2)
+          @instance = DriverNotYetConnectedToTorNetwork.new(...)
+        ensure
+          FileUtils.cd cwd
+        end
+
         def wait_for_tor_connection
-          @instance.get 'about:preferences#connection'
-          Wait.new(timeout: 10).until { @instance.find_element(:id, CONNECTION_STATUS_ID).text == CONNECTED }
+          @instance.get TOR_PREFS_CONNECTION_URL
+          Wait.new(timeout: 10).until { !@instance.find_element(:id, CONNECT_BUTTON_ID).displayed? }
         rescue Selenium::WebDriver::Error::TimeoutError => e
           @instance.quit # abort initialization
           raise TorNetworkError, "Cannot connect to Tor network: #{e.message}"
         end
 
-        def install_addons
-          @instance.install_addon URI.parse(NO_SCRIPT_XPI_URL).open
+        def install_extensions
+          Pathname.new(TBB_EXTENSIONS_DIR).children.each { |xpi_path| @instance.install_addon xpi_path }
         end
       end
     end

data/lib/tor/options.rb

@@ -34,7 +34,7 @@ module Selenium
           ENV['FONTCONFIG_FILE'] = 'fonts.conf'
           FileUtils.rm_rf File.join(Tor::TBB_BROWSER_DIR, *%w[TorBrowser Data fontconfig])
           ENV['GSETTINGS_BACKEND'] = 'memory'
-          FileUtils.cd Tor::TBB_BROWSER_DIR # crucial - fixes [#2](https://gitlab.com/matzfan/selenium-tor/-/issues/2)
+          # cd to TBB_BROWSER_DIR now handled in Tor::Driver
         end
       end
     end

data/lib/tor/profile.rb

@@ -2,8 +2,6 @@
 
 require 'selenium-webdriver'
 require_relative 'options'
-require_relative '../firefox_driver_lock_file_patch' unless
-  Gem::Version.new(Selenium::WebDriver::VERSION) > Gem::Version.new('4.15')
 
 module Selenium
   module WebDriver

data/lib/tor/tor_prefs.rb

@@ -16,7 +16,8 @@ module Selenium
       }.freeze
 
       OTHER_PREFS = {
-        'intl.language_notification.shown' => true # affects font fingerprint (viewport size)
+        'intl.language_notification.shown' => true, # affects font fingerprint (viewport size)
+        'remote.active-protocols' => 3 # new some time after selenium-webdriver 4.16
       }.freeze
 
       TOR_PREFS = FIRST_CONNECTION_PREFS.merge OTHER_PREFS

data/lib/tor/version.rb

@@ -3,7 +3,7 @@
 module Selenium
   module WebDriver
     module Tor
-      VERSION = '0.1.3'
+      VERSION = '0.2.0'
     end
   end
 end

data/selenium_tor.gemspec

@@ -6,19 +6,16 @@ Gem::Specification.new do |spec|
   spec.name = 'selenium_tor'
   spec.version = Selenium::WebDriver::Tor::VERSION
   spec.authors = ['MatzFan']
-  spec.email = ['matzfan@mailinator.com']
 
   spec.summary = 'Selenium extension for Tor Browser'
   spec.description = 'An extension for Selenium::WebDriver that automates Tor Browser'
-  spec.homepage = 'https://gitlab.com/matzfan/selenium_tor'
+  spec.homepage = 'https://gitlab.com/matzfan/selenium-tor'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 2.7.0'
-
-  # spec.metadata['allowed_push_host'] =
+  spec.required_ruby_version = '>= 3.3.3'
 
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://gitlab.com/matzfan/selenium_tor'
-  spec.metadata['changelog_uri'] = 'https://gitlab.com/matzfan/selenium_tor/CHANGELOG.md'
+  spec.metadata['source_code_uri'] = 'https://gitlab.com/matzfan/selenium-tor'
+  spec.metadata['changelog_uri'] = 'https://gitlab.com/matzfan/selenium-tor/CHANGELOG.md'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   # Specify which files should be added to the gem when it is released.
@@ -33,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.16.0'
+  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.22'
 end

metadata

@@ -1,36 +1,36 @@
 --- !ruby/object:Gem::Specification
 name: selenium_tor
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - MatzFan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-08 00:00:00.000000000 Z
+date: 2024-07-10 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.16.0
+        version: '4.22'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.16.0
+        version: '4.22'
 description: An extension for Selenium::WebDriver that automates Tor Browser
 email:
-- matzfan@mailinator.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".jshintrc"
 - ".rubocop.yml"
 - ".ruby-version"
 - ".yamllint"
@@ -41,7 +41,6 @@ files:
 - README.md
 - Rakefile
 - lib/driver.rb
-- lib/firefox_driver_lock_file_patch.rb
 - lib/options.rb
 - lib/selenium_tor.rb
 - lib/service.rb
@@ -53,13 +52,13 @@ files:
 - lib/tor/version.rb
 - selenium_tor.gemspec
 - sig/tor.rbs
-homepage: https://gitlab.com/matzfan/selenium_tor
+homepage: https://gitlab.com/matzfan/selenium-tor
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://gitlab.com/matzfan/selenium_tor
-  source_code_uri: https://gitlab.com/matzfan/selenium_tor
-  changelog_uri: https://gitlab.com/matzfan/selenium_tor/CHANGELOG.md
+  homepage_uri: https://gitlab.com/matzfan/selenium-tor
+  source_code_uri: https://gitlab.com/matzfan/selenium-tor
+  changelog_uri: https://gitlab.com/matzfan/selenium-tor/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -69,14 +68,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.3.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.0.dev
+rubygems_version: 3.5.14
 signing_key:
 specification_version: 4
 summary: Selenium extension for Tor Browser

data/lib/firefox_driver_lock_file_patch.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Selenium
-  module WebDriver
-    module Firefox
-      # patched class
-      class Profile
-        alias old_delete_lock_files delete_lock_files
-
-        def delete_lock_files(directory)
-          %w[.parentlock parent.lock lock].each do |name| # 'lock' file missing from Selenium < 4.16
-            FileUtils.rm_f File.join(directory, name)
-          end
-        end
-      end
-    end
-  end
-end