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
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  
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 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
command string Given command during a session
type string Session’s type
subsystem string 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.
ocred boolean Expensive. Session texts were ocred.
availibility string {archived, available, downloading, missing, unknown} Expensive. Session availability.
created_on string Expensive. The serial number of the node where the session was created.
replicated_on_nodes string Expensive. Session has been replicated on nodes (serial numbers).
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.
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 by ID

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

Deleting Session

Request

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

Example Request

Sending DELETE https://10.0.0.0/api/v2/session/9124292845052624897

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

Response

{
    "result": "success"
}