API v2: Sessions Management¶


Data Structures¶

Note

The following data structure contains read-only fields for retrieving session data.

SessionsModel¶

Attribute

Type

Description

id

string

Object Identifier

leader_session_id

string

Object Identifier

account_id

string

Account’s Identifier, which was used for connection. Requires read right on object type account for all methods: GET, PATCH, and DELETE.

listener_id

string

Listener’s Identifier, which was used for connection

safe_id

string

Safe’s Identifier, which was used for connection. Requires read right on object type safe for all methods: GET, PATCH, and DELETE.

server_id

string

Server’s Identifier, which was used for connection. Requires read right on object type server for all methods: GET, PATCH, and DELETE.

user_id

string

User’s Identifier, which was used for connection. Requires read right on object type user for all methods: GET, PATCH, and DELETE.

started_at

string

Datetime of the session’s start

finished_at

string

Datetime of the session’s end

handled_by

string

Object Identifier

marked_safe_by

string

terminate_at

string

Datetime of the session’s termination

dump_mode

string {all, none, raw, noraw}

Session recording options

protocol

string {http, modbus, mysql, rdp, ssh, system, tcp, tds, telnet, tn3270, tn5250, vnc}

Read-only. Protocol used for connection.

source_ip

string

Source IP address

source_port

number

Port of the source IP address

destination_ip

string

Destination IP address

destination_port

number

Port of the destination IP address

destination_address

string

Expensive. Concatenated destination IP and port.

paused

boolean

retention_locked

boolean

indexed

number

Session indexing status. Values: 0 = Waiting, 1 = Error, 2 = Indexed. Session is indexed when value is 2.

trusted_timestamp

string

Hidden. Base64 encoded timestamping signature.

size

number

reason

string

Reason of the session’s termination or rejection

status

string {approved, disconnected, expired, rejected, terminated, waiting}

active_time

number

ml (Machine Learning)

See the SessionsMLModel table

pending_delete

boolean

password_change

boolean

checkout_forced

boolean

created_at

datetime

Datetime of the record creation

modified_at

datetime

Datetime of the record modification

removed

boolean

login_reason

string

Reason for user’s connection

bits_per_pixel

string

Resolution options

height

string

Resolution options

width

string

Resolution options

type

string

Session’s type

subsystem

string

Read-only. Expensive to use. For example, sftp.

user_name

string

Expensive. User name who created session.

user_removed

boolean

Expensive. User is removed.

user_organization

string

Expensive. User organization who created session.

account_name

string

Expensive. Account name.

account_removed

boolean

Expensive. Account is removed.

server_name

string

Expensive. Server name.

server_removed

boolean

Expensive. Server is removed.

safe_name

string

Expensive. Safe name.

safe_removed

boolean

Expensive. Safe is removed.

listener_name

string

Expensive. Listener name.

listener_removed

boolean

Expensive. Listener is removed.

secret_exposure_state

string {user_blocked, user_removed, user_lost_access, seen}

Expensive. State of user who checked out the current account password. Value ‘seen’ means that user has seen password and have access to it.

ocr_enabled

boolean

Read-only. Expensive. Indicates whether OCR was enabled for the session.

ocrable

boolean

Read-only. Expensive. Indicates whether the session is eligible for OCR processing.

ocred

boolean

Expensive. Indicates whether OCR has been completed for the session.

ocr_progress

number

Read-only. Expensive. Current progress of OCR processing.

availability

string {archived, available, downloading, missing}

Expensive. Session availability.

created_on

string

Expensive. The serial number of the node where the session was created.

archived

boolean

Read-only. Expensive. Session is fully replicated on archive node.

duration

number

Expensive. Session duration in seconds.

activity

number

Expensive. Session active time in percents.

time_limit

number

Expensive. Time in seconds remaining until the session is terminated. Value is available only when terminate_at defined. Value 0 means session is finished or terminated.

unfinished_archive

boolean

Read-only. Expensive to use. Indicates whether the session is not fully replicated on the archive node.

query_text

string

Read-only. Hidden. Used only for filters. Query text to search for.

query_input

boolean

Read-only. Hidden. Used only for filters. Indicates whether to search text in user input.

query_output

boolean

Read-only. Hidden. Used only for filters. Indicates whether to search text in output.

query_comments

boolean

Read-only. Hidden. Used only for filters. Indicates whether to search text in comments.

websocket_url

string

Read-only. Expensive to use. A part of the URL to the websocket that serves the data of this session.

timestamp_status

string {none, pending, completed}

Read-only. Expensive to use. Status of timestamping process.

subprotocol

string {checkout, http, http_rendered, modbus, mysql, rdp, scp, sftp, ssh, ssh_command, tcp, tds, telnet, tn3270, tn5250, vnc, x11}

Read-only. Expensive to use. Session subprotocol.

local

boolean

Read-only. Expensive to use. Indicates that the session is running or has a replica on the current cluster node.

replicated_on_nodes

string-array

Read-only. Expensive to use. List of nodes that the session was fully replicated on.

has_comments

boolean

Read-only. Expensive to use. Indicates whether any comments have been added to the session.

SessionsMLModel¶

Attribute

Type

Description

ml_threat_level

number

Detected threat level

ml_threat_level_min

number

Min threat level value

ml_threat_level_max

number

Max threat level value

ml_converted_at

string

Datetime of the session’s processing

ml_finished_at

string

End datetime of the session’s processing

Retrieve Available Attributes of the SessionsModel¶

Request

Method

GET

Path

/api/v2/objspec/session

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.


Refer to the Batch operations topic to create nested requests for operating on the Sessions objects.


Get Sessions List¶

Request

Method

GET

Path

/api/v2/session

Example Request

GET /api/v2/session

    {
"result": "success",
"session": {
    "id": "3927138875067084301",
    "leader_session_id": "3927138875067084301",
    "listener_id": "3927138875067073099",
    "user_id": "3927138875067072685",
    "safe_id": "3927138875067072584",
    "account_id": "3927138875067088645",
    "server_id": "3927138875067072586",
    "started_at": "2022-04-05 16:06:07.313862+02",
    "finished_at": "2022-04-05 16:07:58.65701+02",
    "dump_mode": "all",
    "protocol": "vnc",
    "source_ip": "10.2.0.0",
    "source_port": 65331,
    "destination_ip": "10.0.0.1",
    "destination_port": 5900,
    "paused": false,
    "retention_locked": false,
    "indexed": 2,
    "size": 371712,
    "status": "approved",
    "active_time": 60,
    "password_change": false,
    "checkout_forced": false,
    "created_at": "2022-04-05 16:06:07.316523+02",
    "modified_at": "2022-04-08 08:16:02.009606+02",
    "height": "768",
    "width": "1024"
}}

Get a Session by ID¶

Request

Method

GET

Path

/api/v2/session/<id>

Example Request

GET /api/v2/session/<id>

    {
"result": "success",
"session": {
    "id": "3927138875067084301",
    "leader_session_id": "3927138875067084301",
    "listener_id": "3927138875067073099",
    "user_id": "3927138875067072685",
    "safe_id": "3927138875067072584",
    "account_id": "3927138875067088645",
    "server_id": "3927138875067072586",
    "started_at": "2022-04-05 16:06:07.313862+02",
    "finished_at": "2022-04-05 16:07:58.65701+02",
    "dump_mode": "all",
    "protocol": "vnc",
    "source_ip": "10.2.0.0",
    "source_port": 65331,
    "destination_ip": "10.0.0.1",
    "destination_port": 5900,
    "paused": false,
    "retention_locked": false,
    "indexed": 2,
    "size": 371712,
    "status": "approved",
    "active_time": 60,
    "password_change": false,
    "checkout_forced": false,
    "created_at": "2022-04-05 16:06:07.316523+02",
    "modified_at": "2022-04-08 08:16:02.009606+02",
    "height": "768",
    "width": "1024"
}}

Modify a Session¶

Request

Method

PATCH

Path

/api/v2/session/<id>

Delete Session¶

Request

Method

DELETE

Path

/api/v2/session/<id>

Example Request

DELETE /api/v2/session/<id>

curl -s -k -X DELETE \
  -H 'Authorization: sgfeea6jsaz4mum9su8w6' \
  'https://10.0.214.98/api/v2/session/9124292845052624897'

Response

{
    "result": "success"
}