API Reference Guide
This document describes the API that can be used to create and launch new Bubbles
through a WebSocket
connection to the Browser Bubble Pro
application.
The Browser Bubble Pro
API requires a Browser Bubble Pro
license.
Browser Bubble Pro
is designed for professionals that need more advanced and customizable options than what the base
Browser Bubble
provides.
Browser Bubble Pro
will only be sold to individuals and businesses with a verifiable point-of-contact.
Please contact us to learn more about Browser Bubble Pro
or to purchase a license.
The server uses web sockets so any client that wants to interface with the API must be able to communicate using web sockets.
By default, Browser Bubble Pro
listens on port 8778 for localhost connections. However, these values can be changed
through the use of command line switches.
To change the port, use the -port N
command line switch where N
is a valid port number.
To change the way that Browser Bubble Pro
listens, use the -listen local
or -listen remote
command line switch.
If exposed for remote access, make sure your firewall allows the connection.
Browser Bubble Pro
can be run headless so there is no UI shown. However, Browser Bubble Pro
is not a Windows service
so it must run within a user session. To run headless simply pass the -headless
command-line switch when starting.
All data transferred to or from the Browser Bubble Pro
server is JSON encoded. In many cases, it may be layers of JSON encoding that
can be unwrapped based on parameter values. The two most important JSON objects are SERVER_REQUEST
and SERVER_RESPONSE
.
SERVER_REQUEST
is sent by the client to the server to perform some action.
{
Version: (int)
MessageID: (long)
DataType: (int)
RequestValue: (str)
}
SERVER_RESPONSE
object is sent by the server in response to a request.{
Version: (int)
ErrorCode: (int)
DataType: (int)
MessageID: (long)
ReturnValue: (str)
}
The Version
field is currently 1
and must be set. When new API capabilities are added that do not fit within the
current constructs, the API version may increment and additional fields added.
The MessageID
value starts at 1
and must increment in value for every client initiated command. The server will
set the SERVER_RESPONSE.MessageID
field to the request value. This allows the client application to track and determine the proper
processing action when a server response is received.
If the server responds with a MessageID
value of -1
then there was an error processing the request. In this case,
the connection will be closed. Reasons this may happen is an invalid MessageID
or a corrupt message.
RequestValue
and ReturnValue
are a string fields but the DataType
determines how it should be interpreted.
It may be as an actual string, an integer or a JSON string that needs deserialized.
DataType
of the SERVER_REQUEST
is BB_DATA_TYPE_JSON
the RequestValue
must be a serialized ACTION
object.{
Action: (int)
SubAction: (int)
ValueString: (str)
}
The ACTION
object contains both an Action
and SubAction
fields that will further describe how to interpret the ValueString
field.
The following are Action
and SubAction
combinations.
BB_SERVER_ACTION_STATUS = 0
BB_SERVER_STATUS_SUB_ACTION_CURRENT = 1
BB_SERVER_STATUS_SUB_ACTION_SHUTDOWN = 2
BB_SERVER_STATUS_SUB_ACTION_LOG = 3
BB_SERVER_ACTION_OPTIONS = 1
BB_SERVER_OPTIONS_SUB_ACTION_SET_OP_VALUE = 1
BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE = 2
BB_SERVER_OPTIONS_SUB_ACTION_REINIT = 3
BB_SERVER_ACTION_BROWSER = 2
BB_SERVER_BROWSER_SUB_ACTION_SYS_QUERY = 1
BB_SERVER_BROWSER_SUB_ACTION_LIST = 2
BB_SERVER_BROWSER_SUB_ACTION_ADD = 3
BB_SERVER_BROWSER_SUB_ACTION_DELETE = 4
BB_SERVER_BROWSER_SUB_ACTION_UPDATE = 5
BB_SERVER_ACTION_SPEECH = 3
BB_SERVER_SPEECH_SUB_ACTION_LIST = 1
BB_SERVER_SPEECH_SUB_ACTION_CREATE = 2
BB_SERVER_SPEECH_SUB_ACTION_DELETE = 3
BB_SERVER_SPEECH_SUB_ACTION_UPDATE = 4
BB_SERVER_ACTION_FONT = 4
BB_SERVER_FONT_SUB_ACTION_LIST = 1
BB_SERVER_FONT_SUB_ACTION_CREATE = 2
BB_SERVER_FONT_SUB_ACTION_DELETE = 3
BB_SERVER_FONT_SUB_ACTION_UPDATE = 4
BB_SERVER_FONT_SUB_ACTION_INSTALL = 5
BB_SERVER_ACTION_DNS = 5
BB_SERVER_DNS_SUB_ACTION_SYNC = 1
BB_SERVER_DNS_SUB_ACTION_LIST = 2
BB_SERVER_DNS_SUB_ACTION_CREATE = 3
BB_SERVER_DNS_SUB_ACTION_DELETE = 4
BB_SERVER_DNS_SUB_ACTION_UPDATE = 5
BB_SERVER_DNS_SUB_ACTION_SINKHOLE_SEARCH = 6
BB_SERVER_ACTION_PROXY = 6
BB_SERVER_PROXY_SUB_ACTION_LIST = 1
BB_SERVER_PROXY_SUB_ACTION_CREATE = 2
BB_SERVER_PROXY_SUB_ACTION_DELETE = 3
BB_SERVER_PROXY_SUB_ACTION_UPDATE = 4
BB_SERVER_ACTION_VPN = 7
BB_SERVER_VPN_SUB_ACTION_LIST = 1
BB_SERVER_VPN_SUB_ACTION_CREATE = 2
BB_SERVER_VPN_SUB_ACTION_DELETE = 3
BB_SERVER_VPN_SUB_ACTION_UPDATE = 4
BB_SERVER_ACTION_BUBBLE = 8
BB_SERVER_BUBBLE_SUB_ACTION_LIST_SAVED = 1
BB_SERVER_BUBBLE_SUB_ACTION_LIST_RUNNING = 2
BB_SERVER_BUBBLE_SUB_ACTION_CREATE = 3
BB_SERVER_BUBBLE_SUB_ACTION_DELETE = 4
BB_SERVER_BUBBLE_SUB_ACTION_UPDATE = 5
BB_SERVER_BUBBLE_SUB_ACTION_DETAILS = 6
BB_SERVER_BUBBLE_SUB_ACTION_GENERATE = 7
BB_SERVER_BUBBLE_SUB_ACTION_SHORTCUT = 8
BB_SERVER_BUBBLE_SUB_ACTION_LAUNCH = 9
BB_SERVER_BUBBLE_SUB_ACTION_TERMINATE = 10
BB_SERVER_BUBBLE_SUB_ACTION_NETWORK = 11
BB_SERVER_BUBBLE_SUB_ACTION_READY = 12
BB_SERVER_BUBBLE_SUB_ACTION_FAILED = 13
BB_SERVER_BUBBLE_SUB_ACTION_SHUTDOWN = 14
BB_SERVER_BUBBLE_SUB_ACTION_DEBUG_PORT = 15
BB_SERVER_ACTION_LAUNCH = 9
BB_SERVER_LAUNCH_SUB_ACTION_LIST = 1
BB_SERVER_LAUNCH_SUB_ACTION_CREATE = 2
BB_SERVER_LAUNCH_SUB_ACTION_DELETE = 3
BB_SERVER_LAUNCH_SUB_ACTION_UPDATE = 4
There are numerous other objects that are defined for specific purposes however, some are more generic and are used across operations. Here are a list of objects that will be found referenced by multiple operations.
{
Code: (str) //DE
Name: (str) //Germany
}
{
ID: (long) //2057
Name: (str) //English - United Kingdom
Code: (str) //en-GB
}
{
Pre: (str)
Post: (str)
Shutdown: (str)
}
BB_OS_DISABLED = 0
BB_OS_WIN7 = 1
BB_OS_WIN8 = 2
BB_OS_WIN81 = 4
BB_OS_WIN10 = 8
BB_OS_WIN11 = 16
BB_OS_CUSTOM = 32
As mentioned, the DataType
field determines how to interpret the RequestValue
and ReturnValue
string.
The following are possible DataType
values.
BB_DATA_TYPE_STRING = 1
BB_DATA_TYPE_INTEGER = 2
BB_DATA_TYPE_JSON = 3
BB_DATA_TYPE_BINARY = 4
BB_DATA_TYPE_BASE64 = 5
BB_DATA_TYPE_STRING
means the value is just a regular string and should not be interpreted in any other way.
BB_DATA_TYPE_INTEGER
means the value is a string representation of a numeric value.
BB_DATA_TYPE_JSON
means that value is a serialized JSON object. The exact object is determined by other fields
or the corresponding MessageID
.
BB_DATA_TYPE_BINARY
type is a hex string represenation of binary data. Each hex must be 2 characters (i.e. '0A' not just 'A'). Once decoded it will be treated as a regular string.
BB_DATA_TYPE_BASE64
is a Base64 string that should be decoded and also treated as a regular string.
There are a wide range of error code values that may be returned. A value of BB_ERROR_NO_ERROR (0)
means an operation was
successful, however anything less than zero indicates an error. When processing SERVER_RESPONSE
, the first value that should
be checked is the ErrorCode
field to determine success or failure. Some of the more common error codes include the following:
BB_ERROR_NO_ERROR = 0
BB_ERROR_GENERIC_ERROR = -1
BB_ERROR_INVALID_PARAMETER = -3
BB_ERROR_INVALID_MODE = -26
BB_ERROR_CREATING_PROCESS = -30
BB_ERROR_NOT_READY = -34
BB_ERROR_LICENSE_INVALID = -361
Browser Bubble Pro
will send status messages to the client in response to certain
events. But the client can also send some of these messages back to the server to control
the application.
{
License: (int)
Drivers: (int)
Browsers: (int)
Options: (int)
InitErrors: (dict[int, str])
Update: (int)
UpdateVersion: (str)
UpdateMessage: (str)
SavedBubbles: (int)
RunningBubbles: (int)
}
The CURRENT_STATE
object provides a snapshot of the current application state. It will
be sent to the client during initialization, reinitialization, if a Bubble
action is attempted
without Browser Bubble Pro
being ready or in response to a client request.
License, Drivers, Browsers and Options
are error code values. Any negative value indicates that
an error was encountered and that particular aspect of Browser Bubble Pro
is not ready. For example,
if the license was not valid then License
will be set to BB_ERROR_LICENSE_INVALID
.
InitErrors
is a dictionary that contains the latest errors, if any, in plain English.
Update and UpdateMessage
are used to indicate if an update is available for download. If Update
is 1
, then an update is available and UpdateMessage
may contain information about the update.
SavedBubbles and RunningBubbles
are just used to provide a quick snapshot of what has been configured
and what is currently executing.
BB_SERVER_STATUS_SUB_ACTION_SHUTDOWN
is sent by the client to close Browser Bubble Pro
.
ACTION.ValueString
must be set to "shutdown"
to confirm the shutdown request. Right before
the connection is finally closed, Browser Bubble Pro
will send this message back to the client to
indicate it is in fact closing. Any running Bubbles
will be handled according to the global options.
Browser Bubble Pro
will send BB_SERVER_STATUS_SUB_ACTION_LOG
messages to the client in response
to errors. This provides some help with debugging issues that may arise. ACTION.ValueString
will be a
serialized LOG_MESSAGE
object.
{
ErrorCode: (int)
Level: (int)
Location: (str)
Message: (str)
}
BB_LOG_LEVEL_DEBUG = 1
BB_LOG_LEVEL_ERROR = 2
BB_LOG_LEVEL_INFO = 3
BB_LOG_LEVEL_WARN = 4
BB_LOG_LEVEL_PRIORITY = 5
Through the API, global options can be queried or set. Some of these options must be set before Browser Bubble Pro
can properly
function. Others can be toggled as needed based on requirements. To set or get an option value, the Action
field will be equal
to BB_SERVER_ACTION_OPTIONS
while the SubAction
field will either be BB_SERVER_OPTIONS_SUB_ACTION_SET_OP_VALUE
or
BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
. Finally the ValueString
will be a serialized string of the OPTIONS_XET
object.
OPTIONS_XET
is not a misspelling. The structure is used for both GET
and SET
operations, hence the XET
name.
{
Op: (int)
SubOp: (int)
Data: (str)
}
The Op
field of OPTIONS_XET
determines what the SubOp
and Data
fields represent. The following are valid Op
values.
BB_OPTIONS_XET_FLAGS = 1
BB_OPTIONS_XET_LICENSE = 2
BB_OPTIONS_XET_ADAPTER = 3
BB_OPTIONS_XET_ADAPTER_LIST = 4
BB_OPTIONS_XET_GLOBAL_DNS = 5
BB_OPTIONS_XET_GLOBAL_AEX = 6
The default network adapter is needed by Browser Bubble Pro
for network routing purposes so it must be set before any Bubbles
can launch. In fact, Browser Bubble Pro
doesn't fully initialize until a default adapter has been specified.
The default adapter can be set during program start-up by passing the -adapter
flag through the command line. There are
two ways to use this switch. -adapter auto
will make Browser Bubble
automatically identify the default
network adapter. Otherwiwse -adapter "adapter name"
can be passed where "adapter name" is a valid network adapater name.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_SET_OP_VALUE
, the OPTIONS_XET.Data
field must be a valid adapter name on the system. OPTIONS_XET.SubOp
is ignored.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
Browser Bubble Pro
will return a JSON encoded ADAPTER
object based on the currently set default network adapter in the SERVER_RESPONSE.ReturnValue
field.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
then Browser Bubble Pro
will return a serialized JSON list of ADAPTER
objects in the SERVER_RESPONSE.ReturnValue
field.
The command is ignored if ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_SET_OP_VALUE
.
{
Name: (str)
MAC: (str)
IP4: (str)
IP6: (str)
Gateway: (dict[str, str])
IsDefault (int)
IsWifi: (int)
}
The global anti-exploit setting can be toggled or queried using the BB_OPTIONS_XET_GLOBAL_AEX
flag.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
the SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and the SERVER_RESPONSE.ReturnValue
will be either "1"
for
on or "0"
for off.
To set the global anti-exploit setting, the OPTIONS_XET.SubOp
should be set to either 1
for on or 0
for off.
OPTIONS_XET.Data
is ignored.
The global DNS setting can be toggled or queried using the BB_OPTIONS_XET_GLOBAL_DNS
flag.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
the SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and the SERVER_RESPONSE.ReturnValue
will be either "1"
for
on or "0"
for off.
To set the global DNS setting, the OPTIONS_XET.SubOp
should be set to either 1
for on or 0
for off.
OPTIONS_XET.Data
is ignored.
The global options flags can set or queried using the BB_OPTIONS_XET_FLAGS
flag.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
the SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and the SERVER_RESPONSE.ReturnValue
will be a bitwise combination of the flags defined below.
To set the global options, the OPTIONS_XET.SubOp
should be a bitwise combination of the flags defined below.
OPTIONS_XET.Data
is ignored.
BB_OPTIONS_FLAG_AUTO_BUBBLE = 1
BB_OPTIONS_FLAG_BLOCK_NET = 2
BB_OPTIONS_FLAG_TERMINATE_ON_EXIT = 4
BB_OPTIONS_FLAG_DELETE_PROFILE = 8
BB_OPTIONS_FLAG_USE_VHD_SANDBOX = 16
BB_OPTIONS_FLAG_VERBOSE_DNS_LOG = 32
BB_OPTIONS_FLAG_AUTO_BUBBLE
: If this option is enabled, then when any enabled browser is executed the user
will be notified to pick a Bubble
. If this option is disabled then only browsers executed through this
application or available shortcuts will be run in a Bubble
. This flag is ignored in Headless
mode.
BB_OPTIONS_FLAG_BLOCK_NET
: For each new Bubble
, browser network connectivity is blocked until explicity
enabled. This can be enabled with the BB_SERVER_BUBBLE_SUB_ACTION_NETWORK
message described below.
BB_OPTIONS_FLAG_TERMINATE_ON_EXIT
: Browser Bubble
enabled browsers will be automatically closed when
Browser Bubble
closes.
BB_OPTIONS_FLAG_DELETE_PROFILE
: If enabled, browser data will be deleted when the browser closes.BB_OPTIONS_FLAG_USE_VHD_SANDBOX
: By default, Browser Bubble
uses VHD mount points for the sandbox.
If there are compatability issues with VHD, then Browser Bubble
can revert back to use the regulard file system.
BB_OPTIONS_FLAG_VERBOSE_DNS_LOG
: Simply provides more insight into DNS resolution if a Bubble
is using the Browser Bubble
resolver.
The Browser Bubble Pro
license should be set during installation. It can be also be provided via the command line when Browser Bubble Pro
starts using the -license
switch followed by the license key. Here is an example of how to use this switch:
Browser Bubble Pro
will not create or launch Bubbles
until a valid license has been provided. Multiple license types are available
to include single-use, multi-use or site-use. If the license is not verified, any attempt to create or launch a Bubble
will
return a STATE
object with the License
field set to BB_ERROR_LICENSE_INVALID (-361)
.
If a valid license is not provided during install or at start-up, then the license key can be set or queried by setting the OPTIONS_XET.Op
field
to BB_OPTIONS_XET_LICENSE
. When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_GET_OP_VALUE
then the
SERVER_RESPONSE.ReturnValue
field will return a serialized JSON string of the LICENSE
object.
When ACTION.SubAction
is BB_SERVER_OPTIONS_SUB_ACTION_SET_OP_VALUE
then the OPTIONS_XET.Data
field must be a valid license key.
The OPTIONS_XET.SubOp
field is ignored.
If the license was successfully written, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
The license is not automatically validated when set. A follow-on reinitialization command (ACTION.SubAction
set to
BB_SERVER_OPTIONS_SUB_ACTION_REINIT
) must be sent.
LICENSE
object is used to provide information about the current license.
{
LicenseKey: (str)
Status: (int)
Expires: (str)
Entitlements: (int)
EndpointCount: (int)
}
The Status
field describes the current license state.
BB_LICENSE_STATUS_INVALID = 0
BB_LICENSE_STATUS_VALID = 1
BB_LICENSE_STATUS_TRIAL = 2
BB_LICENSE_STATUS_EXPIRED = 3
BB_LICENSE_STATUS_REVOKED = 4
The Entitlements
field describes the how the current license can be used in combination with the EndpointCount
field.
BB_LICENSE_ENTITLEMENT_LIGHT = 1
BB_LICENSE_ENTITLEMENT_PRO = 2
BB_LICENSE_ENTITLEMENT_MULTI_SYSTEM = 4
BB_LICENSE_ENTITLEMENT_SERVER_ENABLED = 8
When Browser Bubble Pro
loads, it performs an initialization that verifies settings and validates the license.
If anything fails, it stays in a waiting state until the settings are updated or license is validated. In this state,
no Bubbles
can be launched.
Once changes have been made, the BB_SERVER_OPTIONS_SUB_ACTION_REINIT
action can be sent to restart the
initialization process. Again, settings will be verified and license checked if needed. Reinitialization is an asynchronous
procedure in that a message will be returned right away but the initialization operation will be queued and eventually
executed.
Browser Bubble Pro
will send the client a CURRENT_STATE
message when the reinitialization is complete to indicate if it was
successful or if another error occurred.
Here's an example that shows the structure for the possible options flags when setting new values. Getting values will be similar.
SERVER_REQUEST
Version:
1
MessageID:
1
DataType:
BB_DATA_TYPE_JSON
RequestValue:
ACTION
Action:
BB_SERVER_ACTION_OPTIONS
SubAction:
BB_SERVER_OPTIONS_SUB_ACTION_SET_OP_VALUE
ValueString:
OPTIONS_XET
Op:
BB_OPTIONS_XET_ADAPTER
SubOp:
Ignored
Data:
"Network Adapter Name"
OPTIONS_XET
Op:
BB_OPTIONS_XET_GLOBAL_AEX
SubOp:
1 or 0
Data:
Ignored
OPTIONS_XET
Op:
BB_OPTIONS_XET_GLOBAL_DNS
SubOp:
1 or 0
Data:
Ignored
OPTIONS_XET
Op:
BB_OPTIONS_XET_FLAGS
SubOp:
63
Data:
Ignored
OPTIONS_XET
Op:
BB_OPTIONS_XET_LICENSE
SubOp:
Ignored
Data:
"License Key"
There are additional configurations that can be made beyond the options described above. These include
building font and speech profiles as well as creating launch actions for pre and post Bubble
execution.
Browser Bubble Pro
is able to modify a browser's font profile to match an old Windows version or can
add or remove random font files to create unique profiles. It's very important to understand how
powerful font tracking can be so make sure you understand the implications.
Browser Bubble Pro
cannot redistribute font files from previous Windows versions.
In order to spoof font profiles from other Windows versions, you first must install the fonts so Browser Bubble
knows where to find them. To install, pass a FONT_INSTALL
object in the ACTION.ValueString
with OS
set to an OS constant and set FontPath
to a fully qualified directory path that contains
all of the fonts for that OS. Browser Bubble
has a list of fonts for older Windows versions and will process
the font files found in FontPath
according to the expected list.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
{
OS: (int)
FontPath: (str)
}
Custom font lists can also be created containing specific fonts that are already installed on the system. When Browser Bubble
loads for the first time, it does an inventory of the installed system fonts and these can then be placed into custom lists for a Bubble
to use.
To query the list of created profiles, set ACTION.ValueString
to the string value of BB_FONT_OP_PROFILE
.
The SERVER_REPONSE.ReturnValue
will be a FONT_RESPONSE
object with Op
set to BB_FONT_OP_PROFILE
and Data
set to a serialized list of FONT_PROFILE
objects.
To query the list of installed fonts, set ACTION.ValueString
to the string value of BB_FONT_OP_FONT_ITEM
.
The SERVER_REPONSE.ReturnValue
will be a FONT_RESPONSE
object with Op
set to BB_FONT_OP_FONT_ITEM
and Data
set to a serialized list of FONT_ITEM
objects.
BB_FONT_OP_PROFILE = 1
BB_FONT_OP_FONT_ITEM = 2
{
Op: (int)
Data: (str)
}
{
FontID: (long)
Name: (str)
Fonts: (list[FONT_ITEM])
}
{
FontFileID: (long)
FontName: (str)
FontPath: (str)
}
To create a new font profile, simply set ACTION.ValueString
to the name of the new profile.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and SERVER_REPONSE.ReturnValue
will be a string representation of the id
of the new profile.
To delete a font profile, simply set ACTION.ValueString
to the string value of the ID of the profile you want to
delete. Note that actual font files are not deleted.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Once a font profile is created, you can update it as needed. A font profile update requires that all font items be provided
at the same time. So, to update a profile set ACTION.ValueString
to a serialized FONT_PROFILE
object
that contains all of the fonts, set via FONT_ITEM
objects, in the list. The existing font items in the profile
will be replaced with whatever is passed.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Launch Actions provide a way to execute an arbitrary program before a Bubble
loads, when a Bubble
has started or
when a Bubble
closes. An example use-case would be to connect to a specific VPN before it loads and disconnect
when the Bubble
closes. But whatever the use-case, Launch Actions provide additional flexibility and extensibility
to Browser Bubble Pro
.
To get a list of currently configured launch actions, set ACTION.SubAction
to BB_SERVER_LAUNCH_SUB_ACTION_LIST
.
The SERVER_RESPONSE.ReturnValue
will be a serialized list of LAUNCH_ACTION
objects.
{
ID: (long)
Name: (str)
Flags: (int)
EvalValue: (str)
ProcessPath: (str)
CommandLine: (str)
Timeout: (int)
}
The ProcessPath
field should be a fully qualified path value that will be executed. Note that
the process will run elevated.
If CommandLine
is not empty, it will be passed to the process when started.
Timeout
is interpreted as the number of seconds Browser Bubble
will wait
for the process to finish executing. If the timeout is reached, it is considered a failed action
and may cause the Bubble
to be cancelled depending on the other configurations.
// Action is defined to run before the Bubble launches.
BB_LAUNCH_ACTION_OP_START_PRE = 1
// Action is defined to run right after the Bubble launches.
BB_LAUNCH_ACTION_OP_START_POST = 2
// Action is defined to run after the Bubble shuts down.
BB_LAUNCH_ACTION_OP_START_CLOSE = 4
// Browser Bubble will not wait for the process to finish.
BB_LAUNCH_ACTION_OP_WAIT_NONE = 8
// Browser Bubble will wait for the process to finish or until the 'Timeout' value is reached.
BB_LAUNCH_ACTION_OP_WAIT_COMPLETE = 16
// Browser Bubble will evaluate the output of the process in relation to the set 'EvalValue' field.
BB_LAUNCH_ACTION_OP_WAIT_EVAL = 32
// Output must match 'EvalValue' exactly.
BB_LAUNCH_ACTION_OP_EVAL_IS = 64
// Output must not match 'EvalValue' exactly.
BB_LAUNCH_ACTION_OP_EVAL_IS_NOT = 128
// Output must contain 'EvalValue'
BB_LAUNCH_ACTION_OP_EVAL_CONTAINS = 256
// Output must not contain 'EvalValue'
BB_LAUNCH_ACTION_OP_EVAL_CONTAINS_NOT = 512
// If the eval returns TRUE or the Timeout is reached then the Bubble will be cancelled.
// If the eval returns FALSE then the Bubble will continue to launch.
// This only applies for Pre actions.
BB_LAUNCH_ACTION_OP_ACTION_CANCEL = 1024
// If the eval returns FALSE or the Timeout is reached then the Bubble will continue to launch.
// If the eval returns TRUE, then the Bubble will continue to launch.
// This only applies for Pre actions.
BB_LAUNCH_ACTION_OP_ACTION_IGNORE = 2048
Launch action results can be queried from the Bubble
that ran them. The LAUNCH_RESULT
object
is used to pass information about the launch action result.
{
ErrorCode: (int)
Output: (str)
Eval: (int)
}
The ErrorCode
field will be the exit code returned by the launch action process. The Output
field will contain captured data from the process and the Eval
field will either be 1
or 0
depending on if the evaluation was true or false.
To create a new action, set the ACTION.ValueString
to a serialized LAUNCH_ACTION
object.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and SERVER_REPONSE.ReturnValue
will be a string representation of the id
of the new action.
To delete an action, set the ACTION.ValueString
to a the string representation of the id of the
action you want to delete.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Updating an action is just like creating a new one except that the ID
field must be set with the id
value you want to update.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Speech profiles allow for Bubbles
to project custom speech voices. Speech commands
use the SPEECH
object and associated op codes.
The SPEECH
object is deserialized from the ACTION.ValueString
field.
{
Op: (int)
ID: (long)
Data: (str)
}
BB_SPEECH_PROFILE = 1
BB_SPEECH_VOICE = 2
BB_SPEECH_PROFILE_VOICES = 3
For the following commands, the SPEECH.Op
determines if the operation should be performed
on the speech profile, a speech voice or a profile of voices. The SPEECH.Data
field will be
a JSON encoded object that corresponds to the appropriate Op
value.
When SPEECH.Op
is BB_SPEECH_PROFILE
then SERVER_RESPONSE.ReturnValue
will
be a serialized list of all configured SPEECH_PROFILE
objects. SPEECH.ID
is ignored.
{
ID: (long)
Name: (str)
}
When SPEECH.Op
is BB_SPEECH_VOICE
then SERVER_RESPONSE.ReturnValue
will
be a serialized list of all configured SPEECH_VOICE
objects. SPEECH.ID
is ignored.
{
ID: (long)
Name: (str)
Language: (LANGUAGE)
Age: (int)
Sex: (int)
}
BB_SPEECH_AGE_ADULT = 1
BB_SPEECH_AGE_CHILD = 2
BB_SPEECH_SEX_FEMALE = 1
BB_SPEECH_SEX_MALE = 2
When SPEECH.Op
is BB_SPEECH_PROFILE_VOICES
then SPEECH.ID
must be set to the
id value of the profile you want to get voices for. If the profile id is valid, SERVER_RESPONSE.ReturnValue
will be a serialized list of all configured SPEECH_VOICE
objects for that profile.
To create a new speech profile, set SPEECH.Op
to SPEECH.Data
field to the name of the profile. If successful, SERVER_RESPONSE.ReturnValue
will be the serialized SPEECH
object that was sent but with the SPEECH.ID
value set.
To create a new speech voice, set SPEECH.Op
to SPEECH.Data
field to a serialized SPEECH_VOICE
object. If successful, SERVER_RESPONSE.ReturnValue
will be the serialized SPEECH
object that was sent but with the SPEECH.ID
value set.
To assign a voice to a profile, set SPEECH.Op
to SPEECH.ID
to the
speech profile id and finally set SPEECH.Data
to the string representation of the voice id that should be added.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
To delete a profile or voice , set SPEECH.Op
to the appropriate flag along with
SPEECH.ID
to the id of the object to delete. In the case of deleting a voice from a
profile, it is similar to adding a voice in that SPEECH.ID
is the speech profile id while
SPEECH.Data
is the string representation of the voice id to be removed.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Only a voice profile can be updated. To update an existing voice is a lot like creating a new one except that
SPEECH_VOICE.ID
must be set to a valid voice id. SPEECH.ID
should also be set to the
same id value.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Browser Bubble Pro
works with the existing browsers on the system to provide added privacy and security controls. There is no special
browser requirement to make Browser Bubble Pro
work other than being either Mozilla or Chromium based and 64-bit.
Browser Bubble Pro
has built-in support for the most popular browsers. The support includes having pre-made icons and the ability to
detect the installation and profile directory. If the browser you primarily use is not listed, you can still add the browser for Browser Bubble Pro
to use
as long as it meets the two conditions above.
Here are the list of browser that Browser Bubble Pro
currently has built-in support for.
Those browsers have a defined type value which is used for internal purposes. And as mentioned, you can add
additional browsers that Browser Bubble Pro
does not natively support however, there are
only 8 spots available. The following are the defined BrowserType
values.
BB_BROWSER_FIREFOX = 1
BB_BROWSER_EDGE = 2
BB_BROWSER_CHROME = 4
BB_BROWSER_BLISK = 8
BB_BROWSER_BRAVE = 16
BB_BROWSER_CANARY = 32
BB_BROWSER_CHROMIUM = 64
BB_BROWSER_IRIDIUM = 128
BB_BROWSER_IRON = 256
BB_BROWSER_OPERA = 512
BB_BROWSER_VIVALDI = 1024
BB_BROWSER_FIREFOX_NIGHTLY = 2048
BB_BROWSER_EPIC = 4096
//User defined browsers.
BB_BROWSER_EXTRA_1 = 262144
BB_BROWSER_EXTRA_2 = 524288
BB_BROWSER_EXTRA_3 = 1048576
BB_BROWSER_EXTRA_4 = 2097152
BB_BROWSER_EXTRA_5 = 4194304
BB_BROWSER_EXTRA_6 = 8388608
BB_BROWSER_EXTRA_7 = 16777216
BB_BROWSER_EXTRA_8 = 33554432
The BB_SERVER_BROWSER_SUB_ACTION_SYS_QUERY
command is used to query the list of
browsers installed on the system that Browser Bubble Pro
is configured to identify.
Note that Browser Bubble
tries to locate the default ProfilePath
for the
particular browser. This may or may not be the path actually used. Furthermore, a browser may
have multiple profiles configured but this will only return the first path found.
If the command is successful, the SERVER_RESPONSE.ReturnValue
will be a serialized list of
BROWSER_INSTALL
objects.
{
BrowserType: (int)
BrowserName: (str)
FilePath: (str)
ProfilePath: (str)
ProfileName: (str)
}
The BB_SERVER_BROWSER_SUB_ACTION_LIST
command is used to query the list of
browsers that have been configured.
If the command is successful, the SERVER_RESPONSE.ReturnValue
will be a serialized list of
BROWSER_PROFILE
objects.
{
ID: (long)
Name: (str)
BrowserType: (int)
FilePath: (str)
ProfilePath: (str)
Enabled: (int)
}
To add a browser set ACTION.ValueString
to a serialized BROWSER_PROFILE
object.
BROWSER_PROFILE.BrowserType
should indicate the type of browser it is while BROWSER_PROFILE.FilePath
is the fully qualified path to the browser. BROWSER_PROFILE.ProfilePath
should also be a fully qualified path to a
valid profile for the browser.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and SERVER_REPONSE.ReturnValue
will be a string representation of the id
of the new entry.
To delete a browser profile, set ACTION.ValueString
to the string representation of the browser-bubble id that should be deleted.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Certain browsers details can be updated. Any update is wrapped in a BROWSER_OP
object where BROWSER_OP.Op
is one of the valid values. To set the browser enable status, set
BROWSER_OP.Op
to BB_BROWSER_UPDATE_ENABLE
, BROWSER_OP.ID
to a valid
browser id and set BROWSER_OP.Data
to either "1"
for enabled or "0"
for disabled. Note that they are string values.
To update the browser profile path, set BROWSER_OP.Op
to BB_BROWSER_UPDATE_PROFILE
,
BROWSER_OP.ID
to a valid browser id and set BROWSER_OP.Data
to a fully qualified
profile path.
{
Op: (int)
ID: (long)
Data: (str)
}
BB_BROWSER_UPDATE_ENABLE = 1
BB_BROWSER_UPDATE_PROFILE = 2
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Browser Bubble Pro
allows for custom DNS settings for each Bubble
. This provides
for complete control over DNS leaks as well as DNS privacy. Secure DNS can be applied using the
browser's built-in settings or can be performed by Browser Bubble Pro
itself. Additionally,
Browser Bubble Pro
can filter DNS requests in order to sinkhole ad networks or other undesirable
domains and IPs.
{
DNS: (int)
ID: (long)
Data: (str)
}
{
ProviderID: (long)
Provider: (str)
ServerID: (long)
Country: (str)
DNSType: (int)
Address: (str)
Port: (int)
}
BB_DNS_TYPE_DNS_OVER_TLS = 1
BB_DNS_TYPE_DNS_OVER_HTTPS = 2
Browser Bubble
can sync both DNS providers and DNS sinkholes. Both of these sync options provide a
quick way to add DNS functionality. Both can be synced using the DNS_OP
object. DNS_OP.DNS
should be set to 1
if the sync is related to the DNS providers. Otherwise, sinkholes will be synced.
There are two ways that sinkholes can be synced. First is from an online list currently provided by https://pgl.yoyo.org/as/iplist.php
.
If you prefer to use this list, then make sure DNS_OP.Data
is blank. However, Browser Bubble
can also
import a local list of IP and domains stored on the system. To sync with a local ist, DNS_OP.Data
should be
set to the fully qualified path of the list.
The format for the list is simple text file with each line being a unique entry. The following
shows valid line entries.
# Line is ignored
domain.com
1.2.3.4
5.6.7.8 # example.com
DNS_OP.ID
is are ignored for both sync types.
SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
A list of configured DNS servers can be queried by simply passing BB_SERVER_DNS_SUB_ACTION_LIST
in the
ACTION.SubAction
field. If the command is successful, the SERVER_RESPONSE.ReturnValue
will be a serialized list of DNS_SERVER
objects.
To add a new DNS server, simply set DNS_OP.DNS
to 1
and DNS_OP.Data
to a serialized
DNS_SERVER
object. DNS_OP.ID
and DNS_SERVER.ServerID
are ignored.
To add a new DNS sinkhole entry, set DNS_OP.DNS
to 0
and DNS_OP.Data
to either a valid
domain or IP address. DNS_OP.ID
is ignored.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_JSON
and SERVER_REPONSE.ReturnValue
will be a serialized DNS_OP
object.
DNS_OP.DNS
will be set to the appropriate value based on the requested operation. For adding DNS servers, DNS_OP.ID
will
be the id of the new entry. Sinkholes do not have associated IDs so the value will just be 0
.
Deleting a DNS server or DNS sinkhole entry involves setting DNS_OP.DNS
to an appropriate value while also setting the
either the DNS_OP.ID
field to the correct server entry id or the DNS_OP.Data
field of the IP or domain.
Because the sinkhole list may be 10's of thousands of entries, the full list cannot be queried. Instead it can be searched to determine
if a value is present. To perform a sinkhole serach, set ACTION.ValueString
to a domain or IP address.
If the command was successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
and SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
. If the value was found, SERVER_REPONSE.ReturnValue
will "1"
otherwise,
if it will be "0"
if not.
Proxying is provided through the browser's built-in proxy settings. When using Firefox, proxy settings can be dynamically changed however, Chromium browsers pass the proxy information via the command-line and therefore cannot be changed dynamically.
{
ID: (long)
ProxyName: (str)
Country: (COUNTRY)
IP: (str)
Port: (int)
ProxyType: (int)
Flags: (int)
}
BB_PROXY_TYPE_HTTPS = 1
BB_PROXY_TYPE_SOCKS4 = 2
BB_PROXY_TYPE_SOCKS5 = 3
A list of configured proxy servers can be queried by simply passing BB_SERVER_PROXY_SUB_ACTION_LIST
in the
ACTION.SubAction
field. The SERVER_RESPONSE.ReturnValue
will be a serialized list of PROXY_SERVER
objects.
To add a new proxy server, set ACTION.ValueString
to a serialized PROXY_SERVER
object.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and SERVER_REPONSE.ReturnValue
will be a string representation of the id
of the new entry.
To delete a proxy server, set ACTION.ValueString
to the string representation of the proxy id that should be deleted.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Updating a proxy server is just like adding except that the PROXY_SERVER.ID
must be a valid id value.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Using a VPN provides an extra layer of protection for unprotected connections (although HTTPS is everywhere these days)
but a VPN also helps to make a Bubble
profile more realistic. Many fingerprinting sites will
geo-locate the IP address and compare it to the browsers language, timezone, and DNS. When they disagree, the
fingerprinter will assume there is some type of spoofing going on. Using a VPN based in the country that matches
the Bubble
profile settings adds an extra bit of realism for your browsing.
{
ID: (long)
Provider: (str)
Country: (COUNTRY)
Adapter: (str)
Address: (str)
}
A list of configured proxy servers can be queried by simply passing BB_SERVER_VPN_SUB_ACTION_LIST
in the
ACTION.SubAction
field. The SERVER_RESPONSE.ReturnValue
will be a serialized list of VPN_SERVER
objects.
To add a new VPN server, set ACTION.ValueString
to a serialized VPN_SERVER
object.
VPN_SERVER.ID
and VPN_SERVER.Address
are ignored.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and SERVER_REPONSE.ReturnValue
will be a string representation of the id
of the new entry.
To delete a VPN server, set ACTION.ValueString
to the string representation of the VPN id that should be deleted.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
Updating a VPN server is just like adding except that the VPN_SERVER.ID
must be a valid id value.
VPN_SERVER.Address
are ignored.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
A primary capability of Browser Bubble
is to spoof your fingerprint to prevent malicious trackers
from following you around the web as you browse. By spoofing select values, Browser Bubble
disrupts
Javascript based fingerprinting that sites can use instead of relying on cookies. It's a much more devious and
silent way of tracking user behavior and Browser Bubble
is determined to defeat it.
The following objects and flags are used when configuring Bubbles
. Not all spoof settings
have dedicated objects or flags as they just require a single value.
More details about spoof settings are described in the Bubble section.
{
Flags: (int)
Values1: (int)
Values2: (int)
Values3: (int)
}
BB_BATTERY_FLAG_PLUGGED_IN = 1
BB_BATTERY_FLAG_BATTERY_POWER = 2
BB_BATTERY_FLAG_NO_BATTERY = 4
The Values1, Values2 and Values3
values depend on the Flags
field.
If battery spoofing is enabled, then Values1
is the percentage that the battery has left.
This is represented as an integer between 0 and 100.
If Flags
is BB_BATTERY_FLAG_BATTERY_POWER
then Values2
is the
number of seconds the battery has left while Values3
is the number of seconds before
it will be fully charged.
If Flags
is not BB_BATTERY_FLAG_BATTERY_POWER
then Values2
and
Values3
are ignored.
{
Flags: (int)
Extra: (long)
}
BB_FONT_OPS_DISABLE = 1
BB_FONT_OPS_REMOVE_ALL_BUT_1 = 2
BB_FONT_OPS_REMOVE_ALL_BUT_DEFINED = 4
BB_FONT_OPS_SET_OS = 8
BB_FONT_OPS_SET_CUSTOM = 16
The Flags
field is used to describe the value that the Extra
field may
contain.
if Flags
is BB_FONT_OPS_REMOVE_ALL_BUT_DEFINED
then Extra
must contain a positive integer less than the total number of fonts installed on the machine.
Browser Bubble
will remove all fonts but leave the defined number behind.
If Flags
is BB_FONT_OPS_SET_OS
then Extra
will
be an OS constant describe above.
If Flags
is BB_FONT_OPS_SET_CUSTOM
then Extra
is defined as the
custom font id profile that was previously created.
{
Flag: (int)
Offset: (int)
}
BB_MATH_SPOOFING_OFF = 0
BB_MATH_SPOOFING_RANDOM = 1
BB_MATH_SPOOFING_SET = 2
Math spoofing is only applicable to Firefox because previous changes made to Chromium means that
math spoofing no longer works for those browsers. This is because Chromium switched to a standardized
math library so there is no more variation between OS and browser versions. This was done specifically
to prevent math based fingerprinting.
But for Firefox, spoofing math still applies. If Flag
is BB_MATH_SPOOFING_SET
then the Offset
field should contain an integer value. This value is used to seed a random
number generator to add noise to math calculations. Offset
is ignored for other Flag
values.
{
Flags: (int)
SetVal: (int)
}
BB_MEDIA_DEVICE_SPOOF_OFF = 0
BB_MEDIA_DEVICE_ENUM_RANDOM = 1
BB_MEDIA_DEVICE_ENUM_BLOCK = 2
BB_MEDIA_DEVICE_RENAME_NAMES = 4
BB_MEDIA_DEVICE_SET_SAMPLE = 8
Flags
are a bitwise combination of values to control how media devices are presented.
When Flags
contains BB_MEDIA_DEVICE_SET_SAMPLE
then the SetVal
field should contain an integer value which is used to seed a random number generator. The output of
which provides a randomized, yet sticky, spoofing value.
{
Windows: (int)
Build: (int)
}
The Windows
field is an OS constant defined above. When Windows
is set to
BB_OS_WIN10
then the Build
field should contain a valid build number for the
OS. Examples include 10240, 14393, 16299 and 18362. There are others but it's important to use a
real build value so as not to be unique.
{
IANA: (str) // America/New_York
Name: (str) // Eastern Standard Time
Zone: (str) // UTC-05:00
}
Time zone spoofing requires three pieces of information: the IANA name for the time zone, the actual name for the zone and then the the zone offset expressed as "UTC±hh:mm" string value.
{
Spoof: (int)
Offset: (int)
Level: (int)
}
BB_WEBGL_SPOOFING_OFF = 0
BB_WEBGL_SET_FEATURE_LEVEL = 1
BB_WEBGL_SET_IMAGE_RGB = 2
BB_WEBGL_RANDOMIZE_IMAGE_RBG = 4
BB_WEBGL_LEVEL_9_1 = 1
BB_WEBGL_LEVEL_9_2 = 2
BB_WEBGL_LEVEL_9_3 = 3
BB_WEBGL_LEVEL_10_0 = 4
BB_WEBGL_LEVEL_10_1 = 5
BB_WEBGL_LEVEL_11_0 = 6
BB_WEBGL_LEVEL_11_1 = 7
BB_WEBGL_LEVEL_12_0 = 8
BB_WEBGL_LEVEL_12_1 = 9
The Spoof
field should contain 1 or more flags to define what type of spoofing should be
performed. When Spoof
contains BB_WEBGL_SET_FEATURE_LEVEL
then Level
should be one of the feature levels flags defined above. If Spoof
contains BB_WEBGL_SET_IMAGE_RGB
then Offset
should contain an integer value which is used to seed a random number generator.
Note that spoofing WebGL Feature Levels only works if the default render is Direct3D.
Other spoofing related flags are defined below.
BB_BUBBLE_SPOOF_TIMEZONE = 1
BB_BUBBLE_SPOOF_SCREEN = 2
BB_BUBBLE_SPOOF_CPU_COUNT = 3
BB_BUBBLE_SPOOF_MEMORY = 4
BB_BUBBLE_SPOOF_TOUCHPOINTS = 5
BB_BUBBLE_SPOOF_FONTS = 6
BB_BUBBLE_SPOOF_LANGUAGE = 7
BB_BUBBLE_SPOOF_PLATFORM = 8
// RESERVED = 9
BB_BUBBLE_SPOOF_WEBGL = 10
BB_BUBBLE_SPOOF_MATH = 11
BB_BUBBLE_SPOOF_PERFTIMER = 12
BB_BUBBLE_SPOOF_WEBRTC = 13
// RESERVED = 14
BB_BUBBLE_SPOOF_MEDIA = 15
BB_BUBBLE_SPOOF_SPEECH = 16
BB_BUBBLE_SPOOF_BATTERY = 17
BB_BUBBLE_SPOOF_NETWORK = 18
BB_BUBBLE_SPOOF_CPU_ARCH = 19
BB_BUBBLE_SPOOF_FIREFOX_VERSION = 20
BB_CPU_ARCH_NONE = 0
BB_CPU_ARCH_ARM = 1
BB_CPU_ARCH_I64 = 2
BB_CPU_ARCH_X86 = 3
BB_CPU_ARCH_ARM64 = 4
BB_NETWORK_FLAG_ETHERNET = 1
BB_NETWORK_FLAG_WIFI = 2
Bubbles are the most fundamental part of Browser Bubble
. The following objects and commands
are used to create, modify, launch and terminate Bubbles
.
Currently configured Bubbles
will be returned as a list of BUBBLE_SAVED
objects.
This also contains any previously executed Bubbles
that were saved.
{
ID: (long)
IsInstance: (int)
Name: (str)
ProfilePath: (str)
BrowserID: (long)
DNSID: (long)
ProxyList: (list[long])
VPNID: (long)
Launch: (LAUNCH_ACTIONS)
Options: (int)
BorderColor: (str)
SpoofSettings: (dict[int, str])
}
BorderColor
can either be in the form of a hex string that starts with #
or as an integer
of a color. The format is ARGB.
The Options
field is a bitwise combination of the Bubble Options Flags
defined below. For DNS, proxy,
VPN and border color flags, corresponding fields in the various BUBBLE
structures need to be set with valid data.
BB_BUBBLE_FLAG_ENCRYPT = 1
BB_BUBBLE_FLAG_WIPE_ON_CLOSE = 2
BB_BUBBLE_FLAG_CREATE_SHORTCUT = 4
BB_BUBBLE_FLAG_BORDER_COLOR = 8
BB_BUBBLE_FLAG_ANTI_EXPLOIT_READ = 16
BB_BUBBLE_FLAG_ANTI_EXPLOIT_WRITE = 32
BB_BUBBLE_FLAG_ANTI_EXPLOIT_EXECUTE = 64
BB_BUBBLE_FLAG_DNS_BROWSER = 128
BB_BUBBLE_FLAG_DNS_BB = 256
BB_BUBBLE_FLAG_DNS_BLOCK = 512
BB_BUBBLE_FLAG_PROXY_SET = 1024
BB_BUBBLE_FLAG_VPN_SET = 2048
BB_BUBBLE_FLAG_CLEAN_SLATE = 4096
BB_BUBBLE_FLAG_DEBUG_PORT = 8192
BB_BUBBLE_FLAG_ENCRYPT
: File data encryption is enabled. A password must also be provided.BB_BUBBLE_FLAG_WIPE_ON_CLOSE
: File data will be deleted when the Bubble
closes.BB_BUBBLE_FLAG_CREATE_SHORTCUT
: A shortcut was created. This is a status flag only set when a shortcut created.BB_BUBBLE_FLAG_BORDER_COLOR
: The visible browser window will be highlighted with a border color.BB_BUBBLE_FLAG_ANTI_EXPLOIT_READ
: Read anti-exploit protection enabled.BB_BUBBLE_FLAG_ANTI_EXPLOIT_WRITE
: Write anti-exploit protection enabled.BB_BUBBLE_FLAG_ANTI_EXPLOIT_EXECUTE
: Execute anti-exploit protection enabled.BB_BUBBLE_FLAG_DNS_BROWSER
: Secure DNS through browser settings is enabled.BB_BUBBLE_FLAG_DNS_BB
: Secure DNS through Browser Bubble
is enabled. Not compatible with BB_BUBBLE_FLAG_DNS_BROWSER
.BB_BUBBLE_FLAG_DNS_BLOCK
: DNS filtering and blocking is enabled. Only compatible with BB_BUBBLE_FLAG_DNS_BB
.BB_BUBBLE_FLAG_PROXY_SET
: Proxying through browser settings is enabled.BB_BUBBLE_FLAG_VPN_SET
: VPN is enabled.BB_BUBBLE_FLAG_CLEAN_SLATE
: Bubble will be launched from a sanitized browser profile.BB_BUBBLE_FLAG_DEBUG_PORT
: Bubble will be launched with the --remote-debugging-port
command-line switch.
The SpoofSettings
field, which is used in other Bubble
objects, is a
dictionary with an integer key and string value. The key corresponds to the Spoof Category Flags
defined above. For each spoof setting you want enabled, simply add it to the dictionary with the
value being either a serialized object or simple value. If a flag is not in the dictionary
then that spoof setting is turned off.
BB_BUBBLE_SPOOF_TIMEZONE
: SPOOF_TIMEZONE
object.BB_BUBBLE_SPOOF_SCREEN
: String value in the format of HEIGHTxWIDTHxCOLOR
where height, width, and color are numeric values.BB_BUBBLE_SPOOF_CPU_ARCH
: A string value of a CPU Architecture
flag.BB_BUBBLE_SPOOF_CPU_COUNT
: String representation of a numeric value.BB_BUBBLE_SPOOF_MEMORY
: String representation of a numeric value.BB_BUBBLE_SPOOF_TOUCHPOINTS
: String representation of a numeric value.BB_BUBBLE_SPOOF_FONTS
: SPOOF_FONT
object.BB_BUBBLE_SPOOF_LANGUAGE
: LANGUAGE
object.BB_BUBBLE_SPOOF_PLATFORM
: SPOOF_OS
object.BB_BUBBLE_SPOOF_WEBGL
: SPOOF_WEBGL
object.BB_BUBBLE_SPOOF_MATH
: SPOOF_MATH
object.BB_BUBBLE_SPOOF_PERFTIMER
: A string value of "1"
.BB_BUBBLE_SPOOF_WEBRTC
: A string value of "1"
.BB_BUBBLE_SPOOF_MEDIA
: SPOOF_MEDIA
object.BB_BUBBLE_SPOOF_SPEECH
: String representation of a speech profile ID.BB_BUBBLE_SPOOF_BATTERY
: SPOOF_BATTERY
object.BB_BUBBLE_SPOOF_NETWORK
: String representation of a Network Flags
value.BB_BUBBLE_SPOOF_FIREFOX_VERSION
: Version string.
Currently running Bubbles
will be returned as a list of BUBBLE_RUNNING
objects. If remote debugging was enabled for automation frameworks, then DebugPort
and DebugEndPoint
contain the information needed to connect to the running instance.
{
InstanceID: (long)
BubbleID: (long)
DebugPort: (int)
DebugEndPoint: (str)
DTG: (long)
}
A running Bubble
can be queried to get additional details. The returned result is a
BUBBLE_QUERY
object. To perform the query, set ACTION.ValueString
to the string representation of a BUBBLE_RUNNING.InstanceID
.
{
InstanceID: (long)
Name: (str)
BrowserID: (long)
BrowserPID: (int)
DNSID: (long)
ProxyList: (list[long])
VPNID: (long)
ProfilePath: (str)
PreLaunch: (LAUNCH_RESULT)
PostLaunch: (LAUNCH_RESULT)
Options: (int)
BorderColor: (str)
SpoofSettings: (dict[int, str])
}
To create a new Bubble
, set ACTION.ValueString
to a serialized BUBBLE_CREATE
object.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_INTEGER
and SERVER_REPONSE.ReturnValue
will be the string value of the new
Bubble
ID.
{
Name: (str)
BrowserID: (long)
DNSID: (long)
ProxyList: (list[long])
VPNID: (long)
Launch: (LAUNCH_ACTIONS)
Options: (int)
BorderColor: (str)
SpoofSettings: (dict[int, str])
}
To delete a Bubble
, pass a BUBBLE_DELETE
object that contains an ID
value for
either type of saved Bubble
. If IsInstance
is 1
then ID
should be an
InstanceID
of a previously executed Bubble
. Otherwise, ID
is a regular Bubble
.
Bubbles
that previously executed are only saved if a shortcut is created. If no shortcut was created while a Bubble
ran, then the Bubble
is deleted automatically when the Bubble
closes. Only creating a shortcut keeps
previously executed Bubbles
around longer than their normal process life.
The Bubble
data can be wiped if Wipe
is set to 1
.
Note that browser data will need to be cleaned up manually if Wipe
is not set and global options to
automatically wipe data is disabled. If that option is enabled, then the Wipe
value overrides the global setting.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
{
ID: (long)
IsInstance: (int)
Wipe: (int)
}
Modifying a Bubble
is just like adding one except that the BubbleID
must be set.
All settings passed will replace existing Bubble
settings.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
{
BubbleID: (long)
Options: (int)
DNSID: (long)
ProxyList: (list[long])
VPNID: (long)
Launch: (LAUNCH_ACTIONS)
BorderColor: (str)
SpoofSettings: (dict[int, str])
}
Bubbles
can be quickly created with randomly generated SpoofSettings
. To generate 1 or more
Bubbles
, pass the BUBBLE_GENERATE
object in ACTION.ValueString
. The BrowserID
value determines which browser will be used while Count
should be greater than 0
. Shortcut icons
can also be automatically created for each new Bubble
by setting the IconLocation
field to one of the
valid values defined below. If IconLocation
is BB_ICON_DIRECTORY_USER_DEFINED
then IconPath
must be a fully qualified directory path where the icons will be saved to.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_JSON
and SERVER_REPONSE.ReturnValue
will be a serialized list of BubbleID
values.
{
BrowserID: (long)
Count: (int)
IconLocation: (int)
IconPath: (str)
Flags: (int)
}
BB_ICON_DIRECTORY_NONE = 0
BB_ICON_DIRECTORY_CURRENT_USER_DESKTOP = 1
BB_ICON_DIRECTORY_ALL_USER_DESKTOP = 2
BB_ICON_DIRECTORY_USER_DEFINED = 3
BB_GENERATE_COLOR_BORDER = 1
BB_GENERATE_DEBUG_PORTS = 2
Shortcuts can also be created for existing Bubbles
, both saved and running. To do that, use a BUBBLE_SHORTCUT
object. The IsInstance
field determines how the ID
value is interpreted. If IsInstance
is
1
then ID
must be a valid InstanceID
. Creating a shortcut of a running Bubble
will make automatic changes to the cleanup of the Bubble
files. That means that even if the global settings indicate
that Bubble
files should be automatically deleted when the Bubble
closes, creating a shortcut from a
running Bubble
will mark it to be saved. Manual cleanup is necessary.
If IsInstance
is 0
then ID
must be a valid BubbleID
. No changes to cleanup actions
are made.
Name
is the file name for the new icon while IconLocation
and IconPath
control where the
icon gets created. IconLocation
must not be BB_ICON_DIRECTORY_NONE
.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and SERVER_REPONSE.ReturnValue
will be the fully qualified shortcut path.
{
ID: (long)
IsInstance: (int)
Name: (str)
IconLocation: (int)
IconPath: (str)
}
Launching a Bubble
is done by sending a BUBBLE_LAUNCH
object. Both saved Bubbles
as well as previously launched Bubbles
that were saved can be launched. The ID
field refers
to the saved or instance ID and is interpreted based on the IsInstance
field.
The Flags
field refer to the Bubble Options Flags
which allows for overriding previously set
Bubble
options.
Launching a Bubble
is an async operation. So, if successful, this command will return SERVER_REPONSE.ErrorCode
set to BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
as BB_DATA_TYPE_INTEGER
and
SERVER_REPONSE.ReturnValue
as a string value of the new InstanceID
. However, Browser Bubble Pro
will send follow-on messages during the success or failure of the launch process. A Bubble
is not fully ready until the
BB_SERVER_BUBBLE_SUB_ACTION_READY
message is received.
{
ID: (long)
IsInstance: (int)
Flags: (int)
Password: (str)
DNSID: (long)
ProxyList: (list[long])
VPNID: (long)
}
To stop a Bubble
, send a BUBBLE_TERMINATE
object with the InstanceID
field set to a
valid instance ID value. The Wipe
field behavior is the same as the BUBBLE_DELETE
action.
Like launching, terminating is an async operation so the Bubble
is really not fully terminated until a
BB_SERVER_BUBBLE_SUB_ACTION_SHUTDOWN
message is received.
{
InstanceID: (long)
Wipe: (int)
}
If the global option to block network access is set, then every Bubble
must have network access explicitly
enabled before being unblocked. This is done by sending the BB_SERVER_BUBBLE_SUB_ACTION_NETWORK
message.
ACTION.ValueString
should be the string value for a valid InstanceID
of a running Bubble
.
If successful, SERVER_REPONSE.ErrorCode
will be BB_ERROR_NO_ERROR
, SERVER_RESPONSE.DataType
will be BB_DATA_TYPE_STRING
and the string "OK" will be set in SERVER_REPONSE.ReturnValue
.
This message is a callback from the server to the client. This is sent whenever a Bubble
has fully loaded. Note that while it fully loaded according to Browser Bubble
the browser itself
may still be doing its own initialization.
If Pre and/or Post Launch Actions
were set then the error codes and captured outputs will be provided as well.
{
InstanceID: (long)
BubbleID: (long)
MountPoint: (str)
PreLaunch: (LAUNCH_RESULT)
PostLaunch: (LAUNCH_RESULT)
}
This message is a callback from the server to the client. If a Bubble
fails to load
then the server will send the BUBBLE_FAIL
object to client with failure details. The
ProcessId
value is the PID of the browser process while BrowserPath
is
the fully qualified file path for the browser executable that was attempted to execute. ErrorCode
is an integer value of the failure while the Log
field will contain a message describing
the failure.
{
InstanceID: (long)
ProcessId: (int)
BrowserPath: (str)
ErrorCode: (int)
Log: (str)
}
This message is a callback from the server to the client. This is sent whenever a Bubble
is fully closed and clean-up has been performed. The server will send the BUBBLE_SHUTDOWN
object with both the static and dynamic IDs so any internal bookkeeping can be maintained.
Additionally, if a Shutdown Launch Action
was set, then the error code from the process and any captured
output will be provided.
{
InstanceID: (long)
BubbleID: (long)
ShutdownLaunch: (LAUNCH_RESULT)
}
This message, along with a BUBBLE_DEBUG_PORT
object, is a callback from the server to the client.
If Browser Bubble
detects that the browser instance was started with remote debugging enabled
(through the --remote-debugging-port
switch), then it will attempt to capture the port and WebSocket
endpoint used by the browser so that automation frameworks, such as Puppeteer and Playwright, can connect to the instance.
Passing a port value of 0
to a Chromium or Firefox instance makes the browser select a random port. However, you
can also pass a non-zero value for a specific port however if another instance is already running that is using that port then
it will fail. It is recommended to get a dynamic value (by passing 0) and wait for this message with the required
information instead of hard-coding a port number in your automation scripts.
.launch()
method in the automation frameworks to start a new browser instance is not
supported by Browser Bubble Pro
. Instead, you must launch the Bubble
using the API and then
use the automation framework's .connect()
method in order to begin automation tasks.
{
InstanceID: (long)
Port: (long)
WsEndPoint: (str)
}
A Browser Bubble Pro
client can be written in any language that supports WebSockets. Some languages have
bulit-in web socket capabilities while others require third-party libraries.
Please check our Github page for code examples.
https://github.com/heilig-defense/browser-bubble
25 Jan 2022
-Initial release.
Browser Bubble
and Browser Bubble Pro