Access console scripting and client scripting API

The BeyondTrust access console scripting feature is composed of three parts:

  1. The BeyondTrust Access Console Script file format
  2. Command line parameters for the access console
  3. The BeyondTrust client scripting API

The BeyondTrust Access Console script file

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

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 *} ;

Command line parameters for the Access Console

Two command line parameters exist in the access console to support BRCS:

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

These command line parameters allow users to implement BRCS login via the command line.

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

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

Access console exit status:

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

Examples:

bomgar-acc.exe --run-script "action=start_jump_item_session&client.hostname=ABCEF02&session.custom.external_key=123456789"
bomgar-acc.exe --run-script-file my_script_file.brcs-beta60

The BeyondTrust client scripting API

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

Customers can use the client scripting API to generate BRCS files that can start a session with a specific Jump Item or to log into the access console.

The client scripting API URL is https://access.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://access.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.hostname=ABCDEFG02

The above request prompts the user to download a BeyondTrust access console script file. After downloading the script file, the user can run it using the access console. In this case, the script file contains commands to start a session with the Jump Item whose hostname, comments, public IP, or private IP matches the search string "ABCDEF02".

Parameters for client scripting API

type=rep

type=web_console

 The BeyondTrust client to which the command applies. 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 or 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>&parameter=[value]

The name of the command to run and the necessary parameters. Available actions include:

  • login
  • start_jump_item_session
  • push_and_start_local
  • push_and_start_remote
  • start_rdp_session
  • start_shell_jump_session

Two actions are automatically added to the BRCS file: login and delete_script_file. The delete_script_file action has no parameters.

The web_console type supports only the start_jump_item_session action.