Browser Bubble Pro

All data transferred to or from the Browser Bubble Proserver 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

SERVER_REQUEST is sent by the client to the server to perform some action.

{
	Version: (int)
	MessageID: (long)
	DataType: (int)
	RequestValue: (str)
}

SERVER_RESPONSE

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.

ACTION

When 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.

COUNTRY

{
	Code: (str)		//DE
	Name: (str)		//Germany
}

LANGUAGE

{
	ID: (long)		//2057
	Name: (str)		//English - United Kingdom
	Code: (str)		//en-GB
}

LAUNCH_ACTIONS

{
	Pre: (str)
	Post: (str)
	Shutdown: (str)
}

Operating System Definitions

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.

Current State (BB_SERVER_STATUS_SUB_ACTION_CURRENT)

{
	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.

Shutdown (BB_SERVER_STATUS_SUB_ACTION_SHUTDOWN)

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.

Log (BB_SERVER_STATUS_SUB_ACTION_LOG)

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

{
	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

Adapter (BB_OPTIONS_XET_ADAPTER)

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.

Adapter List (BB_OPTIONS_XET_ADAPTER_LIST)

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.

ADAPTER Object

{
	Name: (str)
	MAC: (str)
	IP4: (str)
	IP6: (str)
	Gateway: (dict[str, str])
	IsDefault (int)
	IsWifi: (int)
}

Anti-Exploit (BB_OPTIONS_XET_GLOBAL_AEX)

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.

DNS (BB_OPTIONS_XET_GLOBAL_DNS)

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.

Flags (BB_OPTIONS_XET_FLAGS)

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.

License (BB_OPTIONS_XET_LICENSE)

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

The 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

Reinitialization

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.

Structure Example

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.

Fonts

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.

Install (BB_SERVER_FONT_SUB_ACTION_INSTALL)

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.

FONT_INSTALL

{
	OS: (int)
	FontPath: (str)
}

List (BB_SERVER_FONT_SUB_ACTION_LIST)

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.

Font Op Flags

BB_FONT_OP_PROFILE = 1
BB_FONT_OP_FONT_ITEM = 2

FONT_RESPONSE

{
	Op: (int)
	Data: (str)
}

FONT_PROFILE

{
	FontID: (long)
	Name: (str)
	Fonts: (list[FONT_ITEM])
}

FONT_ITEM

{
	FontFileID: (long)
	FontName: (str)
	FontPath: (str)
}

Create (BB_SERVER_FONT_SUB_ACTION_CREATE)

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.

Delete (BB_SERVER_FONT_SUB_ACTION_DELETE)

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.

Modify (BB_SERVER_FONT_SUB_ACTION_UPDATE)

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

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.

Launch Actions List (BB_SERVER_LAUNCH_SUB_ACTION_LIST)

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.

LAUNCH_ACTION

{
	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.

LAUNCH_ACTION Flags

// 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.

LAUNCH_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.

Launch Actions Create (BB_SERVER_LAUNCH_SUB_ACTION_CREATE)

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.

Launch Actions Delete (BB_SERVER_LAUNCH_SUB_ACTION_DELETE)

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.

Launch Actions Update (BB_SERVER_LAUNCH_SUB_ACTION_UPDATE)

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

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.

SPEECH

{
	Op: (int)
	ID: (long)
	Data: (str)
}

SPEECH Op Codes

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.

Speech List (BB_SERVER_SPEECH_SUB_ACTION_LIST)

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.

SPEECH_PROFILE

{
	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.

SPEECH_VOICE

{
	ID: (long)
	Name: (str)
	Language: (LANGUAGE)
	Age: (int)
	Sex: (int)
}

SPEECH_VOICE Age

BB_SPEECH_AGE_ADULT = 1
BB_SPEECH_AGE_CHILD = 2

SPEECH_VOICE Sex

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.

Speech Create (BB_SERVER_SPEECH_SUB_ACTION_CREATE)

To create a new speech profile, set SPEECH.Op to BB_SPEECH_PROFILE and the 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 BB_SPEECH_VOICE and the 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 BB_SPEECH_PROFILE_VOICES, 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.

Speech Delete (BB_SERVER_SPEECH_SUB_ACTION_DELETE)

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.

Speech Modify (BB_SERVER_SPEECH_SUB_ACTION_UPDATE)

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.

• Firefox
• Firefox Nightly
• Chrome
• Chrome Canary
• Chromium
• Edge
• Brave
• Blisk
• Epic
• Vivaldi
• Iron

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

Query (BB_SERVER_BROWSER_SUB_ACTION_SYS_QUERY)

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.

BROWSER_INSTALL

{
	BrowserType: (int)
	BrowserName: (str)
	FilePath: (str)
	ProfilePath: (str)
	ProfileName: (str)
}

List (BB_SERVER_BROWSER_SUB_ACTION_LIST)

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.

BROWSER_PROFILE

{
	ID: (long)
	Name: (str)
	BrowserType: (int)
	FilePath: (str)
	ProfilePath: (str)
	Enabled: (int)
}

Add (BB_SERVER_BROWSER_SUB_ACTION_ADD)

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.

Delete (BB_SERVER_BROWSER_SUB_ACTION_DELETE)

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.

Update (BB_SERVER_BROWSER_SUB_ACTION_UPDATE)

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.

BROWSER_OP

{
	Op: (int)
	ID: (long)
	Data: (str)
}

BROWSER_OP Op

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_OP

{
	DNS: (int)
	ID: (long)
	Data: (str)
}

DNS_SERVER

{
	ProviderID: (long)
	Provider: (str)
	ServerID: (long)
	Country: (str)
	DNSType: (int)
	Address: (str)
	Port: (int)
}

DNS_SERVER DNSType

BB_DNS_TYPE_DNS_OVER_TLS = 1
BB_DNS_TYPE_DNS_OVER_HTTPS = 2

List (BB_SERVER_DNS_SUB_ACTION_SYNC)

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.
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.

List (BB_SERVER_DNS_SUB_ACTION_LIST)

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.

Add (BB_SERVER_DNS_SUB_ACTION_CREATE)

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.

Delete (BB_SERVER_DNS_SUB_ACTION_DELETE)

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.

Sinkhole Search (BB_SERVER_DNS_SUB_ACTION_SINKHOLE_SEARCH)

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.

PROXY_SERVER

{
	ID: (long)
	ProxyName: (str)
	Country: (COUNTRY)
	IP: (str)
	Port: (int)
	ProxyType: (int)
	Flags: (int)
}

PROXY_SERVER ProxyType

BB_PROXY_TYPE_HTTPS = 1
BB_PROXY_TYPE_SOCKS4 = 2
BB_PROXY_TYPE_SOCKS5 = 3

List (BB_SERVER_PROXY_SUB_ACTION_LIST)

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.

Add (BB_SERVER_PROXY_SUB_ACTION_CREATE)

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.

Delete (BB_SERVER_PROXY_SUB_ACTION_DELETE)

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.

Modify (BB_SERVER_PROXY_SUB_ACTION_UPDATE)

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.

VPN_SERVER

{
	ID: (long)
	Provider: (str)
	Country: (COUNTRY)
	Adapter: (str)
	Address: (str)
}

List (BB_SERVER_VPN_SUB_ACTION_LIST)

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.

Add (BB_SERVER_VPN_SUB_ACTION_CREATE)

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.

Delete (BB_SERVER_VPN_SUB_ACTION_DELETE)

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.

Modify (BB_SERVER_VPN_SUB_ACTION_UPDATE)

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.

SPOOF_BATTERY

{
	Flags: (int)
	Values1: (int)
	Values2: (int)
	Values3: (int)
}

Battery Flags

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.

SPOOF_FONT

{
	Flags: (int)
	Extra: (long)
}

Font Flags

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.

SPOOF_MATH

{
	Flag: (int)
	Offset: (int)
}

Math Flags

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.

SPOOF_MEDIA

{
	Flags: (int)
	SetVal: (int)
}

Media Flags

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.

SPOOF_OS

{
	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.

SPOOF_TIMEZONE

{
	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_WEBGL

{
	Spoof: (int)
	Offset: (int)
	Level: (int)
}

WebGL Flags

BB_WEBGL_SPOOFING_OFF = 0
BB_WEBGL_SET_FEATURE_LEVEL = 1
BB_WEBGL_SET_IMAGE_RGB = 2
BB_WEBGL_RANDOMIZE_IMAGE_RBG = 4

Direct3D WebGL Feature Level

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.

Spoof Category Flags

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

CPU Architecture

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

Network Flags

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.

List (BB_SERVER_BUBBLE_SUB_ACTION_LIST_SAVED)

Currently configured Bubbles will be returned as a list of BUBBLE_SAVED objects. This also contains any previously executed Bubbles that were saved.

BUBBLE_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.

Bubble Options Flags

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.

List (BB_SERVER_BUBBLE_SUB_ACTION_LIST_RUNNING)

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.

BUBBLE_RUNNING

{
	InstanceID: (long)
	BubbleID: (long)
	DebugPort: (int)
	DebugEndPoint: (str)
	DTG: (long)
}

Query (BB_SERVER_BUBBLE_SUB_ACTION_DETAILS)

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.

BUBBLE_QUERY

{
	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])
}

Create (BB_SERVER_BUBBLE_SUB_ACTION_CREATE)

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.

BUBBLE_CREATE

{
	Name: (str)
	BrowserID: (long)
	DNSID: (long)
	ProxyList: (list[long])
	VPNID: (long)
	Launch: (LAUNCH_ACTIONS)
	Options: (int)
	BorderColor: (str)
	SpoofSettings: (dict[int, str])
}

Delete (BB_SERVER_BUBBLE_SUB_ACTION_DELETE)

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.

BUBBLE_DELETE

{
	ID: (long)
	IsInstance: (int)
	Wipe: (int)
}

Modify (BB_SERVER_BUBBLE_SUB_ACTION_UPDATE)

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.

BUBBLE_UPDATE

{
	BubbleID: (long)
	Options: (int)
	DNSID: (long)
	ProxyList: (list[long])
	VPNID: (long)
	Launch: (LAUNCH_ACTIONS)
	BorderColor: (str)
	SpoofSettings: (dict[int, str])
}

Generate (BB_SERVER_BUBBLE_SUB_ACTION_GENERATE)

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.

BUBBLE_GENERATE

{
	BrowserID: (long)
	Count: (int)
	IconLocation: (int)
	IconPath: (str)
	Flags: (int)
}

IconLocation Flags

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

Bubble Generate Flags

BB_GENERATE_COLOR_BORDER = 1
BB_GENERATE_DEBUG_PORTS = 2

Shortcut (BB_SERVER_BUBBLE_SUB_ACTION_SHORTCUT)

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.

BUBBLE_SHORTCUT

{
	ID: (long)
	IsInstance: (int)
	Name: (str)
	IconLocation: (int)
	IconPath: (str)
}

Launch (BB_SERVER_BUBBLE_SUB_ACTION_LAUNCH)

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.

BUBBLE_LAUNCH

{
	ID: (long)
	IsInstance: (int)
	Flags: (int)
	Password: (str)
	DNSID: (long)
	ProxyList: (list[long])
	VPNID: (long)
}

Terminate (BB_SERVER_BUBBLE_SUB_ACTION_TERMINATE)

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.

BUBBLE_TERMINATE

{
	InstanceID: (long)
	Wipe: (int)
}

Network (BB_SERVER_BUBBLE_SUB_ACTION_NETWORK)

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.

Ready (BB_SERVER_BUBBLE_SUB_ACTION_READY)

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.

BUBBLE_LAUNCHED

{
	InstanceID: (long)
	BubbleID: (long)
	MountPoint: (str)
	PreLaunch: (LAUNCH_RESULT)
	PostLaunch: (LAUNCH_RESULT)
}

Failed (BB_SERVER_BUBBLE_SUB_ACTION_FAILED)

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.

BUBBLE_FAIL

{
	InstanceID: (long)
	ProcessId: (int)
	BrowserPath: (str)
	ErrorCode: (int)
	Log: (str)
}

Shutdown (BB_SERVER_BUBBLE_SUB_ACTION_SHUTDOWN)

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.

BUBBLE_SHUTDOWN

{
	InstanceID: (long)
	BubbleID: (long)
	ShutdownLaunch: (LAUNCH_RESULT)
}

DevTools Protocol (BB_SERVER_BUBBLE_SUB_ACTION_DEBUG_PORT)

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.

BUBBLE_DEBUG_PORT

{
	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

Changelog

25 Jan 2022
-Initial release.

Browser Bubble and Browser Bubble Pro
Copyright (c) 2022 Heilig Defense Inc.

Browser icons are trademarks of their respective developers.