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
listener_id	string	Listener’s Identifier, which was used for connection
safe_id	string	Safe’s Identifier, which was used for connection
server_id	string	Server’s Identifier, which was used for connection
user_id	string	User’s Identifier, which was used for connection
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}	Used protocol 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
paused	boolean
retention_locked	boolean
indexed	number
-trusted_timestamp	string
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)	SessionsMLModel
pending_delete	boolean
password_change	boolean
checkout_forced	boolean
created_at	string	Datetime of the record creation
modified_at	string	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
command	string	Given command during a session
type	string	Session’s type
subsystem	string	For example, sftp

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

Request for retrieving available attributes of the SessionsModel

Method	GET
Path	/api/v2/objspec/session

SessionBackupAssignmentModel

Attribute	Type	Description
session_id	string	ID of the session to backup. Requires backup_id": {} or backup_name: {}.
session_ids	string-array	IDs of the sessions to backup. Requires backup_id": {} or backup_name: {}.
backup_id	string	ID of the backup target. Requires session_id": {} or session_ids: {}.
backup_name	string	Name of the backup target. Requires session_id": {} or session_ids: {}.

Request for retrieving available attributes of the SessionBackupAssignmentModel

Method	GET
Path	/api/v2/objspec/session_backup

Note

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

The next chapter describes procedures for creating separate requests.

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

Retrieving sessions list

Request

Method	GET
Path	/api/v2/session

Retrieving a session

Request

Method	GET
Path	/api/v2/session/<id>

Example request

Sending GET https://10.0.0.0/api/v2/session/41234678819172646916

    {
"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"
}}

Modifying a session

Request

Method	PATCH
Path	/api/v2/session/<id>

Mark existing session for back up

Request

Method	POST
Path	/api/v2/session/<session_id>/backup/<backup_id>

Example request

Sending POST https://10.0.0.0/api/v2/session/2345678901234567890/backup/12345617890123456789

Request

Method	POST
Path	/api/v2/session_backup
Headers	Content-Type: Application/JSON
Body	SessionBackupAssignmentModel

Example request

Sending POST https://10.0.0.0/api/v2/session_backup

{
"backup_name": "Backup_Target_Name",
"session_ids": [
        "2345678901234567890",
        "2345678901234567891"
]
}

Response

{
"result": "success",
"session_ids": [
        "2345678901234567890",
        "2345678901234567891"
        ]
}