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

ℹ️

Note

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

Commands

login

When generating any BeyondTrust Console Script, the login command is automatically added as the first command in the script file. It does not need to be specified in the URL used to generate the script file.

By default, this command opens the access console and attempts to log in using the credentials saved locally in the access console. If no credentials are saved, the command opens the access console login prompt. Once the user has correctly authenticated, the script continues running.

The login command has no effect if a user is already logged into the access console.

If you wish to specify the credentials to be used, you can create a separate script specifically to be used for logging in. The login command passes the login mechanism along with a username and password. Both username and password parameters are sent in plain text and is unencrypted.

⚠️

Important

• You cannot specify multiple commands in the URL used to generate a script. For example, you cannot specify login and multiple start_jump_item_session commands in the same URL. Each command must be generated as a separate script.
• A developer may edit the .brcs script file once it has been generated in order to modify the login credentials and then run another command. BeyondTrust does not support scripts modified in this manner.

Optional parameters for login command

Query examples: login

• Log into the access console, specifying the username and password

https://access.example.com/api/client_script?type=rep&operation=generate&action=login&mechanism=username_password&username=username&password=password

start_shell_jump_session

The start_shell_jump_session command initiates a Shell Jump session, creating an SSH or Telnet connection to a remote network device.

Required parameter for the start_shell_jump_session command

Optional parameters for the start_shell_jump_session command

Query examples: start_shell_jump_session

• Start a Shell Jump session with the computer "ABCDEF02"

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02

• Start a Shell Jump session with the computer "ABCDEF02" through the Jumpoint "Network01"

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02&jumpoint=Network01

• Start a Shell Jump session with the computer "ABCDEF02" through the Jumpoint "Network01". Authenticate with "jsmith", and use a Telnet protocol through port 40 with terminal type vt100

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02&jumpoint=Network01&username=jsmith&protocol=telnet&port=40&terminal=vt100

• Start a Shell Jump session with the computer "ABCDEF02" and associate custom attributes with the session

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

push_and_start_local

The push_and_start_local command attempts to push the endpoint client client to a computer on the local network to start an access session. This can also be described as a local Jump.

Required parameter for push_and_start_local command

Optional parameter for push_and_start_local command

Query examples: push_and_start_local

• Jump to the local network computer "ABCDEF02"

https://access.example.com/api/client_script?type=rep&operation=generate&action=push_and_start_local&hostname=ABCDEF02

• Jump to the local network computer "ABCDEF02" and associate custom attributes with the session

https://access.example.com/api/client_script?type=rep&operation=generate&action=push_and_start_local&hostname=ABCDEF02&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

push_and_start_remote

The push_and_start_remote command attempts to push the endpoint client client to a computer on a remote network through a Jumpoint in order to start an access session. This can also be described as a remote Jump.

Required parameter for push_and_start_remote command

Optional parameters for push_and_start_remote command

Query examples: push_and_start_remote

• Jump to the remote computer "ABCDEF02" through the Jumpoint "Network01"

https://access.example.com/api/client_script?type=rep&operation=generate&action=push_and_start_remote&target=ABCDEF02&jumpoint=Network01

• Jump to the remote computer "ABCDEF02" through the Jumpoint "Network01" and associate custom attributes with the session

https://access.example.com/api/client_script?type=rep&operation=generate&action=push_and_start_remote&target=ABCDEF02&jumpoint=Network01&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

start_jump_item_session

The start_jump_item_session command attempts to start a session with a BeyondTrust Jump Item. Users may run this command for all Jump Items they are permitted to access via the Jump management interface in the access console.

Optional parameters for the start_jump_item_session command

⚠️

Important

At least one client._ parameter must be specified. If multiple client._ parameters are specified, then only clients matching all criteria are returned.

Query examples: start_jump_item_session

• Start a session with a Jump Item whose hostname contains "ABCDEF02"

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.hostname=ABCDEF02

• Start a session with a Jump Item whose comments contain "maintenance" and whose tag contains "server"

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.comments=maintenance&client.tag=server

• Start a session with a pinned Jump Client whose private IP address begins with "10.10.24" and associate custom attributes with the session

https://access.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.private_ip=10.10.24&jump.method=pinned&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

ℹ️

Note

If more than one Jump Item matches the search criteria, then a dialog opens, giving the user the option to select the appropriate Jump Item.