Download reports with AccessSession

The AccessSession query returns full information for all sessions which match given search parameters. You may use any of the following sets of parameters to generate reports:

  • start_date and duration
  • start_time and duration
  • end_date and duration
  • end_time and duration
  • lsid
  • lsids

The reporting API is an authenticated API. For instructions on using authenticated APIs using OAuth, please see Authenticate to the Privileged Remote Access API.

The API account used to call this report must have access to the reporting API.

Parameters for AccessSession

start_date=[YYYY-MM-DD] Specifies that the report should return all sessions, even those still in progress, that began on or after this date and that are within the duration specified below.
start_time=[timestamp] Specifies that the report should return all sessions, even those still in progress, that began at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD] Specifies that the report should return only closed sessions that ended on or after this date and that are within the duration specified below.
end_time=[timestamp] Specifies that the report should return only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer] Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds.
lsid=[string] The ID of the session for which you wish to see details.
lsids=[comma-separated strings] A comma-delimited list of the IDs of sessions for which you wish to see details.

XML response for AccessSession query

<session_list> Contains a <session> element for each session that matches the given criteria. If no sessions are returned, this element will contain no <session> elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Element names and attributes

/session_list/session
lsid (attribute) A string which uniquely identifies this session.
<session_type> Indicates the type of session for which the report was run. The value will always be support in the current BeyondTrust API version.
<lseq>

An incrementing number used to represent sessions in a non-string format.

The LSEQ element is not guaranteed to be unique or strictly sequential.

<start_time> The date and time the session was begun. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the start time as a UNIX timestamp (UTC).
<end_time> The date and time the session was ended. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the end time in UNIX timestamp (UTC). This element will be empty for sessions which are still in progress when the report was run or which closed abnormally.
<duration> Session length in HH:MM:SS format.
<jump_group>

The element's content is the name of the Jump Group. For Personal Jump Groups, the name of the Jump Group is the Private Display Name of the representative who owns the Jump Group. The <jump_group> element has two attributes:

type: This is the Jump Group's type, which can be "shared" or "personal".

id: This is the Jump Group's unique ID for its type. Jump Groups of different types can have the same ID. For Personal Jump Groups, this is the unique ID of the user who owns the Jump Group. Each user can only have a single Personal Jump Group.

<jumpoint> The name of the Jumpoint through which this session was initiated, if any. Also contains an id attribute, which displays the unique ID assigned to the Jumpoint.
<custom_attributes> Contains a <custom_attribute> element for each custom field assigned to a session. This element displays only if custom fields have been defined. The format of each <custom_attribute> element is described below.
<session_chat_view_url> The URL at which this session's chat transcript can be viewed in a web browser. This element is displayed only for sessions that have successfully ended.
<session_chat_download_url> The URL at which this session's chat transcript can be downloaded. This element is displayed only for sessions that have successfully ended.
<session_recording_view_url> The URL at which the video of the session may be viewed in a web browser. This element is displayed only if screen sharing recording was enabled at the time of the session and only if the user initiated screen sharing during the session. It is available only for sessions that have successfully ended.
<session_recording_download_url> The URL at which the video of the session may be downloaded. This element is displayed only if screen sharing recording was enabled at the time of the session and only if the user initiated screen sharing during the session. It is available only for sessions that have successfully ended.
<command_shell_recordings> Contains a <command_shell_recording> element for each command shell that was initiated during the session. This element is displayed only if the user opened a remote command shell during the session, if command shell recording was enabled at the time of the session, and if the requesting user has permission to view session recordings. Each <command_shell_recording> element contains the child elements <download_url> and <view_url> as described below.
<file_transfer_count> The number of file transfers which occurred during the session.
<file_move_count> The number of files renamed via the File Transfer interface during the session.
<file_delete_count> The number of files deleted via the File Transfer interface during the session.
<primary_customer> Lists the gsnumber as an attribute and as an element, the name of the remote endpoint accessed by the user.
<primary_rep> Lists the gsnumber and id as attributes and as an element, the name of the user who owned the session.
<customer_list> A list of all endpoints accessed in the session. There should always be exactly one endpoint per session in the current BeyondTrust API version. The format of each <customer> element is described below.
<rep_list> A list of all users who participated in the session, whether as the session owner or as conference members. The format of each <representative> element is described below.
<session_details>

Contains a chronological list of all events which occurred during the session. This element contains one or more child <event> elements, described below.

/session_list/session/custom_attributes/custom_attribute
display_name (attribute) The display name assigned to the custom attribute.
code_name (attribute) The code name assigned to the custom attribute.
/session_list/session/command_shell_recordings/command_shell_recording
instance (attribute) The instance of the command shell session, starting with 0.
<download_url> The URL at which the video of the command shell session may be downloaded.
<view_url> The URL at which the video of the command shell session may be viewed in a web browser.
/session_list/session/customer_list/customer
gsnumber (attribute) Uniquely identifies the endpoint in regards to its current connection to the BeyondTrust Appliance B Series. A gsnumber may be recycled, so while two endpoints connected at the same time will never have the same gsnumber, one endpoint may have a gsnumber that was assigned to another endpoint in the past. Can be used to correlate a <customer> element with a <primary_customer> or with an event's <performed_by> or <destination> element.
<username>

The name used to identify the endpoint during the session.

<public_ip> The endpoint's public IP address.
<private_ip> The endpoint's private IP address.
<hostname> The hostname of the endpoint.
<os> The operating system of the endpoint.
/session_list/session/rep_list/representative
gsnumber (attribute)

Uniquely identifies the user in regards to their current connection to the BeyondTrust Appliance B Series. A gsnumber is assigned on a per-connection basis, so if a user leaves a session and then rejoins without logging out of the B Series Appliance, their gsnumber will remain the same.

However, if the user's connection is terminated for any reason, when that user logs back into the B Series Appliance, they will be assigned a new gsnumber and will also appear multiple times in the <rep_list> element.

A gsnumber may be recycled, so while two people connected at the same time will never have the same gsnumber, one person may have a gsnumber that was assigned to another person in the past. Can be used to correlate a <representative> element with a <primary_rep> or with an event's <performed_by> or <destination> element.

id (attribute) Unique ID assigned to the user.
<username> The username assigned to the user.
<display_name> The display name assigned to the user. Note that this field contains the display name's value at the time of the conference, which may not match the current value if the display_name has subsequently been changed.
<public_ip> The user's public IP address.
<private_ip> The user's private IP address.
<hostname> The hostname of the user's computer.
<os> The operating system of the user's computer.
<session_owner> Integer value (1 or 0) indicating whether the user was the owner of the session or was merely a conference member.
<seconds_involved> Integer value indicating the number of seconds the user was involved in this session.
<invited>

Integer value (1) present only if the user is an invited user.

/session_list/session/session_details/event
timestamp (attribute) The system time at which the event occurred.
event_type (attribute)

The type of event which occurred. Event types include the following:

Chat Message Registry Imported
Command Shell Session Started* Registry Key Added
Conference Member Added Registry Key Deleted
Conference Member Departed Registry Key Renamed
Conference Member State Changed Registry Value Added
Conference Owner Changed Registry Value Deleted
Credential Injection Attempt Registry Value Modified
Credential Injection Attempt Failed Registry Value Renamed
Directory Created Screen Recording
File Deleted Screenshot Captured
File Download Service Access Allowed
File Download Failed Session End
File Moved Session Foreground Window Changed
File Upload Session Start
File Upload Failed System Information Retrieved
Registry Exported  

*Will only appear if recording is enabled for this session.

<performed_by> The entity that performed the action. Indicates the entity's gsnumber and also its type, indicating whether this action was performed by the system, a endpoint, or a representative.
<destination> The entity to which the event was directed. Indicates the entity's gsnumber and also its type, indicating whether this action was directed to the system, a customer, or a user.
<body>

The text of the message as displayed in the chat log area.

 

<encoded_body> Can be shown in place of the <body> element above. Contains the base64 (RFC 2045 section 6.8) encoded value of what would have been shown in the <body> element, and is shown ONLY if the <body> text contains characters that are invalid according to XML specification. These characters are typically the result of binary data being sent through chat messages.
<filename> The name of the transferred file.
<files> If this event involved the transferring of files, then this element will contain a <file> element for every file transferred.
<filesize> An integer indicating the size of the transferred file.
<system_information>

Applies only to System Information Retrieved events wherein the system information is pulled automatically upon session start. This element contains multiple <category> child elements as described below.

System information is logged only when pulled automatically at the beginning of the session and not when specifically requested by the user. This is to prevent overload with the large amount of dynamic data that can be retrieved from the remote system.

<data>

Contains an arbitrary number of <value name="_" value="_" /> elements. The name and number of these elements varies based on event_type. For example, when a user joins the session, a Conference Member Added event would contain <value> elements for the user's name, private_ip, public_ip, hostname, and os.

/session_list/session/session_details/event/system_information/category
<description> Contains multiple <field> elements, each of which contains a descriptor for the specific data field. For example, the Drives category would have <field> elements Drive, Type, Percent Used, etc. These <field> elements can be compared to table header cells.
<data> Contains multiple <row> elements, each of which contains multiple <field> elements that correspond to the <field> elements above. For example, the Drives category would have a separate <row> for each drive on the endpoint computer. An example <row> might contain <field> elements C:\, Local Disk, 60%, etc. These <row> elements can be compared to table rows, with each <field> element a table cell.

Query examples for AccessSession

Sessions started July 1 2016 to present

https://access.example.com/api/reporting?
generate_report=AccessSession&start_date=2016-07-01&
duration=0

Sessions started the month of July 2016

https://access.example.com/api/reporting?
generate_report=AccessSession&start_date=2016-07-01&
duration=31

 

Sessions started 8:00 AM July 1 2016 to present

https://access.example.com/api/reporting?
generate_report=AccessSession&start_time=1467360000&
duration=0

Sessions started 8:00 AM July 1 2016 to 6:00 PM July 1 2016

https://access.example.com/api/reporting?
generate_report=AccessSession&start_time=1467360000&
duration=36000

Sessions ended July 1 2016 to present

https://access.example.com/api/reporting?
generate_report=AccessSession&end_date=2016-07-01&
duration=0

Sessions ended the month of July 2016

https://access.example.com/api/reporting?
generate_report=AccessSession&end_date=2016-07-01&
duration=31

Sessions ended 8:00 AM July 1 2016 to 6:00 PM July 1 2016

https://access.example.com/api/reporting?
generate_report=AccessSession&end_time=1467360000&
duration=36000

Session c69a8e10bea9428f816cfababe9815fe

https://access.example.com/api/reporting?
generate_report=AccessSession&
lsid=c69a8e10bea9428f816cfababe9815fe

Sessions c69a8e10bea9428f816cfababe9815fe,
a5eeaa58591047b88556f944804227b0,
5bf07601298b495b87310da9ce571e22

https://access.example.com/api/reporting?
generate_report=AccessSession&
lsids=c69a8e10bea9428f816cfababe9815fe,
a5eeaa58591047b88556f944804227b0,
5bf07601298b495b87310da9ce571e22