selenium_tor 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6f9d6ff1e71d45656e35148ac5d58b490e85c23fbe47cb977de1b0b3f0a7de2
-  data.tar.gz: 24a4431f5a6b7957f14ca5d222b0f630f29e9955956622e20e73cdff5c51de6c
+  metadata.gz: d91caf67c6dbe8d0ee5a4e9e1fde84901ec736d0280dc5913b91e9d38e78bc55
+  data.tar.gz: e3e789ac86f09532c03472f52dd80c750695d71f1b7bd4b9b4521880d5f83751
 SHA512:
-  metadata.gz: 3f4a53aa33461f0159c0ff8703786646df23b8f503534710d4cf83c688ee247334262e88661f9d87a9a7ce008377c62032e209b737c7abd61165a0b309d8a262
-  data.tar.gz: 758cbe58b60de4556ff5c95fc82761f919ea1670b131c8afad6f6e6be673092ceb2fa71e5fde1240d5e70c03786eb4d04c75197073af9425381c1d6d66777522
+  metadata.gz: bc39fe85b2f2cceddc76d77c4e5cbbfcc35f658a0af9376affd99d397617523705e4b5a2cf11a74785ff7bfb41bf83cfbd15b87e5472649191b4d346b75f6b64
+  data.tar.gz: 2b0aa0060db12d4f6854b47b47979e9f50b7a013a8ad550a8fdb5268c1d9c8eda76df88090a81e620845cb1e114db6e8e1430cbdd983a0d0c5a0ef7f88758360

data/.rubocop.yml

@@ -1,5 +1,5 @@
 ---
-require:
+plugins:
   - rubocop-minitest
   - rubocop-performance
   - rubocop-rake
@@ -7,14 +7,12 @@ require:
 AllCops:
   TargetRubyVersion: 3.2
   NewCops: enable
+  Exclude:
+    - 'vendor/**/*'  # GitLab caching..
 
 Style/HashSyntax:
   Enabled: false  # yuk Ruby 3.1
 
-Naming/MethodName:
-  Exclude:
-    - !ruby/regexp /test_.*\.rb$/  # for test_FOO constant tests
-
 Security/Eval:
   Exclude:
     - 'test/test_readme.rb'
@@ -36,3 +34,6 @@ Minitest/TestMethodName:
 
 Minitest/AssertTruthy:
   Enabled: false
+
+Minitest/RefuteFalse:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## master (unreleased)
 
+## [2.0.0] - 2025-05-31
+
+### New features
+
+* SocksPort is now auto selected, 'SocksPort'/:socks_port keys are ignored in Tor::Options :tor_opts hash
+* selenium-manager is disabled (avoids chance of FF being downloaded & used)
+* errors in Tor namespace now subclass Selenium::WebDriver::Error::WebDriverError
+* drop Xvfb/headless gem dependency
+* drop deprecated :system_tor options
+
+### Bug fixes
+
+* ControlPort no longer set by default in torrc (security)
+
+## [1.7.0] - 2025-05-21
+
+### New features
+
+* Reuse cached data files in TorProcess to speed up connection times
+* drop support for TB < 14.5 stable
+* add VirtualGL test to Rake tests
+
+### Bug fixes
+
+* [#20](https://gitlab.com/matzfan/selenium-tor/-/issues/20)
+
 ## [1.6.0] - 2024-12-04
 
 * drop support for TB < 14.0 stable

data/README.md

@@ -8,7 +8,8 @@ A Selenium extension for Tor Browser.
 # before_all
 require 'selenium_tor'
 
-options = Selenium::WebDriver::Tor::Options.new
+options = Selenium::WebDriver::Options.tor
+options.args << '-headless'
 @driver = Selenium::WebDriver.for :tor, options: options
 ```
 When you are done don't forget to quit the driver. Failure to do so may leave orphaned tor processes.
@@ -18,6 +19,9 @@ When you are done don't forget to quit the driver. Failure to do so may leave or
 ```
 Once you have a driver instance:
 ```ruby
+@driver
+# => instance_of Selenium::WebDriver::Tor::Driver
+
 @driver.get 'https://check.torproject.org'
 @driver.title
 # => "Congratulations. This browser is configured to use Tor."
@@ -27,7 +31,7 @@ Once you have a driver instance:
 
 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 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.
+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 primary aim is to ensure Selenium Tor site visits leave an identical fingerprint to the thousands of regular Tor Browser users.
 
 ## Installation
 
@@ -41,13 +45,13 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Dependencies and configuration
 
-[Tor Browser](https://www.torproject.org/download). Versions >= 14.0 stable are supported.
+[Tor Browser](https://www.torproject.org/download). Tests are conducted with the latest stable ('release') and alpha versions of Tor Browser. Support for older versions is periodically dropped - see the CHANGELOG.
 
-As with Firefox browser, `geckodriver` needs to be installed and in your PATH.
+As with Firefox browser, `geckodriver` needs to be installed and in your PATH. [Selenium Manager](https://www.selenium.dev/documentation/selenium_manager) is disabled for security reasons, so you are responsible for ensuring the correct (latest) version of geckodriver is installed.
 
 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 = Selenium::WebDriver::Options.tor
 options.binary = '/some/path/to/tor_firefox_binary' # UNNECESSARY
 # => '/some/path/to/tor_firefox_binary'
 ```
@@ -56,21 +60,6 @@ The location of the TBB is not expected to change during code execution.
 
 Tor Selenium is tested on **Linux only** right now.
 
-### Patching libxul.so
-
-A configuration option to patch the libxul.so packaged with Tor Browser is provided. This has the effect of preventing websites from fingerprinting Selenium-driven Tor Browser via a JS call to `navigator.webdriver`:
-```ruby
-@driver_class = Selenium::WebDriver::Tor::Driver
-@driver_class.libxul_patched? # is Tor Browser's libxul.so patched?
-# => false
-@driver_class.patch_libxul # patch libxul.so
-@driver_class.libxul_patched?
-# => true
-@driver_class.unpatch_libxul # revert the patch and restore the libxul.so packaged with Tor Browser
-# => 0
-```
-The patcher uses the [Bsdiff](https://gitlab.com/matzfan/bsdiff) gem, which in turn requires the bzip2 library (`libbz2-dev`).
-
 ## Usage
 ```ruby
 require 'selenium_tor'
@@ -84,21 +73,17 @@ A separate tor process is used for each driver. Failure to call `Driver#quit` af
 
 ### Tor options
 
-In addition to the regular Firefox options, a :tor_opts key may be passed to an instance of `Tor::Options` with a hash of tor options. All valid tor options are recognized - see `man tor`. For convenience, "SocksPort" and "ControlPort" options may be set using snake_case symbols - i.e. :socks_port and :control_port. Additionally, a :tor_opts timeout value may be set with the :timeout key. This overrides the default time allowed for the tor process to bootstrap (10 seconds).
+In addition to the regular Firefox options, a `:tor_opts` key may be passed to an instance of `Tor::Options` with a hash of tor options. All valid tor client options are recognized - see `man tor`. Snake case key symbols may be used if these can be coerced to valid camel case key strings - e.g. `:control_port` becomes 'ControlPort'. Additionally, a `:tor_opts` timeout value may be set with the `:timeout` key. This overrides the default time allowed for the tor process to bootstrap (10 seconds).
 
 ### Multiple driver instances
 
-Running multiple tor processes requires that each uses different ports for SocksPort (and ControlPort, if used). These must be passed using the `:tor_opts` key. An example using the [Parallel gem](https://rubygems.org/gems/parallel):
+Running multiple tor processes requires that each uses different ports for SocksPort (and ControlPort, if used). From version 2.0 the SocksPort is auto selected, so no configuation is required. An example using the [Parallel gem](https://rubygems.org/gems/parallel):
 ```ruby
 require 'parallel'
 
-@socks_port = 9150
-@control_port = 9151
-
 def driver
-  @socks_port += 2
-  @control_port += 2
-  options = Selenium::WebDriver::Tor::Options.new tor_opts: { socks_port: @socks_port, control_port: @control_port }
+  options = Selenium::WebDriver::Options.tor # no needs to pass SocksPort in :tor_opts from version 2.0
+  options.args << '-headless'
   Selenium::WebDriver.for :tor, options: options
 end
 
@@ -111,6 +96,8 @@ end
 @drivers.each(&:quit)
 # => truthy
 ```
+Each Driver instance uses a separate data directory for `torrc` and other files. Starting from version 1.7 cached files created upon first connection to the tor network are copied into subsequent data dirs. This substantially reduces the time subsequent Drivers take to connect to the tor network.
+
 ### Tor Browser specific functionality
 
 You can get and set the security level (shield icon in TB) as follows. 4 is 'Standard', 2 is 'Safer', 1 is 'Safest'.
@@ -153,31 +140,37 @@ 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
 # => instance_of String
 ```
+### Patching libxul.so
 
-## Known issues
+A configuration option to patch the `libxul.so` packaged with Tor Browser is provided. This has the effect of preventing websites from fingerprinting Selenium-driven Tor Browser via a JS call to `navigator.webdriver`:
+```ruby
+@driver_class = Selenium::WebDriver::Tor::Driver
+@driver_class.libxul_patched? # is Tor Browser's libxul.so patched?
+# => false
+@driver_class.patch_libxul # patch libxul.so
+@driver_class.libxul_patched?
+# => true
+@driver_class.unpatch_libxul # revert the patch and restore the libxul.so packaged with Tor Browser
+# => 0
+```
+The patcher uses the [Bsdiff](https://gitlab.com/matzfan/bsdiff) gem.
 
-Known issues are recorded [here](https://gitlab.com/matzfan/selenium-tor/-/issues).
+### Exceptions
 
-### Fingerprinting
+Tor-specific webdriver funcionality raises `Tor::Error` or a subclass. `Tor::Error` itself subclasses `WebDriver::Error::WebDriverError`
 
-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).
+## Known issues
+
+Known issues are recorded [here](https://gitlab.com/matzfan/selenium-tor/-/issues).
 
 ## Testing
 
 ~~After checking out the repo, run `bin/setup` to install dependencies.~~
 
-Tests dependencies are `[bsdiff](https://www.daemonology.net/bsdiff)`, `VirtualGL` (see Fingerprinting above) and `Xvfb` if you want to run headless tests.
-
-Tests are run in the display set by the `DISPLAY` env var, usually :0 by default. To run headless tests, set it to another value:
-
-    $ DISPLAY=:99 bundle exec rake
+    $ bundle exec rake
 
 If you find driver instantiation failing with port bind failure error messages ( these include "Address already in use. Is Tor already running?") check you have no other tor processes running with conflicting ports. With timeout errors, you may also want to check the Tor network is actually up, it isn't always..
 
-If you wish run the `vglrun` WebGL fingerprint test install VirtualGL (see above, assumes you have the relevent drivers installed) and run the following command:
-
-    $ DISPLAY=:99 vglrun bundle exec ruby test/features/fingerprinting/vglrun_test_fingerprintjs.rb
-
 ## Development
 
 You can run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -2,6 +2,7 @@
 
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'rubocop/rake_task'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
@@ -10,8 +11,6 @@ Rake::TestTask.new(:test) do |t|
   # t.warning = false
 end
 
-require 'rubocop/rake_task'
-
 RuboCop::RakeTask.new
 
 task default: %i[test rubocop]