# 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.
- Local development environments (see Testing local applications for more details)
This is achieved using two components:
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.
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.
The remaining of this section presents the following topics:
# Setup a Virtuoso Bridge
To set up a new Virtuoso Bridge:
Obtain the Virtuoso Bridge client for your operative system (no installation is necessary):
Launch it, providing the authentication parameters:
- --token : Authentication token (recommended). See Creating an API access token on how to obtain it.
- -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
# Linux chmod +x bridge_client ./bridge_client --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115 # MacOS chmod +x bridge_client.app ./bridge_client.app --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
- --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:
- --staging : Use Virtuoso staging environment
- --api [api endpoint url] : Target a custom Virtuoso environment API, e.g.,
- -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
# Using a Virtuoso Bridge
To use a previously set Virtuoso Bridge, set it up on the Advanced Settings section of a Goal:
The drop down list will present the bridge id and name of the user that initiated it:
This list will be composed by all public bridges associated with an organization.
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:
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
10.0.0.2:8081). This proxy must be a
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
10.0.0.5:8082). This proxy must be a
SOCKSproxy 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 (
To obtain the ZAP proxy info using the GUI, launch it and from the menu select
From the options window select
Local Proxies to view or change the ZAP proxy info:
This info is also shown on the ZAP window 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:
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:
For more details on using ZAP see the official documentation