Representative console scripting and client scripting API

The BeyondTrust Representative Console Scripting feature is composed of three parts:

1. The BeyondTrust Representative Console Script file format
2. New and deprecated command line parameters for the representative console
3. The BeyondTrust client scripting API

The BeyondTrust representative console script file

A BeyondTrust Representative Console Script (BRCS) is a file that contains a sequence of commands to be executed by the BeyondTrust representative console. The file extension is in the format "brcs-<companySiteName>" (Company Site Name is the name used to access your support site). During installation the BeyondTrust representative console will use the OS to associate the representative console with the BRCS file type. Therefore users can double-click a BRCS file and have it automatically executed by the BeyondTrust representative console.

BRCS files have the following format:

BRCS1.0
<command>
<command>
…

This is more formally expressed as:

brcs_file = header , newline , commands ;
header = "BRCS" , version ;
version = digit , "." , digit ;
commands = command { newline , command } ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
newline = "\n" | "\r\n" ;

Note that script files can have a maximum of 10 commands.

Each command consists of a set of key-value pairs separated by "&". The key in each pair is separated from the value by "=". Keys and values use the percent-encoding algorithm described in RFC3986 section 2.1. This is commonly referred to as url-encoding or url-escaping. It is commonly seen in the address bar of web browsers to represent the parameters passed to a web server. Commands have the following format:

action=<action>&parameter1=value1&parameter2=value2...

This is more formally expressed as:

command = "action=", value, [ parameters ] ;
parameters =  "&", parameter, [ parameters ] ;
parameter = url_encoded_string, "=", url_encoded_string ;
url_encoded_string = {* see RFC 3986 *} ;

New and deprecated command line parameters for the representative console

Two command line parameters have been added to the representative console to support BRCS:

run-script <BRCS command>
run-script-file <path to BRCS file>

These command line parameters allow customers to implement BRCS login via the command line. These two new parameters overlap with two existing parameters. Therefore, the "-jump" and "-push" command line parameters are now deprecated and will be removed in a future release.

Example

Old Command Line	New Command Line
push<hostname>	run-script "action=push_and_start_local&hostname=<hostname>"
jump<search string>	run-script "action=start_pinned_client_session&search_string=<search_string>"

Different behaviors can be seen when running a script from the command line depending on the state of the representative console:

• If the representative console is not running, then attempting to run a script from the command line causes the representative console to start the login dialog. After the representative successfully logs in, the script is run.
• If the representative console is already running, but the representative is not logged in, then the login dialog is shown. After the representative logs in, the script is run.
• If the representative console is already running and the representative is already logged in, then attempting to run a script from the command line causes the existing instance of the representative console to run the script.

Representative console exit status:

• If an invalid script is given on the command line, then the representative console will terminate with an exit status > 0.
• If a valid script is given on the command line, then the representative console will terminate with an exit status of 0.

Examples:

bomgar-rep.exe --run-script "action=generate_session_key&session.custom.external_key=123456789"
bomgar-rep.exe --run-script-file my_script_file.brcs-beta60

The BeyondTrust client scripting API

The client scripting API enables you to generate a BeyondTrust Representative Console Scripting (BRCS) file which allows you to send commands to the BeyondTrust representative console from external applications.

Customers can use the client scripting API to generate BRCS files that can start a support session with a specific Jump Client, push and start a session with a Windows system within a local network, prompt representatives to generate a session key, start a vPro session with a specified system, or to simply log in to the representative console.

The client scripting API URL is https://support.example.com/api/client_script.

This API accepts a client type (rep), an operation to perform (generate), a command to put in the script file, and a set of parameters to pass to the command. Here is an example of a valid Client Scripting API request:

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_pinned_client_session&search_string=ABCDEFG02

The above request will prompt the user to download a BeyondTrust representative console script file. After downloading the script file, the user can run it using the representative console. In this case, the script file will contain commands to start a session with the Jump Client whose hostname, comments, public IP, or private IP matches the search string "ABCDEFG02".

Parameters for client scripting API

type=rep type=web_console	Currently the API only supports rep or web_console as the client type.
operation=generate operation=execute	The operation to perform. Currently the API only supports generate and execute as the operation. If the type is rep, the operation should be generate. If the type is web_console, the operation should be execute.
action=<command> or action=<command>&parameter=[value]	The name of the command to run. Most commands have required and/or optional parameters. Available actions include: login start_rdp_session generate_session_key start_shell_jump_session push_and_start_local start_vpro_session push_and_start_remote start_vnc_session start_jump_item_session delete_script_file Two actions are automatically added to the BRCS file: login and delete_script_file. The delete_script_file action has no parameters. The type web_console supports only the generate_session_key and start_jump_item_session actions.