Virtuoso Guide

# Virtuoso Bridge

Virtuoso Bridge allows Virtuoso to access your local or private application, without the need of changes on the firewall or routing rules on your infrastructure. This enables seamless usage of Virtuoso on:

  • Internal environments behind firewall (e.g., staging and testing environments)
  • Applications with restricted access within your organization network (e.g. https://privateapp.intranet)
  • Local development environments (see Testing local applications for more details)

This is achieved using two components:

  1. Virtuoso Bridge Client - Establishes a secure connection (TLS-encrypted) to the Virtuoso Bridge Server which is then used as a secure tunnel to forward all requests made by Virtuoso Bots through that specific Virtuoso Bridge Client to your internal network.

  2. Virtuoso Bridge Server - Acts as proxy for all traffic coming from Virtuoso Bots and allows access to all network applications accessible by the machine where Virtuoso Bridge Client is deployed.

The following diagram illustrates this functionality, and the connections between the Virtuoso Bridge components, your internal application and Virtuoso Bots.

Bridge overview

The remaining of this section presents the following topics:

# Setup a Virtuoso Bridge

To set up a new Virtuoso Bridge:

  1. Obtain the Virtuoso Bridge client for your operating system (no installation is necessary):

  2. (macOS only) Allow application to be executed on macOS so the downloaded binary is accepted by the operating system

  3. (macOS only) Increase maximum open files limit on macOS as the default limit of open files is too low for normal operation of the bridge, one of the steps needs to be repeated before each execution in a new terminal

  4. Launch it, providing the authentication parameters:

    Or:

    • -e (--email) : User email to access Virtuoso
    • -p (--password) : User password to access Virtuoso

    If both token and email/password are provided, token will be used

Token type

Although you can use a token of type ALL (full-access) to use the Virtuoso Bridge, we strongly recommend you to use a token of type BRIDGE which has a reduced scope of permissions and is designed to work with the Virtuoso Bridge using the minimum permissions needed.

Example:

# Replace the example tokens with tokens created from your user profile

# Linux
chmod +x bridge_client
./bridge_client --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115

# MacOS
chmod +x bridge_client.app
./bridge_client --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115

# Windows
bridge_client.exe --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115

There are also some optional parameters:

  • -n (--name) : Identifier for the bridge (this will appear as your bridge name on Virtuoso). If not provided, the MAC Address of the default network adapter will be used.
  • -o (--out) : Specifies the full path of a log file to be used. If not provided, standard output will be used. Alternatively the value "none" can be used to disable logging completely.
  • -l (--log-level) : Specifies the log level using DEBUG, INFO (default), WARNING or ERROR.
  • --max-retry-time : Specifies the maximum time the client will retry connecting to Virtuoso on connection failure before exiting, in the form of <hours>h<minutes>m<seconds>s (ex: 34m, 1h30m) (default 5m)

# Using the bridge on other Virtuoso environments

By default, the bridge client will connect to Virtuoso production environment. This can be overridden with the following options:

  • --api [api endpoint url] : Target a custom Virtuoso environment API.
  • -b (--bridge) [custom bridge server(s) address] : Use Virtuoso Bridge custom endpoint(s) separated by ';', in the format server:port[;server2:port]. This parameter is mandatory when using a custom api endpoint url.

To connect to the Virtuoso free trial environment, you can use the --app2 shortcut parameter.

Examples:

# Linux - Free trial
./bridge_client --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115 --app2

# Windows - Production US
./bridge_client.exe --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115 --api https://api-us.virtuoso.qa/ --bridge bridge-us.virtuoso.qa:443

# Allow application to be executed on macOS

When using the bridge on a macOS device, it is possible that the operating system blocks its execution due to not being able to verify the developer.

Execution permission in macOS Monterey 12.6

For this macOS version it is required to give execution permissions through the terminal before executing the steps in this section. To grant the permission first execute in a terminal on the folder containing the downloaded bridge client: ./bridge_client

Developer cannot be verified Monterey 12.6

Developer cannot be verified

To give permissions to the app, right-click it to open the context menu, and click 'Open'. Double clicking the app will not show the Open option.

Open from context menu

This adds an exception on the OS to run this app, and the bridge can now be started without issues from the CLI.

Open unsigned app

# Increase maximum open files limit on macOS

By default, macOS has a limit of open files of 256 which is too low for the normal operation of the bridge.

To increase this limit, execute the following commands before running the bridge.

This has to be done everytime before running the bridge, and in the same terminal window.

Should be used together with the parameter --max-connections

# MacOS
sudo launchctl limit maxfiles 65536 200000

# Check if the maximum number of file descriptors is lower than 1000
ulimit -a

# Increase the maximum number of file descriptors that a process can have to 1000 if necessary
ulimit -n 1000

# Checking available Virtuoso Bridges

You can check the available bridges in an organization by going to the Organization Dashboard and clicking the Bridges tab at the top.

Bridge list

After a bridge client has been launched, it should appear on the Bridges section of the organization dashboard, under the MAC address of the network adapter or the name it was given using the -n / --name parameter.

# Using a Virtuoso Bridge

To use a previously set Virtuoso Bridge, set it up on the "Environment" settings section of a Goal, through the Default environment selector:

Goal Bridge setup

The dropdown options will list all available environments and their associated bridges.

Connection capacity at the bridge client

With the bridge, the bandwidth available to Virtuoso will be limited by the capacity of the connection to the bridge server from the client, and from the client to the application under test.

By default, Virtuoso will not limit the number of concurrent sessions sharing the bridge. Bandwidth capacity through the bridge is limited by the capacity of the internet connection (and VPN if in use) of the host running the client, both to the bridge server and to the application under test.

If your goal has many journeys or the bridge client is running over an unstable or limited-bandwidth connection, this can lead to request timeouts which in turn cause journeys to fail part-way through or in some cases a blank screenshot on the first step.

When this happens, you can use the maximum parallelism setting on goals and plans to limit the maximum number of bots testing at the same time. If possible, avoid running the bridge client on machines that require a VPN to access the target application by running the client on a host within the network instead.

# Testing local applications

Due to Chrome browser limitations, it is not possible to direct requests to "localhost" or "127.0.0.1" through Virtuoso Bridge. To overcome this, the configuration should be adjusted to access an alternative address / IP. To support this, on bridge client launch the alternative options available will be presented:

|
| For access to localhost applications, in Virtuoso please replace localhost by one of the following:
|
| myhostname
| 192.168.1.104
| 192.168.122.1
|
| Example:
| http://localhost:8080 -> http://myhostname:8080
|
| For more details please check documentation at:
| https://docs.virtuoso.qa/guide/advanced-topics/virtuoso-bridge/#setup-a-virtuoso-bridge
|

On the goal configuration url and any navigate test steps, localhost should be replaced by one of the presented options.

# Virtuoso Bridge proxy support

Depending on your network architecture or connectivity requirements, it might be needed to use Virtuoso bridge with one or two proxies:

Bridge proxy

If your application can only be accessed through a http proxy or if you require that all traffic targeting the application is directed through a http proxy, you can use the following parameter:

  • --application-http-proxy [http proxy], the proxy value should be provided in the form of <proxy_address>:<proxy_port> (e.g., 10.0.0.2:8081). This proxy must be a HTTP proxy.

On the other hand, your Virtuoso bridge might not be able to reach our Virtuoso servers directly, and it needs a proxy connection too. For these cases, you can use this parameter to configure where the bridge client should point to reach external networks:

  • --outbound-socks-proxy [socks proxy], the proxy value should be provided in the form of <proxy_address>:<proxy_port> (e.g., 10.0.0.5:8082). This proxy must be a SOCKS proxy to properly communicate with Virtuoso.

# Using OWASP® Zed Attack Proxy (ZAP) with Virtuoso Bridge

One of the use cases for Virtuoso bridge proxy support is to integrate with OWASP ZAP tool for security auditing your application via Virtuoso. This can be achieved by using ZAP proxy functionality, and setting up Virtuoso bridge to use it as application proxy (--application-http-proxy parameter).

To obtain the ZAP proxy info using the GUI, launch it and from the menu select Tools->Options:

ZAP Options

From the options window select Local Proxies to view or change the ZAP proxy info:

ZAP Proxy

This info is also shown on the ZAP window status bar:

ZAP Proxy Status Bar

If you are running ZAP in daemon mode, check for the log message with the proxy info:

[ZAP-daemon] INFO  org.zaproxy.zap.DaemonBootstrap - ZAP is now listening on localhost:8888

This is the value you should use while starting the Virtuoso Bridge to allow all traffic to be directed through ZAP. Using the information from the above example it should be:

bridge_client --token <TOKEN> -n zap_bridge --application-http-proxy localhost:8888

Then all tests executed within a Goal setup to use this bridge will be directed to ZAP and subject to analysis:

ZAP Events

When using ZAP the new HUD functionality should be disabled so ZAP does not change the website and affect the journeys/screenshots captured by Virtuoso. To do so, on the options screen select HUD and ensure that Show the HUD welcome screen when a browser is opened is unchecked:

ZAP Disable HUF

For more details on using ZAP see the official documentation

Last Updated: 6/6/2024, 11:19:35 AM

← Virtuoso Fixed IP →